CommunityImagemgithub.com

photo-depth

Dê a uma única foto, pintura ou imagem gerada por IA profundidade real na web. Estima um mapa de profundidade com MoGe-2 (licença MIT) e transforma a imagem em uma janela em uma cena three.js (paralaxe que se sustenta com o movimento da câmera, sem rasgar nas bordas) ou encontra pontos 3D na imagem para colocar objetos.

O que é photo-depth?

O skill photo-depth permite que desenvolvedores e designers transformem imagens 2D estáticas (fotos, pinturas ou arte gerada por IA) em experiências imersivas e interativas em 3D na web. Utilizando o modelo de estimativa de profundidade MoGe-2 (licença MIT), o skill primeiro gera um mapa de profundidade (disparidade/nearness) da imagem. Em seguida, oferece duas aplicações principais: no modo 'window', cria um efeito de paralaxe realista em three.js onde a imagem se comporta como uma janela, com objetos próximos se movendo mais que os distantes e sem rasgos nas bordas; no modo 'place', ajusta planos (como paredes ou placas) e pontos 3D dentro da imagem, permitindo inserir objetos 3D que respeitem a perspectiva e geometria da cena original. O skill suporta Claude Code e outros agentes compatíveis com skills, e inclui scripts para configuração do ambiente Python, geração de profundidade e ajuste de planos. É ideal para criar backdrops, portais, skyboxes, matte paintings ou simplesmente dar vida a imagens planas em sites 3D.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/skyeyesec333/photo-depth/tree/main/skills/photo-depth

Installed? Explore more Imagem skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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 para fit_plane.py.
  • Recusa baixar pesos a menos que --allow-download seja 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, Pillow exact=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.

Habilidades Relacionadas