Guía del usuario

Capítulo 4 — Ventanas auxiliares

Además de la ventana principal (viewport 3D más Inspector), RadianceKit gestiona otras tres ventanas, todas ellas accesibles desde el menú de ayuda. El menú tiene cinco entradas, de arriba abajo: User Guide (⌘?), Keyboard Shortcuts (⌘/), Open Training Logs… (⇧⌘L), Open Exports Folder… y Manage Storage…. Las dos entradas «Open …» no abren ninguna ventana de la app, sino el Finder; por eso no se tratan más a fondo aquí.

Las tres ventanas sencillas (User Guide, Keyboard Shortcuts, Manage Storage) y las dos entradas de menú de carpetas (Open Training Logs / Open Exports Folder) reciben una breve entrada por cada control.

Al final del capítulo hay un apartado de referencia cruzada con el Inspector de la ventana principal: qué puedes deducir de forma útil en el gráfico de pérdida en vivo (Live-Loss-Chart) y en el indicador de recuento de gaussianas durante un entrenamiento en curso.

Guía del usuario (W1–W4)

Ventana de la guía del usuario con barra lateral a la izquierda y contenido Markdown renderizado a la derecha
Ventana de la guía del usuario con barra lateral a la izquierda y contenido Markdown renderizado a la derecha

Qué es: Una ventana de ayuda integrada que renderiza el guide_<idioma>.md incluido con la app. El idioma se deriva de los Settings (pestaña General → Language) o, si allí figura "System", de las preferencias de idioma de macOS. El diseño es clásico: a la izquierda una barra lateral con todos los encabezados, a la derecha el texto corrido.

Cuando necesites un recordatorio rápido de un punto concreto — es decir, como sustituto de una chuleta. La referencia detallada es este manual; la ventana de ayuda integrada es la versión corta para consultas rápidas. Se actualiza con cada lanzamiento de la app, pero se mantiene más superficial en contenido.

W1NavigationSplitView (barra lateral + detalle)

DÓNDE

Help → User Guide (⌘?).

TÉCNICO

Diseño de dos columnas con una barra lateral estrecha (mínimo 180 pt de ancho) para el árbol de contenido y un área de detalle desplazable para el contenido Markdown propiamente dicho. La ventana tiene un tamaño mínimo de 700 × 500 pt. Al abrirse por primera vez, la ventana carga el guide_<lang>.md correspondiente desde el bundle de la app (con guide_en.md como alternativa), lo analiza en registros de bloque (encabezados H1–H4, párrafos, listas, tablas, líneas separadoras) y extrae por separado la estructura de encabezados para la barra lateral. El formato en línea (negrita, cursiva, fragmentos de código) se renderiza mediante el motor Markdown integrado. El idioma se lee de los ajustes de la app, con el caso especial del chino (zh-Hans) y el portugués de Brasil (pt-BR), que se conservan como etiquetas de configuración regional completas porque estas variantes se diferencian de zh y pt respectivamente.

W2List (barra lateral de encabezados)

DÓNDE

Columna izquierda en la ventana de la guía del usuario.

TÉCNICO

Lista de todos los encabezados H2 y H3 del documento Markdown actual. Las entradas H2 aparecen sin sangría con peso de fuente medio, las entradas H3 con 16 pt de sangría a la izquierda y un estilo de primer plano reducido. Ningún otro nivel — ni H1 ni H4 en adelante — aparece en la barra lateral, porque de lo contrario la volverían confusa. Los IDs de anclaje se generan a partir del texto del encabezado mediante slugificación (minúsculas + espacios convertidos en guiones + filtrado de letras/números/guiones — el mismo algoritmo que usa GitHub para sus anclas de Markdown, de modo que incluso las URL externas a la documentación podrían apuntar potencialmente al mismo anclaje). La lista utiliza el estilo nativo de macOS.

W3Button (salto a anclaje desde encabezado)

DÓNDE

Un botón por cada fila de la barra lateral.

TÉCNICO

Cada entrada de la barra lateral es un botón que establece el anclaje actual, pero que visualmente parece un elemento de lista. Una variable observadora dispara entonces el salto de desplazamiento hasta el anclaje correspondiente con una animación suave de 0,3 s. Tras el salto, el valor del anclaje se restablece para que el siguiente clic sobre el mismo anclaje vuelva a dispararse (de lo contrario el observador no se activaría de nuevo, porque el valor no habría cambiado).

W4ScrollView (contenido de detalle)

DÓNDE

Columna derecha.

TÉCNICO

