Capítulo 10 — Modo Iniciante

ONDE

Na barra na borda superior da janela, à esquerda do alternador de modo. Visível apenas no modo iniciante.

TÉCNICO

Mostra as seis fases do pipeline como uma cadeia de botões enfileirados, cada um com ícone e nome, separados por uma seta: Import → Frame Quality → Cameras → Training → Preview → Export. A fase atual está totalmente colorida, as fases já percorridas semitransparentes, as fases ainda não alcançadas em cinza. As fases já concluídas são clicáveis e voltam a elas; a fase atual e todas ainda não alcançadas estão desativadas, assim como toda a cadeia enquanto um processamento estiver em andamento. Uma barra de progresso percentual contínua ao longo de todo o pipeline não existe mais — o progresso da fase em execução é mostrado pelo grande círculo na tela de processamento (C-19).

ONDE

Lado esquerdo do passo de importação, grande retângulo tracejado com ícone. É exibido no modo iniciante com o rótulo „Drop photos or a video here".

TÉCNICO

Área de soltar que faz o ícone saltar brevemente e colore o fundo assim que itens arrastados pairam sobre o campo. Aceita JPG, PNG, TIFF, HEIC, MP4, MOV, PLY, SPZ, .splat, pacotes .radiancescene e diretórios. Roteamento de soltura por tipo: imagens são coletadas e entregues ordenadas, vídeos disparam o caminho de amostragem de frames, arquivos splat abrem diretamente a pré-visualização, pacotes de cena são lidos. Diretórios são enumerados e todas as imagens contidas são importadas. Bookmarks com escopo de segurança para acesso compatível com sandbox são corretamente capturados e liberados. Extensões não suportadas são exibidas como faixa de aviso por 5 segundos.

ONDE

Dentro da zona de soltar, botão proeminente.

TÉCNICO

Botão que abre o diálogo de arquivos do macOS com seleção múltipla e os tipos de arquivo JPG, PNG, TIFF, MP4, MOV, pastas, bem como o formato de cena próprio do app. As URLs resultantes são com escopo de segurança e são encaminhadas pelos mesmos caminhos de importação que arrastar e soltar. Se o usuário selecionar uma pasta, ela é enumerada recursivamente em busca de imagens.

ONDE

Dentro da zona de soltar, visível apenas se o pacote do app contiver a cena de exemplo e ainda não houver imagens/splats importados.

TÉCNICO

Aparece apenas se (a) houver um sample-scene.splat, .spz ou .ply no pacote do app E (b) ainda não houver imagens/vídeos importados e ainda não existir nuvem de pontos. Ao clicar, carrega a nuvem de pontos já pronta (preferindo o formato menor — .splat ~3 MB, .spz ~1.4 MB, fallback .ply) e, após 400 ms, define valores de câmera fixos a partir dos metadados originais da cena de flores para uma perspectiva de entrada esteticamente adequada.

ONDE

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

TÉCNICO

Baixa um conjunto de exemplo fornecido pelo RadianceKit da internet: cerca de 427 MB com 960 frames em resolução total, que são então descompactados e diretamente incorporados ao app. Enquanto outro processamento estiver em andamento, o botão fica desativado e o download não inicia. O progresso do carregamento não é exibido na interface como um valor percentual; que o download terminou você percebe pelo fato de a lista de imagens à direita se preencher com os 960 frames.

ONDE

Barra de ferramentas inferior flutuante do overlay de import, à esquerda do botão de início.

TÉCNICO

Seletor de menu com o rótulo „Quality", que agrupa os presets incluídos por categoria em quatro seções: „Classic", „MCMC (fewer Gaussians, slower)", „Hybrid (sharp detail, compact)" e „Capture — curated real-world (Drone / 360° / Photo)". Uma quinta seção „Custom" é adicionada assim que a versão completa é desbloqueada e pelo menos um preset próprio foi salvo. Estado bloqueado: todos os presets exceto Quick e Preview recebem um sufixo „🔒" no nome se o usuário não possuir a versão completa; ao selecionar, o seletor volta para Preview e abre automaticamente a janela de compra. Ao escolher, o preset é aplicado, o que substitui toda a configuração de treinamento.

