Chapitre 4 — Fenêtres auxiliaires
En plus de la fenêtre principale (viewport 3D plus inspecteur), RadianceKit gère trois autres fenêtres, qui s'ouvrent toutes via le menu Aide. Le menu comporte cinq entrées, de haut en bas : User Guide (⌘?), Keyboard Shortcuts (⌘/), Open Training Logs… (⇧⌘L), Open Exports Folder… et Manage Storage…. Les deux entrées « Open … » n'ouvrent pas de fenêtre de l'application, mais le Finder ; elles ne sont donc pas traitées plus en détail ici.
Les trois fenêtres simples (User Guide, Keyboard Shortcuts, Manage Storage) et les deux entrées de menu liées aux dossiers (Open Training Logs / Open Exports Folder) reçoivent une courte entrée par élément de contrôle.
À la fin du chapitre se trouve une section de renvoi vers l'inspecteur de la fenêtre principale : ce que tu peux utilement lire dans le graphique de perte en direct et dans l'affichage du nombre de gaussiennes pendant un entraînement en cours.
Guide utilisateur (W1–W4)

Ce que c'est : Une fenêtre d'aide intégrée qui affiche le fichier guide_<langue>.md fourni avec l'app. La langue est déterminée à partir des réglages (onglet General → Language) ou, si « System » y est indiqué, à partir des préférences linguistiques de macOS. La mise en page est classique : à gauche la barre latérale avec tous les titres, à droite le texte courant.
Quand tu as besoin d'un rappel rapide sur un point précis — donc en guise d'aide-mémoire. La référence détaillée, c'est ce manuel ; la fenêtre d'aide intégrée en est la version courte pour une consultation rapide. Elle est mise à jour à chaque version de l'app, mais reste plus superficielle sur le fond.
W1NavigationSplitView (barre latérale + détail)
OÙ
Help → User Guide (⌘?).
TECHNIQUE
Mise en page à deux colonnes avec une barre latérale étroite (au moins 180 pt de large) pour l'arborescence du contenu et une zone de détail défilante pour le contenu Markdown proprement dit. La fenêtre a une taille minimale de 700 × 500 pt. À la première ouverture, la fenêtre charge le fichier guide_<lang>.md correspondant depuis le bundle de l'app (repli sur guide_en.md), le parse en enregistrements de blocs (titres H1–H4, paragraphes, listes, tableaux, séparateurs) et extrait séparément la structure des titres pour la barre latérale. Le formatage en ligne (gras, italique, code en ligne) est rendu via le moteur Markdown intégré. La langue est lue depuis les réglages de l'app, avec le cas particulier du chinois (zh-Hans) et du portugais brésilien (pt-BR), qui sont conservés en tant que tags de locale complets, car ces variantes se distinguent de zh et pt respectivement.
W2List (barre latérale des titres)
OÙ
Colonne de gauche dans la fenêtre du guide utilisateur.
TECHNIQUE
Liste de tous les titres H2 et H3 du document Markdown actuel. Les entrées H2 apparaissent sans retrait avec un poids de police medium, les entrées H3 avec un retrait de 16 pt à gauche et un style de premier plan atténué. Tous les autres niveaux — H1 comme H4 et au-delà — n'apparaissent pas dans la barre latérale, car ils la rendraient sinon peu lisible. Les ID d'ancre sont générés à partir du texte du titre par slugification (minuscules + espaces transformés en tirets + filtrage sur lettres/chiffres/tirets — le même algorithme qu'utilise GitHub pour ses ancres Markdown, si bien que des URL externes vers la doc pourraient potentiellement pointer vers la même ancre). La liste utilise le style natif macOS.
W3Button (saut titre → ancre)
OÙ
Un bouton par ligne de barre latérale.
TECHNIQUE
Chaque entrée de la barre latérale est un bouton qui définit l'ancre actuelle, mais qui a visuellement l'apparence d'un élément de liste. Une variable d'observation déclenche alors le saut de défilement vers l'ancre correspondante avec une animation douce sur 0,3 s. Après le saut, la valeur de l'ancre est réinitialisée, afin que le clic suivant sur la même ancre se déclenche à nouveau (sinon l'observateur ne se redéclencherait pas, car la valeur n'aurait pas changé).
W4ScrollView (contenu détaillé)
OÙ
Colonne de droite.
TECHNIQUE
Zone de contenu défilante, empilée verticalement, avec rendu paresseux (lazy rendering), car les guides plus longs peuvent facilement dépasser 200 blocs Markdown — une variante non paresseuse instancierait tout en même temps. Chaque bloc reçoit son propre ID, soit l'ancre du titre (que reçoit chaque titre, indépendamment du niveau), soit un espace réservé indexé. La largeur maximale est de 720 pt, le padding de 32 horizontal / 24 vertical, afin que les lignes longues conservent une mise en page bien lisible. Les tableaux sont rendus cellule par cellule avec des piles horizontales et des lignes de séparation ; le code en ligne via le moteur Markdown intégré. Les vrais blocs de code sont actuellement traités comme des paragraphes — une limitation connue de la fenêtre d'aide.
Raccourcis clavier (W5–W6)

Liste de référence statique en cinq sections. Navigation: Mouse Drag (Orbit/Fly), Shift+Drag/Right-Drag (Pan), Scroll (Zoom), WASD (mouvement Fly-Through), Q/E (Up/Down), F (Toggle Orbit/Fly), Double-click (Re-center), Cmd+Scroll (ajustement du FoV). Views: R (Reset Camera), T (rotation automatique), P (Camera Playback), B (cycle d'arrière-plan), 0–9 (sauter à Training-Cam 1=10%/5=50%/0=dernière), Left/Right Arrow (cam précédente/suivante). Capture: S (capture d'écran vers le bureau), V (vidéo turntable), C (copier les infos caméra). Editor: Tab (mode édition), Click/Drag (sélection par peinture), Option+Click (désélectionner), X / Delete (supprimer la sélection), Cmd-Z (annuler la dernière suppression), [ / ] (taille de pinceau plus petite/plus grande), Esc (annuler la sélection). Training: Option+Space (mettre en pause/reprendre l'entraînement), Cmd+E (exporter la scène). Il n'y a rien de plus ici — pour démarrer, annuler et prolonger l'entraînement, tu passes par le menu Training (chapitre 1).
Ce que c'est : Un simple aperçu statique de tous les raccourcis clavier — Navigation, Views, Capture, Editor, Training. Le contenu est intégré en dur et n'est pas chargé depuis un fichier.
Quand tu cherches le moyen le plus rapide de faire quelque chose dans le viewport. WASD-Fly-Through, R pour réinitialiser la caméra, B pour le cycle d'arrière-plan — tout est indiqué ici.
W5ScrollView (zone de contenu)
OÙ
Aide → Raccourcis clavier (⌘/).
TECHNIQUE
Une simple zone de défilement contenant une liste verticale. Marge intérieure de 20 pt tout autour, pas d'arborescence de navigation latérale (la liste est assez courte). Le contenu est regroupé en cinq sections (Navigation, Views, Capture, Editor, Training). Par combinaison de touches, une ligne avec du texte traduisible dans les deux colonnes. La colonne de gauche (code de touche) est fixée à 180 pt de largeur, afin que les descriptions à droite restent alignées verticalement. Aucune interaction hormis le défilement — cliquer sur une ligne ne déclenche rien, les raccourcis clavier sont de véritables modificateurs de touches dans le menu et sur le viewport.
W6VStack (sections de raccourcis)
OÙ
À l'intérieur du ScrollView.
TECHNIQUE
Sections empilées alignées à gauche avec 16 pt d'espacement. À l'intérieur des cinq sections, un titre suivi d'une série de lignes. Les titres utilisent un style de sous-titre secondaire — volontairement pas de format Title, car les sections n'ont pas besoin d'être navigables. Le contenu est volontairement plat (pas de disclosure, pas de recherche, pas de filtre), pour que le composant fonctionne sans changement sur toutes les versions de macOS et que le fichier reste lisible.
Gérer le stockage (W7–W12)

Vue en tableau de tous les fichiers gérés par RadianceKit. L'en-tête indique 1 356 éléments, 55,1 Go au total. Barre d'outils en haut : « Show in Finder » + « Refresh ». Chaque ligne : icône d'export, nom de fichier (p. ex. training_20260718T194416Z.ply), date d'export, taille (varie ici de 7,8 Mo à 2,24 Go), icône loupe (Reveal) et icône corbeille (Move to Trash). Le tri se fait d'abord par catégorie, puis à l'intérieur d'une catégorie par date, les plus récents en haut. Dans cette capture, les exports PLY dominent, car ce dossier a surtout servi à sauvegarder des résultats d'entraînement.
Ce que c'est : Un aperçu de l'utilisation disque pour tout ce que RadianceKit dépose sous ~/Documents/RadianceKit/ — logs, exports, scènes, ensembles de capture (venant du compagnon iOS), imports (copies de mise en attente des images d'entrée). Par entrée : une taille en octets et deux boutons : « afficher dans le Finder » et « déplacer vers la corbeille ». Ce n'est PAS un nettoyage automatique — l'app ne supprime rien d'elle-même ; c'est toi qui décides pour chaque entrée. Cette fenêtre est traduite : en français, elle s'appelle « Gérer le stockage », les deux boutons de l'en-tête s'appellent « Afficher dans le Finder » et « Actualiser », les boutons de ligne « Afficher dans le Finder » et « Mettre à la corbeille ». Les noms anglais dans les entrées ci-dessous sont les intitulés de la version anglaise.
Quand le disque se remplit. Ce sont surtout les logs qui s'accumulent (un fichier JSONL par tentative d'entraînement, plus le _qualityMetrics.json) ; les exports aussi, bien sûr (PLY à 100 % de données brutes, un par export). Utile également après un plantage, quand le répertoire de mise en attente des imports contient encore d'anciennes copies des images d'entrée.
W7Bouton « Show in Finder »
OÙ
En-tête, en haut à droite de la fenêtre du navigateur de stockage.
TECHNIQUE
Ouvre le dossier de données de RadianceKit dans le Finder — exactement le répertoire dont ce fenêtre liste le contenu. Tu vois ainsi directement la structure des dossiers (Logs, Exports, Scenes, Captures, Imports) et peux aussi déplacer ou copier les fichiers toi-même avec le Finder. L'action ouvre une nouvelle fenêtre Finder ; la liste dans la fenêtre ne se met pas à jour automatiquement — c'est le rôle de « Refresh » (W8).
W8Bouton « Refresh »
OÙ
En-tête, à côté du bouton Finder.
TECHNIQUE
Déclenche un balayage en arrière-plan, exécuté sur une tâche asynchrone initiée par l'utilisateur, afin que le scan de grands arbres de répertoires ne bloque pas l'interface. Le parcours proprement dit traverse chaque sous-dossier connu (Logs, Exports, Scenes, Captures, Imports) et génère une entrée de stockage par enfant direct. Pour chaque entrée, la taille récursive est déterminée — de préférence la consommation disque réelle (y compris le partage de hardlinks APFS), avec repli sur la taille logique du fichier.
W9Liste (entrées de stockage)
OÙ
Contenu principal sous l'en-tête.
TECHNIQUE
Liste avec, par ligne, cette disposition : icône SF Symbol spécifique à la catégorie (document pour les logs, flèche vers le haut pour les exports, cube pour les scènes, iPhone pour les ensembles de capture, bac pour les imports), nom + sous-titre (libellé de type + date de modification formatée), compteur d'octets à droite (aligné à droite, en police à chasse fixe), bouton Reveal (icône loupe), bouton Trash (corbeille). Tri : d'abord par type (les scènes en premier, puis les exports, logs, captures, imports, autre), puis par date de modification décroissante (les plus récents en haut). Si le scan est encore en cours, la zone affiche à la place une progression « Scanning… ». Si rien n'a été trouvé, un affichage d'état vide avec icône de bac apparaît.
W10Bouton de ligne « Reveal in Finder »
OÙ
Par ligne, icône loupe à droite.
TECHNIQUE
Ouvre le Finder et sélectionne l'élément spécifique (fichier ou dossier). Différence avec W7 : W7 ouvre le répertoire racine ; W10 marque précisément cette seule entrée. Flux de travail pratique : identifie une entrée volumineuse, clique sur la loupe, puis copie-la par exemple sur un volume externe.
W11Bouton de ligne « Move to Trash »
OÙ
Par ligne, icône corbeille à droite de la loupe.
TECHNIQUE
Déclenche la boîte de dialogue de confirmation (W12). Ce n'est qu'après confirmation que s'exécute l'opération standard macOS « déplacer vers la corbeille » (donc réversible, pas de suppression directe). Après mise à la corbeille réussie, l'entrée est retirée de la liste et le compteur total d'octets est mis à jour. En cas d'erreur, une boîte de dialogue d'erreur modale s'affiche.
W12ConfirmationDialog (confirmation de suppression)
OÙ
Déclenché par W11, affiché sous forme de feuille macOS.
TECHNIQUE
Boîte de dialogue de confirmation standard avec un titre dynamique « Delete <name>? » et une ligne de message indiquant explicitement que l'entrée atterrit dans la corbeille et peut être restaurée depuis là (jusqu'à ce que la corbeille soit vidée). Deux boutons : « Move to Trash » comme action destructive (affichée en rouge) et « Cancel » avec liaison automatique à la touche Échap. La boîte de dialogue est non-modale en ce sens qu'elle ne bloque que cette fenêtre, pas toute l'app — c'est le standard macOS pour les suppressions réversibles.
Fenêtre principale : historique de la perte et nombre de Gaussians (I39–I41, renvoi croisé)
Trois des affichages de l'inspecteur dans la fenêtre principale méritent une explication à part, car ils sont constamment visibles pendant un entraînement en cours et qu'il existe des règles empiriques importantes pour savoir quand le tracé a l'air sain. Les affichages se trouvent dans l'inspecteur, dans la section Progression, dans le groupe dépliable Historique de la perte (voir chapitre 2 — Inspecteur), et aident à interpréter la progression de l'entraînement.
Quand la courbe de perte est-elle saine ? Une courbe de perte saine montre trois phases : (1) Warmup — pendant les 200 à 500 premières itérations, la perte chute fortement d'une valeur élevée (typiquement 0,15–0,25 pour L1+SSIM combinés selon la scène) jusqu'à environ la moitié. Si la perte ne diminue PAS pendant cette phase, c'est généralement que l'entrée est fautive (images corrompues, poses SfM médiocres, nombre de Gaussians initiaux trop faible). (2) Densification — entre environ 500 et densifyUntilIteration (classiquement 15K, MCMC jusqu'à 20K ou 25K), la perte continue de baisser, souvent avec de petits sauts vers le bas lorsque les opérations de densification insèrent de nouveaux Gaussians et que l'optimiseur les exploite. Le nombre de Gaussians augmente pendant cette phase. (3) Refinement — ensuite, la perte entre dans une traîne de plus en plus plate. Valeurs finales typiques à titre indicatif : une scène d'objet bien éclairée (par exemple le Truck de Tanks-&-Temples avec P4 Quality) atteint L1 ≈ 0,023, tandis que les scènes extérieures étendues comme celles de Mip-NeRF 360 restent naturellement au-dessus (0,04–0,07).
Que signifie un plateau ? Un plateau (la courbe de perte reste horizontale sur plusieurs milliers d'itérations) a deux interprétations : (a) le modèle a convergé, poursuivre l'entraînement n'apporte plus rien — c'est le bon cas. (b) le modèle est bloqué (minimum local, mauvaise information de gradient, un plafond atteint sur la limite du buffer) — le mauvais cas. Les deux ont l'air identiques sur le graphique. Pour les distinguer : regarde le nombre de Gaussians. S'il est également plat ET proche du plafond MCMC (par exemple 150K sur 150K avec le préréglage P8 Quality (MCMC)), tu es à la limite — soit augmenter le plafond, soit accepter le plateau. Si le nombre de Gaussians continue de croître mais que la perte ne baisse pas, c'est que le modèle est bloqué.
Quand arrêter vs continuer l'entraînement ? Règle empirique : si aucune amélioration de la perte minimale pendant 10K itérations → arrête, les itérations supplémentaires sont gaspillées. Avant cela : via le menu Entraînement → Continue Training → « +5,000 iterations », tu peux encore ajouter une prolongation si tu observes une amélioration limite (il n'existe pas de raccourci clavier pour cela). Attention : avec MCMC, le plateau est souvent réel — le plafond est la limite naturelle.
Un plateau du nombre de Gaussians n'est PAS un signal de « terminé ». Il signifie seulement que MCMC a atteint son plafond ou que la Classic Densification est à bout. La vraie question du « terminé » n'est répondue que par PSNR/SSIM/LPIPS sur un ensemble de test indépendant. L'ensemble de test indépendant montre également si ton ensemble de caméras permet une répartition équitable entre vues d'entraînement et vues de test.
PSNR/Holdout est la vérité, la perte n'est qu'un indicateur indirect. La perte est une métrique relative : elle diminue à mesure que ton modèle s'adapte aux vues d'entraînement. Mais une perte faible ne signifie pas automatiquement un bon modèle — si le modèle a appris par cœur les images d'entraînement (overfitting), la perte serait faible, mais le PSNR sur des vues non vues (holdout) serait mauvais. C'est pourquoi, pour l'évaluation finale de la qualité, il faut toujours regarder les métriques holdout, et non la seule perte finale.
Résumé des règles empiriques
- User Guide et Keyboard Shortcuts sont une aide statique — rapides pour des questions ponctuelles, mais pour aller en profondeur, utilise ce manuel. - Ouvre Manage Storage dès que le disque descend sous 10% d'espace libre. Les logs et le staging des imports sont les coupables habituels. - Le plateau de loss et le plateau du nombre de gaussiennes doivent être interprétés séparément. La limite de cap n'est pas un signal de « terminé ». Seule la PSNR sur le holdout mesure la vraie qualité. - 10K itérations sans amélioration du min-loss → arrête l'entraînement.