Capítulo 10 — Modo principiante

DÓNDE

En la barra del borde superior de la ventana, a la izquierda del selector de modo. Solo visible en el modo para principiantes.

TÉCNICO

Muestra las seis etapas de la canalización como una cadena de botones consecutivos, cada uno con un símbolo y un nombre, separados por una flecha: Import → Frame Quality → Cameras → Training → Preview → Export. La etapa actual se muestra con color pleno, las etapas ya completadas semitransparentes, las etapas aún no alcanzadas en gris. Las etapas ya completadas se pueden pulsar y llevan de vuelta a ellas; la etapa actual y todas las aún no alcanzadas están desactivadas, al igual que toda la cadena mientras se ejecuta un procesamiento. Ya no existe una barra de progreso continua en porcentaje para toda la canalización — el progreso de la etapa en curso lo muestra el gran círculo en la pantalla de procesamiento (C-19).

DÓNDE

Lado izquierdo del paso de import, gran rectángulo discontinuo con símbolo. Se muestra en el modo para principiantes con la etiqueta „Drop photos or a video here".

TÉCNICO

Zona de suelta que hace saltar brevemente el símbolo y colorea el fondo en cuanto los elementos arrastrados flotan sobre el campo. Acepta JPG, PNG, TIFF, HEIC, MP4, MOV, PLY, SPZ, .splat, paquetes .radiancescene y directorios. Enrutamiento por tipo al soltar: las imágenes se recopilan y se pasan ordenadas, los videos activan la ruta de muestreo de fotogramas, los archivos splat abren directamente la vista previa, los paquetes de escena se leen. Los directorios se enumeran y se importan todas las imágenes contenidas. Los marcadores con ámbito de seguridad para el acceso conforme al sandbox se toman y liberan correctamente. Las extensiones no compatibles se muestran como un aviso de advertencia durante 5 segundos.

DÓNDE

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

TÉCNICO

Botón que abre el diálogo de archivos de macOS con selección múltiple y los tipos de archivo JPG, PNG, TIFF, MP4, MOV, carpeta así como el formato de escena propio de la aplicación. Las URL resultantes son con ámbito de seguridad y se enrutan por las mismas rutas de import que arrastrar y soltar. Si el usuario selecciona una carpeta, esta se enumera recursivamente en busca de imágenes.

DÓNDE

Dentro de la zona de arrastre, visible solo si el paquete de la aplicación contiene la escena de ejemplo y aún no se han importado imágenes/splats.

TÉCNICO

Aparece solo si (a) hay una sample-scene.splat, .spz o .ply presente en el paquete de la aplicación Y (b) aún no se han importado imágenes/videos y aún no existe una nube de puntos. Al hacer clic carga la nube de puntos ya terminada (se prefiere el formato más pequeño — .splat ~3 MB, .spz ~1.4 MB, alternativa .ply) y establece después de 400 ms valores de cámara codificados a partir de los metadatos originales de la escena de flores para una perspectiva de entrada estéticamente sensata.

DÓNDE

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

TÉCNICO

Descarga un conjunto de ejemplo proporcionado por RadianceKit desde internet: aproximadamente 427 MB de 960 fotogramas de resolución completa, que a continuación se descomprimen y se incorporan directamente a la aplicación. Mientras se ejecuta otro procesamiento, el botón está desactivado y la descarga no se inicia. El progreso de carga no se muestra en la interfaz como porcentaje; que la descarga haya terminado se reconoce porque la lista de imágenes de la derecha se llena con los 960 fotogramas.

DÓNDE

Barra de herramientas flotante inferior de la superposición de import, a la izquierda del botón de inicio.

TÉCNICO

Selector de menú con la etiqueta „Quality", que agrupa los ajustes preestablecidos incluidos por categoría en cuatro secciones: „Classic", „MCMC (fewer Gaussians, slower)", „Hybrid (sharp detail, compact)" y „Capture — curated real-world (Drone / 360° / Photo)". Se añade una quinta sección „Custom" en cuanto se desbloquea la versión completa y se ha guardado al menos un ajuste preestablecido propio. Estado bloqueado: todos los ajustes preestablecidos excepto Quick y Preview reciben un sufijo „🔒" en el nombre si el usuario no posee la versión completa; al seleccionarlo, el selector vuelve a Preview y abre automáticamente la ventana de compra. Al elegir, se aplica el ajuste preestablecido, lo que reemplaza toda la configuración de entrenamiento.

DÓNDE