ONDE

Barra de ferramentas inferior flutuante do overlay de import, à direita do seletor de presets.

TÉCNICO

Botão que permanece cinza enquanto nem imagens nem um vídeo tiverem sido importados. Ao clicar, inicia o pipeline e comuta a máquina de estágios para a sequência Frame-Quality → SfM → Training. O próprio botão não tem mais estado; um processamento em andamento aparece em vez disso como uma tela de processamento separada.

ONDE

Lista de imagens à direita, visível apenas quando um vídeo (em vez de imagens) foi importado.

TÉCNICO

Controle deslizante de 0.5 fps a 30 fps em passos de 0.5. Ao alterar, a densidade de frames é atualizada e, além disso, o número de frames alvo (mínimo 10) é calculado a partir da densidade e da duração do vídeo. O controle deslizante fica fora da lista de imagens, porque elementos de lista bloqueariam eventos de mouse de controles deslizantes. Sob o controle deslizante ficam os frames alvo calculados („247 frames") e a duração do vídeo („1m23s video"). Uma dica exibe o aviso: „Doubling the density doubles the number of frames and increases SfM time by ~100%."

ONDE

Lista de imagens à direita, embaixo à direita; visível apenas se imagens tiverem sido importadas.

TÉCNICO

Botão vermelho. Ao clicar, abre um diálogo de confirmação com o título „Clear all imported files?" e a mensagem „N images will be removed.". A confirmação limpa todas as imagens/vídeos importados, diretórios de staging, a nuvem de pontos, o status de treinamento, o resultado do SfM e todos os caches; a fase volta para Import. Ao clicar em Cancel, tudo é mantido. O diálogo está configurado como caminho padrão não destrutivo (o botão destrutivo é marcado em vermelho).

ONDE

Lista de imagens à direita, cada entrada.

TÉCNICO

