Capítulo 3 — Configurações

ONDE

Settings → General → Interface → seletor Default Mode. Bound:. Default: .simple.

TÉCNICO

Controla em qual dos dois modos de interface o app abre após o próximo início. „Simple Mode" é o fluxo guiado em assistente de 4 passos (Importar → Processamento → Pré-visualização → Exportar, documentado no Capítulo 10 sob Z1–Z4), „Expert Mode" é o layout clássico de três painéis com Navigator, Viewport 3D e Expert Inspector do Capítulo 2. O valor é lembrado entre reinicializações. Efeito idêntico ao menu Mode → Simple Mode (⌘1) / Mode → Expert Mode (⌘2), apenas que o menu alterna a sessão em execução, enquanto este seletor define o padrão para sessões futuras. Ambos os modos acessam o mesmo estado de projeto — projetos, câmeras e configuração de treinamento são preservados ao trocar de modo. Botões da barra de ferramentas específicos do modo são renderizados imediatamente.

ONDE

Settings → General → Interface → seletor Language. Bound:. Default: .system (segue o idioma do macOS).

TÉCNICO

Seleciona o idioma de exibição de toda a interface do app, independentemente do idioma do sistema macOS. O RadianceKit é localizado em 17 idiomas (de, en, pl, en-AU, ar-SA, mais 12 outros). Em „System", o app segue o idioma do macOS. Com uma escolha explícita, a configuração de idioma é lembrada entre reinicializações; o efeito completo geralmente exige um reinício do app, porque os bundles de localização são carregados apenas na inicialização. As 298 chaves de localização documentadas no projeto são todas consideradas, incluindo todos os textos em sub-views e tooltips de ajuda.

ONDE

Settings → General → Viewport → seletor Background. Bound:. Default: .darkGray (RGB 0.1, 0.1, 0.1).

TÉCNICO

Define a cor de fundo padrão do viewport 3D. Três opções: „Dark Gray" (RGB 0.1, 0.1, 0.1 — padrão), „Black" (0, 0, 0) e „White" (1, 1, 1). A configuração persiste o padrão para novos projetos e sessões entre reinicializações e ao mesmo tempo atualiza o renderer Metal em execução imediatamente. Opções idênticas também estão no menu Viewport → Background (M21, M22, M23), mas o seletor das Configurações define o padrão, enquanto o menu alterna a exibição em execução. Importante para capturas de tela e vídeos demo: fundos brancos realçam mais floaters verdes/azuis, fundos escuros são melhores para gravações limpas de renderização.

ONDE

Settings → General → Viewport → toggle „Auto-Rotate After Training". Bound:. Default: false.

TÉCNICO

Inicia uma rotação contínua tipo prato giratório da câmera do viewport ao redor do centroide da cena imediatamente após o fim do treinamento (taxa padrão ~0.3 rad/s). Praticamente útil para sessões demo, comparações A/B e para avaliar logo de uma visão 360° se „floaters" se formaram na borda da cena. O efeito é visualmente idêntico ao menu Viewport → Toggle Auto-Rotation (M16, ⌘⌥T), exceto que este toggle dispara o comportamento automaticamente após o fim do treinamento, em vez de manualmente. Pode ser interrompido a qualquer momento pelo menu ou clicando no viewport (o que pausa a rotação). Não tem influência sobre a performance de treinamento — a rotação só roda depois que o treinamento termina.

ONDE

Settings → General → Training → seletor Live Preview. Bound: AppState.trainingConfig.livePreviewInterval. Default: 0 (Off).

TÉCNICO

