Designer 3D Local

Designer 3D Local e uma plataforma Windows local-first para reconstruir ambientes 3D a partir de fotos. O foco atual do produto e interior amplo: captura guiada, validacao geometrica, reconstrucao por Meshroom/AliceVision, publicacao de OBJ/MTL texturizado e visualizacao web com orbit, pan, zoom, reset, tela cheia e download.

O sistema foi desenvolvido para rodar na propria maquina, sem cloud e sem Funnel publico. A interface abre em http://127.0.0.1:8000; o Tailscale Serve pode apontar para essa mesma porta para acesso privado pela tailnet.

Estado tecnico atual

O pipeline ja cobre o fluxo completo:

• upload ou captura direta pela camera;
• tutorial visual de captura em loop;
• pre-processamento de fotos com normalizacao, classificacao e descarte de frames ruins;
• validacao geometrica por pycolmap;
• reconstrucao e texturizacao local por Meshroom/AliceVision;
• publicacao de manifesto, relatorios, ZIP e viewer web;
• acesso local e, quando configurado, pela URL Tailscale;
• recuperacao de artefato texturizado a partir de cache Meshroom quando a publicacao anterior foi incompleta.

O ultimo ajuste tecnico importante corrige a perda de partes internas. O Meshroom pode gerar uma malha texturizada com milhares de ilhas UV desconectadas; se a limpeza tratar cada ilha como ruido, ela corta piso, pilares e moveis. A regra atual preserva componentes internos em interiores altamente fragmentados por textura e neutraliza apenas o lado externo.

Resultado esperado no viewer:

• Reconstrucao fiel: OBJ/MTL texturizado, priorizado quando ha map_Kd valido e cobertura interna suficiente.
• Reconstrucao real: malha Meshroom sem neutralizacao seletiva, usada como diagnostico.
• Layout limpo: cena estruturada secundaria, publicada somente quando piso/teto/referencia espacial passam nos gates.

Arquitetura

flowchart LR
  UI["React/Vite UI"] --> API["Fastify API local"]
  API --> PRE["Photo analysis"]
  PRE --> COLMAP["pycolmap localize"]
  COLMAP --> GATE["Geometry gate"]
  GATE --> MESHROOM["Meshroom/AliceVision reconstruct"]
  MESHROOM --> CLEAN["Backend mesh cleaner"]
  CLEAN --> CAND["Artifact candidate evaluator"]
  CAND --> MANIFEST["model-manifest.json"]
  MANIFEST --> VIEWER["three.js viewer"]
  API --> TS["Tailscale Serve proxy"]

Loading

Separacao de responsabilidades:

• Localize: pycolmap registra cameras, chunks, loops e metricas geometricas antes de liberar processamento pesado.
• Reconstruct: Meshroom/AliceVision executa SfM, depth maps, meshing, filtering e texturing.
• Understand: o backend extrai referencia espacial, layout limpo e relatorios de qualidade quando ha confianca suficiente.
• Publish: o backend escolhe o melhor candidato seguro. Ele nao deve publicar Reconstrucao fiel sem textura fotografica.
• View: o frontend apenas carrega artefatos publicados. Limpeza pesada fica no backend.

Detalhes adicionais estao em docs/ARCHITECTURE.md.

Pipeline de reconstrucao

1. POST /api/jobs recebe name, sceneType e images[].
2. O backend salva as imagens em jobs/<id>/inputs.
3. photo-analysis calcula nitidez, brilho, contraste, duplicidade, orientacao de captura e score de continuidade.
4. A entrada filtrada e copiada para processing-inputs.
5. run_colmap_capture.py executa chunks sequenciais com overlap e retorna metricas de registro.
6. pipeline-policy decide entre final, best-effort ou rejected.
7. Meshroom roda em serie com preset do tipo de cena.
8. prepareFaithfulMeshArtifact gera a malha fiel limpa, preservando geometria interna valida.
9. createWebTextureAsset gera OBJ/MTL web-safe com atlas ate 8192.
10. evaluateArtifactCandidates escolhe faithful-web, faithful-clean ou baseline.
11. O job publica model-manifest.json, quality-report.json, texture-report.json, visual-report.json e original.zip.

Artefatos publicados

Cada job aceito deve publicar:

• model-manifest.json: contrato consumido pelo viewer.
• quality-report.json: diagnostico de fotos, COLMAP, budget e publicacao.
• texture-report.json: cobertura texturizada, atlas, faces internas/externas e candidato selecionado.
• visual-report.json: renderabilidade e comparacao contra baseline.
• original.zip: OBJ, MTL, texturas e cena estruturada quando disponivel.

Campos tecnicos do relatorio de textura:

• selectedCandidate: candidato publicado no viewer.
• textureCount: quantidade de mapas de textura encontrados no MTL.
• interiorFaceCoverage: razao de faces internas texturizadas.
• exteriorNeutralizedFaces: faces externas convertidas para material neutro.
• webAtlasCount: atlas gerados para uso web.
• maxTextureSide: maior dimensao de textura permitida para o viewer.

Stack

• Frontend: React, TypeScript, Vite, three.js.
• Backend: Node.js, TypeScript, Fastify.
• Reconstrucao: Meshroom/AliceVision.
• Validacao geometrica: Python + pycolmap.
• Viewer: OBJ/MTL, GLB quando viavel, OrbitControls.
• Acesso remoto privado: Tailscale Serve apontando para 127.0.0.1:<porta>.

Requisitos locais

• Windows 10/11.
• Node.js 24+.
• Python 3.14+.
• pycolmap instalado no Python local.
• Meshroom 2025.1.0 ou compativel.
• Tailscale instalado e autenticado, opcional.

Instalacao base:

npm install
python -m pip install pycolmap
npm run build

Inicializacao

.\Start-Designer3D.ps1

O script valida Node, Python, pycolmap, builda o projeto e abre a interface. O backend escuta somente em 127.0.0.1.

Execucao manual:

npm run build
npm start

Configuracao do Meshroom

O app procura o Meshroom em caminhos locais padrao e tambem permite salvar o caminho pela API/UI.

Endpoint:

POST /api/settings/engine

Payload:

{
  "meshroomExecutable": "E:\\Designer_3d\\Meshroom\\Meshroom-2025.1.0\\meshroom_batch.exe"
}

Tailscale

Nao existe backend separado para Tailscale. A URL da tailnet deve encaminhar para a mesma aplicacao local.

Exemplo:

tailscale serve --bg http://127.0.0.1:8000

A UI consulta:

GET /api/settings/routes

para listar localhost e a URL Tailscale quando disponivel.

APIs principais

Metodo	Rota	Uso
GET	/api/system/status	Hardware, Meshroom, Tailscale, rotas e disco
GET	/api/settings/routes	URLs locais e Tailscale
POST	/api/settings/engine	Salvar e validar Meshroom
POST	/api/jobs	Criar reconstrucao com fotos
GET	/api/jobs	Historico
GET	/api/jobs/:id	Estado completo do job
GET	/api/jobs/:id/events	SSE de progresso
POST	/api/jobs/:id/cancel	Cancelamento forte
GET	/api/jobs/:id/model	Manifesto do viewer
GET	/api/jobs/:id/download/original	ZIP com artefatos

Captura recomendada para interiores

Padrao oficial usado nos testes:

• celular na horizontal;
• lente fixa 1x;
• altura aproximada do peito;
• deslocamento real pelo ambiente, sem girar parado;
• revisitar marcos visuais a cada 3 a 5 fotos;
• 70% frames neutros com chao, parede/moveis e linha superior;
• 15% frames altos com teto e encontro parede/teto;
• 15% frames baixos com chao e encontro parede/chao.

O app penaliza frames com chao ou teto dominando demais, blur, duplicidade, oclusao por parede/pilar proximo e reflexos dominantes.

Testes

npm run check
npm run test
npm run build
npm run test:e2e

Cobertura atual do servidor:

• pre-checagem e acceptance gates;
• COLMAP parser e fallback;
• migracao de jobs legados;
• limpeza de malha;
• textura web;
• Tailscale;
• budget de hardware;
• cena estruturada;
• integracao Fastify.

Limites conhecidos

• O sistema nao inventa geometria ausente. Se nenhuma foto cobriu um movel, pilar ou canto com paralaxe suficiente, a malha pode continuar incompleta.
• GLB fiel pode ser omitido quando texturas 8192 tornam o arquivo grande demais para conversao segura. O viewer usa OBJ/MTL como caminho principal.
• Gaussian Splatting esta preparado como camada opcional, mas a publicacao robusta atual usa mesh texturizada.
• O modo best-effort e intencional: quando a geometria e reconhecivel, mas nao fecha todos os gates finais, o app publica o melhor resultado limpo com confianca explicita.

Estrutura do repositorio

apps/
  server/         Fastify, jobs, Meshroom, COLMAP, publicacao de artefatos
  web/            React, upload, captura, historico e viewer 3D
docs/
  ARCHITECTURE.md detalhes da arquitetura local
  VALIDATION.md   criterios e metricas de validacao
pipelines/        presets Meshroom por cena/perfil
tests/e2e/        fluxo browser Playwright
Start-Designer3D.ps1

Diretorios locais ignorados pelo Git:

• jobs/
• capture-sessions/
• Meshroom/
• analysis/
• prepared-sets/
• output/
• logs/
• node_modules/

Isso evita subir fotos privadas, caches pesados e binarios de terceiros.