Capítulo 10 — Modo principiante

DÓNDE

Arriba sobre el flujo, siempre visible.

TÉCNICO

Muestra una barra de progreso horizontal a lo largo de toda la pipeline (Frame Quality → SfM → Training) con asignación de etapas: Frame Quality ocupa 0–5 % (Fase 3.11, muy corta), SfM ocupa 0–30 % de la barra, Training 30–100 %. Junto a ella, texto de estado y visualización en porcentaje nombrada por fase ("SfM 41 %", "Training 12 500/20 000"), para que los usuarios no lean la aparente regresión "41 % SfM → 25 % Training" como un error — la barra muestra el progreso global de la pipeline, no el de la subetapa. El cálculo de ETA arranca en cuanto se mide suficiente velocidad de entrenamiento (típicamente tras las primeras 100 iteraciones). La misma visualización también se usa en el Modo Experto encima del Inspector.

DÓNDE

Lado izquierdo del paso Import, gran rectángulo discontinuo con símbolo. Se muestra en Modo principiante con la etiqueta "Drop photos or a video here".

TÉCNICO

Área de drop que rebota brevemente el símbolo y tiñe el fondo en cuanto los elementos arrastrados pasan sobre el campo. Acepta JPG, PNG, TIFF, HEIC, MP4, MOV, PLY, SPZ, .splat, paquetes .radiancescene y directorios. Enrutado de drop por tipo: las imágenes se recopilan y se pasan ordenadas, los vídeos disparan la vía de frame-sampling, los archivos splat abren la previsualización directamente, los paquetes de escena se leen. Los directorios se enumeran y se importan todas las imágenes contenidas. Los bookmarks security-scoped para acceso compatible con sandbox se adquieren y liberan correctamente. Las extensiones no soportadas se muestran como banner de aviso durante 5 segundos.

DÓNDE

Dentro de la zona de drop, botón prominente.

TÉCNICO

Botón que abre el diálogo de archivo de macOS con selección múltiple y los tipos de archivo JPG, PNG, TIFF, MP4, MOV, carpetas, así como el formato de escena propio de la app. Las URLs resultantes son security-scoped y se enrutan por las mismas vías de importación que arrastrar y soltar. Cuando el usuario selecciona una carpeta, se enumera recursivamente para imágenes.

DÓNDE

Dentro de la zona de drop, solo visible cuando el bundle de la app contiene la escena de muestra y aún no se han importado imágenes/splats.

TÉCNICO

Solo aparece cuando (a) un sample-scene.splat, .spz o .ply está presente en el bundle de la app Y (b) no se han importado imágenes/vídeos y no hay nube de puntos. Al hacer clic, carga la nube de puntos terminada (prefiriendo el formato más pequeño — .splat ~3 MB, .spz ~1,4 MB, fallback .ply) y, tras 400 ms, fija valores de cámara codificados en duro a partir de los metadatos originales de la escena de flores para una perspectiva de entrada estéticamente agradable.

DÓNDE

Dentro de la zona de drop, junto a "Try Sample Scene"; mismas condiciones de visibilidad.

TÉCNICO

Dispara una descarga (repo github.com/bkindler/radiancekit-sample-photos) que carga aprox. 427 MB de 960 fotogramas a resolución completa y los mete en la app. Durante la descarga, el botón se deshabilita. El progreso aparece en la barra de progreso superior como "Downloading X %" en su propia etapa, porque esa etapa mantiene su propia escala 0–100 % y no se solapa con la posterior etapa SfM.

DÓNDE

Barra de herramientas flotante inferior del overlay de importación, a la izquierda del botón Start.

TÉCNICO

Control con etiqueta "Quality" agrupa los ajustes preestablecidos disponibles por categoría (Classic / MCMC / Custom). Los ajustes integrados se agrupan por categoría; las cabeceras de sección están codificadas en duro. Los ajustes custom solo visibles cuando existe alguno. Estado bloqueado: los ajustes que no están en la lista gratuita (Quick + Preview) reciben un sufijo "🔒" junto al nombre cuando el usuario no ha comprado; al seleccionar, el selector vuelve a Preview y abre automáticamente el sheet de compra. Al seleccionar, el ajuste se aplica, lo que reemplaza toda la configuración de entrenamiento.

DÓNDE

Barra de herramientas flotante inferior del overlay de importación, a la derecha del selector de ajustes.

TÉCNICO

Botón que se mantiene atenuado mientras no se hayan importado imágenes ni un vídeo. Al hacer clic, arranca la pipeline y cambia la máquina de etapas en el orden Frame Quality → SfM → Training. El propio botón no tiene más estado; un procesado en curso aparece en su lugar como pantalla de procesado separada.

