GitHub – NullandKale/NullSplats

Aplicativo de desktop Tkinter + OpenGL para treinamento e visualização de splats gaussianos 3D a partir de capturas casuais. Ele agrupa COLMAP para poses de câmera, usa PyTorch + gsplat para treinamento e armazena tudo em uma árvore de cache reproduzível para que as cenas possam ser retomadas posteriormente.

• Ingira uma pasta de vídeo ou imagem, extraia e pontue quadros e selecione automaticamente um subconjunto.
• Execute o COLMAP SfM para produzir poses de câmera e pontos esparsos.
• Treine splats gaussianos na GPU com gsplat; exporte pontos de verificação como .ply ou .splat.
• Visualize splats em um visualizador OpenGL integrado dentro do aplicativo.
• Mantenha entradas/saídas por cena em cache para fluxos de trabalho repetíveis.

Nullsplats oferece suporte a 3 métodos de criação de splats:

1. Treinamento tradicional colmap + gsplat.
2. Profundidade Qualquer coisa 3 Estimativa Gaussiana 3D.
3. Síntese de visão monocular SHARP.

Aqui estão alguns exemplos de splats treinados usando este programa.

Gsplat 50-visualização

Closeup Gsplat

DA3 5 visualizações

Close do DA3

SHARP 1 visualização

Closeup AFIADO

Comparação lado a lado

No meu RTX pro 6000 Blackwell o gsplat treinou em cerca de 5 minutos incluindo o tempo de colmap. Profundidade Qualquer coisa 3 levou cerca de 3-4 minutos, mas usou significativos 16 GB de vram. SHARP produziu um respingo em cerca de 2,5 minutos.

No geral, cada um é muito bom considerando a entrada. O splat SHARP de visualização única é particularmente impressionante. Se o DA3 fosse menos estranho e menos transparente, seria significativamente melhor. A geometria parece muito boa.

Quer discutir desenvolvimento ou obter suporte? Abra um problema ou verifique o discord.

• main.py – ponto de entrada do aplicativo (raiz Tk + guias).
• lugar zero/
  • ui/ – Tk UI, guias, visualizadores OpenGL, shaders (ui/shaders/.vert|.frag).
  • backend/ – extração de quadros, pipeline COLMAP, treinamento splat.
  • util/ – registro, configuração, auxiliares de threading e padrões de caminho de ferramenta.
• build.bat – construtor de pacotes portátil.
• run.bat – lançador usado dentro do pacote portátil.
• requisitos.txt – Dependências do Python.

O aplicativo é organizado em torno de um pequeno objeto de estado central (AppState), quatro guias de UI (Entradas, COLMAP, Treinamento, Exportações) e um pipeline de back-end que lida com extração de quadros, estrutura de movimento COLMAP e treinamento gsplat.

1. main.py configura o log, cria AppState e constrói a raiz Tk em ui/root.py.
2. ui/root.py conecta as quatro guias e roteia a seleção de cena entre elas.
3. A guia Entradas cria cenas, extrai quadros e persiste quadros selecionados/redimensionados.
4. A guia COLMAP executa o SfM para gerar poses de câmera e pontos esparsos.
5. A guia Treinamento executa treinamento gsplat e transmite visualizações ao vivo.
6. A guia Exportações lista pontos de verificação e renderiza visualizações/plataformas giratórias.

• nullsplats/app_state.py possui AppState (config + SceneManager + cena atual).
• nullsplats/backend/io_cache.py define ScenePaths e leitura/gravação de metadados.
• Layout do cache (por cena):
  • cache/entradas//source (cópia original)
  • cache/entradas//quadros_todos
  • cache/entradas//frames_selected
  • cache/entradas//metadados.json
  • cache/saídas//sfm
  • cache/saídas//lugar
  • cache/saídas//renderiza
• nullsplats/backend/scene_manager.py lida com descoberta de cena, persistência de seleção e cache de miniaturas (thumbnails.db).

• ui/root.py cria o ttk.Notebook, instancia guias e coordena alterações de guias.
• Guias:
  • Entradas: ui/tab_inputs.py + mixins
  • COLMAP: ui/tab_colmap.py
  • Treinamento: ui/tab_training.py + mixins de layout/visualização
  • Exportações: ui/tab_exports.py
