gitrusprusandCursor
45b2ed6e22
PLY читается в FilePointCloudSource, CLI отдаёт геометрию в output JSON, а Docker/FastAPI/Three.js дают веб-запуск пайплайна без конфликта libpq на хосте. Co-authored-by: Cursor <cursoragent@cursor.com>
248 lines
12 KiB
Markdown
248 lines
12 KiB
Markdown
# DotsToSirface (Qt 5.11)
|
||
|
||
Демонстрационная программа на Qt 5.11 C++, которая:
|
||
- принимает массив 3D-точек `QVector<Point3f>`;
|
||
- выполняет stage-based pipeline (preprocess -> transform -> registration -> reconstruction);
|
||
- визуализирует точки и полученную треугольную поверхность.
|
||
|
||
## Вход/выход API
|
||
|
||
`src/algorithms/reconstruction/surface_reconstruction.h`:
|
||
|
||
- `struct Point3f { float x, y, z; };`
|
||
- `struct Triangle { int i0, i1, i2; };`
|
||
- `QVector<Triangle> buildSurfaceTriangles(const QVector<Point3f>& points);`
|
||
|
||
`Triangle` хранит индексы вершин в исходном массиве `points`.
|
||
|
||
## Как это работает
|
||
|
||
Реализация использует инкрементальный `Convex Hull 3D`:
|
||
- удаление дубликатов точек (epsilon-сравнение);
|
||
- поиск стартового тетраэдра;
|
||
- поочередное добавление точек с пересчетом видимых граней и горизонта;
|
||
- поддержание ориентированных наружу треугольников.
|
||
|
||
## Ограничения
|
||
|
||
Текущая реализация строит **выпуклую оболочку** облака точек.
|
||
Для невыпуклых объектов и детальной реконструкции произвольной поверхности нужны более сложные алгоритмы (например, alpha-shapes, Poisson reconstruction и т.п.).
|
||
|
||
## Архитектурный каркас под robotics pipeline
|
||
|
||
- `core`: контракты (`PointCloudFrame`, `PipelineContext`, `PipelineStats`, stage-интерфейсы, plugin registry).
|
||
- `adapters`: мосты к источникам и внешним транспортам (`FilePointCloudSource`, `Ros2PointCloudSource`, `PointCloud2`/`tf2` adapters).
|
||
- `strategies`: конкретные стадии пайплайна (preprocess, transform, registration, reconstruction).
|
||
- `factories`: сборка `PipelineExecutor` из plugin-id и профиля.
|
||
|
||
## Этап 1 (backend-first, без CLI)
|
||
|
||
- Парсинг и применение `defaults` параметров стадий вынесены из UI в `core`:
|
||
`src/core/pipeline_stage_defaults.h` и `src/core/pipeline_stage_defaults.cpp`.
|
||
- `MainWindow` больше не содержит backend-логику разбора параметров, а вызывает
|
||
`core::applyStageDefaultsToConfig(...)`.
|
||
- Это позволяет использовать один и тот же backend API из GUI сейчас и из будущего
|
||
CLI на этапе 2 без дублирования логики.
|
||
|
||
## Pipeline Dashboard: UX и анализ цепочки
|
||
|
||
В dashboard реализованы инструменты для пошаговой настройки всей pipeline-цепочки (preprocess + reconstruction):
|
||
|
||
- **Категориальная палитра этапов**: фильтры сгруппированы по логике обработки
|
||
(`Обрезка -> NaN (предочистка) -> Условия/Индексы -> Шум -> Морфология -> Прореживание -> Сглаживание -> Нормали -> Реконструкция`), для каждого фильтра
|
||
доступны краткие подсказки.
|
||
- **Проверка порядка этапов**: при рискованной последовательности (например, когда
|
||
`OutlierRemoval` идет после `VoxelGrid`) показываются предупреждения и рекомендация.
|
||
- **Стартовые пресеты**: доступны шаблоны для типичных источников
|
||
(`LiDAR_scan`, `RGBD_camera`, `Synthetic_clean`) как отправная точка с возможностью
|
||
ручной донастройки.
|
||
- **Метрики между шагами**: показывается вклад каждого preprocess-этапа:
|
||
входные точки, выходные точки, сколько удалено и время шага в миллисекундах.
|
||
- **Единый редактор параметров**: и preprocess-стадии, и реконструкторы поверхности
|
||
настраиваются через одинаковые карточки и один диалог параметров.
|
||
|
||
Пер-шаговые метрики собираются на уровне `core::PipelineExecutor` и возвращаются через
|
||
`PipelineStats::preprocessStepMetrics`, чтобы данные были едиными для GUI и тестов.
|
||
|
||
### Профили выполнения
|
||
|
||
- `desktop_debug`: дефолтный профиль для GUI/отладки.
|
||
- `rpi4_runtime`: профиль для Raspberry Pi 4 (жестче downsampling, лимит точек, reconstruction реже, async-friendly настройки).
|
||
|
||
Выбор профиля:
|
||
- `factories::pipeline::createPipelineExecutorForProfile("desktop_debug")`
|
||
- `factories::pipeline::createPipelineExecutorForProfile("rpi4_runtime")`
|
||
|
||
## Сборка и запуск в WSL
|
||
|
||
Рабочий поток для этого проекта на Windows: собирать и запускать через WSL.
|
||
|
||
```bash
|
||
cd /mnt/d/yakupov/Projects/DotsToSirface/build-wsl
|
||
qmake ../DotsToSirface.pro 'DEFINES+=PCL_ENABLED'
|
||
make -j4
|
||
LIBGL_ALWAYS_SOFTWARE=1 QT_QPA_PLATFORM=xcb ./DotsToSirface
|
||
```
|
||
|
||
Примечания:
|
||
- `DEFINES+=PCL_ENABLED` включает PCL-стадии пайплайна.
|
||
- `LIBGL_ALWAYS_SOFTWARE=1` снижает риски графических артефактов в WSLg.
|
||
- `QT_QPA_PLATFORM=xcb` используется как стабильный backend для Qt в WSL.
|
||
|
||
Перезапуск после правок:
|
||
|
||
```bash
|
||
pkill -f '^./DotsToSirface$' || true
|
||
cd /mnt/d/yakupov/Projects/DotsToSirface/build-wsl
|
||
qmake ../DotsToSirface.pro 'DEFINES+=PCL_ENABLED'
|
||
make -j4
|
||
LIBGL_ALWAYS_SOFTWARE=1 QT_QPA_PLATFORM=xcb ./DotsToSirface
|
||
```
|
||
|
||
## Smoke tests (отдельный runner)
|
||
|
||
Для быстрой проверки пайплайна без GUI добавлен отдельный консольный таргет:
|
||
`DotsToSirfaceTests.pro`.
|
||
|
||
```bash
|
||
qmake DotsToSirfaceTests.pro
|
||
make
|
||
./release/DotsToSirfaceTests.exe
|
||
```
|
||
|
||
При успешном запуске runner печатает `Smoke tests passed.` и завершаетcя с кодом `0`.
|
||
|
||
## CLI режим (этап 2)
|
||
|
||
Для headless-прогона без GUI добавлен CLI-режим в основном бинарнике через `--cli`.
|
||
|
||
Пример:
|
||
|
||
```bash
|
||
cd /mnt/d/yakupov/Projects/DotsToSirface/build-wsl
|
||
qmake ../DotsToSirface.pro 'DEFINES+=PCL_ENABLED'
|
||
make -j4
|
||
./DotsToSirface --cli \
|
||
--input /mnt/d/path/to/cloud.xyz \
|
||
--profile desktop_debug \
|
||
--preprocess pcl_remove_nan,pcl_voxel_grid,pcl_statistical_outlier \
|
||
--reconstruction pcl_greedy_triangulation \
|
||
--stage-default pcl_voxel_grid:leaf=0.03 \
|
||
--stage-default pcl_greedy_triangulation:searchRadius=0.08,mu=2.5,maxNearest=100,maxSurfaceAngle=0.8 \
|
||
--output-json /mnt/d/path/to/result.json
|
||
```
|
||
|
||
CLI печатает краткую сводку по метрикам (`input`, `after preprocess`, `triangles`, `reconstruction ms`).
|
||
|
||
### JSON-конфиг для CLI (этап 2.1)
|
||
|
||
Чтобы не передавать длинную команду, можно задать пайплайн через `--config-json`.
|
||
|
||
Пример `pipeline_config.json`:
|
||
|
||
```json
|
||
{
|
||
"profile": "desktop_debug",
|
||
"preprocessPlugins": ["pcl_remove_nan", "pcl_voxel_grid", "pcl_statistical_outlier"],
|
||
"reconstructionPlugin": "pcl_greedy_triangulation",
|
||
"stageDefaults": {
|
||
"pcl_voxel_grid": "leaf=0.03",
|
||
"pcl_greedy_triangulation": "searchRadius=0.08,mu=2.5,maxNearest=100,maxSurfaceAngle=0.8"
|
||
}
|
||
}
|
||
```
|
||
|
||
Запуск:
|
||
|
||
```bash
|
||
./DotsToSirface --cli --input /mnt/d/path/to/cloud.xyz --config-json /mnt/d/path/to/pipeline_config.json
|
||
```
|
||
|
||
Если одновременно переданы `--config-json` и обычные CLI-флаги (`--preprocess`, `--reconstruction`, `--stage-default`), флаги командной строки имеют приоритет.
|
||
|
||
### Autotune Grid Search (этап 3)
|
||
|
||
Для подбора параметров с целью уменьшения дыр на поверхности добавлен режим:
|
||
`--autotune-config`.
|
||
|
||
Пример `autotune_config.json`:
|
||
|
||
```json
|
||
{
|
||
"baseConfigJson": "/mnt/d/path/to/pipeline_config.json",
|
||
"searchSpace": {
|
||
"pclVoxelLeafSize": [0.02, 0.03, 0.04],
|
||
"pclGreedySearchRadius": [0.06, 0.08, 0.10],
|
||
"neighborRadiusScale": [2.5, 3.0]
|
||
},
|
||
"objective": {
|
||
"connectivityWeight": 0.45,
|
||
"coverageWeight": 0.45,
|
||
"speedPenaltyWeight": 0.10
|
||
},
|
||
"limits": {
|
||
"maxCandidates": 20,
|
||
"topK": 5
|
||
},
|
||
"output": {
|
||
"resultJsonPath": "/mnt/d/path/to/autotune_result.json"
|
||
}
|
||
}
|
||
```
|
||
|
||
Запуск:
|
||
|
||
```bash
|
||
./DotsToSirface --cli \
|
||
--input /mnt/d/path/to/cloud.xyz \
|
||
--autotune-config /mnt/d/path/to/autotune_config.json
|
||
```
|
||
|
||
Опционально можно переопределить путь результата через `--output-json`.
|
||
|
||
Файл `autotune_result.json` теперь содержит поля `title` и `stages` в формате GUI-пресета,
|
||
поэтому его можно загрузить напрямую кнопкой `Загрузить пресет`.
|
||
Дополнительно рядом сохраняется `*_best_preset.json` (чистый preset-JSON).
|
||
|
||
## Docker + Web UI (CLI + PCL)
|
||
|
||
Для запуска пайплайна с PCL в изолированной среде (без конфликтов с `libpq` на хосте) добавлены:
|
||
|
||
- `docker/Dockerfile` — сборка `DotsToSirface` с `PCL_ENABLED` и запуск FastAPI;
|
||
- `docker/docker-compose.yml`;
|
||
- `api/main.py` — HTTP API (`/api/run`, `/api/presets`);
|
||
- `web/` — браузерный 3D viewer (Three.js).
|
||
|
||
### Быстрый старт
|
||
|
||
```bash
|
||
cd docker
|
||
docker compose up --build
|
||
```
|
||
|
||
Откройте в браузере: [http://localhost:8080](http://localhost:8080)
|
||
|
||
1. Загрузите `.ply`
|
||
2. Выберите preset (или оставьте default)
|
||
3. Нажмите **Run pipeline**
|
||
4. В viewer появятся точки и mesh, справа — метрики пайплайна
|
||
|
||
### API
|
||
|
||
- `GET /api/health` — статус сервиса
|
||
- `GET /api/presets` — список JSON-пресетов
|
||
- `POST /api/run` — multipart: `file` + опционально `preset_id`
|
||
|
||
CLI внутри контейнера пишет в `--output-json` не только метрики, но и геометрию:
|
||
`points` (массив `[x,y,z]`) и `triangleIndices` (массив `[i0,i1,i2]`).
|
||
|
||
Конфиг пайплайна по умолчанию: `docker/default_pipeline.json`.
|
||
|
||
## Демо
|
||
|
||
При запуске приложение:
|
||
- генерирует тестовое облако точек (приближенная сфера с небольшим шумом);
|
||
- строит триангуляцию;
|
||
- показывает статистику: количество точек, количество треугольников и время построения;
|
||
- отображает сцену в `QOpenGLWidget` (ЛКМ - вращение, колесо - зум).
|