Chapitre 10 — Mode débutant
Le mode débutant (Simple Mode, Cmd+1) est le workflow guidé pour quiconque reconstruit pour la première fois une scène Gaussian Splatting 3D. Au lieu d'afficher une sidebar pleine de champs d'inspecteur, l'app vous guide en quatre étapes : d'abord importer des images ou une vidéo et choisir un préréglage de qualité, puis le traitement s'exécute (SfM + entraînement), ensuite vous pouvez examiner la scène finie dans un aperçu 3D, et enfin exporter au format souhaité. Une fine barre de progression en haut de la fenêtre indique en permanence à quelle étape vous êtes.
Comparé au mode expert (Cmd+2) qui montre tous les contrôles d'un coup, le mode débutant masque les options inutilisées, affiche des avertissements de validation en cas d'images trop rares ou de mauvaise qualité, et propose à chaque étape uniquement les boutons pertinents. Vous pouvez basculer à tout moment entre mode débutant et mode expert (Cmd+1 / Cmd+2) ; tout l'état — images importées, préréglage choisi, entraînement en cours, nuage de points fini — est conservé.
Z1 — Import (images et préréglage)
Crumb-trail (Import actif) avec workflow en quatre étapes. Drop zone à gauche avec trois CTA : « Browse Files », « Try Sample Scene », « Download Sample Photos (~427 MB) ». Format pills en dessous. À droite « Imported Files » avec compteur « 0 images ». En bas le sélecteur Quality (défaut : Preview) et « Start Processing » (désactivé tant qu'aucune image).
La première étape consiste à fournir des images à l'app : par glisser-déposer dans le grand cadre pointillé au centre, via le bouton « Browse Files » ou en cliquant sur la sample scene livrée. À droite apparaît la liste des images importées avec résolution et taille ; en bas, dans la barre flottante, vous choisissez le préréglage et démarrez avec « Start Processing ». Les avertissements de validation (rouge si < 3 ou < 10 images, orange pour 10–19) indiquent si l'app attend une reconstruction sensée.
C-01ProgressIndicator (indicateur d'étape)
OÙ
Au-dessus du workflow, toujours visible.
TECHNIQUE
Barre de progression horizontale sur tout le pipeline (Frame Quality → SfM → Training) avec allocation : Frame Quality 0–5 %, SfM 0–30 %, Training 30–100 %. À côté, texte de statut et pourcentage par phase (« SfM 41 % », « Training 12 500/20 000 »). Calcul ETA après mesure d'un tempo d'entraînement (typiquement après 100 itérations).
C-03DropZoneView (zone glisser-déposer)
OÙ
Gauche de l'étape import, rectangle pointillé.
TECHNIQUE
Drop zone qui anime le symbole et colore le fond quand des éléments sont au-dessus. Accepte JPG, PNG, TIFF, HEIC, MP4, MOV, PLY, SPZ, .splat, bundles .radiancescene et dossiers. Routage par type : images collectées, vidéos déclenchent le frame sampling, splat ouvre directement l'aperçu, bundles chargés. Sandbox bookmarks correctement gérés. Extensions non supportées affichées en bandeau 5 s.
C-05Browse Files Button
OÙ
Dans la drop zone, bouton prominent.
TECHNIQUE
Ouvre le dialogue de fichiers macOS avec multi-sélection (JPG, PNG, TIFF, MP4, MOV, dossiers, format scène propre). URLs security-scoped, mêmes chemins d'import que le drag-and-drop. Dossier = énuméré récursivement.
C-06Try Sample Scene Button
OÙ
Dans la drop zone, visible si bundle contient la sample scene ET aucun import.
TECHNIQUE
Apparaît si (a) un sample-scene.splat/.spz/.ply existe dans le bundle ET (b) aucun import en cours. Au clic, charge le nuage fini et fixe après 400 ms des valeurs caméra hardcoded pour une perspective d'entrée esthétique.
C-07Download Sample Photos Button
OÙ
Dans la drop zone, à côté de « Try Sample Scene ».
TECHNIQUE
Déclenche un téléchargement (github.com/bkindler/radiancekit-sample-photos) d'environ 427 Mo contenant 960 images. Bouton désactivé pendant le téléchargement. Progression affichée en haut comme « Downloading X % » sur sa propre échelle.
C-09Quality Presets Picker
OÙ
Barre flottante du bas, à gauche du bouton Start.
TECHNIQUE
Contrôle « Quality » groupant les préréglages par catégorie (Classic / MCMC / Custom). Locked state : préréglages hors free-list reçoivent un suffixe « 🔒 » si pas acheté ; au clic, le picker revient sur Preview et ouvre le sheet d'achat.
C-10Start Processing Button
OÙ
Barre flottante du bas, à droite du sélecteur préréglage.
TECHNIQUE
Bouton grisé tant qu'aucune image/vidéo importée. Au clic, lance le pipeline (Frame Quality → SfM → Training). Pas de statut interne ; traitement actif = écran séparé.
C-11Video Sampling Slider
OÙ
Liste images à droite, visible si vidéo importée.
TECHNIQUE
Slider 0,5 fps – 30 fps par pas de 0,5. Calcul du nombre cible (min 10). Slider hors de la liste car les éléments bloqueraient les events souris. Sous le slider : nombre de frames et durée vidéo. Tooltip avertit du coût SfM.
C-12Clear All Button
OÙ
Liste images, en bas, visible si imports.
TECHNIQUE
Bouton rouge. Clic ouvre confirmation « Clear all imported files? ». Vide toutes les images/vidéos, dossiers staging, nuage, statut training, résultat SfM et caches ; stage → Import.
C-13File List ForEach (suppression individuelle)
OÙ
Liste des images, chaque entrée.
TECHNIQUE
Liste avec swipe-to-delete. Par image : icône, nom, résolution, taille. Cache de métadonnées asynchrone. Suppression par swipe trackpad ou Delete. Bouton moins + Backspace + Cmd-Z disponibles uniquement en mode expert (Project Navigator).
C-15Validation Warnings (3 niveaux)
OÙ
Sous la liste images, au-dessus de Clear All.
TECHNIQUE
Trois seuils : - < 3 : bandeau rouge, « At least 3 images are required. » - 3–9 : bandeau rouge, « With fewer than 10 images, SfM often fails... » - 10–19 : orange, « Workable, but quality usually improves with 20+ images. » À partir de 20, plus de bandeau.
C-16COLMAP Workspace Detection
OÙ
Au drop d'un dossier — pas de bouton visible.
TECHNIQUE
Au drop d'un dossier, vérifie disposition workspace : sparse/0/cameras.bin, sparse/cameras.bin ou cameras.bin racine. Si oui, alerte modale demandant si reprendre la reconstruction ou recalculer via Apple Photogrammetry. Idem pour text format et exports ETH3D. Voir chapitre 9 backend Q6.
Quand passer à l'étape suivante ?
Vous pouvez cliquer Start Processing dès que (a) au moins une image ou une vidéo est importée et (b) le bandeau de validation est orange ou disparu. Sur bandeau rouge, l'app laisse démarrer mais le traitement échouera. Recommandation : au moins 20 images, nettes, avec recouvrement notable entre prises consécutives. Choisissez un préréglage adapté au temps disponible.
Z2 — Traitement (SfM + entraînement)
Phase SfM (alignement des caméras) : grand cercle de progression affiche la sous-étape. Texte « Aligning cameras… » en haut à gauche. Crumb-trail marque « Cameras ». Barre haute : progression globale. Animation wireframe en arrière-plan.
Phase entraînement : icône sous-étape « Training Gaussians », pourcentage compte les itérations du préréglage. Ligne métriques live : loss, vitesse, ETA. Bouton Pause permet Resume ; Cancel rejette le résultat.
Dès que le pipeline tourne, l'app affiche un écran plein traitement. Au centre, un grand cercle de progression (220 × 220 px) avec icône d'étape et pourcentage ; en fond, animation discrète. En haut à gauche, un panneau d'info. En bas, Pause/Resume, Cancel et en cas d'erreur Retry.
C-18SplatTrainingView (animation de fond)
OÙ
Fond plein écran derrière le cercle.
TECHNIQUE
Animation décorative qui rend des particules splat selon la progression. SfM mappé sur 0–0.2, training sur 0.2–1.0. Purement décoratif — pas de vrais résultats. Masquée en cas de cancel/échec.
C-19Grand cercle de progression
OÙ
Centre de l'écran traitement, 220 × 220 px.
TECHNIQUE
Deux anneaux : track-ring atténué et progress-ring intérieur (accent ou rouge en erreur). Icône d'étape (cerveau/training, caméra/SfM, film/extraction vidéo, sparkles/quality), titre et pourcentage animé. Interpolation 30 Hz vers la valeur réelle.
C-22Bouton Info (afficher métriques)
OÙ
En haut à gauche de l'écran traitement.
TECHNIQUE
Bouton avec fond Material. Bascule le panneau Info. Icône change Outline ↔ Filled. Tooltip : « Show detailed processing metrics ».
C-23Panneau Info (métriques live)
OÙ
En bas à gauche de l'écran traitement.
TECHNIQUE
Panneau deux colonnes avec fond Ultra-Thin Material. Gauche : info spécifiques à l'étape — SfM statut + %, training itération, loss, L1, D-SSIM, Gaussian-Count, vitesse, elapsed, ETA, SH degree, learning rate. Droite : texte statut, mini chart loss (C-28), nudge (C-32).
C-25Bouton Pause/Resume
OÙ
Barre nav, visible seulement pendant training (PAS SfM).
TECHNIQUE
Bouton bordered. Appelle Pause ou Resume. Label bascule. Non affiché pendant SfM (Apple Photogrammetry sans pause). Pause préserve itération, état gaussien et moments d'optimiseur ; Resume continue.
C-26Bouton Cancel
OÙ
Barre nav, visible pendant traitement.
TECHNIQUE
Bouton rouge. Dialogue « Stop and discard progress? ». Pose le flag cancel, termine le task, tue SfM si besoin, écrit summary annulation dans le log. Contrairement à Pause, les buffers d'entraînement sont rejetés.
C-27Bouton Retry
OÙ
Barre nav, visible si pipeline a échoué.
TECHNIQUE
Bouton accent. Relance tout le pipeline. Vérifie qu'il reste des images/vidéos importées. Anciens logs conservés ; nouveau run nouveau fichier avec timestamp.
C-28Mini chart de loss
OÙ
Panneau Info droite, visible si historique non vide.
TECHNIQUE
Zone compacte 40 px haut. Ligne 1 px en accent. Données filtrées sur valeurs finies (protection NaN). Min/Max recalculés (auto-zoom). Dernière valeur en haut à droite. Construit à chaque tick training (~100 itérations).
C-32Discoverability Nudge (hint mode expert)
OÙ
Panneau Info droite en bas, visible pendant training ET en mode débutant.
TECHNIQUE
Petite ligne avec icône œil et caption « Switch to Expert Mode (⌘2) for live splat preview », 10 pt. Non interactif — l'utilisateur doit appuyer Cmd+2 ou utiliser le menu.
Quand passer à l'étape suivante ?
L'app passe automatiquement à Z3 dès que l'entraînement réussit. La barre nav passe de Pause/Cancel à Back et Export. En cas d'erreur, Retry apparaît.
Z3 — Aperçu (faire tourner le modèle 3D)
Crumb-trail marque « Preview ». Viewport 3D plein écran rend la scène bouquet entraînée. Barre : « Training complete — 3 022 Gaussians in 13 s ». Glisser = tourne, molette zoom. Back = Z2, Export = Z4.
Après l'entraînement, l'app atterrit dans l'aperçu. Vue fullscreen Metal, tourner/zoomer/panner avec souris et trackpad. Au-dessus, overlay : contrôle caméra, statistiques training, reset.
C-36SplatViewportView (vue 3D principale)
OÙ
Fond plein écran de l'étape Preview.
TECHNIQUE
Viewport 3D Metal qui rend le nuage fini. Fork vendored MetalSplatter avec correctifs RadianceKit pour popping/flickering. Pipeline tile-based avec OIT. Si Metal indisponible, fond noir « Metal not available ».
C-37CameraControlsOverlay (overlay contrôle)
OÙ
Au-dessus du viewport, flottant.
TECHNIQUE
Overlay compact avec boutons : auto-rotation turntable, reset caméra, sélection fond Gray/Black/White, Save Screenshot, toggle panneau info. Lie aux paramètres caméra.
C-38Bouton Export (barre nav)
OÙ
Barre nav inférieure en Z3.
TECHNIQUE
Bouton accent avec « Export » et icône share. Au clic, Z4. Vérifie d'abord la version complète — sinon écran de verrouillage (U-06).
Quand passer à l'étape suivante ?
Avant l'export, faites le tour complet : zones couvertes présentes ? Floaters ? Ciel/fond propre ? Problèmes graves = nouvel entraînement (plus d'images, autre préréglage, ou mode expert avec floater reduction).
Z4 — Export (choisir le format)
Crumb-trail marque « Export ». Grid de cartes à gauche avec six options. Tailles calculées live. Sidebar « Export History » à droite. CTA en bas.
Dans l'étape finale, vous choisissez parmi 6 formats via une grille deux colonnes, cliquez Export et choisissez l'emplacement dans le dialogue macOS.
C-39Grid 2 colonnes des formats
OÙ
Côté gauche de l'étape Export.
TECHNIQUE
Grille deux colonnes flexibles, 12 pt d'espacement. Itère sur les 6 formats du mode débutant : PLY, SPZ, glTF, .splat, Orbit Video, Web Viewer. Compressed PLY et SOG réservés au mode expert.
C-40Format Card Button
OÙ
Chaque carte du grid.
TECHNIQUE
Bouton avec layout carte : icône, nom (headline), description 2 lignes, taille estimée (live). Sélection → fond accent + coche. Tooltip = description.
C-41Video Duration Slider
OÙ
Sous le grid, visible si format vidéo.
TECHNIQUE
Slider 3–30 s, pas 1. Largeur max 300 px. Affiché seulement si format vidéo — sinon retiré.
C-42Bouton Export
OÙ
Sous le grid (et sous duration slider si vidéo).
TECHNIQUE
Grand bouton accent. Label : « Export {format} », icône share. Au clic, dialogue d'enregistrement macOS avec extension correcte et nom « scene.{ext} ». Désactivé si pas de résultat ou export en cours.
C-43Export Progress Bar
OÙ
Sous Export, visible pendant export en cours.
TECHNIQUE
Progression largeur max 300 px avec caption « Exporting… N % ». PLY en chunks de 10 000 gaussiens, SPZ une fois après quantisation, orbit video par intervalles de frames.
C-44Export Error Display
OÙ
Sous progress bar, visible si erreur.
TECHNIQUE
Ligne rouge avec icône warning et texte. Fond rouge 8 % opacity. Causes : SOG attend cwebp (pas App Store compliant) ; disque plein ; sandbox error.
C-46Export History List
OÙ
Côté droit de l'étape Export.
TECHNIQUE
Liste de l'historique persistée en JSON dans UserDefaults. Par ligne : badge format, timestamp HH:mm, nom fichier, taille. Clic = Finder avec fichier sélectionné. Empty state : « No exports yet ».
C-48History Context Menu (clic droit)
OÙ
Clic droit sur une ligne d'historique.
TECHNIQUE
Menu contextuel avec deux actions : « Reveal in Finder » et « Copy Path ». Pratique pour drag-and-drop ou ligne de commande.
Quand le workflow est-il terminé ?
Après un export réussi, vous avez votre modèle 3D sur disque et l'historique a une nouvelle entrée. Pas de bouton « Done » — vous pouvez exporter dans n'importe quel nombre de formats sans réentraîner. Back ramène à l'aperçu. Nouvelle scène : Back vers Z1 puis Clear All, ou File → New Project (Cmd+⇧+N).
Passage au mode expert
Appuyez à tout moment sur Cmd+2 ou Mode → Expert Mode (M8). Tout l'état est conservé : images, préréglage, entraînement, nuage, historique, étape. En mode expert, sidebar inspecteur complète avec ~150 contrôles. Project Navigator (chapitre 2) propose les opérations image avancées (bouton moins, Backspace, Cmd-Z, Quick Look), le live preview du viewport, et tous les paramètres Loss/MCMC/densification/Mip-Splatting. Cmd+1 ramène sans perte d'état.
FAQ
Pourquoi mon bouton Start Processing reste-t-il gris ?
Vous n'avez pas encore importé d'images ou de vidéo. Glissez au moins un fichier dans la drop zone ou utilisez « Browse Files ». Dès qu'au moins une entrée est présente, le bouton devient actif.
Pourquoi mon bouton Export est-il verrouillé ?
Deux niveaux : (a) si le pipeline n'est pas fini, désactivé. (b) si version complète non achetée (PurchaseManager.hasAccess == false), écran de verrouillage avec « Unlock Full Version » qui ouvre le sheet d'achat. Quick et Preview permettent l'entraînement gratuit, mais l'export est premium.
Pourquoi ne puis-je pas choisir un préréglage ?
Vous pouvez — mais sans version complète, taper un préréglage premium renvoie sur Preview et ouvre l'achat. Quick et Preview sont les seuls préréglages gratuits.
Pourquoi ma drop zone reste-t-elle vide même en glissant des images ?
Probablement un mismatch UTI. L'app accepte JPG, PNG, TIFF, HEIC, MP4, MOV et les formats splat propres. Autres formats (BMP, GIF, WebP, RAW) NON reconnus. L'app va d'abord par extension de fichier.
Pourquoi SfM prend-il si longtemps avec 30 images ?
Apple Photogrammetry ne scale pas linéairement — certaines configurations (intérieurs complexes, flou, mauvaise lumière) prennent bien plus longtemps. SfM bloqué après 10 min → annulez, retentez avec meilleur matériel, ou mode expert pour COLMAP/Native SfM.
Où trouver mes training logs ?
Help → Open Training Logs (Cmd+⇧+L). Ouvre ~/Documents/RadianceKit/Logs/. Chaque session = un fichier JSONL : config, progress toutes les 100 itérations, summary finale.