Capítulo 4 — Janelas auxiliares
Além da janela principal (viewport 3D mais Inspector), o RadianceKit gerencia mais três janelas, todas abertas pelo menu Help. O menu tem cinco itens, de cima para baixo: User Guide (⌘?), Keyboard Shortcuts (⌘/), Open Training Logs… (⇧⌘L), Open Exports Folder… e Manage Storage…. Os dois itens "Open …" não abrem uma janela do app, mas sim o Finder; por isso não são tratados em detalhe aqui.
As três janelas simples (User Guide, Keyboard Shortcuts, Manage Storage) e os dois itens de menu de pasta (Open Training Logs / Open Exports Folder) recebem uma breve entrada por controle.
No final do capítulo há uma seção de referência cruzada ao Inspector da janela principal: o que você pode interpretar de forma útil no gráfico de perda ao vivo (Live-Loss-Chart) e na exibição da contagem de gaussianas durante um treinamento em andamento.
Guia do Usuário (W1–W4)

O que é: Uma janela de ajuda integrada que renderiza o arquivo guide_<sprache>.md fornecido junto com o app. O idioma é derivado das Settings (aba General → Language) ou, se lá estiver definido como "System", das preferências de idioma do macOS. O layout é clássico: barra lateral à esquerda com todos os títulos, texto corrido à direita.
Quando você precisa de uma lembrança rápida sobre um único ponto — ou seja, como substituto de anotações. A referência completa é este Manual; a janela de ajuda integrada é a versão curta para consulta rápida. Ela é atualizada a cada release do app, mas mantida com conteúdo mais superficial.
W1NavigationSplitView (Sidebar + Detail)
ONDE
Help → User Guide (⌘?).
TÉCNICO
Layout de duas colunas com uma sidebar estreita (no mínimo 180 pt de largura) para a árvore de conteúdo e uma área de detalhe rolável para o conteúdo Markdown propriamente dito. A janela tem um tamanho mínimo de 700 × 500 pt. Ao abrir pela primeira vez, a janela carrega o guide_<lang>.md correspondente do bundle do app (fallback guide_en.md), faz o parsing em registros de bloco (títulos H1–H4, parágrafos, listas, tabelas, linhas divisórias) e extrai separadamente a estrutura de títulos para a sidebar. A formatação inline (negrito, itálico, code-span) é renderizada pela engine de Markdown integrada. O idioma é lido das configurações do app, com o caso especial de chinês (zh-Hans) e português brasileiro (pt-BR), que são mantidos como tags de locale completas, pois essas variantes se diferenciam de zh e pt, respectivamente.
W2List (Sidebar de Títulos)
ONDE
Coluna esquerda na janela do Guia do Usuário.
TÉCNICO
Lista com todos os títulos H2 e H3 do documento Markdown atual. Entradas H2 aparecem sem recuo, com peso de fonte médio; entradas H3 aparecem com 16 pt de recuo à esquerda e estilo de primeiro plano reduzido. Todos os outros níveis — tanto H1 quanto H4 e abaixo — não aparecem na sidebar, pois deixariam a navegação confusa. Os IDs de âncora são gerados a partir do texto do título por slugificação (letras minúsculas + espaços viram traços + filtragem para letras/números/traços — o mesmo algoritmo que o GitHub usa para suas âncoras de Markdown, de forma que até URLs externas para a documentação poderiam potencialmente apontar para a mesma âncora). A lista usa o estilo nativo do macOS.
W3Button (Salto de Título → Âncora)
ONDE
Um botão por linha da sidebar.
TÉCNICO
Cada item da sidebar é um botão que define a âncora atual, mas visualmente parece um item de lista. Uma variável observadora então dispara o salto de rolagem até a âncora correspondente, com uma animação suave de 0,3 s. Depois do salto, o valor da âncora é resetado, para que o próximo clique na mesma âncora dispare novamente (caso contrário, o observador não seria acionado de novo, pois o valor não teria mudado).
W4ScrollView (Conteúdo de Detalhe)
ONDE
Coluna direita.
TÉCNICO
Área de conteúdo rolável, empilhada verticalmente, com renderização preguiçosa (lazy), pois guias mais longos podem facilmente ter mais de 200 blocos Markdown — uma variante não-lazy instanciaria todos simultaneamente. Cada bloco recebe um ID próprio, seja a âncora do título (que todo título recebe, independente do nível) ou um placeholder de índice. A largura máxima é de 720 pt, com padding de 32 horizontal / 24 vertical, para que linhas longas mantenham um layout de boa legibilidade. Tabelas são renderizadas célula por célula com stacks horizontais e linhas divisórias; código inline pela engine de Markdown integrada. Blocos de código reais são atualmente tratados como parágrafo — uma limitação conhecida da janela de ajuda.
Atalhos de Teclado (W5–W6)

