Руководство

Глава 4 — Вспомогательные окна

Помимо главного окна (3D-Viewport и Inspector), RadianceKit управляет тремя дополнительными окнами, которые все открываются через меню Help. Меню содержит пять пунктов, сверху вниз: User Guide (⌘?), Keyboard Shortcuts (⌘/), Open Training Logs… (⇧⌘L), Open Exports Folder… и Manage Storage…. Оба пункта «Open …» открывают не окно приложения, а Finder; поэтому они здесь подробно не рассматриваются.

Три простых окна (User Guide, Keyboard Shortcuts, Manage Storage) и оба пункта меню, связанных с папками (Open Training Logs / Open Exports Folder), получают по короткой записи на каждый элемент управления.

В конце главы приведён раздел с перекрёстными ссылками на Inspector главного окна: что можно осмысленно считать с графика Live-Loss-Chart и с индикатора Gaussian-Count во время выполняющегося обучения.

Руководство пользователя (W1–W4)

Окно руководства пользователя с боковой панелью слева и отрендеренным Markdown-содержимым справа
Окно руководства пользователя с боковой панелью слева и отрендеренным Markdown-содержимым справа

Что это: Встроенное окно справки, отображающее файл guide_<sprache>.md, поставляемый вместе с приложением. Язык определяется из настроек (вкладка General → Language) или, если там указано «System», из языковых настроек macOS. Раскладка классическая: слева боковая панель со всеми заголовками, справа основной текст.

Когда тебе нужно быстро освежить в памяти отдельный момент — то есть как замену шпаргалке. Подробным справочником служит этот Manual; встроенное окно справки — это краткая версия для быстрого поиска. Оно обновляется с каждым релизом приложения, но по содержанию остаётся более поверхностным.

W1NavigationSplitView (боковая панель + детали)

ГДЕ

Help → User Guide (⌘?).

ТЕХНИЧЕСКИ

Двухколоночная раскладка с узкой боковой панелью (минимум 180 pt шириной) для дерева содержимого и прокручиваемой области деталей для собственно Markdown-содержимого. Окно имеет минимальный размер 700 × 500 pt. При первом открытии окно загружает подходящий guide_<lang>.md из App-Bundle (fallback guide_en.md), парсит его в блок-записи (заголовки H1–H4, абзацы, списки, таблицы, разделительные линии) и отдельно извлекает структуру заголовков для боковой панели. Инлайн-форматирование (жирный, курсив, code-span) рендерится встроенным Markdown-движком. Язык считывается из настроек приложения, со специальным случаем китайского (zh-Hans) и бразильского португальского (pt-BR), которые сохраняются как полные locale-теги, потому что эти варианты отличаются от zh и pt соответственно.

W2List (боковая панель заголовков)

ГДЕ

Левая колонка в окне User Guide.

ТЕХНИЧЕСКИ

Список всех заголовков H2 и H3 текущего Markdown-документа. Записи H2 отображаются без отступа с средней жирностью шрифта, записи H3 — с отступом 16 pt слева и приглушённым стилем переднего плана. Все остальные уровни — как H1, так и H4 и ниже — не появляются в боковой панели, поскольку иначе они сделали бы её неудобной для восприятия. Anchor-ID генерируются из текста заголовка через слагификацию (lowercase + пробелы в тире + фильтрация по буквам/цифрам/тире — тот же алгоритм, который GitHub использует для своих Markdown-якорей, так что и внешние URL к документации потенциально попадали бы на тот же якорь). Список использует нативный стиль macOS.

W3Button (переход заголовок → якорь)

ГДЕ

По кнопке на каждую строку боковой панели.

ТЕХНИЧЕСКИ

Каждая запись боковой панели — это кнопка, которая устанавливает текущий якорь, но визуально выглядит как элемент списка. Переменная-наблюдатель затем запускает прокрутку к соответствующему якорю с плавной анимацией продолжительностью 0,3 с. После перехода значение якоря сбрасывается, чтобы следующий клик на тот же якорь снова сработал (иначе наблюдатель не сработал бы повторно, поскольку значение не изменилось).

W4ScrollView (содержимое деталей)

ГДЕ

Правая колонка.

ТЕХНИЧЕСКИ

