AstraScanner2

Обзор

AstraScanner2 — это приложение с открытым исходным кодом для 3D сканирования и реконструкции с использованием RGB-D камер. Программное обеспечение захватывает облачные точки с камеры Astra Pro (или в режиме эмуляции) и предоставляет инструменты для обработки, фильтрации, реконструкции меша и регистрации множественных сканов.

Основные возможности

• ✅ Реальное 3D сканирование с камерой Astra Pro
• ✅ Оптическое отслеживание на основе круговых маркеров (CCTag)
• ✅ Оценка позы с помощью ИИ с ONNX Runtime
• ✅ Продвинутая фильтрация и очистка облачных точек
• ✅ Реконструкция поверхности Пуассона для замкнутых мешей
• ✅ Регистрация ICP для объединения множественных сканов
• ✅ Управление проектами с постоянным хранением
• ✅ Экспорт в несколько форматов (PLY, STL, OBJ, PCD)

Функциональность

GPU-ускорение (CUDA, опционально)

При сборке с -DASTRA_ENABLE_CUDA=ON и наличии NVIDIA GPU (CC 5.0+):

• VoxelGrid — децимация облака через Thrust sort_by_key + reduce_by_key
• NormalEstimation — оценка нормалей через cell-based PCA на GPU
• SOR — Statistical Outlier Removal через cell-based KNN
• ROR — Radius Outlier Removal через cell-based radius search
• NeuralTracker — инференс ONNX через CUDAExecutionProvider

При отсутствии GPU — автоматический fallback на CPU PCL.

📸 3D Сканирование

• Захват в реальном времени с RGB-D камеры (Astra Pro с OpenNI2)
• Режим эмуляции для тестирования без оборудования
• Контроль глубины (настраиваемые минимальные/максимальные расстояния)
• Пропуск кадров для оптимизации производительности
• Поток RGB/Глубины с живым предпросмотром

🔍 Отслеживание на основе маркеров

• Обнаружение CCTag - надежные круговые кодовые маркеры
• Карта маркеров для оценки позы объекта
• Отслеживание уникального ID (ID 0-99 на маркер)
• Устойчивость к перекрытию с субпиксельной точностью
• Режим поворотного стола для автоматического сканирования 360°

🧠 Отслеживание с нейронной сетью

• Модель ONNX для оценки позы
• Поддержка ускорения GPU (опционально)
• Обнаружение ключевых точек для идентификации маркеров
• Уточнение позы с помощью глубокого обучения

🧹 Обработка облачных точек

🏗️ Реконструкция поверхности

• Реконструкция поверхности Пуассона - создает замкнутые меш-сетки
• Оценка нормалей с настраиваемым радиусом поиска
• Ориентация нормалей на основе точки обзора
• Распространение BFS для согласованной ориентации
• Опция переворота нормалей для коррекции

🔗 Регистрация множественных сканов

• Регистрация ICP (Iterative Closest Point)
• Последовательное объединение с эталонным якорем
• Проверка сходимости с опцией пропуска
• Финальное упрощение вокселями для контроля размера

🎨 Постобработка меша

• Сглаживание (vtkSmoothPolyDataFilter) - снижает шум и неровности, уважает топологию меша
• Упрощение меша - уменьшает количество полигонов
• Заполнение отверстий - закрывает пробелы в меше
• Базовая постобработка меша для недеструктивного рабочего процесса

📂 Управление проектами

• Метаданные JSON для структуры проекта
• Хранение PLY для облачных точек
• Множественные сканы на проект
• Функция переименования/изменения порядка
• Сохранение/Загрузка полного состояния проекта

📤 Экспорт

Системные требования

Минимальное оборудование

• CPU: Intel Core i5 или аналог
• RAM: минимум 8 ГБ (рекомендуется 16+ ГБ)
• GPU: Выделенный GPU с OpenGL 3.2+ (для визуализации VTK)
• Хранилище: 50 ГБ свободного места

Поддерживаемая камера

• Orbbec Astra Pro (с OpenNI2 SDK)
• Режим эмуляции: Работает без камеры с использованием синтетических данных

Сборка из исходного кода

Предварительные требования

