Руководство по GUI анализа изображений и CV pipeline

1. Что делает CV GUI

CV GUI помогает находить области на изображении, выделять маски и контуры, распознавать текст, объединять несколько шагов обработки и превращать результат в каноническую разметку проекта. Конкретные типы задач и кандидатов определяет выбранный режим программы.

• Простой режим: выбрать один метод и настроить несколько параметров.
• Линейный pipeline: собрать цепочку шагов один за другим.
• Расширенный pipeline: собрать граф из методов, ветвлений, merge и runtime-inspector.

2. Базовый сценарий работы

1. Откройте изображение или выберите элемент/ROI на холсте.
2. Откройте панель CV/AI и выберите режим обработки.
3. Включите live preview для быстрых итераций или оставьте ручной Apply для тяжёлых методов.
4. Проверьте preview и overlay на холсте.
5. Выберите нужную границу: сохранить технический run, прикрепить mask/result к image series элемента или явно создать canonical elements.

Практический совет: если вы не уверены, с чего начать, сначала ограничьте область интереса (ROI), а уже потом запускайте цветовую или сегментационную обработку. Это быстрее и обычно даёт меньше шума.

Несколько представлений одного проекта

Кнопка раскладки в панели меню может показать одну область A, две области A/B слева–справа или сверху–снизу, три области с A слева и B/C справа либо сетку A/B/C/D 2×2. Это не копии проекта: каноническая разметка, selection и project undo/redo у областей общие, а visual material и pane-local display settings могут быть разными.

• В настройках каждой области можно изменить название, выбрать Source, рабочий CV-result, mask или diagnostic artifact, способ показа и crop source.
• Кнопка Активировать задаёт область для Canvas tools и, по умолчанию, источник пикселей ROI. Запрос активации stale, unmapped или read-only presentation отклоняется; если уже активная область стала несовместимой, owner возвращается к A.
• Linked panes синхронизируют zoom, центр viewport и canvas-курсор. A всегда является участником связанной группы; B/C/D можно отвязать. Read-only область может быть источником навигации, не становясь владельцем project interaction.
• Поле Источник вырезки явно выбирает текущий instance или исходный Source.
• Mask, diff/composite, display-only transform и stale/unmapped result не являются допустимым ROI input. Операция блокируется вместо скрытого возврата к Source.
• Область A нельзя закрыть. B/C/D закрываются явно без удаления presentation; меньшая раскладка не удаляет их скрыто. Общий Reset назначает Source области A, активирует её, закрывает остальные области и возвращает single layout.

Варианты отображения Результат, Градации серого, Инверсия и Псевдоцвет меняют только визуализацию, а не material или recipe. Для сравнения оставьте Source в соседней связанной области.

Предобработка полного изображения

1. Откройте Source или существующее рабочее представление в нужной области.
2. Нажмите Настроить CV; для Source будет создано рабочее processed_raster представление.
3. В Анализ изображения → Обработка представления выберите метод или linear pipeline и нажмите Обновить представление.

У каждого рабочего представления собственные параметры. В его каталоге всегда действует Всё изображение; методы, которым нужны ROI, click, timeline, reference image или побочное изменение проекта, туда не включаются.

3. Основные части панели

• Режим обработки: выбор метода или pipeline.
• Параметры метода: динамическая форма с настройками выбранного метода.
• Предпросмотр: показывает, что именно вернул метод или pipeline.
• Overlay: накладывает маску и контуры на холст, чтобы вы сравнивали результат с исходным изображением.
• Preset-ы: сохраняют удачные наборы параметров.
• Сохранение результатов: отдельные действия для runtime archive, image series выбранного элемента и canonical markup.
• Live preview / Auto / AI: Рисовка на лету пересчитывает результат при изменении параметров; 🔮 Авто подбирает параметры по изображению; AI выбор разрешает LLM предложить алгоритм. Для больших кадров и model-backed методов лучше использовать ручное Обновить превью.
• Сессия и действия: Применить запускает анализ и в основной панели обычно прикрепляет/заменяет cv_result в image series выбранного элемента; Сохранить пишет технический run в именованную CV-сессию; Добавить как элементы создаёт canonical elements, а Добавить маску в результаты добавляет отдельную mask entry.
• Пипетка HSV: берёт цвет из preview и заполняет H/S/V с допусками dH/dS/dV.

