/
klischa
/
AstraScanner2
Обзор
Документация
Войти
/
klischa
/
AstraScanner2
Код
Запросы
0
Задачи
Вики
Пакеты
0
Релизы
0
CI/CD
Аналитика
Безопасность
master
help/SCANNER_USER_GUIDE.html
399 строк
30 KB
klischa
docs: обновление документации до v1.1.0
19 июн 2026, 22:59
19 июн 2026, 22:59
7956be3
Код
Авторство
О чём код?
<!DOCTYPE html> <html lang="ru"> <head> <meta charset="UTF-8" /> <title>Справка по работе со сканером — AstraScanner2</title> <style> body { font-family: "Segoe UI", Arial, sans-serif; margin: 18px 22px; color: #1f2733; line-height: 1.58; background: #ffffff; } h1, h2, h3 { color: #17375e; } h1 { margin-top: 0; } h2 { margin-top: 28px; padding-bottom: 6px; border-bottom: 1px solid #d7e0ea; } h3 { margin-top: 22px; } .lead { background: #f4f8fc; border: 1px solid #d7e5f2; border-radius: 8px; padding: 12px 14px; } .tip { background: #eef8ef; border-left: 4px solid #4da167; padding: 10px 12px; margin: 12px 0; } .warn { background: #fff6e7; border-left: 4px solid #d7962d; padding: 10px 12px; margin: 12px 0; } code { background: #f1f4f7; padding: 1px 5px; border-radius: 4px; font-family: Consolas, monospace; } table { border-collapse: collapse; width: 100%; margin: 12px 0 18px; font-size: 14px; } th, td { border: 1px solid #d8e0e8; padding: 9px 10px; vertical-align: top; text-align: left; } th { background: #eef4fb; color: #1d3557; } ul, ol { padding-left: 22px; } .toc a { text-decoration: none; color: #2457a6; } .toc li { margin: 6px 0; } </style> </head> <body> <h1 id="quickstart">Справка по работе со сканером AstraScanner2 <span style="font-size:16px;color:#888;">v1.1.0</span></h1> <div class="lead"> Это встроенное руководство объясняет, <b>с чего начинать</b>, <b>что делает каждая вкладка</b>, <b>как применять основные настройки</b> и <b>в каком порядке работать со сканером</b>. Документ рассчитан в первую очередь на новичка: если вы открыли программу впервые, начинайте с раздела <b>«Быстрый старт»</b>. </div> <h2>Оглавление</h2> <ol class="toc"> <li><a href="#quickstart">Быстрый старт</a></li> <li><a href="#project-prep">Проект и подготовка</a></li> <li><a href="#home-tab">Что находится на вкладке «Главная»</a></li> <li><a href="#calibration">Как работает калибровка</a></li> <li><a href="#scan-tab">Как пользоваться вкладкой «Сканирование»</a></li> <li><a href="#tracking-modes">Режимы трекинга: ICP, маркеры, нейросеть</a></li> <li><a href="#processing">Как пользоваться вкладкой «Обработка»</a></li> <li><a href="#settings">Объяснение настроек</a></li> <li><a href="#neural-icp">Neural + ICP confirm: что это и когда менять</a></li> <li><a href="#recipes">Готовые сценарии работы</a></li> <li><a href="#troubleshooting">Типовые проблемы и решения</a></li> </ol> <h2 id="project-prep">Быстрый старт: что делать по шагам</h2> <ol> <li><b>Создайте или откройте проект.</b> Проект нужен для сохранения сканов, поз, объединённых облаков и мешей.</li> <li><b>Проверьте камеру.</b> На вкладке «Главная» должны быть понятны статус камеры, интринсики и статус калибровки.</li> <li><b>При необходимости выполните калибровку.</b> Если калибровки нет или вы не уверены в её качестве, соберите 5–12 кадров шахматной доски и выполните калибровку.</li> <li><b>Перейдите на вкладку «Сканирование».</b> Выберите режим трекинга, запустите <code>Preview</code>, затем <code>Scan</code>.</li> <li><b>После захвата перейдите на вкладку «Обработка».</b> Сначала очистите облако, затем при необходимости объедините сканы, постройте меш и выполните постобработку.</li> <li><b>Сохраните результат в проект и экспортируйте его.</b></li> </ol> <div class="tip"> Самый безопасный порядок действий почти всегда такой: <b>Проект → Калибровка → Preview → Scan → Очистка → Merge (если нужно) → Poisson → Экспорт</b>. </div> <h2 id="home-tab">Вкладка «Главная»</h2> <p>Главная вкладка — это стартовый экран перед сканированием.</p> <h3>Блок «Проект»</h3> <table> <tr><th>Элемент</th><th>Что делает</th><th>Когда использовать</th></tr> <tr><td><b>Новый проект</b></td><td>Создаёт новый проект в выбранной папке.</td><td>Перед новой сессией сканирования.</td></tr> <tr><td><b>Открыть проект</b></td><td>Открывает уже существующий проект.</td><td>Когда нужно продолжить старую работу.</td></tr> <tr><td><b>Сохранить</b></td><td>Сохраняет изменения в открытом проекте.</td><td>После изменения сканов, поз, порядка или результата обработки.</td></tr> <tr><td><b>Сохранить как</b></td><td>Сохраняет проект в новую папку/новое место.</td><td>Для дубля проекта или новой версии.</td></tr> <tr><td><b>Перейти к сканированию</b></td><td>Открывает вкладку «Сканирование».</td><td>После подготовки проекта и калибровки.</td></tr> </table> <h3>Блок «Проверка камеры»</h3> <ul> <li><b>Камера</b> — показывает, обнаружено ли устройство.</li> <li><b>Интринсики</b> — показывает, доступны ли параметры камеры.</li> <li><b>Калибровка</b> — показывает, загружен ли файл калибровки.</li> </ul> <h3>Блок «Отображение preview»</h3> <table> <tr><th>Настройка</th><th>Что делает</th><th>Практический смысл</th></tr> <tr><td><b>Цветовая карта глубины</b></td><td>Меняет визуализацию depth preview.</td><td>Не влияет на сами данные; влияет только на удобство просмотра.</td></tr> <tr><td><b>Диапазон</b></td><td>Задает видимый и полезный диапазон расстояний.</td><td>Помогает исключить слишком близкие или дальние точки.</td></tr> <tr><td><b>Сглаживание глубины</b></td><td>Визуально/логически смягчает шум depth-данных.</td><td>Полезно при шумной картинке, но не заменяет дальнейшую очистку облака.</td></tr> <tr><td><b>Инвертировать цвета</b></td><td>Меняет цветовую подачу preview.</td><td>Используется только для удобства оператора.</td></tr> </table> <h3>Блок «Калибровка»</h3> <p>На Главной вкладке дублируется базовый workflow калибровки:</p> <ul> <li><b>Preview</b> — запускает предварительный просмотр RGB-кадра.</li> <li><b>Захватить кадр</b> — добавляет текущий кадр в набор для калибровки.</li> <li><b>Калибровать</b> — запускает вычисление параметров камеры.</li> <li><b>Сброс</b> — очищает собранные кадры и состояние текущей калибровочной сессии.</li> </ul> <h2 id="calibration">Как работает калибровка</h2> <p>Калибровка строится по серии кадров шахматной доски.</p> <ol> <li>Положите или удерживайте шахматную доску перед камерой.</li> <li>Запустите <code>Preview</code>.</li> <li>Сделайте 5–12 кадров под разными углами и на разной дистанции.</li> <li>Нажмите <code>Калибровать</code>.</li> </ol> <div class="warn"> Если все кадры сняты почти с одного ракурса, калибровка может формально завершиться, но её качество будет низким. Для хорошего результата меняйте угол, наклон и положение доски. </div> <table> <tr><th>Поле</th><th>Что означает</th></tr> <tr><td><b>Кадров: X / 12</b></td><td>Сколько полезных кадров уже собрано. Обычно калибровку имеет смысл запускать после 5 и более кадров.</td></tr> <tr><td><b>Статус</b></td><td>Показывает, найден ли паттерн, выполнена ли калибровка и есть ли предупреждения по качеству.</td></tr> </table> <h2 id="scan-tab">Вкладка «Сканирование»</h2> <p>Это главный рабочий экран live-захвата.</p> <table> <tr><th>Элемент</th><th>Что делает</th></tr> <tr><td><b>Preview</b></td><td>Запускает просмотр камеры без полноценного накопления облака.</td></tr> <tr><td><b>Scan</b></td><td>Запускает захват и накопление облака.</td></tr> <tr><td><b>Pause</b></td><td>Приостанавливает/возобновляет активное сканирование.</td></tr> <tr><td><b>Stop</b></td><td>Останавливает захват и завершает сессию.</td></tr> <tr><td><b>Clear</b></td><td>Очищает текущее облако и окно просмотра.</td></tr> <tr><td><a name="quality-mode"></a><b>3D / Quality / RGB / Depth</b></td><td>Переключает большую область просмотра между обычной 3D-сценой, surfel-based Quality heatmap, RGB и картой глубины.</td></tr> <tr><td><b>Distance</b></td><td>Показывает оценку текущего расстояния до объекта по центральной точке depth-кадра.</td></tr> <tr><td><b>Поза</b></td><td>Показывает текущую оценку положения сканера/объекта.</td></tr> </table> <div class="tip"> В режиме <b>Quality</b> облако окрашивается по локальной уверенности покрытия поверхности. Красный означает слабое покрытие, жёлтый — промежуточное, зелёный — уверенное. Строка <code>Coverage: X% good / Y% medium / Z% weak</code> показывает агрегированную статистику по surfel-based coverage tracker. </div> <h3 id="turntable-mode">Режим «Поворотный стол»</h3> <table> <tr><th>Настройка</th><th>Что делает</th></tr> <tr><td><b>Вкл.</b></td><td>Включает периодическое сохранение сканов по таймеру.</td></tr> <tr><td><b>Режим: Отдельные</b></td><td>Каждый шаг поворотного стола сохраняется как отдельный скан проекта.</td></tr> <tr><td><b>Режим: Накопление</b></td><td>Шаги накапливаются в одно облако; удобно для одного итогового результата.</td></tr> <tr><td><b>Интервал</b></td><td>Через сколько секунд выполняется следующий шаг.</td></tr> <tr><td><b>Сканов</b></td><td>Сколько шагов выполнить перед остановкой.</td></tr> </table> <h2 id="tracking-modes">Режимы трекинга</h2> <h3>ICP</h3> <p>Использует геометрическое выравнивание облаков. Подходит, если между кадрами достаточно overlap и облако уже относительно чистое.</p> <h3>Маркеры</h3> <p>Использует маркеры (в первую очередь CCTag) для устойчивой оценки позы. Подходит для контролируемых сценариев и поворотного стола.</p> <h3>Нейросетевой</h3> <p>Использует ONNX-модель для оценки относительной позы по двум облакам. Для надёжности её результат дополнительно проверяется через guard'ы и ICP confirm/refinement.</p> <div class="tip"> Если вы новичок и у вас есть подготовленный диск с маркерами, чаще всего проще начать с <b>режима маркеров</b>. Если маркеров нет — попробуйте <b>ICP</b>. Нейросетевой режим полезен, но чувствителен к качеству реальных облаков. </div> <h2 id="processing">Вкладка «Обработка»</h2> <p>Вкладка разделена на большой viewer и панель инструментов. Работайте по следующему порядку:</p> <ol> <li>Очистка облака</li> <li>Подготовка объекта</li> <li>Регистрация сканов (если их несколько)</li> <li>Реконструкция поверхности</li> <li>Постобработка меша</li> </ol> <h3 id="cloud-cleanup">1. Очистка облака</h3> <table> <tr><th>Инструмент</th><th>Что делает</th><th>Когда применять</th></tr> <tr><td><b>SOR</b></td><td>Удаляет статистические выбросы по локальному окружению точки.</td><td>Когда облако «шумит» случайными точками.</td></tr> <tr><td><b>ROR</b></td><td>Удаляет точки, у которых мало соседей в заданном радиусе.</td><td>Когда вокруг объекта много одиночных шумовых точек.</td></tr> <tr><td><b>Воксель</b></td><td>Упрощает облако, объединяя близкие точки в воксельную сетку.</td><td>Когда облако слишком плотное и тяжёлое.</td></tr> <tr><td><b>Magic Wand</b></td><td>Быстрая комбинированная очистка.</td><td>Когда нужен быстрый старт без тонкой ручной настройки.</td></tr> </table> <h3 id="object-prep">2. Подготовка объекта</h3> <table> <tr><th>Инструмент</th><th>Что делает</th></tr> <tr><td><b>Удалить фон</b></td><td>Ищет и удаляет крупную плоскую поверхность (например, стол).</td></tr> <tr><td><b>Выделить объект</b></td><td>Пытается выделить основной кластер/объект через region growing.</td></tr> </table> <h3 id="icp-merge">3. Регистрация сканов (ICP)</h3> <p>Используется, когда проект содержит несколько отдельных сканов одного объекта.</p> <ul> <li><b>Max correspondence distance</b> — насколько далеко ICP ищет соответствия между облаками.</li> <li><b>Iterations</b> — сколько итераций разрешено ICP.</li> <li><b>Финальный воксель</b> — дополнительная децимация результата после объединения.</li> <li><b>Пропускать несошедшиеся</b> — безопаснее при плохих данных: скан не будет насильно добавлен в merge.</li> </ul> <h3 id="poisson">4. Реконструкция поверхности (Poisson)</h3> <table> <tr><th>Параметр</th><th>Что означает</th><th>Как интерпретировать</th></tr> <tr><td><b>Depth</b></td><td>Глубина октодерева.</td><td>Больше = больше деталей, но выше время и память.</td></tr> <tr><td><b>Point weight</b></td><td>Насколько реконструкция должна следовать исходным точкам.</td><td>Больше = ближе к данным, но может усилить шум.</td></tr> <tr><td><b>Samples/node</b></td><td>Число точек на лист дерева.</td><td>Помогает бороться с шумом и дырками.</td></tr> <tr><td><b>Normal radius / k ближайших</b></td><td>Как оцениваются нормали.</td><td>Критично для качества Poisson.</td></tr> </table> <h3 id="mesh-post">5. Постобработка меша</h3> <table> <tr><th>Инструмент</th><th>Что делает</th></tr> <tr><td><b>Сгладить меш</b></td><td>Смягчает неровности и шум на поверхности.</td></tr> <tr><td><b>Упростить меш</b></td><td>Уменьшает число полигонов для более лёгкого результата.</td></tr> <tr><td><b>Закрыть дыры</b></td><td>Пытается зашить небольшие отверстия в поверхности.</td></tr> </table> <h2 id="settings">Настройки: что означают основные параметры</h2> <h3>Сканирование</h3> <table> <tr><th>Параметр</th><th>Что делает</th><th>Когда увеличивать / уменьшать</th></tr> <tr><td><b>Scan timeout</b></td><td>Максимальная длительность одной сессии сканирования.</td><td>Увеличивайте для долгих сканов, уменьшайте для дисциплины оператора.</td></tr> <tr><td><a name="voxel-leaf-size"></a><b>Voxel leaf size</b></td><td>Размер ячейки вокселизации.</td><td>Больше = быстрее и грубее, меньше = детальнее и тяжелее.</td></tr> <tr><td><a name="frame-skip"></a><b>Frame skip</b></td><td>Добавлять в накопление каждый N-й кадр.</td><td>Больше = меньше точек и выше скорость; меньше = плотнее результат.</td></tr> <tr><td><b>Depth min / max</b></td><td>Минимальная и максимальная полезная дистанция.</td><td>Сужайте диапазон вокруг реального объекта для более чистого облака.</td></tr> </table> <h3>Фильтры</h3> <table> <tr><th>Параметр</th><th>Смысл</th></tr> <tr><td><b>SOR meanK</b></td><td>Сколько соседей учитывать при статистической оценке.</td></tr> <tr><td><b>SOR stddev</b></td><td>Насколько строго считать точку выбросом.</td></tr> <tr><td><b>ROR radius</b></td><td>Радиус поиска соседей.</td></tr> <tr><td><b>ROR min neighbors</b></td><td>Минимум соседей в радиусе для сохранения точки.</td></tr> </table> <h3 id="icp-settings">ICP</h3> <table> <tr><th>Параметр</th><th>Смысл</th></tr> <tr><td><a name="icp-max-correspondence"></a><b>Max correspondence distance</b></td><td>Порог поиска соответствий между облаками.</td></tr> <tr><td><b>Max iterations</b></td><td>Число шагов ICP.</td></tr> <tr><td><b>Skip non-converged</b></td><td>Не добавлять сканы, если ICP не сошёлся.</td></tr> <tr><td><b>Voxel output</b></td><td>Финальная децимация после мержа.</td></tr> </table> <h3 id="poisson-settings">Poisson</h3> <table> <tr><th>Параметр</th><th>Смысл</th></tr> <tr><td><a name="poisson-depth"></a><b>Depth</b></td><td>Уровень детализации реконструкции.</td></tr> <tr><td><a name="poisson-point-weight"></a><b>Point weight</b></td><td>Насколько сильно меш привязывается к исходным точкам.</td></tr> <tr><td><b>Samples per node</b></td><td>Баланс между детализацией и устойчивостью к шуму.</td></tr> <tr><td><a name="poisson-normal-radius"></a><b>Normal radius / k nearest</b></td><td>Способ оценки нормалей.</td></tr> </table> <h3>Трекинг и маркеры</h3> <table> <tr><th>Параметр</th><th>Что делает</th></tr> <tr><td><b>Размер маркера</b></td><td>Физический размер используемого маркера.</td></tr> <tr><td><b>Мин. маркеров для инициализации</b></td><td>Сколько маркеров нужно, чтобы построить начальную карту.</td></tr> <tr><td><b>Detector type</b></td><td>Выбор между Circular и CCTag.</td></tr> <tr><td><b>Show markers</b></td><td>Показывать ли детектированные маркеры на RGB preview.</td></tr> <tr><td><b>Use CUDA for neural</b></td><td>Пытаться ли использовать GPU для ONNX Runtime.</td></tr> </table> <h2 id="neural-icp">Neural + ICP confirm</h2> <p>В нейросетевом режиме модель сначала предлагает позу, а затем она дополнительно проверяется и уточняется коротким ICP.</p> <table> <tr><th>Параметр</th><th>Что делает</th><th>Как понимать</th></tr> <tr><td><b>Enable ICP confirm</b></td><td>Включает подтверждение neural pose через ICP.</td><td>Для реальных данных обычно лучше держать включённым.</td></tr> <tr><td><b>ICP max correspondence distance</b></td><td>Порог поиска соответствий для confirm-stage.</td><td>Если слишком мало — ICP не сойдётся; если слишком много — может принять плохие соответствия.</td></tr> <tr><td><b>ICP max iterations</b></td><td>Число итераций ICP confirm.</td><td>Слишком мало — не успеет дойти до решения; слишком много — лишнее время и риск подстройки под шум.</td></tr> <tr><td><a name="neural-icp-fitness"></a><b>ICP max fitness</b></td><td>Максимально допустимая ошибка ICP после сходимости.</td><td>Меньше = строже, больше = мягче.</td></tr> <tr><td><a name="neural-icp-correction-translation"></a><b>Max correction translation</b></td><td>Насколько ICP может поправить neural pose по трансляции.</td><td>Если ICP исправляет сильнее — исходная neural pose считается подозрительной.</td></tr> <tr><td><a name="neural-icp-correction-rotation"></a><b>Max correction rotation</b></td><td>Насколько ICP может довернуть neural pose.</td><td>Полезно как защита от sim-to-real ошибок модели.</td></tr> </table> <div class="tip"> Если вы не знаете, какие значения поставить, начните со сбалансированного профиля из документа <code>NEURAL_ICP_TUNING_GUIDE.md</code>: <b>0.03 / 20 / 0.0025 / 0.03 / 6°</b>. </div> <h2 id="gpu">GPU-ускорение (CUDA)</h2> <p>При сборке с флагом <code>-DASTRA_ENABLE_CUDA=ON</code> и наличии NVIDIA GPU (Compute Capability 5.0+) следующие операции автоматически выполняются на GPU:</p> <table> <tr><th>Операция</th><th>Как ускоряется</th><th>CPU fallback</th></tr> <tr><td><b>VoxelGrid</b></td><td>Thrust <code>sort_by_key</code> + <code>reduce_by_key</code></td><td><code>pcl::VoxelGrid</code></td></tr> <tr><td><b>NormalEstimation</b></td><td>Cell-based PCA на GPU (3×3×3 окрестность)</td><td><code>pcl::NormalEstimation</code></td></tr> <tr><td><b>SOR</b></td><td>Cell-based KNN + mean/stddev filter</td><td><code>pcl::StatisticalOutlierRemoval</code></td></tr> <tr><td><b>ROR</b></td><td>Cell-based radius search + count filter</td><td><code>pcl::RadiusOutlierRemoval</code></td></tr> <tr><td><b>NeuralTracker</b></td><td><code>CUDAExecutionProvider</code> (ONNX)</td><td>ONNX CPU</td></tr> </table> <div class="tip"> <b>Как проверить, что GPU работает:</b> при запуске в логах появится строка <code>[CUDA] Initialised — device: NVIDIA GeForce RTX 3060 …</code> (или название вашей видеокарты). Если GPU недоступен, будет <code>[CUDA] No capable device detected, falling back to CPU</code>. Программа всегда работает — с GPU или без. </div> <div class="tip"> Для сборки с CUDA требуется: CUDA Toolkit 12.x, Thrust (в составе CUDA), совместимый драйвер NVIDIA. Подробнее — в файле <code>GPU_IMPLEMENTATION_PLAN.md</code>. </div> <h2 id="recipes">Готовые сценарии работы</h2> <h3>Сценарий 1: Один объект, один скан</h3> <ol> <li>Создать проект.</li> <li>При необходимости выполнить калибровку.</li> <li>На вкладке «Сканирование» запустить Preview, затем Scan.</li> <li>Остановить захват.</li> <li>На вкладке «Обработка» очистить облако.</li> <li>При необходимости сразу строить меш через Poisson.</li> </ol> <h3>Сценарий 2: Несколько сканов одного объекта</h3> <ol> <li>Сохранить каждый скан в проект.</li> <li>Перейти на вкладку «Обработка».</li> <li>В блоке ICP объединить все сканы проекта.</li> <li>Сохранить merge-результат в проект.</li> <li>После этого строить меш.</li> </ol> <h3>Сценарий 3: Поворотный стол</h3> <ol> <li>Открыть проект.</li> <li>Включить режим поворотного стола на вкладке «Сканирование».</li> <li>Выбрать режим: отдельные или накопление.</li> <li>Установить интервал и число сканов.</li> <li>Запустить Scan и дождаться завершения всех шагов.</li> </ol> <h2 id="troubleshooting">Типовые проблемы и решения</h2> <table> <tr><th>Проблема</th><th>Что проверить первым делом</th></tr> <tr><td>Облако слишком шумное</td><td>Сузьте диапазон depth, увеличьте SOR/ROR, попробуйте Magic Wand.</td></tr> <tr><td>Маркерный трекинг нестабилен</td><td>Проверьте освещение, размер маркера, тип детектора и число видимых маркеров.</td></tr> <tr><td>Нейросетевой трекинг часто отклоняется</td><td>Смотрите причины reject в логах и таблицы в quick reference / tuning guide.</td></tr> <tr><td>ICP merge даёт плохой результат</td><td>Проверьте overlap между сканами, max correspondence distance и качество исходных облаков.</td></tr> <tr><td>Poisson не строит меш</td><td>Очистите облако, проверьте плотность данных, попробуйте уменьшить шум и настроить нормали.</td></tr> <tr><td>Меш выглядит «вывернутым»</td><td>Попробуйте flip normals или согласованную ориентацию нормалей.</td></tr> <tr><td>Ничего не сохраняется в проект</td><td>Убедитесь, что проект открыт и путь записи доступен.</td></tr> </table> <div class="warn"> Если сомневаетесь, не меняйте много параметров сразу. Лучше изменить <b>один параметр</b>, сделать короткий прогон и посмотреть, стало ли лучше. </div> </body> </html>