User Guide

Chapter 4 — Auxiliary Windows

Alongside the main window (3D viewport plus Inspector), RadianceKit manages three additional windows, all of which are opened via the Help menu. The menu has five entries, from top to bottom: User Guide (⌘?), Keyboard Shortcuts (⌘/), Open Training Logs… (⇧⌘L), Open Exports Folder…, Manage Storage…. The two "Open …" entries don't open an app window but the Finder; for this reason they aren't covered further here.

The three simple windows (User Guide, Keyboard Shortcuts, Manage Storage) and the two folder menu items (Open Training Logs / Open Exports Folder) each get a short entry per control.

At the end of the chapter there's a cross-reference section to the Inspector of the main window: what you can meaningfully read off the live loss chart and the Gaussian count display while a training run is in progress.

User Guide (W1–W4)

User Guide window with sidebar on the left and rendered Markdown content on the right
User Guide window with sidebar on the left and rendered Markdown content on the right

What it is: A built-in help window that renders the guide_<language>.md shipped with the app. The language is derived from Settings (General tab → Language) or, if that's set to "System", from the macOS language preferences. The layout is classic: a sidebar with all headings on the left, the body text on the right.

When you need a quick reminder about a single point — i.e. as a substitute for keywords. This manual is the detailed reference; the built-in help window is the short version for quick lookup. It gets updated with every app release, but is kept more superficial in content.

W1NavigationSplitView (Sidebar + Detail)

WHERE

Help → User Guide (⌘?).

TECHNICAL

Two-column layout with a narrow sidebar (at least 180 pt wide) for the content tree and a scrollable detail area for the actual Markdown content. The window has a minimum size of 700 × 500 pt. When first opened, the window loads the matching guide_<lang>.md from the app bundle (fallback guide_en.md), parses it into block records (headings H1–H4, paragraphs, lists, tables, dividers), and separately extracts the heading structure for the sidebar. Inline formatting (bold, italic, code span) is rendered via the built-in Markdown engine. The language is read from the app settings, with the special case of Chinese (zh-Hans) and Brazilian Portuguese (pt-BR), which are kept as full locale tags because these variants differ from plain zh and pt, respectively.

W2List (heading sidebar)

WHERE

Left column in the User Guide window.

TECHNICAL

List of all H2 and H3 headings in the current Markdown document. H2 entries appear without indentation with medium font weight, H3 entries with 16 pt left indentation and reduced foreground style. All other levels — H1 as well as H4 and deeper — do not appear in the sidebar, because they would otherwise make it cluttered. Anchor IDs are generated from the heading text via slugification (lowercase + spaces to dashes + filtering to letters/numbers/dashes — the same algorithm GitHub uses for its Markdown anchors, so external URLs to the docs could potentially land on the same anchor). The list uses the native macOS style.

W3Button (heading → anchor jump)

WHERE

One button per sidebar row.

TECHNICAL

Each sidebar entry is a button that sets the current anchor, but visually looks like a list entry. An observer variable then triggers the scroll jump to the corresponding anchor with a smooth animation over 0.3 s. After the jump, the anchor value is reset so that the next click on the same anchor fires again (otherwise the observer wouldn't trigger again, because the value hasn't changed).

W4ScrollView (detail content)

WHERE

Right column.

TECHNICAL

Scrollable, vertically stacking content area with lazy rendering, because longer guides can easily have more than 200 Markdown blocks — a non-lazy variant would instantiate all of them at once. Each block gets its own ID, either the heading anchor (which every heading gets, regardless of level) or an index placeholder. Maximum width is 720 pt, padding 32 horizontal / 24 vertical, so that long lines keep a well-readable layout. Tables are rendered cell by cell with horizontal stacks and divider lines; inline code by the built-in Markdown engine. Actual code blocks are currently treated as paragraphs — a known limitation of the help window.

Keyboard Shortcuts (W5–W6)

Keyboard Shortcuts window — five groups Navigation/Views/Capture/Editor/Training with hotkey column on the left and description on the right
Keyboard Shortcuts window — five groups Navigation/Views/Capture/Editor/Training with hotkey column on the left and description on the right

A static reference list in five sections. Navigation: Mouse Drag (Orbit/Fly), Shift+Drag/Right-Drag (Pan), Scroll (Zoom), WASD (Fly-Through movement), 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 (Jump to 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 mode), Click/Drag (Paint-Select), Option+Click (Deselect), X / Delete (Delete selection), Cmd-Z (Undo last deletion), [ / ] (Decrease/increase brush size), Esc (Clear selection). Training: Option+Space (Pause/resume training), Cmd+E (Export scene). That's all that's here — Start, Cancel and the extensions are reached via the Training menu (Chapter 1).