Прокручиваемая, вертикально складывающаяся область содержимого с ленивым рендерингом, поскольку более длинные руководства легко могут содержать свыше 200 Markdown-блоков — нелениый вариант создавал бы все блоки одновременно. Каждый блок получает собственный ID: либо якорь заголовка (его получает каждый заголовок, независимо от уровня), либо индекс-заглушку. Максимальная ширина — 720 pt, отступы 32 по горизонтали / 24 по вертикали, так что длинные строки сохраняют удобочитаемую раскладку. Таблицы рендерятся ячейка за ячейкой с помощью горизонтальных стеков и разделительных линий; инлайн-код — встроенным Markdown-движком. Настоящие блоки кода в данный момент обрабатываются как параграф — известное ограничение окна справки.

Клавиатурные сокращения (W5–W6)

Окно Keyboard Shortcuts — пять групп Navigation/Views/Capture/Editor/Training со столбцом горячих клавиш слева и описанием справа
Окно Keyboard Shortcuts — пять групп Navigation/Views/Capture/Editor/Training со столбцом горячих клавиш слева и описанием справа

Статический справочный список в пяти секциях. Navigation: Mouse Drag (Orbit/Fly), Shift+Drag/Right-Drag (Pan), Scroll (Zoom), WASD (движение в режиме Fly-Through), Q/E (Up/Down), F (Toggle Orbit/Fly), Double-click (Re-center), Cmd+Scroll (FoV-Adjust). Views: R (Reset Camera), T (Auto-Rotation), P (Camera Playback), B (Background-Cycle), 0–9 (переход к Training-Cam 1=10%/5=50%/0=last), Left/Right Arrow (Prev/Next Cam). Capture: S (Screenshot to Desktop), V (Turntable-Video), C (Copy Camera Info). Editor: Tab (Edit-Modus), Click/Drag (Paint-Select), Option+Click (Deselect), X / Delete (удалить выделение), Cmd-Z (отменить последнее удаление), [ / ] (уменьшить/увеличить размер кисти), Esc (снять выделение). Training: Option+Space (пауза/продолжение обучения), Cmd+E (экспортировать сцену). Больше здесь ничего нет — запуск, отмену и продления ты найдёшь в меню Training (глава 1).

Что это такое: Простой статический обзор всех сочетаний клавиш — Navigation, Views, Capture, Editor, Training. Содержимое встроено жёстко и не подгружается из файла.

Когда ты ищешь самый быстрый способ сделать что-то во Viewport. WASD-Fly-Through, R для сброса камеры, B для переключения фона — всё это здесь.

W5ScrollView (область содержимого)

ГДЕ

Help → Keyboard Shortcuts (⌘/).

ТЕХНИЧЕСКИ

Простая область прокрутки с вертикальным списком внутри. Padding 20 по периметру, без дерева навигации в боковой панели (список достаточно короткий). Содержимое сгруппировано в пять секций (Navigation, Views, Capture, Editor, Training). На каждую комбинацию клавиш — строка с переводимым текстом в обеих колонках. Левая колонка (код клавиши) зафиксирована на ширине 180 pt, чтобы описания справа оставались выровненными по вертикали. Никакого взаимодействия, кроме прокрутки — клик по строке ничего не запускает, сочетания клавиш — это настоящие клавиатурные модификаторы в меню и во Viewport.

W6VStack (секции сокращений)

ГДЕ

Внутри ScrollView.

ТЕХНИЧЕСКИ

Секции сложены по левому краю с отступом 16 pt. Внутри каждой из пяти секций — заголовок и последовательность строк. Заголовки используют вторичный стиль Subheadline — намеренно не формат Title, поскольку секции не должны быть навигируемыми. Содержимое намеренно плоское (без Disclosure, без Search, без Filter), чтобы компонент работал без изменений на любой версии macOS, а файл оставался читаемым.

Управление хранилищем (W7–W12)

Окно Manage Storage — заголовок показывает „1,356 items · 55.1 GB total”, таблица с экспортированными PLY-файлами, отсортированными по дате, для каждого — иконка + имя файла + размер + дата
Окно Manage Storage — заголовок показывает „1,356 items · 55.1 GB total", таблица с экспортированными PLY-файлами, отсортированными по дате, для каждого — иконка + имя файла + размер + дата

Табличное представление всех файлов, которыми управляет RadianceKit. Заголовок насчитывает 1356 элементов, 55,1 ГБ общего размера. Панель инструментов сверху: „Show in Finder" + „Refresh". Каждая строка: иконка экспорта, имя файла (например, training_20260718T194416Z.ply), дата экспорта, размер (здесь варьируется от 7,8 МБ до 2,24 ГБ), иконка-лупа (Reveal) и иконка корзины (Move to Trash). Сортировка сначала по категории, а внутри категории по дате, новейшие сверху. На этом снимке доминируют PLY-экспорты, потому что в этом хранилище прежде всего сохранялись результаты обучения.