Lista de referência estática em cinco seções. Navigation: Mouse Drag (Orbit/Fly), Shift+Drag/Right-Drag (Pan), Scroll (Zoom), WASD (movimento Fly-Through), Q/E (Up/Down), F (Toggle Orbit/Fly), Double-click (Re-center), Cmd+Scroll (ajuste de FoV). Views: R (Reset Camera), T (Auto-Rotation), P (Camera Playback), B (Background-Cycle), 0–9 (pula para Training-Cam 1=10%/5=50%/0=último), Left/Right Arrow (Prev/Next Cam). Capture: S (Screenshot to Desktop), V (vídeo Turntable), C (Copy Camera Info). Editor: Tab (modo de edição), Click/Drag (seleção por pintura), Option+Click (desmarcar seleção), X / Delete (apagar seleção), Cmd-Z (desfazer última exclusão), [ / ] (diminuir/aumentar tamanho do pincel), Esc (limpar seleção). Training: Option+Space (pausar/retomar treinamento), Cmd+E (exportar cena). Nada além disso está aqui — Start, Cancel e as extensões você acessa pelo menu Training (capítulo 1).
O que é: Uma visão geral estática e simples de todos os atalhos de teclado — Navigation, Views, Capture, Editor, Training. O conteúdo é fixo e não é carregado a partir de um arquivo.
Quando você procura a forma mais rápida de fazer algo no Viewport. WASD-Fly-Through, R para Camera-Reset, B para o Background-Cycling — tudo está aqui.
W5ScrollView (área de conteúdo)
ONDE
Help → Keyboard Shortcuts (⌘/).
TÉCNICO
Uma área de rolagem simples com uma lista vertical dentro. Padding de 20 ao redor, sem árvore de navegação lateral (a lista é curta o bastante). O conteúdo é agrupado em cinco seções (Navigation, Views, Capture, Editor, Training). Para cada combinação de teclas há uma linha com texto traduzível em ambas as colunas. A coluna esquerda (código da tecla) tem largura fixa de 180 pt, para que as descrições à direita permaneçam alinhadas verticalmente. Nenhuma interação além de rolar — clicar em uma linha não dispara nada, os atalhos de teclado são modificadores de teclado reais no menu e no viewport.
W6VStack (seções de atalhos)
ONDE
Dentro do ScrollView.
TÉCNICO
Seções empilhadas alinhadas à esquerda com 16 pt de espaçamento. Dentro das cinco seções, cada uma tem um Heading + sequência de linhas. Os headings usam um estilo secundário de subheadline — propositalmente sem formato de Title, pois as seções não precisam ser navegáveis. O conteúdo é propositalmente plano (sem disclosure, sem search, sem filter), para que o componente funcione sem alterações em qualquer versão do macOS e o arquivo permaneça legível.
Manage Storage (W7–W12)

