Capítulo 2 — Inspetor (Expert View)

ONDE

Inspetor → seção de predefinições → botão Save… (barra de ações embaixo).

TÉCNICO

Abre um popover com campo de texto e botões Save/Cancel. O estado atual da TrainingConfig é persistido como nova predefinição do usuário (codificada em JSON, salva entre apps). A ação de salvar copia todos os 81 parâmetros de treinamento mais a estratégia de densification atual. A predefinição vai automaticamente para a categoria Custom, independentemente de qual built-in serviu de base. Nomes vazios e só com whitespace são descartados. Nomes já existentes não são rejeitados — cada predefinição tem ID interno próprio; nomes duplicados são tecnicamente permitidos, mas confundem na prática.

ONDE

Popover Save → campo de texto „Preset Name".

TÉCNICO

Campo de texto simples com moldura arredondada, forma larga. O valor é assumido como nome de predefinição ao clicar em Save. Sem limite de tamanho na UI, mas o nome salvo precisa ser codificável em JSON e exibível nas listas da UI — emojis e acentos funcionam. O conteúdo é resetado para string vazia ao abrir o popover. O botão Save fica desabilitado enquanto o campo após trim estiver vazio. Não há auto-suggest nem pré-preenchimento com o nome da predefinição ativa.

ONDE

Popover Save → botão Cancel (à esquerda).

TÉCNICO

Fecha o popover sem salvar. Descarta o conteúdo do campo — na próxima abertura, ele é resetado para vazio pela lógica do botão Save… (I1). Estilo de botão padrão, sem diálogos de confirmação, sem hotkeys. A TrainingConfig atual permanece inalterada, pois o caminho de save não foi executado.

ONDE

Popover Save → botão Save (à direita, estilo proeminente).

TÉCNICO

Dispara a persistência real. Faz nova validação de nome não vazio (check defensivo) e grava a TrainingConfig atual como JSON no armazenamento do app. Depois fecha o popover. Destacado em azul, fica cinza enquanto o campo está vazio. Se o save falhar (p. ex. armazenamento cheio — muito improvável), por ora não há diálogo de erro visível; a predefinição simplesmente não apareceria no próximo início do app.

ONDE

Inspetor → seção de predefinições → barra de ações → botão Export….

TÉCNICO

Exporta a predefinição atualmente selecionada como arquivo .radiancepreset (internamente JSON). Desabilitado se nenhuma predefinição estiver selecionada. Ao clicar, o app abre um diálogo de salvar com nome pré-definido (nome da predefinição + extensão .radiancepreset). O formato salvo contém a TrainingConfig completa mais metadados (nome, categoria, ID, flag built-in). Duplo clique no Finder abre o app — mas não dispara o import automaticamente; o usuário precisa usar o botão Import (I6).

ONDE

Inspetor → seção de predefinições → barra de ações → botão Import….

TÉCNICO

Abre um diálogo de arquivo que só permite .radiancepreset (multi-seleção desabilitada). Ao escolher, o JSON é carregado, validado e inserido na categoria Custom — com nova ID interna para não colidir com built-ins. O import sempre seta a categoria como Custom, mesmo que a predefinição original tenha sido um built-in. Arquivos corrompidos ou incompatíveis com versão de schema antiga são silenciosamente rejeitados, sem diálogo de erro (o log do console traz a razão).

ONDE

Inspetor → seção de predefinições → toda linha de predefinição em toda categoria.

TÉCNICO

Clicar numa linha substitui todos os campos da TrainingConfig pelos valores da predefinição, memoriza o ID da ativa e zera o status Modified. O check de ativo antes da linha só aparece quando a predefinição está selecionada E não modificada. Assim que um valor é alterado na TrainingConfig (slider, stepper, toggle nas outras seções do Inspetor), aparece um badge laranja „Modified" depois do nome. Predefinições built-in não podem ser sobrescritas — em caso de modificação, é preciso criar uma cópia via Save… (I1).

ONDE

Clique direito em qualquer linha → primeiro item „Export…".

TÉCNICO