DÓNDE

Lista de imágenes a la derecha, visible solo cuando se ha importado un vídeo (en lugar de imágenes).

TÉCNICO

Deslizador 0,5 fps – 30 fps en pasos de 0,5. Al cambiar, la densidad de fotogramas se actualiza y, además, se calcula el número de fotogramas objetivo (al menos 10) a partir de densidad y duración del vídeo. El deslizador queda fuera de la lista de imágenes, porque los ítems de lista bloquearían eventos de ratón de los deslizadores. Bajo el deslizador se muestran los fotogramas objetivo calculados ("247 frames") y la duración del vídeo ("1m23s video"). El tooltip avisa: "Doubling the density doubles the number of frames and increases SfM time by ~100%."

DÓNDE

Lista de imágenes a la derecha, abajo a la derecha; visible solo cuando se han importado imágenes.

TÉCNICO

Botón rojo. El clic abre un diálogo de confirmación con título "Clear all imported files?" y mensaje "N images will be removed.". La confirmación borra todas las imágenes/vídeos importados, los directorios de staging, la nube de puntos, el estado de entrenamiento, el resultado de SfM y todos los cachés; la etapa salta de vuelta a Import. En Cancel, todo se conserva. El diálogo se configura como vía predeterminada no destructiva (botón destructivo marcado en rojo).

DÓNDE

Lista de imágenes a la derecha, cada entrada.

TÉCNICO

Lista sobre las imágenes importadas con swipe-to-delete. Por imagen una fila con icono, nombre de archivo, resolución ("1920 × 1080") y tamaño de archivo (formateado KB/MB). La resolución viene de una caché de metadatos rellenada de forma asíncrona desde las cabeceras de imagen, para que la UI no bloquee. La acción de borrado ofrece el borrado por swipe típico de macOS (swipe a la izquierda en una fila con trackpad), así como borrado por teclado para la fila seleccionada. Nota: la vía extendida de borrado de imagen con botón menos explícito, backspace y Cmd-Z para deshacer se añadió solo en Modo Experto en el Project Navigator — en Modo principiante se queda con el borrado por swipe.

DÓNDE

Bajo la lista de imágenes, sobre el botón Clear All.

TÉCNICO

Tres umbrales sucesivos basados en el número de imágenes importadas (solo activos cuando hay imágenes y no vídeo): - < 3 imágenes: banner rojo (octógono rojo), texto "At least 3 images are required. Camera alignment cannot be computed from fewer images." - 3–9 imágenes: banner rojo, texto "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 imágenes: banner naranja (triángulo de aviso), texto "Workable, but quality usually improves with 20+ images and good coverage around the scene."

A partir de 20 imágenes el banner desaparece. Los umbrales están codificados en duro y se basan en más de 560 experimentos de entrenamiento empíricos.

DÓNDE

Al soltar una carpeta — no un botón visible, sino lógica de detección.

TÉCNICO

Al soltar un directorio se comprueba si contiene uno de los tres layouts canónicos de workspace: sparse/0/cameras.bin, sparse/cameras.bin o directamente cameras.bin en la raíz. Si es así, la enumeración estándar de imágenes se aborta y en su lugar se abre un alert modal preguntando al usuario si se debe usar la reconstrucción existente o si las imágenes deben pasarse de nuevo por Apple Photogrammetry. Misma vía también para workspaces en formato de texto (cameras.txt) y exportaciones ETH3D. Véase el backend Q6 del Capítulo 9 para detalles. Funciona en Modo principiante igual que en Modo Experto.

DÓNDE

Fondo a pantalla completa tras el círculo de progreso, oculto al cancelar o en error.

TÉCNICO

Animación decorativa que, según el progreso de la pipeline (0…1), renderiza un número creciente de pequeñas partículas splat animadas. La fuente es un valor de progreso calculado que mapea las fases SfM a 0–0,2 y el entrenamiento a 0,2–1,0 (Frame Quality a 0–0,05). De este modo los splats visiblemente "se construyen" mientras corre el entrenamiento. Puramente decorativo — la visualización no muestra resultados intermedios reales del entrenamiento actual (eso sería la live preview en Modo Experto). En cancel o fallo se oculta y solo se mantiene visible el círculo de estado.

DÓNDE

Centro de la pantalla de procesado, 220 × 220 píxeles.

TÉCNICO