Visualização em tabela de todos os arquivos gerenciados pelo RadianceKit. O cabeçalho conta 1.356 itens, 55,1 GB de tamanho total. Barra de ferramentas acima: „Show in Finder" + „Refresh". Cada linha: ícone de exportação, nome do arquivo (ex.: training_20260718T194416Z.ply), data de exportação, tamanho (varia aqui de 7,8 MB a 2,24 GB), ícone de lupa (Reveal) e ícone de lixeira (Move to Trash). A ordenação é primeiro por categoria e, dentro de uma categoria, por data, com as mais recentes no topo. Nesta captura predominam as exportações PLY, porque neste local foram salvos principalmente resultados de treinamento.
O que é: Uma visão geral do uso de disco para tudo que o RadianceKit armazena em ~/Documents/RadianceKit/ — logs, exportações, cenas, pacotes de captura (do companion iOS), importações (cópias temporárias das imagens de entrada). Por item, um tamanho em bytes e dois botões: „im Finder anzeigen" e „in den Papierkorb verschieben". NÃO é uma limpeza automática — o app em si não apaga nada; você decide item por item. Esta janela é traduzida: em alemão chama-se „Speicher verwalten", os dois botões do cabeçalho se chamam „Im Finder anzeigen" e „Aktualisieren", os botões de linha „Im Finder anzeigen" e „In den Papierkorb legen". Os nomes em inglês nos itens abaixo são as denominações da versão em inglês.
Quando o disco começa a ficar cheio. Sobretudo os logs se acumulam (um JSONL por tentativa de treinamento, mais o _qualityMetrics.json); as exportações também, claro (PLY é 100% dados brutos, um por exportação). Também útil após uma falha, quando o diretório de staging de importações ainda tem cópias antigas das imagens de entrada espalhadas por aí.
W7Botão „Show in Finder"
ONDE
Cabeçalho, canto superior direito da janela do navegador de armazenamento.
TÉCNICO
Abre a pasta de dados do RadianceKit no Finder — exatamente o diretório cujo conteúdo esta janela lista. Assim você vê a estrutura de pastas (Logs, Exports, Scenes, Captures, Imports) diretamente e também pode mover ou copiar os arquivos usando o próprio Finder. A ação abre uma nova janela do Finder; a lista na janela não é atualizada com isso — é para isso que serve „Refresh" (W8).
W8Botão „Refresh"
ONDE
Cabeçalho, ao lado do botão do Finder.
TÉCNICO
Dispara uma varredura em segundo plano que roda como uma tarefa assíncrona iniciada pelo usuário, para que a varredura de árvores de diretório grandes não bloqueie a interface. A travessia percorre cada subpasta conhecida (Logs, Exports, Scenes, Captures, Imports) e cria um item de armazenamento para cada filho direto. Para cada item, o tamanho recursivo é determinado — preferencialmente o uso real de disco (incluindo o compartilhamento de hardlinks do APFS), com fallback para o tamanho lógico do arquivo.
W9List (itens de armazenamento)
ONDE
Conteúdo principal abaixo do cabeçalho.
TÉCNICO
Lista com este layout por linha: ícone SF Symbol específico da categoria (documento para Logs, seta de upload para Exports, cubo para Scenes, iPhone para pacotes de captura, bandeja para Imports), nome + subtítulo (rótulo de tipo + data de modificação formatada), contador de bytes à direita (alinhado à direita, monoespaçado), botão Reveal (ícone de lupa), botão Trash (lixeira). Ordenação: primeiro por tipo (Scenes primeiro, depois Exports, Logs, Captures, Imports, Other), secundariamente por data de modificação decrescente (mais recentes no topo). Se a varredura ainda estiver em andamento, o local exibe em vez disso um progresso „Scanning…". Se nada foi encontrado, uma exibição de estado vazio com ícone de bandeja.
W10Botão de linha „Reveal in Finder"
ONDE
Por linha, ícone de lupa à direita.
TÉCNICO
Abre o Finder e seleciona o item específico (arquivo ou pasta). Diferença em relação a W7: W7 abre o diretório raiz; W10 marca exatamente esse item. Fluxo de trabalho prático: identifique um item grande, clique na lupa, depois copie-o, por exemplo, para um volume externo.
W11Botão de linha „Move to Trash"
ONDE
Por linha, ícone de lixeira à direita da lupa.
TÉCNICO
Aciona a caixa de diálogo de confirmação (W12). Só após a confirmação é executada a operação padrão do macOS „mover para a lixeira" (portanto reversível, sem exclusão direta). Após o descarte bem-sucedido, o item é removido da lista e o contador de bytes total é atualizado. Em caso de erro, uma caixa de diálogo de erro modal é exibida.
W12ConfirmationDialog (confirmação de exclusão)
ONDE
É acionado pelo W11, exibido como uma sheet do macOS.
TÉCNICO
Caixa de diálogo de confirmação padrão com título dinâmico „Delete <name>?" e uma linha de mensagem que indica explicitamente que o item vai para a lixeira e pode ser restaurado de lá (até que a lixeira seja esvaziada). Dois botões: „Move to Trash" como ação destrutiva (exibida em vermelho) e „Cancel" com atalho automático de Esc. A caixa de diálogo é não modal no sentido de que bloqueia apenas essa janela, não o app inteiro — isso é o padrão do macOS para exclusões reversíveis.
Janela principal: histórico de perda e contagem de Gaussians (I39–I41, referência cruzada)
Três dos indicadores do Inspector na janela principal merecem uma explicação própria, porque ficam constantemente visíveis durante um treinamento em andamento e existem regras práticas importantes sobre quando o histórico parece saudável. Os indicadores ficam no Inspector na seção Progresso, no grupo expansível Histórico de Perda (veja o Capítulo 2 — Inspector), e ajudam a interpretar o progresso do treinamento.
Quando a curva de loss está saudável? Uma curva de loss saudável mostra três fases: (1) Warmup — nas primeiras 200–500 iterações, o loss cai abruptamente de um valor alto (tipicamente 0.15–0.25 para L1+SSIM combinados, dependendo da cena) para cerca da metade. Se o loss NÃO cair nessa fase, geralmente a entrada está errada (imagens corrompidas, poses do SfM ruins, número de Gaussians iniciais pequeno demais). (2) Densification — entre ~500 e densifyUntilIteration (classicamente 15K, no MCMC até 20K ou 25K), o loss continua caindo, muitas vezes com pequenos saltos para baixo quando operações de densify inserem novos Gaussians e o otimizador os aproveita. A contagem de Gaussians aumenta nessa fase. (3) Refinement — depois disso, o loss entra em uma cauda cada vez mais achatada. Valores finais típicos como referência: uma cena de objeto bem iluminada (como o Truck de Tanks-&-Temples com P4 Quality) fica em torno de L1 ≈ 0.023, enquanto cenas externas amplas como as do Mip-NeRF 360 naturalmente ficam acima disso (0.04–0.07).
O que significa um platô? Um platô (a curva de loss anda na horizontal por vários milhares de iterações) tem duas interpretações: (a) o modelo convergiu, treinar mais não traz benefício algum — este é o caso bom. (b) o modelo está travado (mínimo local, informação de gradiente ruim, um limite no buffer atingido) — o caso ruim. Ambos parecem idênticos no gráfico. Para diferenciar: observe a contagem de Gaussians. Se ela também estiver estagnada E próxima do limite do MCMC (por exemplo, 150K de 150K no preset P8 Quality (MCMC)), você atingiu o limite — ou aumenta o limite ou aceita o platô. Se a contagem de Gaussians ainda está crescendo, mas o loss não cai, isso é travamento.
Quando interromper ou continuar treinando? Regra prática: se não houver melhora no loss mínimo por 10K iterações → interrompa, iterações adicionais são desperdiçadas. Antes disso: pelo menu Training → Continue Training → „+5,000 iterations" você pode adicionar uma extensão, caso perceba uma melhora limítrofe (não existe atalho de teclado para isso). Atenção: no MCMC o platô costuma ser real — o limite é a fronteira natural.
Platô na contagem de Gaussians NÃO é sinal de "concluído". Isso significa apenas que o MCMC atingiu o limite ou que a Classic Densification se esgotou. A verdadeira questão de "concluído" só é respondida por PSNR/SSIM/LPIPS em um conjunto de teste independente. O conjunto de teste independente também mostra se seu conjunto de câmeras permite, de fato, uma divisão justa entre ângulos de treinamento e de teste.
PSNR/Holdout é a verdade, o loss é apenas um proxy. O loss é uma métrica relativa: ele cai enquanto seu modelo se ajusta às views de treinamento. Mas um loss baixo não significa automaticamente um modelo bom — se o modelo decorou as imagens de treinamento (overfitting), o loss seria pequeno, mas o PSNR em views não vistas (holdout) seria ruim. Por isso: para a avaliação final de qualidade, sempre observe as métricas de holdout, não apenas o loss final.
Regra de Ouro
- User Guide e Keyboard Shortcuts são ajuda estática — rápidos para dúvidas pontuais, mas para se aprofundar use este manual aqui. - Abra o Manage Storage assim que o disco cair abaixo de 10% de espaço livre. Logs e o staging de Imports costumam ser os grandes vilões. - Plateau de loss e plateau de contagem de Gaussianas devem ser interpretados separadamente. O limite de cap não é um sinal de "pronto". A qualidade real só é medida pelo PSNR do holdout. - 10 mil iterações sem melhora no min-loss → pare o treinamento.