Lista das imagens importadas com deslizar-para-excluir. Por imagem, uma linha com ícone, nome do arquivo, resolução („1920 × 1080") e tamanho do arquivo (formatado em KB/MB). A resolução vem de um cache de metadados preenchido de forma assíncrona a partir dos cabeçalhos das imagens, para que a interface não seja bloqueada. A remoção é feita pelo típico deslizar para excluir do macOS (deslizar no trackpad para a esquerda sobre uma linha); a lista não tem seleção de linhas, portanto não há exclusão via teclado aqui. Observação: o caminho estendido de exclusão de imagem com botão de menos explícito, Backspace e Cmd-Z para desfazer foi adicionado apenas no modo Expert no Project Navigator — no modo iniciante, permanece o deslizar-para-excluir.

ONDE

Abaixo da lista de imagens, acima do botão Clear-All.

TÉCNICO

Três limiares consecutivos baseados no número de imagens importadas (ativo apenas se houver imagens e nenhum vídeo): - < 3 imagens: faixa vermelha (octógono vermelho), texto „At least 3 images are required. Camera alignment cannot be computed from fewer images." - 3–9 imagens: faixa vermelha, 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 imagens: faixa laranja (triângulo de aviso), texto „Workable, but quality usually improves with 20+ images and good coverage around the scene."

A partir de 20 imagens, a faixa desaparece. Os limiares são fixos e baseiam-se em mais de 560 experimentos empíricos de treinamento.

ONDE

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

TÉCNICO

Ao soltar um diretório, é verificado se ele contém um dos três layouts canônicos de workspace: sparse/0/cameras.bin, sparse/cameras.bin ou diretamente cameras.bin na raiz. Se for o caso, a enumeração padrão de imagens é interrompida e, em vez disso, é aberto um alerta modal que pergunta ao usuário se a reconstrução existente deve ser usada ou se as imagens devem ser processadas novamente pela Apple Photogrammetry. Mesmo caminho também para workspaces em formato de texto (cameras.txt) e exportações ETH3D. Veja capítulo 9 Backend Q6 para detalhes. Funciona no modo iniciante da mesma forma que no modo Expert.

ONDE

Fundo em tela cheia atrás do círculo de progresso, ocultado em caso de cancelamento ou erro.

TÉCNICO

Animação decorativa que renderiza, conforme o progresso do pipeline (0…1), um número crescente de pequenas partículas de splat animadas. A fonte é um valor de progresso calculado que mapeia as fases de SfM para 0–0.2 e o treinamento para 0.2–1.0 (a verificação de qualidade dos frames para 0–0.05). Assim, os splats "se constroem" visivelmente enquanto o treinamento avança. Puramente decorativa — a exibição não mostra resultados intermediários reais do treinamento atual (isso seria a Live-Preview no modo Expert). Em caso de Cancel ou falha, ela é ocultada e apenas o círculo de status permanece visível.

ONDE

No centro da tela de processamento, 220 × 220 pixels.

TÉCNICO

Dois anéis renderizados um sobre o outro: por fora um anel de trilha atenuado, por dentro um anel de progresso preenchido com traço na cor de destaque ou vermelho (vermelho em caso de erro). O anel segue o progresso real do estágio atual diretamente (suavizado por uma breve animação de entrada/saída), para que a exibição coincida com a linha de progresso do modo Expert. Dentro do círculo há um ícone de estágio (cérebro para treinamento, câmera para SfM, filme para extração de frames de vídeo, sparkles para a verificação de qualidade dos frames, globo para o desdobramento de material em 360°), título do estágio e o número de progresso. Esse número é o contador de iterações ("12.500/20.000") durante o treinamento, e em todos os outros estágios uma porcentagem. O ícone pulsa suavemente enquanto o processamento está ativo. Em caso de erro, o título muda para o estágio que falhou ("Structure from Motion Failed", "Training Failed"), o anel e o número ficam vermelhos. Após um cancelamento, o círculo exibe em vez disso uma cruz laranja com "Cancelled!".

ONDE

No canto superior esquerdo da tela de processamento, 32 × 32 pixels.

TÉCNICO

Botão simples com fundo de material. Ativa ou desativa o painel de informações. O ícone alterna entre círculo de informação em contorno e círculo de informação preenchido, quando ativo. Animação suave de entrada. No tooltip: "Show detailed processing metrics".

ONDE

No canto inferior esquerdo da tela de processamento, visível apenas quando os detalhes de processamento estão exibidos.

TÉCNICO

Painel de duas colunas com fundo de material ultra-fino. Coluna esquerda: linhas de informação específicas do estágio — para SfM, texto de status e porcentagem; para treinamento, iteração, Loss combinado, Loss L1, Loss D-SSIM, contagem de Gaussians (colorida em laranja), velocidade (it/s), tempo decorrido, ETA calculada, SH-Degree e taxa de aprendizado. Coluna direita: texto de status, string de informação de tempo, gráfico de Loss inline (ver C-28) e um aviso de descoberta (discoverability nudge, ver C-32). Todos os valores são lidos do status de treinamento, atualizado a cada tick de treinamento.

ONDE

Barra de navegação inferior, visível apenas durante o estágio de treinamento (NÃO durante SfM) e enquanto o processamento estiver em andamento.

TÉCNICO

Bordered Button. Chama Pause ou Resume, conforme o status. O rótulo alterna entre "Pause" (com ícone de pausa) e "Resume" (ícone de play). Durante a etapa de SfM, o botão não é exibido, pois o Apple Photogrammetry não possui semântica de pausa. O estado de pausa preserva completamente iteração, status dos Gaussians e o momentum do otimizador — Resume continua exatamente de onde parou.

ONDE

Barra de navegação inferior, visível enquanto o processamento está em andamento (SfM ou treinamento).

TÉCNICO

Botão vermelho com borda. Abre um diálogo de confirmação com o título "Stop and discard progress?", com os botões "Discard Progress" (destrutivo) e "Keep Running" (cancelar). Ao confirmar, a flag de cancelamento é definida, a tarefa de treinamento é encerrada, o subprocesso de SfM é encerrado se necessário, e uma linha de resumo com o status de cancelamento é escrita no log JSONL. Diferentemente de Pause, os buffers de treinamento e o status são descartados.

ONDE

Barra de navegação inferior, visível quando o pipeline falhou (o status de SfM começa com "SfM failed" ou o treinamento está em estado de erro).

TÉCNICO

Botão de destaque (Accent Button). Reinicia todo o pipeline. Antes de iniciar, verifica-se se ainda há imagens/vídeos importados. Os logs de erro anteriores permanecem no diretório JSONL; uma nova execução escreve um novo arquivo de log com o timestamp atual.

ONDE

No painel de informações, coluna direita, visível apenas durante o treinamento com histórico de progresso não vazio.

TÉCNICO

Área de desenho compacta (40 pixels de altura), desenha o histórico de Loss como uma linha de 1 pixel na cor de destaque. Os dados são filtrados para valores finitos (proteção contra NaN em treinamentos instáveis). Min/Max são calculados sobre todo o histórico — ou seja, o gráfico faz auto-zoom no intervalo de valores. O último valor de Loss aparece no canto superior direito, acima do gráfico. O próprio histórico é construído no estado do app a cada tick de treinamento (tipicamente a cada 100 iterações).

ONDE

No painel de informações, coluna direita embaixo, visível apenas durante o treinamento E no modo Iniciante.

TÉCNICO

Pequena linha com ícone de olho e texto de legenda "Switch to Expert Mode (⌘2) for live splat preview", em tom discreto e fonte de 10 pontos. Não é um elemento interativo, apenas um aviso. Não reage a cliques — o usuário precisa efetivamente pressionar Cmd+2 ou clicar no menu Mode → Expert Mode.

ONDE

Plano de fundo em tela cheia da etapa de pré-visualização.

TÉCNICO

Viewport 3D baseado em Metal que renderiza a nuvem de pontos finalizada. O renderizador é o PRÓPRIO rasterizador ForwardPass do RadianceKit — o mesmo que já renderiza os splats durante o treinamento — ou seja, um verdadeiro WYSIWYG (o que é treinado é exibido e exportado exatamente assim). Pipeline de renderização baseado em tiles com Order-Independent Transparency. Se o renderizador não puder ser inicializado (por exemplo, porque o Metal não está disponível no sistema), aparece em vez disso um fundo preto com o texto „Metal not available". A visualização ignora a Safe Area, de modo que o modelo se estende até a borda da janela.

ONDE

Sobre o viewport, flutuando: dois botões de ícone no canto superior esquerdo, abaixo deles, no canto inferior esquerdo, o painel de informações.

TÉCNICO

A sobreposição consiste em exatamente dois botões: "Scene Info" exibe e oculta o painel de informações no canto inferior esquerdo, o segundo alterna o modo de câmera entre "Orbit" (circular em torno de um ponto-alvo) e "Fly-Through" (voo livre). O painel de informações mostra a taxa de quadros, o número de Gaussians, o modo de câmera, o ângulo de visão, a resolução de renderização e a amostragem; durante um treinamento em andamento, adiciona-se uma linha de status do treinamento, e após seu término, uma linha de conclusão. Carregamentos de cena com falha ou em andamento são exibidos como uma linha de status própria, independentemente do botão de informações. Rotação automática, redefinir câmera, cor de fundo e captura de tela não são botões de sobreposição, mas sim itens do menu "Viewport".

ONDE

Barra de navegação inferior em Z3.

TÉCNICO

Botão de destaque com o rótulo "Export" e ícone de compartilhamento. Um clique dispara a transição para Z4. Antes disso, a visão superior verifica se a versão completa está desbloqueada — caso contrário, a tela de exportação é substituída pela tela de bloqueio (veja U-06).

ONDE

Página principal à esquerda da etapa de exportação.

TÉCNICO

Grade de cartões com duas colunas flexíveis e 12 pontos de espaçamento. Itera sobre os formatos oferecidos no modo Iniciante — um subconjunto filtrado da lista completa de formatos, contendo apenas os 6 formatos mais importantes: PLY, SPZ, glTF, .splat, Orbit Video, Web Viewer. Os demais formatos são oferecidos apenas no modo Expert.

ONDE

Cada cartão na grade.

TÉCNICO

Botão simples com layout de cartão: ícone (por exemplo, zíper de documento para PLY, caixa de arquivo para SPZ, ícone de vídeo para Orbit Video) no topo, nome do formato como título, legenda de descrição (truncada em 2 linhas), abaixo o tamanho de arquivo estimado (calculado ao vivo a partir do formato, contagem de gaussianas e grau SH, formatado como KB/MB). Ao clicar, o formato é selecionado. O cartão selecionado recebe fundo de destaque, borda de destaque e um ícone de marca de verificação no canto superior direito. O tooltip é a descrição do formato.

ONDE

Abaixo da grade de formatos, visível apenas quando um formato de vídeo está selecionado (Orbit Video ou Social Video).

TÉCNICO

Controle deslizante de 3 a 30 segundos em passos de 1 segundo, vinculado à duração do vídeo no estado do app. Largura máxima de 300 pixels. Só é exibido quando um formato de vídeo está selecionado. Em formatos que não são vídeo, o controle deslizante é completamente removido da visualização — sem espaço vazio.

ONDE

Abaixo da grade de formatos (e abaixo do controle de duração, caso um vídeo seja escolhido).

TÉCNICO

Botão grande de destaque. Rótulo: "Export {Nome-do-Formato}", ícone de compartilhamento. Ao clicar, abre-se o diálogo de salvar do macOS com a extensão de arquivo correspondente ao formato. O nome de arquivo sugerido vem do nome da cena atual; se nenhum estiver definido (por exemplo, porque a cena nunca foi salva), o nome será "scene". Ao confirmar, a exportação é gravada no local escolhido. Desativado se não houver resultado de treinamento disponível ou se uma exportação já estiver em andamento. Abaixo do botão está a métrica do resultado ("2.991 Gaussians • SH degree 3").

ONDE

Abaixo do botão de exportação, visível apenas enquanto uma exportação está em andamento.

TÉCNICO

Indicador de progresso com largura máxima de 300 pixels, abaixo dele a legenda "Exporting… N %". O valor vai de 0 a 1 e é atualizado durante a gravação — no PLY em blocos de 10.000 gaussianas, no SPZ uma única vez após a quantização, no Orbit Video em intervalos de quadro.

ONDE

Abaixo da barra de progresso, visível apenas se ocorreu um erro na última exportação.

TÉCNICO

Linha vermelha com triângulo de aviso e o texto "Export failed: …" junto com a descrição do erro. Fundo vermelho com 8 % de opacidade, cantos arredondados. Largura máxima de 400 pixels. Causas comuns de erro: falha de gravação com o disco cheio; erro de sandbox em destinos de salvamento fora da área permitida.

ONDE

Lado direito da etapa de exportação.

TÉCNICO

Lista com o histórico de exportações (armazenado permanentemente nas preferências do app, atualizada após cada exportação bem-sucedida). Cada linha mostra um distintivo de formato (pequeno, na cor de destaque), timestamp (HH:mm), nome de arquivo (truncado em 1 linha) e tamanho de arquivo formatado. Clicar em uma linha abre o Finder com o arquivo selecionado. Estado vazio: "No exports yet".

ONDE

Clique com o botão direito em uma linha do histórico.

TÉCNICO

Menu de contexto em cada item da lista com duas ações: "Reveal in Finder" (abre o Finder com o arquivo selecionado, assim como o clique simples) e "Copy Path" (coloca o caminho completo do arquivo como texto na área de transferência). Esta última é útil para arrastar e soltar em outros apps ou para passar à linha de comando.