Text / OCR использует локальный Tesseract из ocr.runtime. YOLO, три SAM backend и OmniParser требуют отдельно готового ml.runtime и подходящих local model assets. Наличие пункта в списке методов означает доступность интерфейса, а не готовность runtime или уже загруженные веса. См. управление моделями и весами.

Кнопка настроек LLM открывает профиль роли CV. Model-backed и OCR-методы требуют соответствующих runtime-компонентов. LLM-подключения · Зависимости

4. Жизненный цикл CV-результата

CV candidate, canonical markup и FeatureMatch

CV method сначала выдаёт result/evidence: preview, detections, contours, mask и metrics. Это ещё не объект Selector. Review связывает candidate с markup_candidate_id и создаёт accepted decision; затем готовятся patch и apply preview. Только явный apply после проверки target, revision и отсутствия дублей меняет canonical project.

Проверка candidate и создание FeatureMatch — разные операции: первая продвигает evidence в canonical markup, вторая фиксирует конкретное найденное occurrence уже существующего feature. Это также разные записи project JSON и разные undo/redo mutations.

Verified bundle хранит source snapshot при его наличии, execution recipe, config snapshot, metrics, standard/extra outputs, SHA-256/size metadata, coordinate contracts и write report. Manifest публикуется только после успешной записи и readback всех обязательных ссылок.

Именованная CV-сессия — runtime archive в ScrephData/screen_selector/cv/results, а не второй project format. Список recent sessions содержит не более десяти ID, но это не retention файлов: автоматической очистки старых session directories здесь нет. При сохранении canonical project Selector импортирует только CV entries, прикреплённые к element image series, копирует их artifacts в <name>_artifacts и создаёт project-local result manifest. Неприкреплённый технический archive в package не попадает.

Как CV artifacts входят в project package →

5. Video CV и temporal tracking

Workspace Video CV анализирует последовательность кадров Capture с durable source/timeline identity. Можно обработать выделенный диапазон, текущий clip, весь timeline, окно из 11 кадров вокруг playhead или live stream; направление задаётся отдельно. Pre-roll и post-roll расширяют offline-границы, шаг кадров прореживает вход, а масштаб 100/75/50/25% уменьшает нагрузку с нормализацией результата обратно в координаты источника.

• Analysis ROI и exclusion areas привязаны к selection context. Если selection изменился, запуск блокируется до обновления контекста — старая ROI не применяется молча.
• Live reader имеет очередь на четыре кадра и явную политику backpressure: reject, drop oldest или drop newest. Stop/cancel закрывает reader; gaps в offline sequence диагностируются и сбрасывают temporal processor.
• Overlay разделён на motion, tracks, accepted markup, detections, optical flow, events и candidates. История запусков позволяет восстановить параметры, повторить run и перейти к проблеме.

Temporal providers

Встроенный registry включает UAV Sparse Camera Stabilization, OpenCV MOG2 Motion, MIL/CSRT/KCF trackers, Farneback Optical Flow, Activity Events, Native Scene Difference и conditional PySceneDetect Content. Недоступный provider выключается с причиной и repair action: CSRT/KCF требуют подходящий opencv-contrib, PySceneDetect — свою dependency. SAM 2.1 Prompt Mask Propagation сейчас является недоступным internal target будущего isolated worker, а не обычным рабочим backend.

Run, track apply и редактирование

1. Запустите provider и дождитесь completed, partial, cancelled или failed. Snapshot входа, config, provenance, coverage, issues и observations сохраняются в temporal run store.
2. Для tracker-run выберите track и подготовьте apply preview. План показывает observations/keyframes/lost states и ожидаемую revision, сохраняя manual/protected observations существующего track.
3. Подтвердите apply. Проект должен быть заранее сохранён или открыт: операция пишет Selector-owned sidecar <project>.temporal-markup.json с revision guard и project undo/redo.

