Chapter 10 — Beginner Mode

WHERE

In the bar at the top edge of the window, to the left of the mode switcher. Only visible in Beginner Mode.

TECHNICAL

Shows the six stages of the pipeline as a chain of buttons lined up in a row, each with an icon and name, separated by an arrow character: Import → Frame Quality → Cameras → Training → Preview → Export. The current stage is fully colored, already completed stages are semi-transparent, stages not yet reached are gray. Already completed stages are clickable and jump back; the current stage and all stages not yet reached are disabled, as is the entire chain while processing is running. There is no longer a continuous percentage progress bar across the entire pipeline — the progress of the running stage is shown by the large circle on the processing screen (C-19).

WHERE

Left side of the Import step, large dashed rectangle with icon. Shown in Beginner Mode with the label "Drop photos or a video here".

TECHNICAL

Drop area that makes the icon briefly bounce and colors the background as soon as drag items hover over the field. Accepts JPG, PNG, TIFF, HEIC, MP4, MOV, PLY, SPZ, .splat, .radiancescene bundles, and directories. Drop routing by type: images are collected and passed on sorted, videos trigger the frame-sampling path, splat files open the preview directly, and scene bundles are parsed. Directories are enumerated and all contained images are imported. Security-scoped bookmarks for sandbox-compliant access are correctly acquired and released. Unsupported extensions are shown as a warning banner for 5 seconds.

WHERE

Inside the drop zone, prominent button.

TECHNICAL

Button that opens the macOS file dialog with multi-selection and the file types JPG, PNG, TIFF, MP4, MOV, folders, as well as the app's own scene format. Result URLs are security-scoped and are routed through the same import paths as drag and drop. If the user selects a folder, it is recursively enumerated for images.

WHERE

Inside the drop zone, only visible if the app bundle contains the sample scene and no images/splats have been imported yet.

TECHNICAL

Only appears if (a) a sample-scene.splat, .spz or .ply is present in the app bundle AND (b) no images/videos have been imported yet and no point cloud exists yet. When clicked, it loads the finished point cloud (preferring the smallest format — .splat ~3 MB, .spz ~1.4 MB, fallback .ply) and after 400 ms sets hardcoded camera values from the original metadata of the flower scene for an aesthetically pleasing initial perspective.

WHERE

Inside the drop zone, next to "Try Sample Scene"; same visibility conditions.

TECHNICAL

Downloads a sample set provided by RadianceKit from the internet: approximately 427 MB of 960 full-resolution frames, which are then unpacked and imported directly into the app. While another process is running, the button is disabled and the download does not start. Download progress is not shown in the interface as a percentage; you can tell the download is finished by the fact that the image list on the right fills up with the 960 frames.

WHERE

Floating bottom toolbar of the Import overlay, to the left of the Start button.

TECHNICAL

Menu picker with the label "Quality" that groups the bundled presets into four sections by category: "Classic", "MCMC (fewer Gaussians, slower)", "Hybrid (sharp detail, compact)" and "Capture — curated real-world (Drone / 360° / Photo)". A fifth section, "Custom", is added once the full version has been unlocked and at least one custom preset has been saved. Locked state: all presets except Quick and Preview get a "🔒" suffix on the name if the user doesn't own the full version; selecting one snaps the picker back to Preview and automatically opens the purchase window. Choosing a preset applies it, replacing the entire training configuration.

WHERE

Floating bottom toolbar of the Import overlay, to the right of the preset picker.

TECHNICAL

Button that stays gray as long as neither images nor a video have been imported. Clicking it starts the pipeline and switches the stage machine into the sequence Frame Quality → SfM → Training. The button itself has no further status; a running process instead appears as a separate processing screen.

WHERE

Right-hand image list, visible only if a video (instead of images) was imported.

TECHNICAL

Slider from 0.5 fps to 30 fps in steps of 0.5. When changed, the frame density is updated and additionally the number of target frames (at least 10) is calculated from density and video length. The slider sits outside the image list because list items would block mouse events from sliders. Below the slider are the calculated target frames ("247 frames") and the video length ("1m23s video"). Tooltip warns: "Doubling the density doubles the number of frames and increases SfM time by ~100%."

WHERE

Right-hand image list, bottom right; visible only if images have been imported.

TECHNICAL

Red button. Clicking opens a confirmation dialog with the title "Clear all imported files?" and the message "N images will be removed.". Confirming clears all imported images/videos, staging directories, the point cloud, the training status, the SfM result, and all caches; the stage jumps back to Import. On Cancel, everything is preserved. The dialog is configured as a non-destructive default path (destructive button marked red).

WHERE

Right-hand image list, each entry.

TECHNICAL

List of the imported images with swipe-to-delete. Each image gets a row with an icon, file name, resolution ("1920 × 1080"), and file size (formatted KB/MB). Resolution comes from a metadata cache that is filled asynchronously from the image headers so the interface doesn't block. Removal happens via the macOS-typical swipe-delete (trackpad swipe to the left on a row); the list has no row selection, so there is no keyboard delete here. Note: The extended image-delete path with an explicit minus button, backspace, and Cmd-Z to undo was only added in Expert Mode in the Project Navigator — in Beginner Mode it remains swipe-delete only.