Что это: Обзор использования диска для всего, что RadianceKit сохраняет в ~/Documents/RadianceKit/ — логи, экспорты, сцены, пакеты захвата (от iOS-компаньона), импорты (промежуточные копии входных изображений). У каждой записи размер в байтах и две кнопки: „показать в Finder" и „переместить в корзину". Это НЕ автоматическая очистка — само приложение ничего не удаляет; ты решаешь по каждой записи отдельно. Это окно локализовано: по-русски оно называется «Управление хранилищем», обе кнопки в заголовке называются «Показать в Finder» и «Обновить», кнопки в строках — «Показать в Finder» и «Переместить в корзину». Английские названия в записях ниже — это обозначения из английской версии.

Когда диск заполняется. Прежде всего накапливаются логи (один JSONL-файл на каждую попытку обучения, плюс _qualityMetrics.json); экспорты, конечно, тоже (PLY — 100% необработанные данные, один файл на экспорт). Также полезно после сбоя, когда в промежуточном каталоге импортов ещё лежат старые копии входных изображений.

W7Кнопка „Show in Finder"

ГДЕ

Заголовок сверху справа в окне обозревателя хранилища.

ТЕХНИЧЕСКИ

Открывает папку данных RadianceKit в Finder — именно тот каталог, содержимое которого перечислено в этом окне. Так ты сразу видишь структуру папок (Logs, Exports, Scenes, Captures, Imports) и можешь перемещать или копировать файлы прямо в Finder самостоятельно. Действие открывает новое окно Finder; список в этом окне при этом не обновляется — для этого есть „Refresh" (W8).

W8Кнопка „Refresh"

ГДЕ

Заголовок, рядом с кнопкой Finder.

ТЕХНИЧЕСКИ

Запускает фоновое сканирование, которое выполняется как инициированная пользователем асинхронная задача, чтобы сканирование больших деревьев каталогов не блокировало интерфейс. Само сканирование проходит по каждой известной подпапке (Logs, Exports, Scenes, Captures, Imports) и создаёт запись хранилища для каждого прямого дочернего элемента. Для каждой записи вычисляется рекурсивный размер — предпочтительно фактический объём, занятый на диске (включая совместное использование APFS-хардлинков), с резервным вариантом — логическим размером файла.

W9Список (записи хранилища)

ГДЕ

Основное содержимое под заголовком.

ТЕХНИЧЕСКИ

Список со следующим макетом для каждой строки: специфичная для категории иконка SF Symbols (документ для Logs, стрелка загрузки для Exports, куб для Scenes, iPhone для пакетов захвата, лоток для Imports), имя + подзаголовок (метка типа + отформатированная дата изменения), счётчик байтов справа (выровнен по правому краю, моноширинный шрифт), кнопка Reveal (значок лупы), кнопка Trash (значок корзины). Сортировка: сначала по типу (сначала Scenes, затем Exports, Logs, Captures, Imports, Other), затем по дате изменения по убыванию (новейшие сверху). Пока сканирование ещё выполняется, на этом месте отображается индикатор прогресса „Scanning…". Если ничего не найдено, отображается пустое состояние со значком лотка.

W10Кнопка строки „Reveal in Finder"

ГДЕ

В каждой строке, значок лупы справа.

ТЕХНИЧЕСКИ

Открывает Finder и выделяет конкретный элемент (файл или папку). Отличие от W7: W7 открывает корневой каталог; W10 выделяет именно эту одну запись. Практичный рабочий процесс: определи крупную запись, кликни на лупу, затем скопируй её, например, на внешний том.

W11Кнопка строки „Move to Trash"

ГДЕ

В каждой строке, значок корзины справа рядом с лупой.

ТЕХНИЧЕСКИ

Запускает диалог подтверждения (W12). Только после подтверждения выполняется стандартная операция macOS «переместить в корзину» (то есть обратимая, без прямого удаления). После успешного перемещения в корзину запись удаляется из списка, а счётчик общего размера в байтах обновляется. При ошибках отображается модальный диалог с ошибкой.

W12ConfirmationDialog (подтверждение удаления)

ГДЕ

Вызывается W11, отображается как sheet macOS.

ТЕХНИЧЕСКИ