Mesma funcionalidade do I5 (botão Export…), mas mais cômoda — não precisa pré-selecionar. Exporta direto a predefinição da linha clicada. Funciona igualmente para todas as categorias (built-in ou Custom), sem restrição. A exportação contém o flag built-in e a categoria original; no re-import, a categoria vai para Custom como descrito em I6.

ONDE

Clique direito em qualquer linha → segundo item „Duplicate".

TÉCNICO

Clona a predefinição para a categoria Custom. Gera nova ID interna, acrescenta „ Copy" ao nome e salva a cópia. Funciona também para built-ins — o clone fica editável. O original permanece intocado. A TrainingConfig é copiada valor por valor (JSON roundtrip), sem ligações de referência entre original e cópia.

ONDE

Clique direito em linhas próprias → último item „Delete" (vermelho, destrutivo).

TÉCNICO

Só visível em predefinições Custom. Built-ins não são apagáveis. Marcado como destrutivo, aparece em vermelho no menu de contexto e fica após um divisor para evitar cliques acidentais. Não há diálogo de confirmação — um clique apaga imediatamente. Apagada não é restaurável (Cmd-Z não funciona aqui — undo existe no build atual só para a lista de imagens, não para operações de predefinição). Se a apagada estava ativa, a TrainingConfig atual permanece; só a seleção é zerada.

ONDE

Inspetor → seção de predefinições → cada cabeçalho de categoria (Classic, MCMC, SceneClass, Custom).

TÉCNICO

Estado de colapso por categoria com padrões diferentes: Classic começa aberta, MCMC, SceneClass e Custom começam fechadas. O estado não é persistido — ao reiniciar o app, todas voltam ao padrão. A setinha gira com animação. O número à direita no cabeçalho mostra quantas predefinições há na categoria. A área de clique cobre todo o cabeçalho.

ONDE

Inspetor → Configuração de treinamento → Camera Alignment (seletor segmentado em cima).

TÉCNICO

Seletor segmentado com duas opções: Apple Photogrammetry e Native (Beta). A escolha define o backend SfM usado na próxima reconstrução de câmeras. Influencia ainda quais outros elementos do Inspetor ficam visíveis: Native exibe o FOV Override (I13), necessário só para frames de vídeo sem EXIF. Observação: para capturas externas muito grandes, você pode carregar o resultado de uma ferramenta externa (Metashape ou COLMAP) via import de workspace — ver Capítulo 1 (M5) e Capítulo 9 (Q3, Q6).

ONDE

Inspetor → Configuração de treinamento → FOV Override (só visível com Camera Alignment = Native).

TÉCNICO

Campo de texto numérico (faixa 0–170°), padrão 0 = determinação automática por EXIF ou heurística. Entrada manual é necessária quando as imagens vêm de vídeo sem metadados de distância focal. Valores típicos: iPhone Wide ≈ 73°, DJI Mavic Wide-Crop ≈ 70°, drone com sensor full frame ≈ 84°. O valor é clampeado para [0, 170] — valores fora são reduzidos. Atua só no pipeline SfM nativo (Q4/Q5); Apple Photogrammetry ignora este valor.

ONDE

Inspetor → Configuração de treinamento → Densification (seletor segmentado, sempre visível).

TÉCNICO

Alterna entre as duas estratégias de densification: Classic (procedimento 3DGS original com clone/split/prune e threshold de gradiente) e MCMC (Stochastic Gradient Langevin Dynamics com relocação, NeurIPS 2024). Ao mudar de Classic para MCMC, o app reseta automaticamente os campos específicos de MCMC para valores padrão testados (pesos de regularização = 0, multiplicador de cap MCMC 3.0, schedule de sample/noise). Sem essa inicialização automática, sessões com predefinições antigas sofriam do bug de MCMC collapse de v1.4.4 (460K→5 Gaussians, watchdog kill). A escolha do seletor define também quais elementos do Inspetor ficam visíveis — em MCMC aparecem I16/I17. Efeito detalhado de cada campo no Capítulo 6, T11–T16 (Classic) e T61–T73 (MCMC).