Dos anillos renderizados uno sobre otro: por fuera un anillo de pista atenuado, por dentro un anillo de progreso relleno con stroke de acento o rojo (rojo en error). Dentro del círculo, un icono de etapa (cerebro para entrenamiento, cámara para SfM, película para extracción de fotogramas de vídeo, destellos para Frame Quality), título de etapa y el número de porcentaje animado en vivo en fuente redondeada de 32 puntos. El icono pulsa suavemente mientras el procesado está activo. La visualización interpola en un timer de 30 Hz de forma suave hacia el progreso real actual — con un "creep" constante (0,0003/frame) más un share proporcional (4 % del gap) y un techo suave que se fija al 80 % del siguiente hito esperado (para SfM a partir de una tabla de hitos codificada). De este modo el progreso se siente fluido, incluso si las actualizaciones SfM reales solo llegan cada pocos segundos.

DÓNDE

Arriba a la izquierda en la pantalla de procesado, 32 × 32 píxeles.

TÉCNICO

Botón simple con fondo material. Conmuta el panel de info on/off. El icono cambia entre info-circle outline e info-circle filled cuando está activo. Animación de fade-in suave. Tooltip "Show detailed processing metrics".

DÓNDE

Abajo a la izquierda en la pantalla de procesado, visible solo cuando showProcessingInfo == true.

TÉCNICO

Panel de dos columnas con fondo material ultradelgado. Columna izquierda: líneas de info específicas de etapa — para SfM, texto de estado y porcentaje; para entrenamiento, iteración, loss combinado, loss L1, loss D-SSIM, número de Gaussianos (coloreado en naranja), velocidad (it/s), tiempo transcurrido, ETA calculado, grado SH y learning rate. Columna derecha: texto de estado, string de info de tiempo, gráfico de loss inline (véase C-28) y un discoverability nudge (véase C-32). Todos los valores se leen del estado de entrenamiento, que se actualiza en cada tick de entrenamiento.

DÓNDE

Barra de navegación inferior, visible solo durante la etapa de entrenamiento (NO durante SfM) y mientras corre el procesado.

TÉCNICO

Botón con borde. Llama a Pause o Resume según el estado. La etiqueta cambia entre "Pause" (con icono de pausa) y "Resume" (icono de play). Durante el paso SfM el botón no se muestra, porque Apple Photogrammetry no tiene semántica de pausa. El estado de pausa preserva por completo la iteración, el estado de Gaussianos y el momentum del optimizador — Resume continúa donde se detuvo previamente.

DÓNDE

Barra de navegación inferior, visible mientras corre el procesado (SfM o entrenamiento).

TÉCNICO

Botón rojo con borde. Abre un diálogo de confirmación con título "Stop and discard progress?", botones "Discard Progress" (destructivo) y "Keep Running" (cancel). En la confirmación se fija la cancel flag, se termina la tarea de entrenamiento, se termina el subproceso SfM si procede, y se escribe una línea de resumen con estado de cancelación en el log JSONL. A diferencia de Pause, los buffers y el estado de entrenamiento se descartan.

DÓNDE

Barra de navegación inferior, visible cuando la pipeline ha fallado (el estado SfM empieza con "SfM failed" o el entrenamiento está en estado de error).

TÉCNICO

Botón de acento. Reinicia toda la pipeline. Antes de arrancar se comprueba si aún están presentes las imágenes/vídeos importados. Los logs de error anteriores se mantienen en el directorio JSONL; un nuevo run escribe un nuevo archivo de log con la marca de tiempo actual.

DÓNDE

En el panel de info, columna derecha, visible solo durante el entrenamiento con historial no vacío.

TÉCNICO

Área de dibujo compacta (40 píxeles de alto), dibuja el historial de loss como línea de 1 píxel en color de acento. Los datos se filtran a valores finitos (protección NaN para entrenamientos inestables). Min/Max se calculan sobre todo el historial — el gráfico hace así auto-zoom al rango de valores. El último valor de loss queda arriba a la derecha sobre el gráfico. El propio historial se construye en el estado de la app en cada tick de entrenamiento (típicamente cada 100 iteraciones).

DÓNDE

En el panel de info, columna derecha abajo, visible solo durante el entrenamiento Y en Modo principiante.

TÉCNICO

Línea pequeña con icono de ojo y texto de caption "Switch to Expert Mode (⌘2) for live splat preview", en tono discreto y fuente de 10 puntos. Sin elemento interactivo, solo una pista. No reacciona al clic — el usuario tiene que pulsar realmente Cmd+2 o hacer clic en el menú Mode → Expert Mode.

DÓNDE

Fondo a pantalla completa del paso de previsualización.

TÉCNICO

Vista 3D basada en Metal que renderiza la nube de puntos terminada. El renderer es el fork de MetalSplatter vendored con fixes RadianceKit para popping/flickering. Pipeline de renderizado basado en tiles con transparencia independiente del orden. Si el renderer no puede inicializarse (p. ej., porque Metal no está disponible en el sistema), aparece en su lugar un fondo negro con texto "Metal not available". La vista ignora el safe area, para que el modelo llegue al borde de la ventana.