• Fluxos do assistente:
  • Assistente embutido em entradas: ui/tab_inputs_wizard.py (pop-up único com entradas + predefinição de treinamento + opções COLMAP).
  • Janela do assistente independente: ui/wizard.py

• ui/tab_inputs.py é o coordenador do fluxo de trabalho de Entradas.
• ui/tab_inputs_scenes.py renderiza a barra lateral da cena e o gerenciamento da cena.
• ui/tab_inputs_grid.py renderiza a grade de quadros virtualizados e as miniaturas.
• Principais usos de back-end: backend/video_frames.py, backend/scene_manager.py.

• ui/tab_colmap.py executa SfM e gerencia configurações/logs COLMAP.
• Chamadas de back-end:
  • backend/sfm_pipeline.py (COLMAP CLI)

• ui/tab_training.py orquestra execuções de treinamento, gerencia o registro em log e possui o estado de visualização.
• O método de treinamento é selecionável (gsplat ou DA3). A visualização ao vivo é apenas gsplat.
• ui/tab_training_layout.py cria os widgets da IU.
• ui/tab_training_preview.py lida com pesquisa de visualização + fila de visualização na memória.
• Chamadas de back-end:
  • backend/splat_train.py (loop de treinamento gsplat)

• ui/tab_exports.py lista pontos de verificação, abre um visualizador de visualização e renderiza plataformas giratórias.
• Usa GLCanvas para exibir pontos de verificação .ply e imageio para saída de vídeo.

• identificadores backend/video_frames.py:
  • extração ffmpeg/ffprobe
  • pontuação de nitidez/variância
  • seleção automática dos melhores frames
  • persistência de cache de seleções

• backend/sfm_pipeline.py executa extração de recursos COLMAP, correspondência, mapeamento e conversão de modelo. Os registros vão para cache/saídas//sfm/logs.

• backend/splat_train.py é o ponto de entrada do treinamento.
• Módulos de suporte:
  • backend/splat_train_config.py (dataclasses e retornos de chamada)
  • backend/splat_train_io.py (análise de texto COLMAP + carregamento de quadro)
  • backend/splat_train_ops.py (configuração CUDA, otimizadores, auxiliares de exportação)
  • backend/gs_utils.py (utilitários de otimização de câmera/aparência)
• Back-end DA3: backend/splat_backends/profundidade_anything3_trainer.py (inferência de profundidade qualquer coisa 3 + exportação gs_ply)

• ui/gl_canvas.py é a superfície de visualização principal:
  • Wraps GaussianSplatViewer para exibição OpenGL ao vivo.
  • Usa SplatRenderer (rasterização gsplat) para renderizações offline e toca-discos.
  • Suporta visualizações na memória via PreviewPayload.
• ui/gaussian_splat_viewer.py é o renderizador OpenGL (quads + shaders instanciados).
• ui/gaussian_splat_camera.py contém ajudantes matemáticos de câmera.
• Os shaders residem em ui/shaders/gaussian_splat.vert e ui/shaders/gaussian_splat.frag.
• Painéis de controle:
  • ui/render_controls.py (controles básicos)
  • ui/advanced_render_controls.py (depuração/escala/câmera)
  • ui/colmap_camera_panel.py (aplicar poses COLMAP)

• util/threading.py executa tarefas em segundo plano e empacota retornos de chamada para o thread Tk.
• util/logging.py define um console consistente + registrador de arquivo em logs/app.log.
• util/tooling_paths.py resolve caminhos COLMAP e CUDA padrão.

• requisitos.txt contém dependências principais (torch, gsplat, PyOpenGL, etc.).
• build.bat cria um pacote portátil com DLLs venv, COLMAP e CUDA.
• run.bat é o inicializador dentro do pacote portátil.

• Windows (destino principal) ou um ambiente Linux com binários correspondentes.
• Python 3.10+ com pip/venv.
• GPU com driver compatível com CUDA; Compilação PyTorch CUDA instalada.
• ffmpeg/ffprobe em PATH (para extração de vídeo).
• Binários COLMAP (construção CUDA recomendada) em ferramentas/colmap ou caminho fornecido pelo usuário.
• Opcional: binários GLOMAP em ferramentas/glomap (uso futuro).
• Opcional: back-end do Depth Anything 3 (pip install do GitHub; sem submódulo).
• Opcional: back-end SHARP (tools/sharp incluído; instale dependências editáveis).