Área de contenido desplazable, apilada verticalmente, con renderizado perezoso (lazy), porque las guías más largas pueden superar fácilmente los 200 bloques de Markdown — una variante no perezosa instanciaría todos a la vez. Cada bloque recibe su propio ID, ya sea el anclaje del encabezado (que recibe cada encabezado, independientemente del nivel) o un marcador de posición de índice. El ancho máximo es de 720 pt, con relleno (padding) de 32 horizontal / 24 vertical, de modo que las líneas largas conserven un diseño bien legible. Las tablas se renderizan celda por celda con pilas horizontales y líneas separadoras; el código en línea mediante el motor Markdown integrado. Los bloques de código reales se tratan actualmente como párrafo — una limitación conocida de la ventana de ayuda.

Atajos de Teclado (W5–W6)

Ventana de atajos de teclado — cinco grupos Navigation/Views/Capture/Editor/Training con columna de teclas a la izquierda y descripción a la derecha
Ventana de atajos de teclado — cinco grupos Navigation/Views/Capture/Editor/Training con columna de teclas a la izquierda y descripción a la derecha

Lista de referencia estática en cinco secciones. Navigation: Mouse Drag (Orbit/Fly), Shift+Drag/Right-Drag (Pan), Scroll (Zoom), WASD (movimiento Fly-Through), Q/E (Up/Down), F (Toggle Orbit/Fly), Double-click (Re-center), Cmd+Scroll (ajuste de FoV). Views: R (Reset Camera), T (Auto-Rotation), P (Camera Playback), B (Background-Cycle), 0–9 (saltar a Training-Cam 1=10%/5=50%/0=último), Left/Right Arrow (Prev/Next Cam). Capture: S (Screenshot to Desktop), V (Turntable-Video), C (Copy Camera Info). Editor: Tab (modo edición), Click/Drag (Paint-Select), Option+Click (Deselect), X / Delete (eliminar selección), Cmd-Z (deshacer última eliminación), [ / ] (reducir/aumentar tamaño de pincel), Esc (deseleccionar). Training: Option+Space (pausar/reanudar entrenamiento), Cmd+E (exportar escena). Aquí no hay nada más — Start, Cancel y las extensiones las encuentras en el menú Training (Capítulo 1).

Qué es: Una sencilla vista general estática de todos los atajos de teclado — Navigation, Views, Capture, Editor, Training. El contenido está integrado de forma fija y no se carga desde un archivo.

Cuando busques la forma más rápida de hacer algo en el Viewport. WASD-Fly-Through, R para Camera-Reset, B para el Background-Cycling — todo está aquí.

W5ScrollView (área de contenido)

DÓNDE

Help → Keyboard Shortcuts (⌘/).

TÉCNICO

Un área de desplazamiento simple con una lista vertical dentro. Padding de 20 alrededor, sin árbol de navegación lateral (la lista es lo bastante corta). El contenido está agrupado en cinco secciones (Navigation, Views, Capture, Editor, Training). Por cada combinación de teclas hay una fila con texto traducible en ambas columnas. La columna izquierda (código de tecla) está fijada a un ancho de 180 pt, de modo que las descripciones a la derecha queden alineadas verticalmente. Sin interacción salvo el desplazamiento — hacer clic en una fila no desencadena nada, los atajos de teclado son modificadores de teclado reales en el menú y en el Viewport.

W6VStack (secciones de atajos)

DÓNDE

Dentro del ScrollView.

TÉCNICO

Secciones apiladas alineadas a la izquierda con 16 pt de separación. Dentro de las cinco secciones hay respectivamente un encabezado + una secuencia de filas. Los encabezados usan un estilo secundario de subtítulo — deliberadamente sin formato de título, porque las secciones no necesitan ser navegables. El contenido es deliberadamente plano (sin disclosure, sin búsqueda, sin filtro), para que el componente funcione sin cambios en cualquier versión de macOS y el archivo siga siendo legible.

Gestionar almacenamiento (W7–W12)

Ventana Manage Storage — el encabezado muestra „1,356 items · 55.1 GB total”, tabla con archivos de exportación PLY ordenados por fecha, cada uno con icono + nombre de archivo + tamaño + fecha
Ventana Manage Storage — el encabezado muestra „1,356 items · 55.1 GB total", tabla con archivos de exportación PLY ordenados por fecha, cada uno con icono + nombre de archivo + tamaño + fecha

Vista de tabla de todos los archivos gestionados por RadianceKit. El encabezado cuenta 1.356 elementos, 55,1 GB en total. Barra de herramientas arriba: „Show in Finder" + „Refresh". Cada fila: icono de exportación, nombre de archivo (p. ej. training_20260718T194416Z.ply), fecha de exportación, tamaño (aquí varía entre 7,8 MB y 2,24 GB), icono de lupa (Reveal) e icono de papelera (Move to Trash). El orden es primero por categoría y dentro de una categoría por fecha, la más reciente arriba. En esta captura predominan las exportaciones PLY, porque en este almacenamiento se guardaron sobre todo resultados de entrenamiento.