Barra de herramientas flotante inferior de la superposición de import, a la derecha del selector de ajustes preestablecidos.

TÉCNICO

Botón que permanece en gris mientras no se hayan importado ni imágenes ni un video. Al hacer clic inicia la canalización y conmuta la máquina de etapas a la secuencia Frame-Quality → SfM → Training. El propio botón no tiene ningún otro estado; un procesamiento en curso aparece en cambio como una pantalla de procesamiento separada.

DÓNDE

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

TÉCNICO

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

DÓNDE

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

TÉCNICO

Botón rojo. Al hacer clic se abre un diálogo de confirmación con el título „Clear all imported files?" y el mensaje „N images will be removed.". Al confirmar se vacían todas las imágenes/videos importados, los directorios de preparación, la nube de puntos, el estado de entrenamiento, el resultado de SfM y todas las cachés; la etapa vuelve al import. Con Cancel todo se conserva. El diálogo está configurado como camino por defecto no destructivo (el botón destructivo marcado en rojo).

DÓNDE

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

TÉCNICO

Lista sobre las imágenes importadas con deslizar para eliminar. Por imagen una fila con icono, nombre de archivo, resolución („1920 × 1080") y tamaño de archivo (formateado en KB/MB). La resolución proviene de una caché de metadatos, que se rellena de forma asíncrona a partir de las cabeceras de imagen para que la interfaz no se bloquee. Se elimina mediante el gesto típico de macOS de deslizar para eliminar (deslizar con el trackpad hacia la izquierda sobre una fila); la lista no admite selección de filas, por lo que aquí no existe un borrado por teclado. Nota: la ruta ampliada de eliminación de imágenes con botón de menos explícito, retroceso y Cmd-Z para deshacer se añadió solo en el modo experto en el Project Navigator — en el modo para principiantes se mantiene el deslizar para eliminar.

DÓNDE

Debajo de la lista de imágenes, encima del botón Clear All.

TÉCNICO

Tres umbrales consecutivos basados en la cantidad de imágenes importadas (activo solo si hay imágenes y no hay video): - menos de 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 advertencia), 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 y se basan en experimentos empíricos de más de 560 entrenamientos.

DÓNDE

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

TÉCNICO

Al soltar un directorio, se comprueba si contiene uno de los tres diseños canónicos de espacio de trabajo: sparse/0/cameras.bin, sparse/cameras.bin o directamente cameras.bin en la raíz. Si es así, se interrumpe la enumeración estándar de imágenes y en su lugar se abre una alerta modal que pregunta al usuario si debe usarse la reconstrucción existente o si las imágenes deben pasarse de nuevo por Apple Photogrammetry. La misma ruta también para espacios de trabajo en formato texto (cameras.txt) y exportaciones ETH3D. Ver el capítulo 9 Backend Q6 para más detalles. Funciona igual en el modo para principiantes que en el modo experto.

DÓNDE

Fondo a pantalla completa detrás del círculo de progreso, oculto al cancelar o en caso de error.

TÉCNICO

Animación decorativa que, según el progreso de la pipeline (0…1), renderiza una cantidad creciente de pequeñas partículas splat animadas. La fuente es un valor de progreso calculado que asigna las fases de SfM a 0–0.2 y el entrenamiento a 0.2–1.0 (Frame-Quality a 0–0.05). Así los splats se "construyen" visiblemente mientras avanza el entrenamiento. Es puramente decorativa — la visualización no muestra resultados intermedios reales del entrenamiento actual (eso sería la vista previa en vivo en el modo experto). Al cancelar o en caso de fallo se oculta y solo permanece visible el círculo de estado.

DÓNDE

En el centro de la pantalla de procesamiento, 220 × 220 píxeles.

TÉCNICO

Dos anillos renderizados uno sobre el otro: por fuera un anillo de referencia atenuado, por dentro un anillo de progreso relleno con trazo de acento o rojo (rojo en caso de error). El anillo sigue el progreso real de la etapa en curso de forma directa (suavizado mediante una breve animación de entrada/salida), para que la visualización coincida con la línea de progreso del modo experto. Dentro del círculo hay un icono de etapa (cerebro para el entrenamiento, cámara para SfM, película para la extracción de fotogramas de video, destellos para la verificación de calidad de los fotogramas, globo terráqueo al desenvolver material de 360°), el título de la etapa y el número de progreso. Este número es, durante el entrenamiento, el contador de iteraciones ("12 500/20 000"), en todas las demás etapas un porcentaje. El icono pulsa suavemente mientras el procesamiento está activo. En caso de error, el título cambia a la etapa que falló ("Structure from Motion Failed", "Training Failed"), el anillo y el número se ponen en rojo. Tras una cancelación, el círculo muestra en cambio una cruz naranja con "Cancelled!".