После применения доступны manual keyframe из текущей ROI, удаление keyframe, trim/terminate, split, состояния occluded/outside, undo/redo, безопасный merge без неоднозначных пересечений, смена track ID и retrack от manual keyframe. Это явная prepare/apply граница temporal markup, а не автоматическое принятие всех observations.

Экспорт активного run

• Neutral JSON содержит run/provider/status, hashes, coverage, provenance, config, observations и optional codegen IR из сохранённого recipe. Это данные, не исполняемый скрипт.
• Annotated preview создаёт MJPG AVI по текущим полям start/end и timeline mapping, рисуя track и motion bounding boxes. Нужны положительный Capture FPS, каждый запрошенный кадр и рабочий OpenCV VideoWriter.

Оба экспорта являются artifacts выбранного run, а не dataset export и не project save. Файлы и границы temporal data →

6. Фактический каталог методов

В основной панели зарегистрировано 28 пользовательских одиночных методов. Это реальные пункты выбора, а не число уникальных математических алгоритмов: например, MobileSAM, FastSAM и EfficientSAM — три backend одного семейства promptable segmentation.

• Фильтры и цвет: Edges (Canny), Color (HSV), Color Mask (K-Means).
• Сегментация и маски: GrabCut, Watershed, SLIC Superpixels, YOLO segmentation, MobileSAM, FastSAM, EfficientSAM.
• Текст и структура: Text / OCR, OmniParser, Hough Lines, Hough Circles, MSER, Connected Components, Contours, Adaptive Threshold.
• GUI, reference и temporal: Template Match, Point Region Grow, Shape Analyze, Line/Rect Layout, Feature Match, Before/After Diff, Align To Reference, Target Track (KLT), UI Layout (Local), Visual ReID.

Для linear pipeline и method-flow graph дополнительно зарегистрировано 14 служебных узлов: Grayscale, Brightness/Contrast, Gamma, Gaussian Blur, Median Blur, CLAHE, Resize, Crop/Pad, Rotate, Deskew, Apply Mask to Image, Invert Mask, Morphology и Extract Contours. Они нужны для построения потока данных и поэтому не дублируются в списке одиночных методов.

Что меняет режим программы

• General: 28 общих методов и 14 pipeline-узлов образуют нейтральный image-analysis каталог.
• GUI Automation: использует общие CV-возможности и добавляет GUI-типы, markup refs, review draft и promotion patch. Это semantic/authoring layer, а не ещё 42 отдельных метода.
• Industrial / UAV: имеют собственные pipeline-операции, но их каталоги смешивают CV, preprocessing, orchestration, decisions и export nodes. Эти workspace экспериментальны, поэтому число зарегистрированных шагов не следует читать как число production-ready алгоритмов.

7. Линейный pipeline

Линейный pipeline удобен, когда вам нужен предсказуемый поток без ветвлений: например, сначала выделить границы, потом очистить маску, потом извлечь контуры. Он проще для быстрого старта и легче переносится между проектами.

• Каждый шаг исполняется сверху вниз.
• Вы редактируете параметры одного шага за раз.
• Панель preview шагов помогает понять, на каком этапе появился шум или потерялся объект.
• Если цепочка остаётся линейной, её легко поддерживать и потом переносить в advanced mode.

8. Расширенный pipeline: подробное руководство

Расширенный pipeline предназначен для сложных сценариев, где обычной линейной цепочки уже недостаточно. Он позволяет строить полноценный граф обработки: использовать несколько веток, объединять результаты, держать отдельный preview-выход и смотреть runtime-трассу по шагам.

Когда переходить в расширенный режим

• Нужно сравнить две разные ветки обработки одной и той же картинки.
• Нужно выбрать один из вариантов по условию.
• Нужно отдельно управлять результатом и предпросмотром.
• Нужен runtime inspector, чтобы видеть payload каждого узла и каждой связи.

Важно: расширенный режим экспериментальный. Пока у него свой draft-состояние, а линейный pipeline остаётся основным форматом, пока вы явно не примените обратно exportable graph.

Структура экрана advanced pipeline