DA3 usa a API oficial Depth Anything 3 e emite .ply respinga no cache. Requer a instalação do projeto via pip do GitHub:

pip install git+https://github.com/ByteDance-Seed/Depth-Anything-3

As configurações do DA3 ficam na guia Treinamento (resolução de processo, seleção de visualização e pontuação de visualização baseada em COLMAP). Se faltar confiança no COLMAP, o DA3 volta para visualizações com espaçamento uniforme.

SHARP é executado em imagens únicas e pode, opcionalmente, usar intrínsecos COLMAP para execuções de múltiplas visualizações. O repositório inclui a fonte SHARP em tools/sharp; instale-o em modo editável:

pip install -e tools/sharp

Da raiz do repositório:

python -m venv .venv
.venv\Scripts\activate.bat
pip install -r requirements.txt

Se você precisar inicializar o PyTorch/gsplat compatível com CUDA, execute tools\setup_cuda_venv.bat (ajudante opcional, se presente).

Para suporte DA3:

pip install git+https://github.com/ByteDance-Seed/Depth-Anything-3

Para suporte SHARP (se você ignorou os requisitos):

pip install -e tools/sharp

Com o venv ativo:

Os logs vão para logs e stdout; cache reside em cache/inputs/ e cache/saídas/.

• Guia Entradas: escolha ou crie um ID de cena, selecione a pasta de vídeo ou imagem, defina a contagem de quadros candidatos/alvo e, em seguida, Extraia quadros. Quadros e metadados chegam ao cache/entradas//.
• Guia COLMAP: verifique o caminho COLMAP, o matcher e o modelo da câmera e execute o SfM. As saídas vão para cache/outputs//sfm.
• Guia Treinamento: configure o dispositivo CUDA e os hiperparâmetros de treinamento e, em seguida, execute o treinamento. As saídas vão para cache/outputs//splats.
• Guia Exportações: navegue pelos pontos de verificação e visualize-os no visualizador.

build.bat cria um pacote autocontido em build\NullSplats-portable e build\NullSplats-portable.zip.

• Pré-requisito: .venv preenchido com todos os deps (incluindo CUDA PyTorch/gsplat).
• Opcional: configure SKIP_CLEAN=1 para reutilizar um pacote existente; passe um caminho CUDA como o primeiro argumento para substituir CUDA_PATH/CUDA_HOME para cópia DLL. Defina REQUIRE_CUDA=0 se desejar ignorar intencionalmente o agrupamento de DLLs CUDA (caso contrário, a compilação falhará quando CUDA estiver ausente). A cópia CUDA extrai DLLs de CUDA_SRC\bin (cud*/nv*).
• Opcional: defina SKIP_ZIP=1 para pular a criação do zip (mais rápido). Se 7z estiver em PATH, a compactação usará -mx=0 (somente armazenamento) para velocidade; caso contrário, volta para PowerShell Compress-Archive -CompressionLevel Fastest.
• O construtor remove pacotes Python não utilizados (tqdm, tyro, opencv-python, PyYAML) e copia apenas DLLs CUDA principais; COLMAP está incluído, GLOMAP não.
• Se você precisar depurar o pacote CUDA, build.bat imprime os caminhos de origem e destino, além de listagens de diretórios para as DLLs copiadas. Defina REQUIRE_CUDA=1 para falhar rapidamente quando nenhum for copiado.
• Execute a partir da raiz do repositório:

Dentro do pacote, use run.bat para iniciar; ele ativa o venv empacotado e precede os caminhos CUDA e COLMAP empacotados.

1. O download é apenas Windows + CUDA.
2. COLMAP não é construído durante o processo de construção.
3. O download é grande.
4. Às vezes, as miniaturas não carregam.
5. A renderização Splat está ligeiramente errada.
6. O controle da câmera não é ótimo.
7. Não inclui ffmpeg na compilação.
8. Pode precisar do SDK CUDA no caminho, mesmo que esteja incluído.

• Padrão COLMAP: ferramentas/colmap/COLMAP.bat incluídas, se presente; caso contrário, especificado pelo usuário.
• Padrão CUDA: empacotado cuda/ dentro do pacote; caso contrário, CUDA_PATH/CUDA_HOME, então C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8.
• Cache: criado sob demanda em cache/entradas e cache/saídas.