DÓNDE

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

TÉCNICO

Botón sencillo con fondo de material. Activa o desactiva el panel de información. El icono alterna entre círculo de información con contorno y círculo de información relleno cuando está activo. Animación de aparición suave. En el tooltip "Show detailed processing metrics".

DÓNDE

Abajo a la izquierda en la pantalla de procesamiento, visible solo cuando los detalles de procesamiento están mostrados.

TÉCNICO

Panel de dos columnas con fondo de material ultra-fino. Columna izquierda: líneas de información específicas de la etapa — para SfM texto de estado y porcentaje; para el entrenamiento iteración, Loss combinado, Loss L1, Loss D-SSIM, recuento de Gaussians (coloreado en naranja), velocidad (it/s), tiempo transcurrido, ETA calculada, grado SH y tasa de aprendizaje. Columna derecha: texto de estado, cadena de información de tiempo, gráfico de Loss inline (ver C-28) y un aviso de descubribilidad (ver C-32). Todos los valores se leen del estado del 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 dure el procesamiento.

TÉCNICO

Botón con borde. Invoca Pause o Resume según el estado. La etiqueta cambia entre "Pause" (con icono de pausa) y "Resume" (icono de reproducción). Durante el paso SfM el botón no se muestra, porque Apple Photogrammetry no conoce la semántica de pausa. El estado de pausa conserva por completo la iteración, el estado de los Gaussians y el momentum del optimizador — Resume continúa exactamente donde se detuvo antes.

DÓNDE

Barra de navegación inferior, visible mientras el procesamiento está en curso (SfM o entrenamiento).

TÉCNICO

Botón con borde en rojo. Abre un diálogo de confirmación con el título "Stop and discard progress?", botones "Discard Progress" (destructivo) y "Keep Running" (Cancel). Al confirmar se establece el indicador de cancelación, se termina la tarea de entrenamiento, se finaliza el subproceso de SfM si es necesario, y se escribe una línea de resumen con el estado de cancelación en el registro JSONL. A diferencia de Pause, el búfer de entrenamiento y el estado se descartan.

DÓNDE

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

TÉCNICO

Botón de acento. Reinicia toda la pipeline. Antes del inicio se comprueba si todavía hay imágenes/videos importados disponibles. Los registros de error anteriores se conservan en el directorio JSONL; una nueva ejecución escribe un nuevo archivo de registro con la marca de tiempo actual.

DÓNDE

En el panel de información, columna derecha, visible solo durante el entrenamiento con un historial no vacío.

TÉCNICO

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

DÓNDE

En el panel de información, columna derecha abajo, visible solo durante el entrenamiento Y en el modo principiante.

TÉCNICO

Pequeña línea con icono de ojo y texto de leyenda "Switch to Expert Mode (⌘2) for live splat preview", en un tono discreto y tipografía de 10 puntos. No es un elemento interactivo, solo un aviso. No reacciona al clic — el usuario debe realmente presionar Cmd+2 o hacer clic en el menú Mode → Expert Mode.

DÓNDE

Fondo a pantalla completa del paso de vista previa.

TÉCNICO

Viewport 3D basado en Metal que renderiza la nube de puntos terminada. El renderizador es el rasterizador ForwardPass PROPIO de RadianceKit — el mismo que ya renderiza los splats durante el entrenamiento — es decir, verdadero WYSIWYG (lo que se entrena se muestra y exporta exactamente igual). Pipeline de renderizado basado en tiles con Order-Independent Transparency. Si el renderizador no puede inicializarse (por ejemplo, porque Metal no está disponible en el sistema), aparece en su lugar un fondo negro con el texto „Metal not available". La vista ignora el área segura (safe area), de modo que el modelo llega hasta el borde de la ventana.

DÓNDE

Sobre el viewport, flotando: dos botones de icono arriba a la izquierda, debajo el panel de información abajo a la izquierda.

TÉCNICO