1. CMake 3.22 или выше
2. Visual Studio 2019/2022 с поддержкой C++
3. vcpkg менеджер пакетов
4. Python 3.8+ (для генерации маркеров)

Зависимости (через vcpkg)

# Установка зависимостей
vcpkg install cctag pcl vtk opencv4 qtbase --triplet x64-windows

Шаги сборки

1. Клонировать репозиторий

git clone https://gitverse.ru/klischa/AstraScanner2.git
cd AstraScanner2

1. Настроить с помощью CMake

cmake -S . -B build `
  -DCMAKE_TOOLCHAIN_FILE=C:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake

1. Собрать проект

cmake --build build --config Release

1. Запустить приложение

.\build\Release\AstraScanner.exe

Примечание: репозиторий называется AstraScanner2, а имя исполняемого файла в текущей конфигурации сборки — AstraScanner.exe.

Сборка с поддержкой OpenNI2

Для включения поддержки камеры Astra Pro:

cmake -S . -B build `
  -DCMAKE_TOOLCHAIN_FILE=C:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake `
  -DOPENNI2_ROOT="C:/orbbec/OpenNI_2.3.0.86_202210111950_4c8f5aa4_beta6_windows/Win64-Release/sdk"

cmake --build build --config Release

Автоматические задачи после сборки

Система сборки автоматически копирует:

• Плагины платформы Qt (platforms/)
• DLL-файлы runtime vcpkg
• DLL ONNX Runtime (onnxruntime.dll)
• OpenNI2 SDK (если включен)
• Модель ИИ (models/pose_regressor.onnx)
• Директория данных (data/)

Руководство по использованию

Первый запуск

1. Запустить приложение

.\build\Release\AstraScanner.exe

1. Создать новый проект
   • Файл → Новый проект
   • Выбрать директорию проекта
   • Ввести название проекта
2. Настроить сканер
   • Настройки → Параметры…
   • Установить диапазон глубины (например, 0.3-1.5 метра)
   • Настроить размер вокселя (0.005 = 5 мм)
   • Установить пропуск кадров для производительности

Рабочий процесс сканирования

Базовое сканирование

1. Нажмите кнопку “Сканировать” для начала
2. Двигайте объект или камеру
3. Нажмите “Стоп” при завершении
4. Предпросмотр результата в 3D просмотрере

Режим поворотного стола

Для сканирования 360° с вращающимся поворотным столом:

1. Включите флажок “Поворотный стол”
2. Установите количество сканов (например, 4 оборота)
3. Установите интервал между сканами (например, 5 секунд)
4. Нажмите “Сканировать” и дождитесь завершения

Отслеживание на основе маркеров

1. Распечатайте маркеры CCTag (см. Руководство по маркерам)
2. Закрепите маркеры на поворотном столе или объекте
3. Перейдите в Настройки → Параметры
4. Установите размер маркера и тип детектора
5. Используйте режим отслеживания “На основе маркеров”

Рабочий процесс обработки

1. Применить фильтры (Настройки → Параметры → Фильтры)
2. Реконструировать меш (вкладка Обработка → Poisson)
3. Объединить сканы, если существует несколько сканов
4. Сгладить/упростить меш по мере необходимости
5. Экспортировать в нужный формат

Рабочий процесс экспорта

1. Выберите скан из списка проекта
2. Нажмите кнопку “Экспорт”
3. Выберите формат (PLY/STL/OBJ/PCD)
4. Сохраните в нужное местоположение

Настройка камеры

Конфигурация Astra Pro

1. Установить OpenNI2 SDK
   • Скачать с сайта Orbbec
   • Установить с поддержкой драйвера
2. Настроить OpenNI2 в CMake

   -DOPENNI2_ROOT="C:/orbbec/OpenNI_2.3.0.86_202210111950_4c8f5aa4_beta6_windows/Win64-Release/sdk"
   

3. Проверить камеру
   • Приложение должно обнаружить Astra Pro
   • Зеленый индикатор статуса = камера активна
   • Если активируется режим эмуляции, проверьте установку драйвера

Режим эмуляции

Если камера не подключена, приложение автоматически переходит в режим эмуляции и генерирует синтетические тестовые кадры.

Руководство по маркерам (CCTag)

Что такое маркеры CCTag?

Маркеры CCTag (Circular Code Tag) - это круговые сигнальные маркеры с уникальными ID. Они обеспечивают:

• Уникальную идентификацию (IDs 0-99 на маркер)
• Надежное обнаружение при частичном перекрытии
• Субпиксельную точность для оценки позы
• Ориентацию по черному внешнему кольцу

Генерация маркеров

Предварительные требования

pip install svgwrite

Генерация сетки маркеров (A4)

# Маркеры с 3 кольцами (ID 0-29, 2 на ID)
cd markers
python generate_markers_grid.py --rings 3 --addId --generatePdf --generatePng

# Маркеры с 4 кольцами (ID 0-29, 2 на ID)
python generate_markers_grid.py --rings 4 --addId --generatePdf --generatePng

Генерация индивидуальных маркеров

# 100 маркеров с 3 кольцами
python generate.py --rings 3 --num 100 --outdir markers3 --margin 100 --addId

# 100 маркеров с 4 кольцами
python generate.py --rings 4 --num 100 --outdir markers4 --margin 100 --addId

Характеристики маркеров

Рекомендации по печати

1. Используйте матовую бумагу для снижения отражений
2. Высокое разрешение (минимум 300 DPI)
3. Проверьте размер перед резкой
4. Закрепите на неразъемной поверхности

Использование маркеров в приложении

1. Настроить параметры маркеров (Настройки → Параметры)
   • Размер маркера (например, диаметр 300 мм)
   • Тип детектора: CCTag
   • Количество колец: 3 или 4
   • Минимальная вероятность идентификации: 1e-6
2. Разместите маркеры на объекте или поворотном столе
3. Начните сканирование - маркеры будут автоматически обнаружены
4. Используйте отслеживание на основе маркеров для стабильной оценки позы

Файлы конфигурации маркеров

• Рабочая конфигурация приложения: data/marker_disk_config.json
• Пример конфигурации: marker_disk_config.example.json

Приложение читает именно файл из data/. Если вы меняете параметры диска или детекции, редактируйте этот файл.

Устранение неполадок

Приложение не запускается

Проблема: Отсутствуют DLL-файлы или папка platforms

Решение:

1. Пересобрать проект
2. Проверить, что build/Release/ содержит:
   • папку platforms/
   • файл onnxruntime.dll
   • все DLL-файлы vcpkg

Камера не обнаружена

Проблема: Активируется режим эмуляции вместо Astra Pro

Решения:

1. Проверить установку OpenNI2 SDK
2. Проверить путь OpenNI2 в конфигурации CMake
3. Убедиться, что драйверы Orbbec установлены
4. Проверить диспетчер устройств на наличие Astra Pro

Маркеры не обнаружены

Проблема: Детектор CCTag не находит маркеры

Решения:

1. Увеличить размер маркера (минимум 30 пикселей радиус)
2. Улучшить освещение
3. Использовать 4-кольцевые маркеры для лучшей надежности
4. Уменьшить расстояние до камеры
5. Проверить качество печати маркеров

Плохое качество сканирования

Проблема: Зашумленное или редкое облачное облако

Решения:

1. Уменьшить размер вокселя (например, 0.003 = 3 мм)
2. Настроить диапазон глубины ближе к объекту
3. Уменьшить пропуск кадров для большего количества кадров
4. Применить фильтры SOR/ROR после захвата
5. Убедиться в хорошем освещении объекта

Низкая производительность

Проблема: Низкий FPS или высокое использование CPU

Решения:

1. Увеличить пропуск кадров (например, 5-10)
2. Увеличить размер листа вокселя
3. Отключить цветную камеру, если не требуется
4. Использовать GPU для ONNX, если доступно
5. Закрыть другие приложения

Документация

Дополнительные ресурсы

• Встроенная справка в программе - меню Справка → Руководство по работе со сканером…, кнопка Справка для новичка на вкладке Главная и контекстные кнопки ? возле ключевых разделов интерфейса
• README-DEV.md - Руководство разработчика с командами сборки
• MARKERS.md - Полное руководство по маркерам
• TESTS.md - Документация по тестированию
• BUILD_BASELINE_AUDIT.md - Аудит текущей build/test baseline
• ARCHITECTURE_FILE_SPEC.md - Подробная спецификация по файлам и их связям
• MERMAID_ARCHITECTURE_DIAGRAMS.md - Mermaid-диаграммы архитектуры и детальный neural/ICP runtime path
• NEURAL_ICP_TUNING_GUIDE.md - Практическая настройка порогов neural + ICP confirm
• NEURAL_ICP_QUICK_REFERENCE.md - Короткая шпаргалка для оператора и тестировщика
• KNOWN_LIMITATIONS.md - Зафиксированные ограничения и ожидаемое поведение
• FIXES_REPORT.md - Отчёт по исправлениям кода (нейросетевой трекинг, CMake, mesh smoothing и др.)
• Документация CCTag - Документация библиотеки CCTag

Структура проекта

Файлы вида *REPORT.md и исторические .yaml-артефакты являются служебными/историческими материалами и не считаются основным источником актуальной документации по сборке и использованию.

AstraScanner2/
├── CMakeLists.txt
├── README.md
├── README-DEV.md
├── TESTS.md
├── MARKERS.md
├── KNOWN_LIMITATIONS.md
├── data/
├── models/
├── src/
│   ├── main.cpp
│   ├── gui/
│   ├── controllers/
│   ├── capture/
│   ├── calibration/
│   ├── filters/
│   ├── services/
│   ├── marker_tracker/
│   ├── tracking/
│   ├── project/
│   ├── export/
│   ├── settings/
│   └── models/
├── tests/
├── aiservice/
├── deploy/
└── markers/

Начиная с текущей архитектуры проект разделён на три уровня:

• binders — собирают крупные UI-блоки,
• controllers — управляют пользовательскими flow и асинхронным orchestration,
• services — реализуют прикладную обработку облаков, регистрацию и реконструкцию.

Ключевые классы

Разработка

Запуск тестов

# Настройка тестов
cmake -S . -B build_test `
  -DCMAKE_TOOLCHAIN_FILE=C:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake `
  -DAstraScanner_BUILD_TESTS=ON

# Сборка тестов
cmake --build build_test --config Release

# Запуск всех тестов
ctest -C Release -V

Добавление новых функций

1. Создать ветку функции
2. Реализовать в соответствующей поддиректории src/
3. Добавить юнит-тесты в tests/
4. Обновить документацию
5. Отправить pull request

Стиль кода

• Стандарт C++17
• Соглашения по коду Qt
• Комментарии Doxygen для публичных API
• Реализации, безопасные для потоков

Лицензия

MIT Лицензия - см. LICENSE.MD для подробной информации.

Благодарности

Зависимости

• Qt6 - Прикладной фреймворк
• OpenCV - Компьютерное зрение
• PCL - Библиотека облачных точек
• VTK - Инструмент визуализации
• ONNX Runtime - Инференс нейронных сетей
• CCTag - Обнаружение маркеров
• Eigen3 - Линейная алгебра
• vcpkg - Управление зависимостями

Авторы

• Команда AstraScanner
• Внесли вклад Klischa и другие

Список изменений

v1.1.0 (Текущая версия)

• GPU-ускорение (CUDA): VoxelGrid, NormalEstimation, SOR, ROR через Thrust
• Neural + ICP confirm: подтверждение нейросетевой позы итеративным ICP
• Surfel Coverage Tracker: оценка качества покрытия поверхности (угловое, стабильность)
• Quality Heatmap: визуализация качества сканирования в реальном времени
• Контекстная справка: встроенный HelpDialog с поиском по якорям
• Исправления: 30+ багов (потокобезопасность, падения, маркеры, CUDA, сборка)

v1.0.0

• Полная функциональность 3D сканирования
• Обнаружение и отслеживание маркеров CCTag
• Оценка позы с нейронной сетью
• Реконструкция поверхности Пуассона
• Регистрация ICP множественных сканов
• Система управления проектами
• Экспорт в PLY/STL/OBJ/PCD
• Комплексный набор фильтров
• Режим автоматизации поворотного стола