What it is: A simple static overview of all keyboard shortcuts — Navigation, Views, Capture, Editor, Training. The content is hard-coded and isn't loaded from a file.

When you're looking for the fastest way to do something in the viewport. WASD fly-through, R for camera reset, B for background cycling — they're all here.

W5ScrollView (content area)

WHERE

Help → Keyboard Shortcuts (⌘/).

TECHNICAL

A simple scroll area with a vertical list inside. Padding 20 all around, no sidebar navigation tree (the list is short enough). Content is grouped into five sections (Navigation, Views, Capture, Editor, Training). One row per key combination with translatable text in both columns. Left column (key code) fixed at 180 pt width, so the descriptions on the right stay vertically aligned. No interaction other than scrolling — clicking a row doesn't trigger anything, the keyboard shortcuts are real keyboard modifiers in the menu and on the viewport.

W6VStack (shortcut sections)

WHERE

Inside the ScrollView.

TECHNICAL

Left-aligned stacked sections with 16 pt spacing. Within each of the five sections: a heading followed by a sequence of rows. Headings use a secondary subheadline style — deliberately not a title format, because the sections don't need to be navigable. Content is deliberately flat (no disclosure, no search, no filter), so the component runs unchanged on every macOS version and the file stays readable.

Manage Storage (W7–W12)

Manage Storage window — header shows „1,356 items · 55.1 GB total”, table with export PLY files sorted by date, each with icon + filename + size + date
Manage Storage window — header shows „1,356 items · 55.1 GB total", table with export PLY files sorted by date, each with icon + filename + size + date

Table view of all files managed by RadianceKit. Header counts 1,356 items, 55.1 GB total size. Toolbar at top: "Show in Finder" + "Refresh". Each row: export icon, filename (e.g. training_20260718T194416Z.ply), export date, size (varies here from 7.8 MB to 2.24 GB), magnifying-glass icon (Reveal), and trash-can icon (Move to Trash). Sorting is first by category and within a category by date, newest at the top. In this screenshot PLY exports dominate, because this location was mainly used to back up training results.

What it is: A disk-usage overview for everything RadianceKit stores under ~/Documents/RadianceKit/ — logs, exports, scenes, capture bundles (from the iOS companion), imports (staging copies of the input images). Each entry has a size in bytes and two buttons: "Show in Finder" and "Move to Trash". This is NOT automatic cleanup — the app doesn't delete anything on its own; you decide per entry. This window is localised: in German it's called "Speicher verwalten", the two header buttons are called "Im Finder anzeigen" and "Aktualisieren", the row buttons "Im Finder anzeigen" and "In den Papierkorb legen". The English names in the entries below are the labels from the English version.

When your disk fills up. The logs in particular accumulate (one JSONL per training attempt, plus the _qualityMetrics.json); the exports of course too (PLY is 100% raw data, one per export). Also useful after a crash, when the imports staging directory still has old copies of the input images lying around.

W7Button "Show in Finder"

WHERE

Header at the top right of the storage browser window.

TECHNICAL

Opens the RadianceKit data folder in the Finder — exactly the directory whose contents this window lists. This lets you see the folder structure (Logs, Exports, Scenes, Captures, Imports) directly and also move or copy files using Finder itself. The action opens a new Finder window; the list in the window does not update as a result — that's what "Refresh" (W8) is for.

W8Button "Refresh"

WHERE

Header, next to the Finder button.

TECHNICAL

Triggers a background scan that runs on a user-initiated asynchronous task, so scanning large directory trees doesn't block the UI. The actual walk goes through every known subfolder (Logs, Exports, Scenes, Captures, Imports) and creates a storage entry for each direct child. For each entry the recursive size is determined — preferring the actual disk usage (including APFS hard-link sharing) with a fallback to the logical file size.

W9List (storage entries)

WHERE

Main content below the header.

TECHNICAL

List with this layout per row: category- specific SF Symbol icon (document for logs, upload arrow for exports, cube for scenes, iPhone for capture bundles, tray for imports), name + subtitle (kind label + formatted modification date), byte counter on the right (right-aligned, monospaced), Reveal button (magnifying-glass symbol), Trash button (trash can). Sorting: primarily by kind (scenes first, then exports, logs, captures, imports, other), secondarily by modification date descending (newest at top). While the scan is still running, a "Scanning…" progress indicator is shown instead. If nothing was found, an empty-state display with a tray icon appears.