El overlay consta exactamente de dos botones: „Scene Info" muestra y oculta el panel de información abajo a la izquierda, el segundo alterna el modo de cámara entre „Orbit" (girar alrededor de un punto objetivo) y „Fly-Through" (vuelo libre). El panel de información muestra la tasa de fotogramas, el número de Gaussians, el modo de cámara, el ángulo de visión, la resolución de renderizado y el muestreo; durante un entrenamiento en curso se añade una línea de estado de entrenamiento, y al finalizar una línea de finalización. Las cargas de escena fallidas o en curso se muestran como línea de estado propia independientemente del interruptor de información. Rotación automática, restablecer cámara, color de fondo y captura de pantalla no son botones del overlay, sino entradas del menú „Viewport".

DÓNDE

Barra de navegación inferior en Z3.

TÉCNICO

Botón de acento con la etiqueta „Export" e icono de compartir. Al hacer clic se activa el cambio a Z4. Antes, la vista superior comprueba si la versión completa está desbloqueada — si no, en lugar de la etapa de exportación se muestra la vista de bloqueo (ver U-06).

DÓNDE

Página principal izquierda 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 el modo Principiante — un subconjunto filtrado de la lista completa de formatos que contiene solo los 6 formatos más importantes: PLY, SPZ, glTF, .splat, Orbit Video, Web Viewer. Los demás formatos solo se ofrecen en el modo Experto.

DÓNDE

Cada tarjeta de la cuadrícula.

TÉCNICO

Botón sencillo con diseño de tarjeta: icono (p. ej., cremallera de documento para PLY, caja de archivo para SPZ, icono de video para Orbit Video) arriba, nombre del formato como título, descripción-caption (recortada a 2 líneas), debajo el tamaño de archivo estimado (calculado en vivo a partir del formato, el número de gaussianas y el grado SH, y formateado como KB/MB). Al hacer clic se selecciona el formato. La tarjeta seleccionada recibe fondo de acento, borde de acento y un icono de marca arriba a la derecha. El tooltip es la descripción del formato.

DÓNDE

Debajo de la cuadrícula de formatos, visible solo cuando se elige un formato de video (Orbit Video o Social Video).

TÉCNICO

Control deslizante de 3 a 30 segundos en pasos de 1 segundo, vinculado a la duración del video en el estado de la app. Ancho máximo de 300 píxeles. Solo se muestra si está seleccionado un formato de video. Con formatos que no son de video, el control deslizante se elimina por completo de la vista — sin espacio muerto.

DÓNDE

Debajo de la cuadrícula de formatos (y debajo del control de duración, si se ha elegido video).

TÉCNICO

Botón de acento grande. Etiqueta: «Export {nombre de formato}», símbolo de compartir. Al hacer clic se abre el diálogo de guardado de macOS con la extensión de archivo correspondiente al formato. El nombre de archivo propuesto proviene del nombre de la escena actual; si no se ha establecido ninguno (por ejemplo, porque la escena nunca se ha guardado), es «scene». Al confirmar, la exportación se escribe en la ubicación elegida. Desactivado si no hay resultado de entrenamiento o si ya hay una exportación en curso. Debajo del botón está la cifra clave del resultado («2.991 Gaussians • SH degree 3»).

DÓNDE

Debajo del botón de exportar, visible solo mientras una exportación está en curso.

TÉCNICO

Indicador de progreso con ancho máximo de 300 píxeles, debajo el pie «Exporting… N %». El valor va de 0 a 1 y se actualiza durante la escritura — en PLY en bloques de 10 000 gaussianas, en SPZ una sola vez tras la cuantización, en Orbit Video en intervalos de fotogramas.

DÓNDE

Debajo de la barra de progreso, visible solo si en la última exportación se produjo un error.

TÉCNICO

Línea roja con triángulo de advertencia y el texto «Export failed: …» junto con la descripción del error. Fondo rojo con 8 % de opacidad, esquinas redondeadas. Ancho máximo de 400 píxeles. Causas frecuentes de error: fallo de escritura por disco lleno; errores de sandbox con destinos de guardado fuera del rango permitido.

DÓNDE

Lado derecho del paso de exportación.

TÉCNICO

Lista sobre el historial de exportación (guardada de forma permanente en las preferencias de la app, mantenida tras cada exportación exitosa). Cada fila muestra la insignia de formato (pequeña, con color de acento), marca de tiempo (HH:mm), nombre de archivo (recortado a 1 línea) y tamaño de archivo formateado. Al hacer clic en una fila se abre el 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 el Finder con el archivo seleccionado, igual que el clic simple) y «Copy Path» (coloca la ruta completa del archivo como texto en el portapapeles). Esta última es útil para arrastrar y soltar en otras apps o para pasarla a la línea de comandos.