Capítulo 10 — Modo Iniciante

ONDE

No topo, acima do fluxo, sempre visível.

TÉCNICO

Mostra uma barra horizontal de progresso de toda a pipeline (Frame Quality → SfM → Training) com alocação por estágio: Frame Quality ocupa 0–5 % (Fase 3.11, muito curta), SfM 0–30 % da barra, Training 30–100 %. Ao lado, texto de status e porcentagem nominada por fase („SfM 41 %", „Training 12 500/20 000"), para o usuário não ler o aparente retrocesso „41 % SfM → 25 % Training" como erro — a barra mostra o progresso total, não o sub-stage. ETA começa quando há velocidade suficiente medida (tipicamente após as primeiras 100 iters). Mesma exibição no Expert Mode acima do Inspetor.

ONDE

Lado esquerdo do passo de import, retângulo grande tracejado com símbolo. No Modo Iniciante o label é „Drop photos or a video here".

TÉCNICO

Drop zone que faz o símbolo pular brevemente e colore o fundo quando há drag em cima. Aceita JPG, PNG, TIFF, HEIC, MP4, MOV, PLY, SPZ, .splat, bundles .radiancescene e diretórios. Routing por tipo: imagens coletadas e ordenadas; vídeos disparam frame sampling; arquivos splat abrem direto a pré-visualização; bundles de cena são lidos. Diretórios são enumerados e todas as imagens importadas. Bookmarks security-scoped (sandbox) são gerenciados. Extensões não suportadas viram banner por 5 s.

ONDE

Dentro da drop zone, botão de destaque.

TÉCNICO

Botão que abre o file dialog do macOS com multi-seleção e tipos JPG, PNG, TIFF, MP4, MOV, pastas e o formato Scene do app. URLs vindas são security-scoped e seguem os mesmos caminhos de drag-and-drop. Se o usuário escolhe uma pasta, enumeração recursiva por imagens.

ONDE

Dentro da drop zone, visível só se o bundle do app trouxer a sample scene E não houver imagens/splats ainda.

TÉCNICO

Aparece se: (a) sample-scene.splat, .spz ou .ply existe no bundle E (b) sem imagens/vídeos importados E sem nuvem pronta. Ao clicar, carrega a nuvem (prefere o menor formato — splat ~3 MB, spz ~1.4 MB, fallback ply) e em 400 ms seta valores de câmera hardcoded para uma perspectiva agradável.

ONDE

Dentro da drop zone, ao lado de „Try Sample Scene"; mesmas condições de visibilidade.

TÉCNICO

Dispara download (repo github.com/bkindler/radiancekit-sample-photos) de ~427 MB com 960 frames em resolução plena e alimenta o app. Durante o download, botão desabilitado. O progresso entra na barra superior como „Downloading X %" em estágio próprio, porque mantém escala 0–100 % e não se sobrepõe com SfM.

ONDE

Barra inferior flutuante do overlay de import, à esquerda do Start.

TÉCNICO

Controle com label „Quality" agrupa predefinições por categoria (Classic / MCMC / Custom). Predefinições built-in agrupadas por categoria; cabeçalhos hardcoded. Custom só visível se há. Locked state: predefinições fora da free list (Quick + Preview) recebem sufixo „🔒" se o usuário não comprou; ao selecionar, o picker volta para Preview e abre o purchase sheet automaticamente. Selecionar aplica a predefinição e substitui toda a TrainingConfig.

ONDE

Barra inferior flutuante do import, à direita do picker de predefinição.

TÉCNICO

Botão cinza enquanto não há imagens ou vídeo importado. Ao clicar, inicia a pipeline e coloca a stage machine em Frame Quality → SfM → Training. Sem mais status; o processamento em curso aparece em tela separada.

ONDE

Lista de imagens à direita; só com vídeo importado.

TÉCNICO

Slider 0.5 fps – 30 fps em passos 0.5. Mudar atualiza densidade de frames e calcula número-alvo (mínimo 10) a partir de densidade e duração. Fora da lista de imagens porque itens de lista bloqueariam eventos do slider. Abaixo, frames calculados („247 frames") e duração do vídeo („1m23s video"). Tooltip avisa: „Doubling the density doubles the number of frames and increases SfM time by ~100 %.".

ONDE

Lista de imagens à direita, embaixo à direita; só com imagens importadas.

TÉCNICO

Botão vermelho. Clique abre um diálogo „Clear all imported files?" com mensagem „N images will be removed.". Confirmar limpa imagens/vídeos, staging, nuvem, status de treinamento, resultado SfM e caches; stage volta a Import. Em Cancel, nada muda. Diálogo configurado como caminho padrão não-destrutivo (destrutivo em vermelho).

ONDE

Lista de imagens à direita, cada entrada.