• Верхняя панель действий: быстрые операции вроде Quick Add, Snippets, Auto Layout, Repair Graph, Apply to Linear.
• Холст графа: основная рабочая область с узлами, связями, комментариями и группами.
• Правая колонка инспекторов: сведения о выбранном объекте, payload, pinned inspector и selection preview.
• Runtime debug область: история выполнения, scrubber по шагам, diff, pinned runtime step и preview истории.
• Validation / Search / Recommendations: быстрый переход к проблемам, поиск по графу и рекомендации по исправлению.

Типы узлов

• Source: входное изображение, point prompt, константы.
• Method: реальные CV-методы: edge detection, segmentation, OCR, contour extraction и т.д.
• Control: условные узлы и merge для выбора или объединения веток.
• Utility: технические узлы вроде reroute, чтобы сделать граф чище.
• Sink: финальные точки вывода результата и preview.

В типичном графе всегда присутствуют как минимум Input Image и Result Output. Они задают начало и явную конечную точку потока. Если в графе несколько веток и нет явного result output, runtime может посчитать конфигурацию неоднозначной.

Как собирать граф на практике

1. Откройте вкладку Advanced рядом с линейным редактором.
2. Добавьте узлы через Quick Add или кнопку Add Node.
3. Соединяйте порты перетаскиванием от выхода к совместимому входу.
4. Если граф разрастается, используйте reroute и comment/group frames.
5. Для сложного ветвления вставляйте If и Merge узлы.
6. После изменений проверяйте validation panel и summary справа.

Рекомендуемый стартовый паттерн: `Input Image -> один-два method nodes -> Result Output`. Сначала убедитесь, что этот скелет работает, и только потом добавляйте ветвление, merge и отдельный preview sink.

Редактирование и навигация

• Delete удаляет выбранные узлы, связи или группы.
• F2 переименовывает выбранный узел.
• Ctrl+D дублирует выделение.
• Tab или Space открывают Quick Add.
• A запускает auto layout.
• Ctrl+0 подгоняет масштаб под граф.

Runtime inspector: как читать выполнение графа

После запуска обработки расширенный pipeline сохраняет runtime-снимок. Он показывает не только итоговую картинку, но и то, что происходило в каждом узле: какие входы были доступны, что узел вернул, какая ветка условия была выбрана, и где появился warning или error.

• Runtime scrubber: переход между полным видом и отдельными runtime-шагами.
• Current / Pinned step: удобно сравнивать два состояния графа или две ветки выполнения.
• Selection preview: показывает preview именно выбранного узла или связи.
• Payload inspector: помогает понять, какой тип данных идёт по связи: image, mask, contours, detections, text.

Горячие клавиши runtime: `Alt+Home` — к началу трассы, `Alt+Left/Right` — шаг назад/вперёд, `Alt+End` — полный вид.

Draft, синхронизация и применение к линейному pipeline

У advanced mode есть собственное состояние редактирования. Пока граф содержит ветвления, utility/control узлы или другие нелинейные конструкции, он может оставаться только advanced draft. Если же конфигурация остаётся linearly exportable, вы можете нажать Apply to Linear и вернуть её в обычный линейный pipeline.

• Resync from Linear перезагружает граф из текущего линейного pipeline.
• Apply to Linear записывает graph обратно в линейный формат, если это возможно.
• Repair Graph предлагает безопасные исправления, если структура неполная или сломана.

9. Советы по производительности

• Для тяжёлых графов выключайте live preview и запускайте Apply вручную.
• Ограничивайте ROI перед сложной обработкой, если не нужен весь экран.
• Используйте reroute и comment frames, чтобы не превращать граф в трудно читаемую “паутину”.
• После крупных перестроений делайте Auto Layout и проверяйте validation summary.

10. Частые проблемы и что делать

• Preview пустой: проверьте, что граф заканчивается в Result Output или Preview sink и что у узлов есть совместимые входы.
• Граф не применяется к linear: обычно причина в ветвлении, merge, utility/control nodes или другом нелинейном фрагменте.
• Слишком много шума: уменьшите ROI, добавьте фильтрацию маски или разбейте задачу на несколько шагов вместо одного универсального метода.
• Результат нестабилен между кадрами: зафиксируйте область, уменьшите количество веток и проверяйте runtime trace по шагам, а не только итоговый preview.