# CAD-Viewer（Русский）

[English](./README.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md) | [Español](./README.es.md) | [Português](./README.pt.md) | [Русский](./README.ru.md) | [Čeština](./README.cs.md)

cad-viewer — `первый в мире веб-просмотрщик и редактор DXF/DWG, который полностью работает в браузере без каких-либо серверных сервисов`.
Благодаря разбору DWG/DXF, обработке геометрии и рендерингу непосредственно в браузере cad-viewer обеспечивает по-настоящему serverless просмотр и редактирование CAD — идеально для облачных приложений, офлайн-работы и сценариев с повышенными требованиями к конфиденциальности.

Кроме того, здесь есть то, что редко встретишь в других CAD-просмотрщиках — **экспорт в один самодостаточный HTML-файл в один клик**. Скачанный `.html` содержит снимок чертежа и лёгкую среду просмотра, поэтому получатель может открыть файл, перемещаться, масштабировать, переключать слои и измерять расстояния в любом современном браузере **без CAD-приложения, без сервера и без установки**. Большинство настольных и веб CAD-просмотрщиков позволяют смотреть чертёж только внутри своего продукта; cad-viewer превращает активный чертёж в переносимый офлайн-артефакт, который можно отправить по почте, заархивировать или разместить на статическом хостинге — идеально для обмена с клиентами, архивов соответствия и изолированных (air-gapped) рабочих процессов. Офлайн-просмотрщик также потребляет значительно меньше памяти, чем традиционные настольные инструменты при открытии того же чертежа (см. [сравнение памяти](#использование-памяти-автономного-html) ниже).

- [**🌐 Живая демонстрация**](https://mlightcad.github.io/cad-viewer/)
- **🌐 Документация API**: [Read the Docs](https://cad-viewer.readthedocs.io/en/latest/) (с версиями) · [GitHub Pages](https://mlightcad.github.io/cad-viewer/docs/) (последняя/dev)
- [**🌐 Wiki**](https://github.com/mlightcad/cad-viewer/wiki)
- X (Twitter): [@mlightcad](https://x.com/mlightcad)
- YouTube: [@mlightcad](https://www.youtube.com/@mlightcad)
- Medium: [@mlightcad](https://medium.com/@mlightcad)
- Juejin(稀土掘金): [@mlightcad](https://juejin.cn/column/7501992214283501579)

### Приложения на базе cad-viewer

Команда [Thingraph](https://cad.thingraph.site/) создаёт промышленные просмотрщики DWG/DXF и интеграции с платформами на базе cad-viewer, обслуживая десятки тысяч пользователей по всему миру:

- [DWG Viewer Web App](https://cad.thingraph.site/dwg-viewer) — браузерный просмотрщик DWG/DXF, которым инженерные команды по всему миру пользуются для быстрого serverless доступа к чертежам. Установка для вашей платформы:
  - [Google Drive](https://workspace.google.com/marketplace/app/dwg_viewer/641533811831) — открытие DWG/DXF из Drive через **Open with**
  - [VS Code](https://marketplace.visualstudio.com/items?itemName=thingraph.dwg-viewer) — пользовательский редактор только для чтения для `.dwg` / `.dxf`
  - [Cursor](https://open-vsx.org/extension/thingraph/dwg-viewer) — то же расширение через Open VSX
  - [Confluence](https://marketplace.atlassian.com/apps/2890472615/dwg-viewer-for-confluence) — встраивание превью DWG/DXF на страницы
  - [Windows Explorer](https://cad.thingraph.site/install/windows) — миниатюры и предпросмотр в проводнике

Приложения и интеграции сообщества:

- [flyfish-dev/cad-viewer](https://github.com/flyfish-dev/cad-viewer) — промышленный браузерный CAD-просмотрщик для DWG, DXF, DWF, DWFx и XPS ([живая демонстрация](https://cad-viewer-iys.pages.dev))
- [Nextcloud CAD Viewer](https://github.com/ashcoft/nextcloud-cad-viewer) — нативное приложение Nextcloud для просмотра DWG/DXF в браузере ([App Store](https://apps.nextcloud.com/apps/cad_viewer))

Пакеты для Linux от сообщества:

- [CAD Viewer AppImage](https://github.com/pass-wind/cad-viewer-appimage) — AppImage на Electron для Linux (~114 MB), протестирован на Fedora
- [cad-viewer (AUR)](https://aur.archlinux.org/packages/cad-viewer) — исходный пакет Arch Linux с системным Electron (~5.4 MB)
- [cad-viewer-bin (AUR)](https://aur.archlinux.org/packages/cad-viewer-bin) — бинарный пакет Arch Linux со встроенными шрифтами/шаблонами для полностью офлайн открытия чертежей

![CAD-Viewer Quick Demo](./assets/cad-viewer.gif)

## Возможности

- **Высокая производительность** просмотра больших файлов DWG/DXF с плавным рендерингом 60+ FPS
- **Без бэкенда** — файлы разбираются и обрабатываются полностью в браузере
- **Повышенная безопасность данных** — файлы никогда не покидают ваше устройство, обеспечивая полную конфиденциальность
- **Простая интеграция** — не требуется настройка сервера или серверной инфраструктуры
- Модульная архитектура для бесшовной интеграции со сторонними системами
- **Экспорт в офлайн HTML** — экспорт текущего чертежа в один самодостаточный `.html`-файл со встроенным просмотрщиком (панорамирование/масштаб, масштаб по границам, слои, измерение расстояний, интерфейс EN/ZH). Открывается офлайн в любом браузере; экземпляр cad-viewer или бэкенд не требуются.
- Рабочие процессы офлайн- и онлайн-редактирования
- Движки 3D-рендеринга THREE.js с продвинутыми техниками оптимизации
- Спроектирован для расширяемости и интеграции с платформами вроде CMS, Notion и WeChat

## Начало работы

### Требования

- [Node.js](https://nodejs.org/) >= 24
- [pnpm](https://pnpm.io/) >= 10

### Установка

```bash
git clone https://github.com/mlightcad/cad-viewer.git
cd cad-viewer
pnpm install
```

### Разработка

```bash
# Запуск полнофункционального просмотрщика (cad-viewer)
pnpm dev

# Или запуск простого просмотрщика
pnpm dev:simple
```

### Сборка

```bash
pnpm build
```

### Предпросмотр

```bash
# Предпросмотр полнофункционального просмотрщика
pnpm preview

# Предпросмотр простого просмотрщика
pnpm preview:simple
```

## Как пользоваться

### Операции в настольном браузере
- **Выделение**: левый клик по объектам
- **Увеличение/уменьшение**: прокрутка колёсика мыши вверх/вниз
- **Панорамирование**: удерживайте среднюю кнопку мыши и перетаскивайте
- **Удаление**: выделите объекты и нажмите клавишу `Del`

### Операции в браузере на планшете/мобильном
- **Выделение**: касание объектов
- **Масштаб**: жест pinch двумя пальцами
- **Панорамирование**: перетаскивание одним пальцем

## Система плагинов

CAD-Viewer построен вокруг модульной **системы плагинов** в [`@mlightcad/cad-simple-viewer`](packages/cad-simple-viewer). Плагины реализуют интерфейс `AcApPlugin` и подключаются к жизненному циклу просмотрщика через `onLoad` / `onUnload` — обычно для регистрации команд, добавления UI или подключения конвейеров экспорта/импорта.

Загружайте плагины через `AcApDocManager.instance.pluginManager` (`loadPlugin`, `registerLazyPlugin` или `plugins.fromConfig` при создании менеджера документов). Плагины экспорта поддерживают **ленивую загрузку**: зарегистрируйте небольшую заглушку заранее и загружайте тяжёлый бандл только когда пользователь запускает связанную команду (например `-chtml`, или при подтверждении экспорта из диалога `chtml` в `cad-viewer`).

Монорепозиторий поставляет несколько официальных плагинов. Каждый решает одну задачу; комбинируйте их по необходимости. **Установка, регистрация и детали API описаны в README каждого пакета** — см. ссылки ниже.

### Официальные плагины

| Пакет | Роль | Команды / возможности |
|---------|------|-------------------------|
| [`@mlightcad/cad-simple-ui-plugin`](packages/cad-simple-ui-plugin) | **Панель инструментов и менеджер слоёв** для `cad-simple-viewer` (plain DOM, без Vue/React) | `layer`, панель инструментов по умолчанию (вид, измерение, экспорт, рецензирование, тема, локаль) |
| [`@mlightcad/cad-agent-plugin`](packages/cad-agent-plugin) | **CAD-агент на естественном языке** (AI-панель чата + вызовы инструментов чертежа) | `agent` |
| [`@mlightcad/cad-html-plugin`](packages/cad-html-plugin) | Экспорт чертежей в **автономный HTML** | `chtml` (диалог в `cad-viewer`), `-chtml` (командная строка) |
| [`@mlightcad/cad-pdf-plugin`](packages/cad-pdf-plugin) | **Экспорт и импорт PDF** (векторный конвейер) | `cpdf`, `ipdf` |
| [`@mlightcad/cad-svg-plugin`](packages/cad-svg-plugin) | **Экспорт SVG** и общий векторный рендерер (также используется экспортом PDF) | `csvg` |

### `@mlightcad/cad-simple-ui-plugin` — UI-оболочка для простого просмотрщика

[`cad-simple-viewer`](packages/cad-simple-viewer) намеренно **не поставляет прикладной UI** — только холст и CAD-ядро. Если вы встраиваете простой просмотрщик в своё веб-приложение и хотите готовую оболочку без полной Vue-оболочки [`cad-viewer`](packages/cad-viewer), **`cad-simple-ui-plugin` — предназначенный UI-слой**.

Он предоставляет:

- **Настраиваемую панель инструментов** (размещение на любой стороне, стандартные CAD-команды, вложенные меню, пользовательские элементы)
- **Плавающий менеджер слоёв** (вкл/выкл слоя, выбор цвета ACI, масштаб к слою по двойному клику)
- **Синхронизацию темы** с sysvar `COLORTHEME` и CSS-токенами `--ml-ui-*` на вашем host-элементе
- **Синхронизацию локали** с `AcApI18n` (английский / китайский)

Все виджеты не зависят от фреймворка (plain DOM). Полное Vue-приложение [`cad-viewer`](packages/cad-viewer) имеет собственный UI на Element Plus и не требует этого плагина; используйте `cad-simple-ui-plugin`, когда вы строите непосредственно на `cad-simple-viewer`.

→ **Быстрый старт, настройка панели инструментов и параметры:** [packages/cad-simple-ui-plugin/README.md](packages/cad-simple-ui-plugin/README.md)

### `@mlightcad/cad-agent-plugin` — AI-помощник для чертежей

[`cad-agent-plugin`](packages/cad-agent-plugin) добавляет **CAD-агента на естественном языке** в приложения на базе `cad-simple-viewer`. Пользователи описывают желаемое простым языком; агент вызывает CAD-инструменты для анализа чертежа и создания или изменения геометрии.

Он предоставляет:

- **Лениво загружаемый** `AcApPlugin` (команда запуска: `agent`), чтобы AI-бандл не был на критическом пути
- **Vue-панель чата** (`AgentChatPanel`) на базе Vercel AI SDK (`Experimental_Agent` + `@ai-sdk/vue`)
- **Конфигурацию LLM на стороне браузера** — API-ключи для OpenAI, Anthropic или совместимых с OpenAI эндпоинтов остаются на клиенте (зашифрованы в `localStorage`)
- **CAD-инструменты фазы 1** — `get_drawing_context`; `draw_line`, `draw_circle`, `draw_arc`, `draw_rectangle`, `draw_polyline`, `draw_text`; `set_current_layer`, `create_layer`, `zoom_extents`
- **Строки UI** на английском / китайском / турецком / чешском через слой i18n плагина

Полное Vue-приложение [`cad-viewer`](packages/cad-viewer) регистрирует агента автоматически при установке пакета (вкладка палитры). [`cad-simple-viewer-example`](packages/cad-simple-viewer-example) подключает его во вкладку дока через `cad-simple-ui-plugin`. Host-приложения вызывают `registerLazyAgentPlugin` и `setAgentPaletteOpener`, чтобы разместить панель где нужно.

→ **Установка, регистрация и список инструментов:** [packages/cad-agent-plugin/README.md](packages/cad-agent-plugin/README.md)

### Плагины экспорта (HTML / PDF / SVG)

Эти плагины добавляют команды экспорта (и импорта PDF) в тот же менеджер плагинов. Они **лениво загружаются**, чтобы начальный вес страницы оставался небольшим. Демо [`cad-simple-viewer-example`](packages/cad-simple-viewer-example) регистрирует все три плагина экспорта, `cad-simple-ui-plugin` и `cad-agent-plugin`; полное приложение [`cad-viewer`](packages/cad-viewer) регистрирует плагины экспорта и плагин агента (при установке) при bootstrap.

- **HTML** — однофайловый офлайн-просмотрщик для обмена и архивирования: [packages/cad-html-plugin/README.md](packages/cad-html-plugin/README.md)  
  (Headless CLI с тем же конвейером: [packages/cad-html-exporter-cli/README.md](packages/cad-html-exporter-cli/README.md))
- **PDF** — векторный экспорт PDF и импорт PDF в CAD: [packages/cad-pdf-plugin/README.md](packages/cad-pdf-plugin/README.md)
- **SVG** — векторный экспорт SVG: [packages/cad-svg-plugin/README.md](packages/cad-svg-plugin/README.md)

#### Использование памяти автономного HTML

При открытии образца чертежа [`canteen.dwg`](https://cdn.jsdelivr.net/gh/mlightcad/cad-data@main/data/canteen.dwg) потребление памяти примерно следующее:

| Просмотрщик | Потребление памяти |
|--------|-------------|
| AutoCAD 2020 | 320 MB |
| GstarCAD Viewer (浩辰看图王) | 246 MB |
| Автономный HTML (режим измерения) | 56 MB |
| Автономный HTML (режим просмотра) | 33 MB |

Офлайн HTML-просмотрщик использует примерно **на 83% меньше памяти, чем AutoCAD 2020**, и примерно **на 77% меньше, чем GstarCAD Viewer** в режиме просмотра, при этом поддерживая панорамирование/масштаб, переключение слоёв и измерение расстояний (режим измерения).

## Производительность

CAD-Viewer спроектирован для **исключительной производительности** и может обрабатывать очень большие файлы DXF/DWG, сохраняя высокую частоту кадров. Применяются несколько продвинутых технологий рендеринга для оптимизации:

- **Пользовательские шейдерные материалы**: GPU-ускоренные шейдерные материалы для эффективного рендеринга сложных типов линий и штриховок
- **Пакетная геометрия**: объединение точек, линий и областей с одинаковым материалом для резкого сокращения draw calls
- **Instanced Rendering**: оптимизация рендеринга повторяющейся геометрии через instancing
- **Оптимизация Buffer Geometry**: эффективное управление памятью и объединение геометрии для снижения нагрузки на GPU
- **Кэширование материалов**: повторное использование материалов для похожих объектов для минимизации смены состояния
- **Оптимизация WebGL**: использование современных возможностей WebGL для аппаратно-ускоренного рендеринга

Эти оптимизации позволяют CAD-Viewer плавно рендерить сложные CAD-чертежи с тысячами объектов, сохраняя отзывчивое взаимодействие с пользователем.

## Известные проблемы

Путь DWG с открытым исходным кодом по умолчанию основан на [LibreDWG](https://github.com/LibreDWG/libredwg). Он хорошо работает для многих чертежей, но покрытие сущностей всё ещё ограничено, WASM-бандл значительно больше, запуск медленнее, потребление памяти выше, а очень большие файлы DWG могут вызывать ошибки нехватки памяти. Также это создаёт соображения по лицензированию GPL для коммерческих продуктов с закрытым исходным кодом.

Если вам нужна лучшая совместимость, меньшее потребление памяти, поддержка больших файлов или более чистая коммерческая лицензия, см. наш [**проприетарный парсер DWG**](./PROPRIETARY-PARSER.md).

| Параметр | Парсер на базе LibreDWG | Проприетарный парсер DWG |
|------|------------------------|------------------------|
| Поддерживаемые сущности | Ограниченное покрытие | Более широкое покрытие |
| Размер бандла | ~13 MB | ~437 KB |
| Скорость загрузки | Медленный запуск | Значительно быстрее запуск |
| Потребление памяти | Выше | Ниже |
| Большие файлы DWG | Возможен OOM на больших файлах | Такой проблемы нет |
| Лицензия | Риск распространения GPL | Нет проблемы распространения GPL |

## Дорожная карта

Цель проекта — создать полнофункциональную **2D-систему в браузере, похожую на AutoCAD** (просмотрщик + редактор), с модульной архитектурой и интеграцией, не зависящей от фреймворка.

Обозначения:
- [x] Завершено
- [ ] Запланировано
- [ ] ⏳ В процессе

### Ядро файлов и данных

#### Поддержка файлов

* [x] Загрузка DXF
* [x] Загрузка DWG
* [x] Экспорт в автономный HTML (встроенный просмотрщик)
* [x] Потоковая / инкрементальная загрузка больших файлов
* [ ] ⏳ Совместимость версий файлов (R12–Latest)

#### Модель данных

* [x] Единая модель данных сущностей
* [x] Поддержка таблицы слоёв
* [x] Структура блоков / вставок
* [ ] ⏳ Управление handle и object ID: сейчас objectId совпадает с handle и представлен как одна строка вместо bigint (int64).
* [ ] ⏳ Поддержка XData / словаря расширений
* [ ] Обработка proxy-сущностей

### Рендеринг и производительность

#### Движок рендеринга

* [x] Рендеринг на WebGL (Three.js)
* [x] Оптимизированный конвейер только для 2D
* [x] Организация сцены по слоям
* [x] Рендеринг layout / paper space
* [ ] Поддержка viewport-сущностей

#### Оптимизация производительности

* [x] Объединение и пакетная обработка геометрии
* [x] Пространственная индексация (базовая)
* [x] Продвинутый пространственный индекс (R-tree / BVH)
* [ ] Рендеринг с уровнем детализации (LOD)
* [ ] Multi-canvas / tiled rendering для очень больших чертежей

### Просмотр и навигация

#### Управление видом

* [x] Панорамирование
* [x] Масштаб (колёсико / рамка)
* [x] Вписать в вид / по границам
* [ ] Именованные виды
* [ ] История видов (отмена / повтор изменений вида)

#### Управление отображением

* [x] Видимость слоёв вкл/выкл
* [x] Заморозка / блокировка слоёв
* [x] Отображение толщины линий
* [ ] Масштабирование типов линий
* [x] Переключение фона / темы

### Выделение и взаимодействие

#### Выделение

* [x] Выделение одного объекта
* [x] Подсветка выделенных объектов
* [x] Рамочное выделение (window)
* [x] Пересекающее выделение (crossing)
* [x] Фильтры выделения (по типу / слою)
* [x] Циклическое выделение

#### Привязка (OSNAP)

* [x] Конечная точка
* [x] Середина
* [x] Центр
* [ ] Пересечение
* [ ] Нормаль / касательная
* [x] Ближайшая
* [ ] Трассировка привязки


### Редактирование и модификация

#### Базовое редактирование

* [x] Фреймворк редактирования сущностей
* [x] Перемещение
* [x] Копирование
* [x] Поворот
* [ ] Масштабирование
* [x] Удаление
* [x] Отмена / повтор

#### Редактирование геометрии

* [x] Grip points
* [ ] Растягивание
* [ ] Обрезка
* [ ] Удлинение
* [x] Смещение
* [ ] Разбиение
* [ ] Соединение / скругление / фаска (2D)

### Инструменты рисования и создания

#### Базовые сущности

* [x] Линия
* [x] Полилиния
* [x] Сплайн
* [x] Окружность
* [x] Дуга
* [x] Эллипс
* [x] Прямоугольник / многоугольник

#### Продвинутые сущности

* [x] Штриховка
* [ ] Текст (однострочный / многострочный)
* [ ] Размеры (линейный, выровненный, угловой)
* [ ] Создание и вставка блоков

### Измерение

* [x] Расстояние
* [x] Длина дуги
* [x] Площадь
* [x] Угол
* [ ] Координата
* [ ] Статистика объектов (длина, площадь, количество)

### Размеры

* [x] Линейный размер
* [ ] Угловой размер
* [ ] Координата

### Свойства и UI-панели

#### Палитра свойств

* [x] Свойства выделенного объекта
* [ ] Редактирование слоя, цвета, типа линии
* [x] Обновление в реальном времени при изменении

#### Панели и UI

* [x] Менеджер слоёв
* [ ] Менеджер блоков
* [x] История команд / консоль
* [x] Строка состояния (привязка, ортогональ, сетка)

#### Система команд

* [x] Реестр команд
* [x] Псевдонимы команд
* [x] Подсказки команд (в стиле AutoCAD)

### Интеграция и расширяемость

#### Интеграция с фреймворками

* [x] Ядро, не зависящее от фреймворка
* [ ] Пример интеграции с React
* [x] Пример интеграции с Vue
* [ ] Интеграция с OpenLayers / Map
* [ ] Встраивание в CMS / Notion

#### Система плагинов

* [x] API плагинов
* [ ] Поддержка пользовательских сущностей
* [x] Пользовательские команды

### Офлайн- и онлайн-редактирование

#### Офлайн-редактор

* [x] Локальное редактирование в браузере
* [x] Сохранение в DXF
* [ ] Сохранение набора изменений / diff
* [ ] Персистентность в IndexedDB

#### Онлайн-редактор

* [ ] Проектирование backend API
* [ ] Аутентификация пользователей
* [ ] Версионирование файлов
* [ ] Контроль доступа для нескольких пользователей
* [ ] Совместная работа в реальном времени (в будущем)

### Целевые платформы

* [ ] ⏳ Интеграция с Google Drive
* [ ] Просмотрщик для WeChat Mini Program
* [ ] Поддержка мобильного браузера (только чтение)

### Документация и сообщество

* [x] Документация по архитектуре
* [x] Справочник API
* [ ] Руководство для участников
* [x] Примеры проектов
* [x] Поддержка дорожной карты и changelog

Дорожная карта намеренно детализирована, чтобы участники могли ясно видеть, **что уже есть**, **чего не хватает** и **где нужна помощь**.

## Участие в разработке

Мы приветствуем вклад! Открывайте issues или pull requests с исправлениями ошибок, новыми функциями или предложениями. При сообщении об ошибках ссылка на проблемный чертёж поможет воспроизвести и исправить проблему.

## Лицензия

Монорепозиторий cad-viewer в основном распространяется под лицензией [MIT](LICENSE).

Загрузка DXF использует встроенный MIT-парсер в `@mlightcad/data-model`. **Путь загрузки DWG по умолчанию** в `@mlightcad/cad-simple-viewer` зависит от пакетов GPL-3.0 (`libredwg-web` / `@mlightcad/libredwg-converter`). Если вы поставляете продукт с закрытым исходным кодом и не можете распространять GPL-код своим клиентам, используйте [**проприетарный парсер DWG**](./PROPRIETARY-PARSER.md) — он заменяет этот конвертер и позволяет остальному стеку оставаться только под MIT.

→ **Коммерческий парсер:** [PROPRIETARY-PARSER.md](./PROPRIETARY-PARSER.md) (объём, лицензирование, цены, интеграция, соответствие GPL, поддержка)