ONDE

Inspetor → Configuração de treinamento → MCMC Quality (só com Densification = MCMC).

TÉCNICO

Alterna a gradient accumulation entre 2 passos (ativo) e 1 passo (inativo). Acumula gradientes de duas vistas de câmera consecutivas antes do passo do otimizador. Empiricamente (Sessão 33, V544a) reduz o L1 final em cerca de 6% (0.0246 com Quality vs 0.0261 sem, em média de 3 trials em Horse Full MCMC). Preço: tempo de treinamento dobra. Em treinamentos muito longos (200K iterações), gera 10+ minutos extras de espera — vale apenas quando os últimos pontos percentuais de qualidade são realmente necessários. Atua apenas no treinamento, não no formato de export nem no viewport.

ONDE

Inspetor → Configuração de treinamento → Auto-scale by scene (só com MCMC).

TÉCNICO

Quando ativo, escala o limite efetivo de Max Gaussians por SfM-Init-Point-Count × MCMC Cap Multiplier (padrão 3.0). Exemplo: SfM entrega 250K pontos iniciais, base cap = 150K, multiplier 3.0 → limite efetivo = max(150K, 750K) = 750K. Quando desativado, vale somente a base. Introduzido na v1.4.5 porque grandes capturas externas com mais de 1000 frames e densidade proporcional de pontos SfM mato a densification com a cap fixa de 150K — pontos supérfluos ficavam, novos não podiam surgir. Padrão OFF em Custom, ON em built-ins MCMC. Atua apenas em tempo de treinamento, não no export.

ONDE

Inspetor → Configuração de treinamento → GroupBox → Max Iterations.

TÉCNICO

Stepper com faixa 1 000–100 000, passo 1 000. Define o número total de iterações do otimizador. Correlaciona linearmente com o tempo de treinamento (metade ≈ 50 % do tempo). Sweet spots empíricos: 20K (Classic Balanced, L1≈0.028), 40K (Classic Quality, L1≈0.023), 200K (MCMC Full, L1≈0.0246). Acima de 40K no Classic quase não há ganho médio — diminishing returns. Ao alterar, se o link (I19) está ativo, Densify Until é proporcionalmente arrastado (razão padrão 0.5, i.e. Densify-Until = Max/2).

ONDE

Inspetor → Configuração de treinamento → GroupBox → pequeno botão de link entre Max Iterations e Densify Until.

TÉCNICO

Botão toggle que congela a razão de Densify Until para Max Iterations. Em ativo (ícone de link destacado), a cada mudança em Max Iterations, Densify Until é puxado proporcionalmente. Em unlink (ícone link-plus), os valores ficam independentes. Padrão é linked, porque reflete a correlação típica — dobrar iterações em geral exige densification proporcionalmente mais longa. A razão é calculada a partir do valor atual no instante de ativar o link; razão típica é 0.5 (Densify Until = metade do número de iters).

ONDE

Inspetor → Configuração de treinamento → GroupBox → Densify Until.

TÉCNICO

Stepper com faixa 500–50 000, passo 500. Define o índice de iteração a partir do qual nenhum novo Gaussian é adicionado por clone/split (Classic) ou relocação (MCMC). Depois disso, só posição e cor são refinadas. Valores mais altos = mais Gaussians = arquivo maior, tempo por iteração maior (+30-60 % de GPU time por passo). Valores típicos: 15K (para 30K Max-Iter), 20K (para 40K), 100K (para 200K MCMC). Com link ativo (I19), escala junto. Atua diferente em Classic vs MCMC: Classic para o crescimento totalmente; MCMC para a lógica de relocação, mas sample/noise adaption continuam.

ONDE

Inspetor → Configuração de treinamento → GroupBox → SSIM Weight.

TÉCNICO