TÉCNICO

Lista das imagens importadas com swipe-to-delete. Por imagem: ícone, nome, resolução („1920 × 1080") e tamanho (KB/MB). Resolução vem de um cache de metadados preenchido assíncrono dos headers para não bloquear UI. Apagar oferece swipe (trackpad esquerda) e Delete na seleção. Aviso: a remoção estendida com botão de menos explícito, Backspace e Cmd-Z foi adicionada apenas no Expert Mode (Project Navigator); no Modo Iniciante segue swipe.

ONDE

Sob a lista de imagens, acima do Clear All.

TÉCNICO

Três limiares por contagem de imagens (só com imagens e sem vídeo): - < 3: banner vermelho (red octagon), texto „At least 3 images are required. Camera alignment cannot be computed from fewer images." - 3–9: banner vermelho, „With fewer than 10 images, SfM often fails and the trained scene tends to overfit […]. 15–20 minimum recommended; 30+ for object captures." - 10–19: banner laranja (warning triangle), „Workable, but quality usually improves with 20+ images and good coverage around the scene."

A partir de 20, o banner some. Limiares hard-coded com base em 560+ experimentos empíricos.

ONDE

Ao soltar uma pasta — sem botão visível, lógica de detecção.

TÉCNICO

Ao soltar diretório, checa um de três layouts: sparse/0/cameras.bin, sparse/cameras.bin ou cameras.bin na raiz. Se sim, a enumeração padrão é cancelada e um alerta modal pergunta se usa a reconstrução existente ou refaz por Apple Photogrammetry. Mesma lógica para text format (cameras.txt) e exports ETH3D. Ver Capítulo 9 backend Q6. Funciona igual em Iniciante e Expert.

ONDE

Fundo completo atrás do círculo, oculto em cancel ou falha.

TÉCNICO

Animação decorativa que, conforme o progresso (0…1), renderiza um número crescente de partículas splat. A fonte é um valor calculado de progresso: SfM mapeado em 0–0.2, treinamento em 0.2–1.0 (Frame Quality em 0–0.05). Splats „crescem" visivelmente durante o treinamento. Apenas decorativa — não mostra resultados reais (isso seria Live Preview no Expert). Em cancel/erro some, fica só o círculo.

ONDE

Centro da tela de processamento, 220×220 px.

TÉCNICO

Dois anéis sobrepostos: anel de track suave fora; anel de progresso com acento ou vermelho dentro (vermelho em erro). No meio: ícone de stage (cérebro para Training, câmera para SfM, filme para extração de frames, sparkles para Frame Quality), título e % animada em 32 pt rounded. Ícone pulsa enquanto ativo. Interpolação a 30 Hz suaviza em direção ao progresso real, com creep constante (0.0003/frame) + parte proporcional (4 % do gap) e soft ceiling em 80 % do próximo milestone esperado (para SfM de tabela hardcoded). Sensação suave mesmo se updates reais vêm a cada poucos segundos.

ONDE

Acima à esquerda na tela, 32×32 px.

TÉCNICO

Botão simples com material. Alterna o painel info. Ícone muda entre info-outline e info-filled quando ativo. Animação suave. Tooltip „Show detailed processing metrics".

ONDE

Embaixo à esquerda na tela, só com showProcessingInfo == true.

TÉCNICO

Painel em duas colunas com material ultra-thin. Coluna esquerda: linhas info por estágio — para SfM status e %; para Training iteração, loss combinado, L1, D-SSIM, Gaussian count (laranja), speed (it/s), elapsed, ETA, SH degree e LR. Coluna direita: status, time info, mini loss chart inline (ver C-28) e nudge de discoverability (ver C-32). Valores vêm do status de treinamento atualizado a cada tick.

ONDE

Barra inferior, só durante Training (NÃO durante SfM) e enquanto processamento roda.

TÉCNICO

Botão bordered. Chama Pause ou Resume. Label alterna entre „Pause" (ícone pause) e „Resume" (play). Em SfM, não exibido — Apple Photogrammetry não tem semântica de pause. Pause preserva iteração, status de Gaussians e momento Adam inteiro — Resume continua exatamente de onde parou.

ONDE

Barra inferior, durante processamento (SfM ou Training).

TÉCNICO

Botão bordered vermelho. Abre diálogo „Stop and discard progress?" com „Discard Progress" (destrutivo) e „Keep Running" (cancel). Confirmar seta flag de cancel, termina a task, mata o subprocesso SfM se necessário e grava summary com cancel no log JSONL. Diferente de Pause, buffers e status são descartados.

ONDE

Barra inferior, se a pipeline falhou (status SfM começa com „SfM failed" ou Training em erro).

TÉCNICO

Botão de acento. Reinicia toda a pipeline. Checa imagens importadas antes. Logs de erro anteriores permanecem; novo run grava novo JSONL com timestamp atual.

ONDE

No painel info, coluna direita; só durante treinamento com histórico não vazio.

TÉCNICO

Área de desenho compacta (40 px alta), desenha loss history como linha de 1 px em cor de destaque. Filtra para finitos (proteção NaN). Min/Max sobre toda história — auto-zoom. Último valor de loss acima à direita do chart. O history é preenchido a cada tick (~100 iters).

ONDE

No painel info, coluna direita embaixo; só durante treinamento E no Modo Iniciante.

TÉCNICO

Linha pequena com ícone de olho e caption „Switch to Expert Mode (⌘2) for live splat preview", em tonalidade discreta e 10 pt. Não é interativo — o usuário aperta Cmd+2 ou o menu Mode → Expert Mode.

ONDE

Fundo cheio do passo preview.

TÉCNICO

Viewport 3D Metal que renderiza a nuvem. O renderer é o fork MetalSplatter vendored com fixes do RadianceKit para popping/flickering. Pipeline tile-based com order-independent transparency. Se o renderer não inicializa (p. ex. Metal indisponível), aparece fundo preto com „Metal not available". A vista ignora safe area, modelo vai até a borda.

ONDE

Acima do viewport, flutuante.

TÉCNICO

Overlay compacto com botões para auto-rotation (turntable), reset camera, escolha de background (Gray/Black/White), save screenshot, toggle info. Liga aos parâmetros de câmera (distância, azimuth, elevation, target, FOV) e controla o turntable. Durante o treinamento (caso Expert com viewport rodando ao vivo) o overlay mostra também linha de status compacta.

ONDE

Barra inferior em Z3.

TÉCNICO

Botão de acento com label „Export" e ícone de share. Clique muda para Z4. Antes, a view-pai checa se a versão completa está desbloqueada — senão, em vez do palco de export, aparece a tela de bloqueio (ver U-06).

ONDE

Lado esquerdo principal do passo Export.

TÉCNICO

Grid de cards em duas colunas flex com 12 pt de espaço. Itera sobre os formatos oferecidos no Iniciante — subconjunto filtrado dos 6 mais importantes: PLY, SPZ, glTF, .splat, Orbit Video, Web Viewer. Compressed PLY e SOG estão SÓ no Expert.

ONDE

Cada card no grid.

TÉCNICO

Botão simples com layout em card: ícone (p. ex. zipper para PLY, archive box para SPZ, vídeo para Orbit Video) em cima, nome em headline, caption descritiva (2 linhas), embaixo tamanho estimado (live a partir de formato, Gaussian count e SH degree em KB/MB). Clique seleciona; card selecionado fica com acento, borda e check à direita. Tooltip = descrição.

ONDE

Sob o grid, só com formato de vídeo (Orbit Video ou Social Video).

TÉCNICO

Slider 3–30 s em passos 1, ligado ao comprimento de vídeo no estado. Largura máxima 300 px. Só aparece com vídeo selecionado. Em formatos não-vídeo, sumir totalmente — sem espaço morto.

ONDE

Sob o grid (e sob o slider de duração, se vídeo).

TÉCNICO

Botão grande com cor de acento. Label: „Export {nome do formato}", ícone share. Clique abre diálogo de salvar do macOS com extensão correspondente e nome padrão „scene.{ext}"; ao confirmar, grava no URL escolhido. Desativado se não há resultado de treinamento ou export já roda.

ONDE

Sob o botão Export, só durante export.

TÉCNICO

Progresso com largura máx 300 px, abaixo caption „Exporting… N %". Valor 0 a 1, atualizado durante gravação — em PLY em chunks de 10 000 Gaussians, em SPZ após quantização, em Orbit Video por intervalos de frame.

ONDE

Sob a barra, só se o último export deu erro.

TÉCNICO

Linha vermelha com warning icon e texto do erro. Fundo vermelho com 8 % opacity, cantos arredondados. Larg máx 400 px. Causas comuns: SOG esperando cwebp no PATH (não sandbox); falha de gravação com disco cheio; sandbox recusando destino fora da área permitida.

ONDE

Lado direito do passo Export.

TÉCNICO

Lista da history (persistida como JSON em UserDefaults, mantida após cada export bem-sucedido). Linha mostra badge de formato (pequeno, acento), timestamp (HH:mm), nome de arquivo (1 linha) e tamanho formatado. Clique abre Finder com arquivo selecionado. Empty state „No exports yet".

ONDE

Clique direito numa linha da history.

TÉCNICO

Menu de contexto por linha com duas ações: „Reveal in Finder" (igual ao clique simples) e „Copy Path" (coloca o caminho completo na área de transferência). O segundo é útil para drag-and-drop em outros apps ou para terminal.