DÓNDE

Sobre la vista, flotante.

TÉCNICO

Overlay UI compacto con botones para auto-rotación (turntable), reset de cámara, elección de fondo (gris/negro/blanco), guardar captura, toggle del panel de info. Vincula a los parámetros de cámara (distancia, azimut, elevación, target, FOV) y controla el auto-turntable. Durante el entrenamiento (cuando el usuario en Modo Experto quiere ver la vista corriendo en paralelo), el overlay muestra además una línea compacta de estado de entrenamiento.

DÓNDE

Barra de navegación inferior en Z3.

TÉCNICO

Botón de acento con etiqueta "Export" e icono de share. El clic dispara el cambio a Z4. Antes, la vista padre comprueba si la versión completa está desbloqueada — si no, en lugar de la etapa de exportación se muestra la vista de lock (véase U-06).

DÓNDE

Lado principal izquierdo del paso de exportación.

TÉCNICO

Cuadrícula de tarjetas con dos columnas flexibles y 12 puntos de espaciado. Itera sobre los formatos ofrecidos en Modo principiante — un subconjunto filtrado de la lista completa de formatos que contiene solo los 6 más importantes: PLY, SPZ, glTF, .splat, vídeo orbital, visor web. Compressed PLY y SOG se ofrecen SOLO en Modo Experto.

DÓNDE

Cada tarjeta en la cuadrícula.

TÉCNICO

Botón simple con layout de tarjeta: icono (p. ej., document zipper para PLY, archive box para SPZ, icono de vídeo para vídeo orbital) arriba, nombre de formato como headline, caption de descripción (truncado a 2 líneas), debajo el tamaño de archivo estimado (calculado en vivo a partir de formato, número de Gaussianos y grado SH y formateado como KB/MB). Al hacer clic se selecciona el formato. La tarjeta seleccionada recibe un fondo de acento, borde de acento y un icono de check arriba a la derecha. El tooltip es la descripción del formato.

DÓNDE

Bajo la cuadrícula de formatos, visible solo cuando se elige un formato de vídeo (vídeo orbital o vídeo social).

TÉCNICO

Deslizador 3–30 segundos en pasos de 1 segundo, vincula a la duración del vídeo en el estado de la app. Ancho máximo 300 píxeles. Solo se muestra cuando se selecciona un formato de vídeo. Para formatos no de vídeo, el deslizador se elimina por completo de la vista — sin espacio muerto.

DÓNDE

Bajo la cuadrícula de formatos (y bajo el deslizador de duración, si se eligió vídeo).

TÉCNICO

Gran botón de acento. Etiqueta: "Export {format-name}", icono de share. Al hacer clic se abre el diálogo de guardar de macOS con una extensión adecuada al formato y nombre predeterminado "scene.{ext}"; en la confirmación, la exportación se escribe en la URL elegida. Deshabilitado cuando no hay resultado de entrenamiento o ya está corriendo una exportación.

DÓNDE

Bajo el botón Export, visible solo mientras corre una exportación.

TÉCNICO

Visualización de progreso con ancho máximo 300 píxeles, debajo el caption "Exporting… N %". El valor corre de 0 a 1 y se actualiza durante la escritura — con PLY en chunks de 10 000 Gaussianos, con SPZ una vez tras la cuantización, con vídeo orbital en intervalos de frame.

DÓNDE

Bajo la barra de progreso, visible solo cuando ocurrió un error durante la última exportación.

TÉCNICO

Línea roja con icono de aviso y texto de error. Fondo rojo con opacidad del 8 %, esquinas redondeadas. Ancho máximo 400 píxeles. Causas comunes de error: SOG espera cwebp en el PATH del sistema (no compatible con App Store); error de escritura con espacio de disco lleno; error de sandbox con destinos de guardado fuera del área permitida.

DÓNDE

Lado derecho del paso de exportación.

TÉCNICO

Lista sobre el historial de exportación (persistente como JSON en los UserDefaults, mantenida tras cada exportación exitosa). Cada fila muestra insignia de formato (pequeña, color de acento), marca de tiempo (HH:mm), nombre de archivo (truncado a 1 línea) y tamaño formateado. El clic en una fila abre Finder con el archivo seleccionado. Estado vacío: "No exports yet".

DÓNDE

Clic derecho en una fila del historial.

TÉCNICO

Menú contextual en cada entrada de la lista con dos acciones: "Reveal in Finder" (abre Finder con archivo seleccionado, como el clic simple) y "Copy Path" (coloca la ruta de archivo completa como texto en el portapapeles). Lo último es útil para arrastrar y soltar en otras apps o para pasar a la línea de comandos.