Determina o intervalo de iterações em que o snapshot de treinamento em andamento é renderizado no viewport 3D. Quatro valores discretos: 0 („Off"), 50, 250, 1000 iterações. Com Live Preview ativo, o treinador copia o buffer de Gaussians da GPU para um buffer de render separado e dispara um redraw do viewport. Com „Off", o viewport só é atualizado após a conclusão do treinamento. Custo de performance: a cada 50 iterações ~5–10% mais lento em M3 Ultra, a cada 250 iterações ~1–2% mais lento, a cada 1000 iterações imperceptível. Overhead de memória constante ~2 GB para o buffer de snapshot, independentemente do intervalo. O valor serve como padrão para novos treinamentos; após o início do treinamento, o Training Inspector mostra o valor real ao vivo daquele treinamento. No intervalo 50, a impressão visual é uma „cresca" fluida da nuvem de pontos; em 1000 parece travada.

ONDE

Settings → General → Training → seletor Throttle. Bound: AppState.trainingConfig.throttleDelayMs. Default: 0 (Off).

TÉCNICO

Insere um atraso artificial em milissegundos entre as iterações de treinamento. Quatro valores discretos: 0 („Off"), 2 („Light"), 5 („Moderate"), 10 („Eco"). Sentido: em treinamentos mais longos (várias horas), a GPU é normalmente usada a 100%, o que leva a uma UI do sistema visivelmente mais lenta (cursor travando, outros apps ficam pesados). O atraso de throttle dá à GPU pausas em que outras tarefas podem ser executadas. O custo de performance é considerável: com 5 ms de throttle, um treinamento típico de 40K dura cerca de 50–80% mais que sem throttle. No modo de performance „Eco" (10 ms) o atraso por iteração é maior que a própria iteração — fator 2–3× mais lento. Com throttle ativo, aparece um aviso abaixo do seletor: „Throttle is on. Training will be slower than usual." O app em si não reage de forma perceptivelmente melhor — só outros apps se beneficiam.

ONDE

Settings → General → Experimental — Outdoor Floater Reduction → toggle „Sky Masking". Bound: AppState.trainingConfig.skyMaskingEnabled. Default: false.

TÉCNICO

Ativa a segmentação pré-treinamento de pixels de céu baseada em Apple Vision. Antes do início do treinamento, a região do céu é extraída para cada câmera de entrada via Apple Vision foreground mask (Sky = Background) e atribuída como máscara por pixel à respectiva câmera. Durante o treinamento, a contribuição de loss por pixel é multiplicada pelo complemento da máscara de céu — pixels de céu contribuem com 0 para o gradiente, de modo que Gaussians que projetam no céu não recebem sinais de otimização e portanto não ficam mais „densos" ou „mais brilhantes". Reduz significativamente os floaters (grumos escuros no céu) em cenas externas/de drone. Custa ~3% de regressão de L1 no treinamento Classic de 40K (ver memory/dev_outdoor-floater-reduction.md). Só faz sentido em cenas externas com céu claramente reconhecível; em cenas internas ou com fundo branco, a segmentação de céu identifica áreas erradas e bloqueia sinais de loss válidos. Ao contrário dos demais toggles experimentais, o valor não é lembrado entre reinicializações do app — no próximo início, ele está desligado de novo.

ONDE

Settings → General → Experimental — Outdoor Floater Reduction → toggle „Mid-Training Floater Cleanup". Bound:. Default: false.

TÉCNICO

Liga, no treinamento Classic 40K (preset „P4 Quality"), dois passes adicionais de controle de densidade: na iteração 20,000 e na iteração 30,000. Ambos varrem todos os Gaussians por três critérios: (a) opacidade muito baixa (padrão 0.005), (b) tamanho ínfimo em screen-space, (c) sem contribuição de loss nas últimas 1000 iterações. Gaussians que satisfazem todas as três condições são removidos. Efeito: ~5–15% menos Gaussians ao fim do treinamento, visivelmente menos grumos escuros no céu em cenas de drone/externas. Custa ~1–3% de regressão de L1 em cenas internas em close-up, por isso não é ativado por padrão. O valor é lembrado entre reinicializações (ao contrário do S7). As duas iterações de limpeza (20K, 30K) são fixas e atualmente não podem ser alteradas via UI; em treinamentos mais curtos (p. ex. P2 Preview 5K) o toggle não tem efeito, pois nunca alcança essas marcas de iteração. Detalhes: memory/dev_outdoor-floater-reduction.md.

ONDE

Settings → General → Experimental — Outdoor Floater Reduction → toggle „Reduce Elongated Gaussians". Bound:. Default: false.

TÉCNICO

Ativa uma regularização adicional de anisotropia no termo de loss. Durante a otimização, para cada Gaussian a anisotropia é calculada como a razão entre o maior e o menor eixo de escala. Se a razão excede um limiar (, padrão 10.0), um termo de penalidade é somado ao loss, escalado proporcionalmente ao excesso. Efeito: Gaussians em forma de agulha, típicos de artefatos cross-hatch e em listras em grama e folhagem densa, são durante o treinamento forçados a formas mais arredondadas ou removidos. Em troca, ~6 % de regressão de L1 em cenas internas padrão, sem efeito em capturas estritas de objeto. O sweet spot é em voos de drone sobre vegetação. Grava em, persiste via. Implementação em optimizer.metal como penalidade adicional no cálculo do gradiente. Veja a nota na memória do projeto: V549d foi a versão lançada, uma versão posterior V549f com regularização de escala mais agressiva foi revertida por regressão catastrófica. Detalhes: memory/dev_outdoor-floater-reduction.md e memory/dev_v549f-needle-reduction.md.

ONDE

Settings → General → Experimental — Outdoor Floater Reduction → toggle „Reconstruct Sky Dome". Bound:. Default: false.

TÉCNICO

Ativa a projeção de Sky Dome pré-treinamento (V549e MVP). Depois do SfM e antes do início do treinamento, a máscara de céu Apple Vision compartilhada com S7 é extraída da imagem para cada câmera de entrada, os pixels de céu são des-projetados com as intrínsecas da câmera para uma superfície esférica virtual (raio padrão 8× o raio da cena). Nessa esfera, ~5000 novos Gaussians são inicializados com médias de cor dos pixels de céu projetados, escala muito grande (1.0 em unidades de cena) e opacidade inicial 0.95. Esses 5000 Gaussians não são uma máscara de céu no sentido clássico — eles são treinados como todos os outros, mas a alta opacidade inicial os mantém numa casca fina. Resultado: em vistas novas 360° em cenas externas/de drone aparecem cor de céu real e estruturas de nuvens em vez de grumos escuros tipo confete. O valor é lembrado entre reinicializações. Só faz sentido em cenas externas com pelo menos 360° de cobertura de câmera; em capturas puras de objeto sem visão de céu não tem efeito. Status: experimental, a validação A/B mais ampla em outros conjuntos externos ainda está pendente.

ONDE

Settings → AI Helpers → primeira seção → toggle „AI Helpers enabled". Bound:. Default: true.

TÉCNICO

Chave mestra sobre todas as features de AI Helpers no pipeline. Quando desligada, o pipeline de import e SfM pula completamente todos os estágios de pré-processamento baseados em ML — sem chamada a Apple Vision, sem carregamento de modelo CoreML, sem acordar a NPU. Quando ligada, os sub-toggles individuais (S12–S14) são consultados. O valor é lembrado entre reinicializações. Afeta os seguintes estágios: (a) pre-check de qualidade de frame antes do SfM (S12), (b) detecção de loop closure (S13), (c) sky masking automático como valor padrão para novos treinamentos (S14). Importante: quando desligada, os três sub-toggles ficam desabilitados e visualmente acinzentados. O aviso no rodapé enfatiza que todos os AI Helpers rodam estritamente on-device — sem upload de imagem, sem processamento na nuvem. A garantia de privacidade vem do uso exclusivo do framework Apple Vision (local na Neural Engine) e de modelos CoreML que vêm diretamente no bundle do app.

ONDE

Settings → AI Helpers → seção Available → toggle „Frame quality check". Bound:. Default: true.

TÉCNICO

Ativa o screener de qualidade de frame (Fase 3.11), que analisa cada frame importado antes da chamada de SfM. Passos do pipeline por frame: (a) filtro de variância laplaciana do Apple Vision (detecção de borrão — limiar ~150), (b) verificação de super/sub-exposição baseada em histograma (limiar: >5% pixels em 0 ou 255), (c) detecção de frame em branco (desvio padrão < 5 em todos os pixels). Frames que passam em todos os três checks seguem diretamente. Frames que falham em pelo menos um check disparam um diálogo modal de confirmação que lista cada frame problemático com thumbnail e justificativa e pergunta se ele deve ser removido. Importante: sem exclusão automática — o diálogo é sempre obrigatório, o usuário tem a última palavra. Performance: ~50 ms por frame em M3 Ultra, roda em paralelo. Quando desligado, todos os frames vão direto para o SfM sem checagem. Com a chave mestra (S11) desabilitada, este toggle fica acinzentado e sem efeito. Status entregue conforme memória: SHIPPED 2026-05-23.

ONDE

Settings → AI Helpers → seção Available → toggle „Loop closure detection". Bound:. Default: true.

TÉCNICO

Ativa a detecção de loop closure baseada em Apple Vision Feature Print. Para cada frame importado, é calculado um vetor de features de ~768 dimensões, que representa um embedding neural do conteúdo da imagem. Em seguida, todos os feature prints são comparados par a par via cosine similarity. Pares com similaridade > 0.85 e distância no índice de frames > 50 (ou seja, frames não adjacentes) são identificados como „candidatos a loop closure" e gravados num arquivo JSONL sidecar na pasta do projeto. Apenas informativo — a sequência de imagens importada não é modificada. Sentido: dá ao solver de SfM (especialmente COLMAP) uma dica de que esses frames formam cluster no espaço 3D. Para SfM nativo, a informação sidecar é atualmente só documentativa; o COLMAP usa as dicas internamente via custom matches file (integração manual possível, não conectada automaticamente). Performance: ~200 ms por frame em M3 Ultra, roda em paralelo. Quando desligado, não há feature prints gerados. Com a chave mestra (S11) desabilitada, acinzentado.

ONDE

Settings → AI Helpers → seção Available → toggle „Auto sky masking". Bound: UserDefaults.standard.bool(forKey: "aiHelpersSkyMaskingDefault") (via binding customizado). Default: false.

TÉCNICO

Define o valor padrão para a configuração de Sky Masking de S7 em novas configurações de treinamento. Diferente de S11–S13, a configuração real de Sky Masking vive por sessão de treinamento e não é lembrada entre reinicializações do app (ver S7). Para que a UI dos AI Helpers possa ainda assim oferecer um padrão persistente para „novos treinamentos", existe esse valor sombra: é lembrado entre reinicializações e é assumido como padrão inicial para Sky Masking ao configurar um novo treinamento (p. ex. novo import de projeto). Com a chave mestra (S11) desabilitada, acinzentado.