W10Row button "Reveal in Finder"

WHERE

Per row, magnifying-glass symbol on the right.

TECHNICAL

Opens the Finder and selects the specific item (file or folder). Difference from W7: W7 opens the root directory; W10 selects exactly this one entry. Handy workflow: identify a large entry, click the magnifying glass, then copy it to, say, an external volume.

W11Row button "Move to Trash"

WHERE

Per row, trash icon to the right of the magnifying glass.

TECHNICAL

Triggers the confirmation dialog box (W12). Only after confirmation does the standard macOS "move to trash" operation run (i.e. reversible, not a direct delete). After successfully moving to trash, the entry is removed from the list and the total byte counter updates. On errors, a modal error dialog is shown.

W12ConfirmationDialog (delete confirmation)

WHERE

Triggered by W11, presented as a macOS sheet.

TECHNICAL

Standard confirmation dialog with a dynamic title "Delete <name>?" and a message line that explicitly points out that the entry will end up in the trash and can be restored from there (until the trash is emptied). Two buttons: "Move to Trash" as a destructive action (shown in red) and "Cancel" with an automatic Esc binding. The dialog is non-modal in the sense that it only blocks this window, not the whole app — that's the macOS standard for reversible deletions.

Main Window: Loss History and Gaussian Count (I39–I41, Cross-Reference)

Three of the Inspector displays in the main window deserve their own explanation, because they are visible constantly during a running training run and because there are important rules of thumb for when the curve looks healthy. The displays sit in the Inspector in the Progress section, in the expandable group Loss History (see chapter 2 — Inspector), and help you read the training progress.

When is the loss curve healthy? A healthy loss curve shows three phases: (1) Warmup — during the first 200–500 iterations, the loss drops steeply from high (typically 0.15–0.25 for combined L1+SSIM, depending on the scene) to roughly half that. If the loss does NOT drop in this phase, the input is usually wrong (broken images, bad SfM poses, too few initial Gaussians). (2) Densification — between ~500 and densifyUntilIteration (classic 15K, MCMC up to 20K or 25K), the loss keeps falling, often with small downward jumps when densify operations insert new Gaussians and the optimizer makes use of them. The Gaussian count rises during this phase. (3) Refinement — after that, the loss runs into a flattening tail. Typical final values for orientation: a well-lit object scene (such as Tanks-&-Temples Truck with P4 Quality) lands at L1 ≈ 0.023, while expansive outdoor scenes like those from Mip-NeRF 360 naturally stay above that (0.04–0.07).

What does a plateau mean? A plateau (the loss curve runs horizontally over several thousand iterations) has two interpretations: (a) the model has converged, further training won't achieve anything more — that's the good case. (b) the model is stuck (local minimum, poor gradient information, a cap at the buffer limit) — the bad case. Both look identical on the chart. To tell them apart: look at the Gaussian count. If it's also flat AND close to the MCMC cap (e.g. 150K of 150K with the preset P8 Quality (MCMC)), you're at the limit — either raise the cap or accept the plateau. If the Gaussian count is still growing but the loss isn't dropping, that's stuck.

When to stop vs. keep training? Rule of thumb: 10K iterations with no improvement in the min loss → stop, further iterations are wasted. Before that: via the Training menu → Continue Training → "+5,000 iterations" you can still append an extension if you're seeing marginal improvement (there's no keyboard shortcut for this). Note: with MCMC, the plateau is often genuine — the cap is the natural limit.

A Gaussian count plateau is NOT a "done" signal. It only means that MCMC has reached its cap or that Classic Densification has been exhausted. The real "done" question is only answered by PSNR/SSIM/LPIPS on an independent test set. The independent test set also shows whether your camera set allows for a fair split into training and test viewpoints.

PSNR/holdout is the truth, loss is just a proxy. The loss is a relative metric: it drops as your model adapts to the training views. A low loss, however, doesn't automatically mean a good model — if the model has memorized the training images (overfitting), the loss would be small, but the PSNR on unseen views (holdout) would be poor. Therefore: for the final quality assessment, always look at the holdout metrics, not at the end loss alone.

Rule-of-Thumb Box

- User Guide and Keyboard Shortcuts are static help — fast for keyword questions, use this manual for depth. - Open Manage Storage as soon as the disk drops below 10% free space. Logs and imports staging are the usual culprits. - Loss plateau and Gaussian-count plateau must be interpreted separately. Cap limit is not a "done" signal. Real quality is only measured by holdout PSNR. - 10K iterations without min-loss improvement → stop training.