Qué es: Una vista general del uso del disco para todo lo que RadianceKit guarda en ~/Documents/RadianceKit/ — registros, exportaciones, escenas, paquetes de captura (del acompañante para iOS), importaciones (copias de staging de las imágenes de entrada). Por cada entrada hay un tamaño en bytes y dos botones: „mostrar en el Finder" y „mover a la papelera". NO es una limpieza automática — la app no elimina nada por sí misma; tú decides por cada entrada. Esta ventana está traducida: en alemán se llama „Speicher verwalten", los dos botones del encabezado se llaman „Im Finder anzeigen" y „Aktualisieren", los botones de fila „Im Finder anzeigen" y „In den Papierkorb legen". Los nombres en inglés en las entradas de abajo son las designaciones de la versión en inglés.

Cuando el disco se llena. Sobre todo los registros se acumulan (un JSONL por cada intento de entrenamiento, más el _qualityMetrics.json); las exportaciones también, por supuesto (PLY es 100% datos crudos, uno por exportación). También es útil después de un fallo, cuando el directorio de staging de importaciones todavía tiene copias antiguas de las imágenes de entrada por ahí.

W7Botón „Show in Finder"

DÓNDE

Encabezado, arriba a la derecha en la ventana del navegador de almacenamiento.

TÉCNICO

Abre la carpeta de datos de RadianceKit en el Finder — exactamente el directorio cuyo contenido lista esta ventana. Así ves la estructura de carpetas (Logs, Exports, Scenes, Captures, Imports) directamente y también puedes mover o copiar los archivos con el propio Finder. La acción abre una nueva ventana del Finder; la lista de la ventana no cambia con ello — para eso está „Refresh" (W8).

W8Botón „Refresh"

DÓNDE

Encabezado, junto al botón del Finder.

TÉCNICO

Dispara un escaneo en segundo plano que se ejecuta en una tarea asíncrona iniciada por el usuario, para que el escaneo de árboles de directorios grandes no bloquee la interfaz. El recorrido en sí pasa por cada subcarpeta conocida (Logs, Exports, Scenes, Captures, Imports) y genera una entrada de almacenamiento por cada hijo directo. Para cada entrada se determina el tamaño recursivo — preferiblemente el consumo real de disco (incluyendo el uso compartido de hardlinks de APFS) con reserva en el tamaño lógico del archivo.

W9List (entradas de almacenamiento)

DÓNDE

Contenido principal debajo del encabezado.

TÉCNICO

Lista con este diseño por fila: icono SF Symbol específico de la categoría (documento para Logs, flecha hacia arriba para Exports, cubo para Scenes, iPhone para paquetes de captura, bandeja para Imports), nombre + subtítulo (etiqueta de tipo + fecha de modificación formateada), contador de bytes a la derecha (alineado a la derecha, monoespaciado), botón Reveal (icono de lupa), botón Trash (papelera). Orden: primero por tipo (Scenes primero, luego Exports, Logs, Captures, Imports, Other), en segundo lugar por fecha de modificación descendente (la más reciente arriba). Si el escaneo todavía está en curso, en ese lugar se muestra en su lugar un progreso „Scanning…". Si no se encontró nada, se muestra un estado vacío con icono de bandeja.

W10Botón de fila „Reveal in Finder"

DÓNDE

Por fila, icono de lupa a la derecha.

TÉCNICO

Abre el Finder y selecciona el elemento específico (archivo o carpeta). Diferencia con W7: W7 abre el directorio raíz; W10 marca exactamente esa única entrada. Flujo de trabajo práctico: identifica una entrada grande, haz clic en la lupa, luego cópiala, por ejemplo, a un volumen externo.

W11Botón de fila „Move to Trash"

DÓNDE

Por fila, icono de papelera a la derecha, junto a la lupa.

TÉCNICO

Desencadena el cuadro de diálogo de confirmación (W12). Solo después de confirmar se ejecuta la operación estándar de macOS „mover a la papelera" (es decir, reversible, sin eliminación directa). Tras el traslado exitoso a la papelera, la entrada se elimina de la lista y se actualiza el contador total de bytes. En caso de error se muestra un diálogo de error modal.

W12ConfirmationDialog (confirmación de eliminación)

DÓNDE

Se activa mediante W11, se muestra como una hoja (sheet) de macOS.

TÉCNICO

Diálogo de confirmación estándar con título dinámico „Delete <name>?" y una línea de mensaje que indica explícitamente que la entrada irá a la papelera y podrá restaurarse desde allí (hasta que se vacíe la papelera). Dos botones: „Move to Trash" como acción destructiva (mostrada en rojo) y „Cancel" con vinculación automática a la tecla Esc. El diálogo es no modal en el sentido de que solo bloquea esta ventana, no toda la app — eso es el estándar de macOS para eliminaciones reversibles.

