Profundidade de foto: uma imagem que se comporta como um lugar
0. setup ambiente Python com MoGe-2 (uma vez; pergunta antes de baixar) scripts/setup.sh
1. depth imagem → mapa de proximidade (+ distância 16-bit, câmera, npz bruto) scripts/depth.py
2a. window a imagem como uma janela em three.js examples/portal.js
2b. place planos e pontos no próprio 3D da imagem scripts/fit_plane.py
3. check olhe para ela dos ângulos extremos que você realmente usará
scripts/ e examples/ referem-se às pastas no próprio diretório deste skill (${CLAUDE_SKILL_DIR}, tanto para um plugin quanto para um skill copiado), não ao projeto do usuário. Defina S como essa pasta scripts/ e execute "$S/depth.py" e os outros pelo caminho completo.
0. Configuração (uma vez)
Verifique primeiro: um ambiente existente com import moge funcionando pode ser reutilizado (pergunte ao usuário onde ele mantém um). Caso contrário, pergunte ao usuário antes de baixar, nomeando o que será baixado: PyTorch e ajudantes do PyPI (cerca de 1 GB instalado), código-fonte do MoGe e duas pequenas bibliotecas do GitHub (commits fixos, alguns MB) e, posteriormente, os pesos do modelo (cerca de 1,3 GB, Ruicheng/moge-2-vitl no Hugging Face). Então:
"$S/setup.sh" <pasta-para-o-ambiente> --yes
Detalhes, notas sobre GPU e outros modelos: references/setup.md.
1. Profundidade
<env>/.venv/bin/python "$S/depth.py" picture.jpg --out public/depth/ [--dist16] [--npz]
- Sempre escreve
<stem>-near.webp: proximidade (disparidade), 0 o céu, 1 a coisa mais próxima, bordas próximas crescidas em 2 px para que a borda de um objeto se mova com ele. 10-25 KB para uma imagem de 1-2K. --dist16:<stem>-dist16.webp(distância logarítmica em 16 bits, R alto G baixo, sem perdas) e<stem>-camera.json(intrínsecos estimados). Para reconstruir a imagem como uma superfície.--npz: profundidade métrica bruta parafit_plane.py.- Recusa baixar pesos a menos que
--allow-downloadseja passado: pergunte ao usuário primeiro. - Imprime a fração válida, percentis de profundidade e o campo de visão estimado. Leia-os: "válido 20%" ou um campo de visão de 150° significa que o modelo não entendeu a imagem.
Execute novamente sempre que a imagem mudar: um mapa de profundidade de uma versão mais antiga da imagem desloca cada borda.
2a. A janela
examples/portal.js é um material three.js autocontido (copie-o para o projeto). A imagem é a cena vista de um ponto de repouso (sua posição padrão da câmera). De qualquer outro lugar, cada pixel do vidro mostra o que está ao longo da linha de visão através dele, encontrado percorrendo o mapa de proximidade em 16 passos, de modo que coisas próximas cubram coisas distantes e as bordas não rasguem. Detalhes, ajustes e modos de falha: references/portal.md.
import { makePortal } from "./portal.js";
const portal = makePortal({ map, near, width: 4, height: 2.5 });
scene.add(portal.mesh); portal.setRest(defaultCameraPosition);
// a cada quadro: portal.update(camera);
examples/portal.html é uma demonstração em um único arquivo: sirva uma pasta com a imagem, seu mapa de proximidade, portal.js e a página, abra portal.html?pic=<arquivo>&near=<arquivo> e mova o ponteiro.
Verifique da maneira que será vista: mantenha a câmera nas posições mais à esquerda, direita, superior e inferior que o site realmente usa (para uma verificação automatizada, a demonstração honra window.__view = [x, y]) e observe cada uma:
- Não consegue ver profundidade? A primeira versão deste efeito em um site real era muito fraca para ser notada: diminua
uQ.y(0,6 → 0,4). - Coisas próximas se movem mais contra a moldura, ou o céu nada? A profundidade está invertida (distância usada como proximidade).
- Manchas ou objetos duplicados em movimentos grandes: uma única imagem não tem nada atrás de seus objetos próximos. Mantenha os movimentos da câmera pequenos, ou suavize-os (
uEase), ou pinte uma camada de fundo (references/placing.md).
2b. Colocando coisas na imagem
<env>/.venv/bin/python "$S/fit_plane.py" plane out/city-depth.npz --box 410,120,520,260
<env>/.venv/bin/python "$S/fit_plane.py" plane out/city-depth.npz --box 410,120,520,260 --corners 415,128 515,124 516,250 414,255
<env>/.venv/bin/python "$S/fit_plane.py" point out/city-depth.npz 640,700
Os pixels são da própria imagem (--norm para 0..1). A saída é JSON no espaço da câmera three.js (câmera na origem olhando para -Z, metros). flatness_rms_m diz o quão plana a região realmente é: alguns centímetros em uma parede a 40 m de distância é plano. Escolha cantos dentro das bordas de um painel (não uma caixa ao redor dele) e o letreiro seguirá a forma real do painel em vez de parecer desequilibrado. Reconstruindo a imagem inteira como uma superfície 3D, bordas rasgadas, camadas de fundo: references/placing.md.
Regras
- Licenças: O código e os pesos do MoGe-2 são MIT. Vários modelos populares de profundidade não são liberados para uso comercial (consulte references/setup.md): verifique antes de trocar de modelos para um cliente ou portfólio que venda trabalhos.
- A licença da própria imagem ainda se aplica a tudo que for feito a partir dela.
- Máscaras em alfa: se uma imagem carrega uma máscara em seu canal alfa (água, céu), salve o WebP sem perdas com RGB exato (
cwebp -lossless -exact, Pillowexact=True). Alfa com perdas zera a cor sob pixels transparentes e a borra. - Pergunte antes de baixar qualquer coisa (pacotes, pesos), nomeando o que, de onde e o tamanho.