Стандартный диалог подтверждения с динамическим заголовком „Delete <name>?" и строкой сообщения, которая явно указывает, что запись попадёт в корзину и может быть восстановлена оттуда (пока корзина не очищена). Две кнопки: „Move to Trash" как деструктивное действие (отображается красным) и „Cancel" с автоматической привязкой к Esc. Диалог является немодальным в том смысле, что блокирует только это окно, а не всё приложение — это стандарт macOS для обратимых удалений.

Главное окно: история потерь и количество гауссианов (I39–I41, перекрёстная ссылка)

Три индикатора Inspector в главном окне заслуживают отдельного объяснения, потому что они постоянно видны во время выполняющегося обучения, и существуют важные практические правила о том, когда график выглядит здоровым. Индикаторы расположены в Inspector в разделе Fortschritt, в раскрывающейся группе Verlustverlauf (см. главу 2 — Inspector) и помогают оценивать прогресс обучения.

Когда кривая Loss здорова? Здоровая кривая Loss показывает три фазы: (1) Warmup — в первые 200–500 итераций Loss резко падает с высокого уровня (обычно 0.15–0.25 для комбинации L1+SSIM, в зависимости от сцены) примерно до половины. Если Loss на этой фазе НЕ падает, значит, обычно неверны входные данные (испорченные изображения, плохие позы SfM, слишком малое количество начальных гауссианов). (2) Densification — между ~500 и densifyUntilIteration (классически 15K, MCMC до 20K или 25K) Loss продолжает падать, часто с небольшими скачками вниз, когда операции Densify добавляют новые гауссианы, а оптимизатор их использует. Количество гауссианов на этой фазе растёт. (3) Refinement — после этого Loss переходит в постепенно выполаживающийся хвост. Типичные конечные значения для ориентира: хорошо освещённая сцена с объектом (например, Tanks-&-Temples Truck с P4 Quality) достигает L1 ≈ 0.023, обширные внешние сцены вроде тех, что в Mip-NeRF 360, закономерно остаются выше (0.04–0.07).

Что означает плато? Плато (кривая Loss идёт горизонтально на протяжении нескольких тысяч итераций) имеет две интерпретации: (a) модель сошлась, дальнейшее обучение уже ничего не даёт — это хороший случай. (b) модель застряла (локальный минимум, плохая информация о градиенте, упор в лимит буфера) — плохой случай. Оба варианта выглядят на графике одинаково. Различить их можно так: посмотри на количество гауссианов. Если оно тоже плоское И близко к пределу MCMC (например, 150K из 150K при пресете P8 Quality (MCMC)), значит, ты упёрся в лимит — либо повысь Cap, либо прими плато как есть. Если количество гауссианов ещё растёт, а Loss не падает, значит, это застревание.

Когда прерывать, а когда продолжать обучение? Практическое правило: если за 10K итераций минимальный Loss не улучшился → прерывай, дальнейшие итерации потрачены впустую. До этого момента: через меню Training → Continue Training → «+5,000 iterations» ты можешь добавить продление, если видишь пограничное улучшение (для этого нет сочетания клавиш). Внимание: при MCMC плато часто настоящее — Cap является естественной границей.

Плато количества гауссианов — это НЕ сигнал «готово». Оно означает лишь, что MCMC достиг Cap или что Classic Densification исчерпал себя. На настоящий вопрос «готово ли» отвечают только PSNR/SSIM/LPIPS на независимом тестовом наборе. Независимый тестовый набор также показывает, допускает ли твой набор камер честное разделение на обучающие и тестовые ракурсы.

PSNR/Holdout — это истина, Loss — лишь приближение. Loss является относительной метрикой: он падает по мере того, как твоя модель подстраивается под обучающие виды (Views). Но низкий Loss не означает автоматически хорошую модель — если модель заучила обучающие изображения наизусть (переобучение, Overfitting), Loss был бы низким, но PSNR на невиданных видах (Holdout) была бы плохой. Поэтому: для итоговой оценки качества всегда смотри на метрики Holdout, а не только на конечный Loss.

Блок эмпирических правил

- User Guide и Keyboard Shortcuts — это статичная справка: удобны для быстрых вопросов по ключевым словам, а для глубокого понимания используй именно это руководство. - Открывай Manage Storage, как только на диске остаётся меньше 10% свободного места. Логи и Imports-Staging — обычные виновники. - Плато функции потерь (Loss-Plateau) и плато числа гауссианов (Gaussian-Count-Plateau) нужно интерпретировать раздельно. Достижение лимита (Cap-Limit) не означает сигнал «готово». Реальное качество измеряется только через Holdout-PSNR. - Если за 10K итераций нет улучшения минимальной потери → останови обучение.