WHERE

Below the image list, above the Clear All button.

TECHNICAL

Three consecutive thresholds based on the number of imported images (only active if images are present and there's no video): - < 3 images: red banner (red octagon), text "At least 3 images are required. Camera alignment cannot be computed from fewer images." - 3–9 images: red banner, text "With fewer than 10 images, SfM often fails and the trained scene tends to overfit […]. 15–20 images minimum recommended; 30+ for object captures." - 10–19 images: orange banner (warning triangle), text "Workable, but quality usually improves with 20+ images and good coverage around the scene."

From 20 images onward, the banner disappears. Threshold values are hardcoded and based on empirical experience from 560+ training experiments.

WHERE

When a folder is dropped — no visible button, just detection logic.

TECHNICAL

When a directory is dropped, it is checked whether it contains one of three canonical workspace layouts: sparse/0/cameras.bin, sparse/cameras.bin, or directly cameras.bin in the root. If so, the standard image enumeration is aborted and instead a modal alert opens, asking the user whether the existing reconstruction should be used, or whether the images should be sent through Apple Photogrammetry again. Same path also applies for text-format workspaces (cameras.txt) and ETH3D exports. See chapter 9, Backend Q6, for details. Works the same in Beginner Mode as in Expert Mode.

WHERE

Full-screen background behind the progress circle, hidden on cancellation or error.

TECHNICAL

Decorative animation that renders an increasing number of small animated splat particles depending on pipeline progress (0…1). The source is a computed progress value that maps SfM phases to 0–0.2 and training to 0.2–1.0 (frame quality to 0–0.05). This makes the splats visibly "build up" as training runs. Purely decorative — the display shows no real intermediate results of the current training run (that would be Live Preview in Expert Mode). On cancel or failure it is hidden and only the status circle remains visible.

WHERE

Centered on the processing screen, 220 × 220 pixels.

TECHNICAL

Two rings rendered on top of each other: an outer muted track ring, and an inner filled progress ring with an accent or red stroke (red on error). The ring directly follows the actual progress of the current stage (smoothed via a brief fade-in/fade-out animation), so the display matches the progress line in Expert Mode. Inside the circle is a stage icon (brain for training, camera for SfM, film for video frame extraction, sparkles for the frame quality check, globe for unwrapping 360° material), stage title, and the progress number. This number is the iteration counter ("12,500/20,000") during training, and a percentage in all other stages. The icon pulses gently as long as processing is active. On error the title switches to the failed stage ("Structure from Motion Failed", "Training Failed"), and the ring and number turn red. After a cancellation the circle instead shows an orange cross with "Cancelled!".

WHERE

Top left on the processing screen, 32 × 32 pixels.

TECHNICAL

Simple button with a material background. Toggles the info panel on or off. Icon switches between an info-circle outline and a filled info-circle when active. Gentle fade-in animation. In the tooltip: "Show detailed processing metrics".

WHERE

Bottom left on the processing screen, visible only when processing details are shown.

TECHNICAL

Two-column panel with an ultra-thin material background. Left column: stage-specific info lines — for SfM the status text and percentage; for training the iteration, combined loss, L1 loss, D-SSIM loss, Gaussian count (colored orange), speed (it/s), elapsed time, computed ETA, SH degree, and learning rate. Right column: status text, time-info string, an inline loss chart (see C-28), and a discoverability nudge (see C-32). All values are read from the training status, which is updated on every training tick.

WHERE

Bottom navigation bar, visible only during the training stage (NOT during SfM) and only while processing is running.

TECHNICAL

Bordered button. Calls pause or resume depending on status. Label switches between "Pause" (with pause icon) and "Resume" (play icon). During the SfM step the button is not shown, because Apple Photogrammetry has no pause semantics. The paused state fully preserves iteration, Gaussian status, and optimizer momentum — Resume continues exactly where it left off.

WHERE

Bottom navigation bar, visible while processing is running (SfM or training).

TECHNICAL

Red bordered button. Opens a confirmation dialog titled "Stop and discard progress?", with buttons "Discard Progress" (destructive) and "Keep Running" (cancel). On confirmation the cancel flag is set, the training task is ended, the SfM subprocess is terminated if necessary, and a summary line with the cancellation status is written to the JSONL log. Unlike Pause, the training buffer and status are discarded.

WHERE

Bottom navigation bar, visible when the pipeline has failed (SfM status starts with "SfM failed" or training is in an error state).

TECHNICAL

Accent button. Restarts the entire pipeline. Before starting, it checks whether imported images/videos are still present. Previous error logs remain in the JSONL directory; a new run writes a new log file with the current timestamp.

WHERE

In the info panel, right column, visible only during training with a non-empty history.

TECHNICAL

Compact drawing area (40 pixels tall), draws the loss history as a 1-pixel line in the accent color. Data is filtered to finite values (NaN protection for unstable training runs). Min/max are computed over the entire history — so the chart auto-zooms to the current value range. The last loss value appears in the top right above the chart. The history itself is built up in the app state on every training tick (typically every 100 iterations).

WHERE

In the info panel, bottom right column, visible only during training AND in Beginner Mode.

TECHNICAL

Small line with an eye icon and caption text "Switch to Expert Mode (⌘2) for live splat preview", in a subdued tone and 10-point font. Not an interactive element, just a hint. Does not respond to clicks — the user must actually press Cmd+2 or click the Mode → Expert Mode menu.

WHERE

Full-screen background of the preview step.

TECHNICAL

Metal-based 3D viewport that renders the finished point cloud. The renderer is RadianceKit's OWN ForwardPass rasterizer — the same one that already renders the splats during training — so it's genuine WYSIWYG (what is trained is displayed and exported exactly as such). Tile-based rendering pipeline with order-independent transparency. If the renderer cannot be initialized (e.g. because Metal is not available on the system), a black background with "Metal not available" text appears instead. The view ignores the safe area, so the model reaches all the way to the window edge.

WHERE

Floating over the viewport: two icon buttons at the top left, with the info panel below them at the bottom left.

TECHNICAL

The overlay consists of exactly two buttons: "Scene Info" shows and hides the info panel at the bottom left, the second toggles the camera mode between "Orbit" (circling around a target point) and "Fly-Through" (free flying). The info panel shows frame rate, Gaussian count, camera mode, field of view, render resolution, and sampling; during an active training run, a training status line is added, and after it ends, a completion line. Failed or ongoing scene loading processes are shown as their own status line independently of the info toggle. Auto-rotation, resetting the camera, background color, and screenshot are not overlay buttons but entries in the "Viewport" menu.

WHERE

Bottom navigation bar in Z3.

TECHNICAL

Accent button with the label "Export" and a share icon. Clicking triggers the switch to Z4. Beforehand the parent view checks whether the full version is unlocked — if not, the lock view is shown instead of the export stage (see U-06).

WHERE

Left main area of the export step.

TECHNICAL

Card grid with two flexible columns and 12-point spacing. Iterates over the formats offered in Beginner mode — a filtered subset of the full format list containing only the 6 most important formats: PLY, SPZ, glTF, .splat, orbit video, web viewer. The remaining formats are only offered in Expert mode.

WHERE

Each card in the grid.

TECHNICAL

Simple button with card layout: icon (e.g., a document zipper for PLY, an archive box for SPZ, a video icon for orbit video) on top, format name as headline, description caption (truncated to 2 lines), below that the estimated file size (calculated live from format, Gaussian count, and SH degree, and formatted as KB/MB). Clicking selects the format. The selected card gets an accent background, accent border, and a checkmark icon in the top right. The tooltip is the format description.

WHERE

Below the format grid, visible only when a video format is selected (orbit video or social video).

TECHNICAL

Slider 3–30 seconds in 1-second increments, bound to the video length in app state. Maximum width 300 pixels. Only shown when a video format is selected. For non-video formats, the slider is completely removed from view — no dead space.

WHERE

Below the format grid (and below the duration slider, if a video is selected).

TECHNICAL

Large accent button. Label: "Export {Format Name}", share icon. Clicking opens the macOS save dialog with the file extension matching the format. The suggested file name comes from the current scene's name; if none is set (e.g., because the scene has never been saved), it reads "scene". Upon confirmation, the export is written to the chosen location. Disabled when no training result is available or an export is already running. Below the button is the result's key figure ("2,991 Gaussians • SH degree 3").

WHERE

Below the export button, visible only while an export is running.

TECHNICAL

Progress indicator with max width 300 pixels, below it a caption "Exporting… N %". The value runs from 0 to 1 and is updated during writing — for PLY in chunks of 10,000 Gaussians, for SPZ once after quantization, for orbit video at frame intervals.

WHERE

Below the progress bar, visible only if an error occurred during the last export.

TECHNICAL

Red line with a warning triangle and the text "Export failed: …" along with an error description. Red background with 8% opacity, rounded corners. Max width 400 pixels. Common error causes: write errors due to a full disk; sandbox errors for save destinations outside the permitted range.

WHERE

Right side of the export step.

TECHNICAL

List of the export history (stored permanently in the app settings, updated after every successful export). Each row shows a format badge (small, accent-colored), timestamp (HH:mm), file name (truncated to 1 line), and formatted file size. Clicking a row opens Finder with the selected file. Empty state: "No exports yet".

WHERE

Right-click on a history row.

TECHNICAL

Context menu on each list entry with two actions: "Reveal in Finder" (opens Finder with the selected file, like a simple click) and "Copy Path" (places the full file path as text on the clipboard). The latter is useful for drag-and-drop into other apps or for passing to the command line.