Реструктуризация проекта и генератор синтетических датасетов эхолота.

Перенесены backend/frontend/desktop/engine, добавлены вкладки конструктора сцен и генератора датасета с параметрами лучей и длины сетки рельефа, обновлены API и Docker-сборка. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-17 12:25:00 +03:00
parent 18a58f2e85
commit 4f253b860f
134 changed files with 5263 additions and 863 deletions
@@ -0,0 +1,115 @@
+# Архитектура DotsToSurface
+
+Этот документ описывает **логические слои** проекта и соответствие **физических папок**.
+
+## Три слоя
+
+| Слой | Папки | Ответственность |
+|------|-------|-----------------|
+| **Engine** (C++) | `src/engine/` | Обработка облака точек: preprocess, PCL, реконструкция, метрики, CLI |
+| **Backend** (HTTP) | `backend/` | REST API: пресеты, validate, wizard, вызов CLI, отдача статики Vue |
+| **Frontend (Web)** | `frontend/web/` | Dashboard в браузере, Pinia, Three.js viewer |
+| **Frontend (Desktop)** | `src/desktop/` | Qt Widgets + QML dashboard, OpenGL viewer |
+
+**Важно:** Python и Vue **не выполняют** пайплайн сами. Backend вызывает бинарник `DotsToSurface --cli` через `subprocess` ([`backend/main.py`](backend/main.py)).
+
+## Карта репозитория
+
+```
+DotsToSurface/
+├── src/
+│   ├── main.cpp           # Entry: --cli или Qt GUI
+│   ├── engine/            # Engine — C++ пайплайн
+│   │   ├── core/
+│   │   ├── strategies/
+│   │   ├── adapters/
+│   │   ├── algorithms/
+│   │   ├── cli/
+│   │   ├── factories/
+│   │   └── tests/
+│   └── desktop/           # Frontend (Desktop) — Qt/QML
+│       ├── mainwindow.cpp
+│       ├── glview.cpp
+│       └── qml/
+├── backend/               # Backend — FastAPI
+├── frontend/
+│   └── web/               # Frontend (Web) — Vue 3
+├── docker/                # Infra — сборка и runtime-образ
+├── presets/               # Shared — JSON-пресеты
+└── DotsToSurface.pro
+```
+
+Артефакты сборки **не в git**: `build/`, `frontend/web/dist/`, `frontend/web/node_modules/`.
+
+## Потоки данных
+
+### Web (Docker или локально)
+
+```mermaid
+flowchart LR
+  Browser[Browser Vue3] -->|HTTP /api/*| FastAPI[backend/main.py]
+  FastAPI -->|subprocess| CLI[DotsToSurface --cli]
+  CLI --> Engine[PipelineExecutor]
+  Engine --> JSON[result.json]
+  JSON --> FastAPI
+  FastAPI --> Browser
+```
+
+### Desktop (Qt)
+
+```mermaid
+flowchart LR
+  QML[Qt QML Dashboard] --> MainWindow[MainWindow C++]
+  MainWindow --> Engine[PipelineExecutor in-process]
+  Engine --> GLView[OpenGL viewer]
+```
+
+## Что работает без C++ бинарника
+
+| Endpoint / функция | Без `DotsToSurface` |
+|--------------------|---------------------|
+| `GET /api/catalog`, `/api/presets`, `/api/builtin-presets` | Да |
+| `POST /api/validate-config`, `/api/wizard` | Да |
+| `GET /api/demo` | Да (точки генерирует Python) |
+| `POST /api/run` | **Нет** — нужен CLI |
+
+## Сценарии разработки
+
+### Web-версия целиком (рекомендуется)
+
+```bash
+cd docker
+docker compose up --build
+# → http://localhost:8080
+```
+
+### Frontend отдельно
+
+```bash
+cd frontend/web
+npm install
+npm run dev
+# → http://localhost:5173, /api проксируется на :8080
+```
+
+### Engine + Desktop локально
+
+```bash
+qmake DotsToSurface.pro 'DEFINES+=PCL_ENABLED'
+make -j$(nproc)
+./DotsToSurface
+```
+
+## Shared и известный техдолг
+
+- **`presets/`** — JSON-шаблоны; читаются Qt и Backend.
+- **`pipelineUiCatalog`** — дублирован в Qt и Vue:
+  - [`src/desktop/qml/shared/PipelineUiCatalog.js`](src/desktop/qml/shared/PipelineUiCatalog.js)
+  - [`frontend/web/src/catalog/pipelineUiCatalog.js`](frontend/web/src/catalog/pipelineUiCatalog.js)
+
+## Указатели по папкам
+
+- [backend/README.md](backend/README.md)
+- [frontend/web/README.md](frontend/web/README.md)
+- [src/README.md](src/README.md)
+- [docker/README.md](docker/README.md)