Slider 0.0–1.0 em passos de 0.05, exibição „0.20". Mistura L1 loss (0.0) e SSIM loss (1.0). L1 puxa brilho por pixel, SSIM puxa similaridade estrutural (bordas, estatísticas locais). Padrão 0.2 vem do paper original 3DGS (Kerbl 2023) e foi confirmado em muitas sessões como compromisso robusto. Valores mais altos (0.5+) priorizam preservação de detalhe, mas podem ignorar erros de brilho locais. Mais baixos (< 0.1) levam à perda de detalhe em bordas nítidas. O cálculo de SSIM roda no shader com janela Gaussian 11×11. Performance: em 0.0 (só L1) o treinamento é cerca de 8–12 % mais rápido, pois o cálculo SSIM é pulado no shader.

ONDE

Inspetor → Configuração de treinamento → GroupBox → Render Scale.

TÉCNICO

Slider 0.25–1.0 em passos de 0.25, exibição „100%". Escala a resolução de renderização do treinamento relativa ao tamanho da imagem fonte. Maior alavanca sobre performance: 50 % reduz GPU time em ~75 % (4× menos pixels), 25 % em ~94 %. O gradient threshold escala junto automaticamente. Sob o slider aparece um indicador ao vivo de resolução em MP (p. ex. „2304×1296 (3.0 MP)"). Se o valor atual diverge do recomendado, aparece em laranja „— recommended: 50%". A recomendação visa ~3 MP efetivos — a região mais eficiente em GPUs Apple Silicon. Imagens fonte em 4K recebem 25 % recomendado; FullHD recebe 100 %. Mudar também dispara realocação de buffers.

ONDE

Inspetor → Enhancements → Post-Training Compactification.

TÉCNICO

Ativa o pós-processamento V443: após o fim das iterações, Gaussians com opacidade abaixo de 0.01 (1 % de visibilidade) são removidos. Empiricamente reduz o tamanho do arquivo em ~55–58 % sem perda visual — porque esses Gaussians visualmente não contribuíam. Roda como pass GPU de compactificação; duração de frações de segundo a poucos segundos, conforme a contagem. Não afeta performance de treinamento. Com este toggle desligado, Gaussians invisíveis são exportados também — relevante apenas se você pretende usar o formato para outro estágio de treinamento (Continue Training); senão, desperdício de espaço.

ONDE

Inspetor → Enhancements → MetalFX Spatial Upscaling.

TÉCNICO

Ativa o MetalFX Spatial Upscaler da Apple no renderer do viewport. Se a resolução de treinamento (via I22 Render Scale) é menor que o tamanho do viewport, o MetalFX upscala o frame renderizado para o tamanho de exibição via ML. Entrega os resultados mais nítidos entre as opções de scaling, porque o modelo ML é otimizado para bordas nítidas. O pipeline do renderer é reconfigurado ao alternar — efeito visível imediatamente, sem reiniciar. Tem precedência sobre MPS Lanczos (I28): se ambos estão ativos, MetalFX vence. Overhead de performance no viewport ~1–2 ms por frame em M3. Atua só no live viewport, não em exports renderizados (orbit video, screenshots) — esses vão em resolução de fonte plena.

ONDE

Inspetor → Enhancements → MPS Lanczos Scaling.

TÉCNICO