Ventana principal: historial de pérdida y recuento de gaussianas (I39–I41, referencia cruzada)

Tres de las visualizaciones del Inspector en la ventana principal merecen una explicación propia, porque se ven constantemente durante un entrenamiento en curso y existen reglas prácticas importantes sobre cuándo el historial se ve saludable. Las visualizaciones se encuentran en el Inspector, en la sección Progreso, en el grupo desplegable Historial de pérdida (ver Capítulo 2 — Inspector), y ayudan a interpretar el progreso del entrenamiento.

¿Cuándo es saludable la curva de pérdida? Una curva de pérdida saludable muestra tres fases: (1) Calentamiento — en las primeras 200–500 iteraciones, la pérdida cae bruscamente desde un valor alto (típicamente 0.15–0.25 para L1+SSIM combinado, según la escena) hasta aproximadamente la mitad. Si la pérdida NO cae en esta fase, normalmente la entrada es incorrecta (imágenes dañadas, poses SfM deficientes, número de gaussianas iniciales demasiado bajo). (2) Densificación — entre ~500 y densifyUntilIteration (clásicamente 15K, MCMC hasta 20K o 25K), la pérdida sigue bajando, a menudo con pequeños saltos hacia abajo cuando las operaciones de densificación insertan nuevas gaussianas y el optimizador las aprovecha. El recuento de gaussianas aumenta en esta fase. (3) Refinamiento — después, la pérdida entra en una cola cada vez más plana. Valores finales típicos como orientación: una escena de objeto bien iluminada (por ejemplo, Tanks-&-Temples Truck con P4 Calidad) se sitúa en L1 ≈ 0.023, mientras que escenas exteriores amplias como las de Mip-NeRF 360 se mantienen naturalmente por encima (0.04–0.07).

¿Qué significa una meseta? Una meseta (la curva de pérdida transcurre horizontalmente durante varios miles de iteraciones) tiene dos interpretaciones: (a) el modelo ha convergido, seguir entrenando ya no aporta nada — este es el caso bueno. (b) el modelo está atascado (mínimo local, información de gradiente deficiente, un límite en el buffer) — el caso malo. Ambos se ven idénticos en el gráfico. Para distinguirlos: observa el recuento de gaussianas. Si también es plano Y está cerca del límite de MCMC (por ejemplo, 150K de 150K en el preset P8 Calidad (MCMC)), has llegado al límite — o subes el límite o aceptas la meseta. Si el recuento de gaussianas sigue creciendo pero la pérdida no baja, entonces está atascado.

¿Cuándo interrumpir y cuándo seguir entrenando? Regla práctica: si durante 10K iteraciones no hay mejora en la pérdida mínima → interrumpe, más iteraciones son desperdiciadas. Antes de eso: en el menú Entrenamiento → Continuar entrenamiento → «+5,000 iterations» puedes añadir una prórroga si observas una mejora marginal (no hay atajo de teclado para esto). Atención: en MCMC la meseta suele ser real — el límite es la frontera natural.

Una meseta en el recuento de gaussianas NO es una señal de «terminado». Solo significa que MCMC ha alcanzado su límite o que la Densificación Clásica está agotada. La pregunta real de si «está terminado» solo la responden PSNR/SSIM/LPIPS en un conjunto de prueba independiente. El conjunto de prueba independiente también muestra si tu conjunto de cámaras permite una división justa entre ángulos de entrenamiento y de prueba.

PSNR/Holdout es la verdad, la pérdida es solo un indicador indirecto. La pérdida es una métrica relativa: cae mientras tu modelo se ajusta a las vistas de entrenamiento. Sin embargo, una pérdida baja no significa automáticamente un buen modelo — si el modelo ha memorizado las imágenes de entrenamiento (sobreajuste), la pérdida sería pequeña, pero la PSNR en vistas no vistas (holdout) sería mala. Por eso: para la evaluación final de calidad, mira siempre las métricas de holdout, no solo la pérdida final.

Consejo práctico

  • La Guía del usuario y los Atajos de teclado son ayuda estática — útiles para consultas puntuales; para profundizar, usa este manual.
  • Abre Manage Storage en cuanto el disco baje del 10% de espacio libre. Los registros y el staging de importaciones suelen ser los culpables habituales.
  • El plateau de pérdida y el plateau de número de gaussianas deben interpretarse por separado. El límite máximo no es una señal de "terminado". La calidad real solo se mide con el PSNR de holdout.
  • 10K iteraciones sin mejora del min-loss → detén el entrenamiento.