Ativa Metal Performance Shaders da Apple com resampling Lanczos como upscaler do viewport. Lanczos é resampling clássico com filtro sinc de 8 taps — mais nítido que bilinear, algoritmo clássico sem ML. O pipeline é reconfigurado ao alternar. É ignorado se MetalFX (I27) também está ativo. Overhead mínimo (<0.5 ms por frame), mas qualidade abaixo do MetalFX. Uso: fallback para cenas em que o MetalFX produz artefatos (p. ex. estruturas de linha fortes, que o ML ocasionalmente „suaviza"). Atua, como I27, só no live viewport, não em exports.

ONDE

Inspetor → Enhancements → Perceptual Loss.

TÉCNICO

Slider 0.0–0.2 em passos de 0.01; exibe em 0.0 como „Off", senão como „0.05" etc. Ativa um termo de loss adicional que compara blur Gaussian multi-escala do render com a imagem ground truth (3 escalas de blur). Captura diferenças estruturais que L1+SSIM sozinhos não pegam. Implementação V460. Empiricamente, 0.05–0.1 melhora o L1 em alguns por cento, mas custa ~5 % de tempo de treinamento (forward pass extra pelos kernels). Acima de 0.15, o treinamento fica instável e o L1 piora (o termo domina a otimização). Atua durante o treinamento, não no pós-processamento — apesar da posição em „Enhancements", não é um realce posterior.

ONDE

Inspetor → Métricas → Iteration. Read-only.

TÉCNICO

Exibição no formato „4523 / 40000" — iteração atual sobre o total planejado. Conta em sincronia com o loop, que empurra valores a cada ~30 iters. A segunda corresponde ao valor de Max Iterations no instante de início; não muda mais, mesmo se o usuário alterar o stepper — a corrida em andamento usa snapshot próprio. Se Continue Training (+5K/+10K/+20K) for usado, o denominador aumenta.

ONDE

Inspetor → Métricas → Loss. Read-only.

TÉCNICO

Float com seis casas decimais (p. ex. „0.024385"). Mede o L1+SSIM combinado (mix por I21 SSIM Weight) mais opcionalmente Perceptual Loss (I29) e outros regularizadores. A escala não é absoluta, depende da cena — para comparações exige o mesmo dataset. Valores finais típicos em boas configurações: - Classic Quality 40K iters: 0.022–0.025 (Horse, Truck, Garden) - MCMC Full 200K iters: 0.024–0.028 - Outdoor drone 30K: 0.030–0.060 (pior por geometria) - Indoor apartamentos: 0.018–0.025

Valores acima de 0.10 após 5K iters indicam problemas de SfM (poses ruins) — abortar e recalcular.

ONDE

Inspetor → Métricas → Learning Rate. Read-only.

TÉCNICO

Exibição em notação científica (p. ex. „1.60e-04"). Learning rate atual dos parâmetros de posição (3DGS tem seis LRs independentes para posição, SH-DC, SH-Rest, opacidade, escala, rotação — a de posição é mostrada como representativa). Valor inicial padrão 1.6e-4, com decaimento exponencial até ~1.6e-6 no fim. O decaimento é ajustável pelo campo LR Schedule na configuração de treinamento (campo T no Capítulo 6). Se o LR continuar incomumente alto (p. ex. 1e-3 ou mais depois de 10K iters), pode indicar config carregada errada.

ONDE

Inspetor → Métricas → SH Degree. Read-only.

TÉCNICO

Inteiro 0–3. Grau de spherical harmonics da representação de cor. Começa em 0 (só DC, ou seja, cor independente de direção — só uma constante RGB por Gaussian) e sobe ao longo do treinamento até 3. O schedule padrão sobe 1 a cada 1000/2000/3000 iters. SH-3 corresponde a 48 coeficientes de cor por Gaussian (3 canais × 16 funções base SH). Grau mais alto significa mais reflexão dependente de direção (superfícies brilhantes parecem corretamente diferentes em ângulos diferentes), mas também mais memória e treinamento mais lento.

ONDE

Inspetor → Métricas → Gaussians. Read-only.

TÉCNICO

Número atual de Gaussians no modelo, formatado com separador de locale (p. ex. „524.318"). Crescimento: - Classic: começa nos pontos iniciais SfM (50K–300K), cresce por clone/split até antes do Densify Until, depois estático até o fim (modulo pruning). - MCMC: amostras adicionadas até o cap MCMC, depois só relocação.

Valores finais saudáveis: - Classic Quality: 400K–700K (Horse 524K, Garden 800K) - MCMC Full: exatamente no cap (padrão 150K, com auto-scale multiplier × contagem SfM, dependendo da cena 500K–1.5M)

Em MCMC, queda abaixo de 60 % do cap → anomalia (indicador de collapse; aponta regularizadores agressivos demais).

ONDE

Inspetor → Métricas → GPU Memory. Read-only.

TÉCNICO

Estimativa do consumo do buffer de Gaussians como contagem × 616 bytes (formatado em memory style). 616 bytes é o tamanho empírico de um Gaussian completo (posição, escala, rotação, opacidade, coeficientes SH grau 3, acumulador de gradiente). A exibição não inclui overhead do renderer (tile buffer, sort buffer, backward buffer) — o consumo real de GPU costuma estar 2–3× acima. Em 500K Gaussians: exibido ~290 MB, real ~700 MB. Em 1.5M: exibido ~880 MB, real ~2.5 GB. Em M3 Max com 64+ GB de unified memory, não crítico; em M3 Pro com 18 GB, já no limite.

ONDE

Inspetor → Métricas → Speed. Read-only.

TÉCNICO

Iterações por segundo com uma casa decimal („24.3 it/s"). Calculado pelo trainer como média móvel das últimas ~100 iters. Valores típicos: - Preset Quick (1K iters): 80–120 it/s (curto, sem steady state) - Classic 20K @ 1.0 Render Scale (cena Truck, M3 Max): 25–35 it/s - Classic 20K @ 0.5 Render Scale: 80–120 it/s - MCMC 200K @ 0.5 Render Scale: 25–50 it/s (mais lento por relocação) - Com 1M+ Gaussians e resolução plena: <10 it/s

Velocidade caindo ao longo do treinamento é normal — mais Gaussians = mais compute por iter. Quedas abruptas (p. ex. de 30 para 5 it/s) indicam thermal throttling de GPU ou apps concorrentes.

ONDE

Inspetor → Métricas → Elapsed. Read-only.

TÉCNICO

Tempo já decorrido como „4:23" (m:ss) ou „1:23:45" (h:mm:ss). Troca de formato a partir de 1 hora. Mede apenas o tempo de treinamento, não as fases anteriores (cálculo SfM, import de imagens). Em pause/resume o relógio continua — é wall clock, não CPU time.

ONDE

Inspetor → Métricas → ETA. Read-only.

TÉCNICO

Tempo estimado restante como „17:42" ou „1:12:35". Cálculo: (Max Iterations − iter atual) / iters por segundo. Mostra „–" quando a velocidade é zero (logo no início ou em pause). A estimativa não é ajustada para a desaceleração típica perto do fim — em MCMC e Classic com Densify Until grande, o treinamento tende a ficar mais lento porque mais Gaussians entram em cena. Real geralmente fica 10–20 % acima da ETA inicial.

ONDE

Inspetor → Gráfico de loss → label à esquerda „Current: 0.0287". Read-only.

TÉCNICO

Float do último sample de loss, com quatro casas. Idêntico ao I31 (Loss em métricas), só com formato mais compacto. Fonte é a Loss History — uma lista que ganha entrada a cada ~30 iters. Só valores finitos vão para a lista — NaN/Infinity (raro, em bugs de explosão de gradiente) são filtrados.

ONDE

Inspetor → Gráfico de loss → label à direita „Min: 0.0245" (verde). Read-only.

TÉCNICO

Mínimo de todos os loss vistos no run atual. É recomputado ao vivo da Loss History — sem persistência separada. Exibido em verde porque „Min" = „best so far". A linha tracejada verde na borda inferior do chart marca essa Y visualmente. Em sessões Continue Training, o rastreio de mínimo reinicia — a antiga history é substituída pela nova na UI (não apensada). Se a corrida atual rodar pior que a anterior, o Min exibido pode ser maior que o resultado final anterior.

ONDE

Inspetor → Gráfico de loss → segundo chart embaixo (laranja). Read-only.

TÉCNICO

Gráfico de linha do número de Gaussians ao longo das iters. Fonte: a Gaussian Count History (lista de pares (iter, count) preenchida pelo trainer a cada ~30 iters). Escala Y dinâmica entre mínimo e máximo da history. Em Classic, a curva sobe firme até Densify Until; depois fica plana (com pequenas oscilações de pruning). Em MCMC: sobe íngreme até o cap, depois fica horizontal (relocação mantém constante). Se a curva cai apesar do treinamento ativo, a densification está prunindo agressivo demais — indício de padrões errados ou do bug conhecido MCMC collapse (tema do hotfix v1.4.4).