Profundidad de foto: una imagen que se comporta como un lugar
0. preparación entorno Python con MoGe-2 (una vez; pregunta antes de descargar) scripts/setup.sh
1. profundidad imagen → mapa de cercanía (+ distancia 16 bits, cámara, npz crudo) scripts/depth.py
2a. ventana la imagen como una ventana en three.js examples/portal.js
2b. colocar planos y puntos en el 3D propio de la imagen scripts/fit_plane.py
3. verificar mírala desde los ángulos extremos que realmente usarás
scripts/ y examples/ se refieren a las carpetas dentro del propio directorio de esta habilidad (${CLAUDE_SKILL_DIR}, tanto para un plugin como para una habilidad copiada), no al proyecto del usuario. Establece S como esa carpeta scripts/ y ejecuta "$S/depth.py" y las demás con la ruta completa.
0. Preparación (una vez)
Verifica primero: un entorno existente con import moge funcionando se puede reutilizar (pregunta al usuario dónde guarda uno). De lo contrario pregunta al usuario antes de descargar, indicando qué se descarga: PyTorch y ayudantes desde PyPI (aproximadamente 1 GB instalado), el código fuente de MoGe y dos pequeñas bibliotecas desde GitHub (commits fijos, unos pocos MB), y luego los pesos del modelo (aproximadamente 1.3 GB, Ruicheng/moge-2-vitl en Hugging Face). Luego:
"$S/setup.sh" <carpeta-para-el-entorno> --yes
Detalles, notas sobre GPU y otros modelos: references/setup.md.
1. Profundidad
<env>/.venv/bin/python "$S/depth.py" picture.jpg --out public/depth/ [--dist16] [--npz]
- Siempre escribe
<stem>-near.webp: cercanía (disparidad), 0 el cielo, 1 el objeto más cercano, bordes cercanos expandidos 2 píxeles para que el borde de un objeto se mueva con él. 10-25 KB para una imagen de 1-2K. --dist16:<stem>-dist16.webp(distancia logarítmica en 16 bits, R alto G bajo, sin pérdida) y<stem>-camera.json(la cámara intrínseca estimada). Para reconstruir la imagen como una superficie.--npz: profundidad métrica cruda parafit_plane.py.- Se niega a descargar pesos a menos que se pase
--allow-download: pregunta al usuario primero. - Imprime la fracción válida, los percentiles de profundidad y el campo de visión estimado. Léelos: "válido 20%" o un campo de visión de 150° significa que el modelo no entendió la imagen.
Vuelve a ejecutarlo cada vez que la imagen cambie: un mapa de profundidad de una versión anterior de la imagen desplaza cada borde.
2a. La ventana
examples/portal.js es un material three.js autocontenido (cópialo en el proyecto). La imagen es la escena vista desde un punto de reposo (tu posición de cámara predeterminada). Desde cualquier otro lugar, cada píxel del vidrio muestra lo que hay a lo largo de la línea de visión a través de él, encontrado recorriendo el mapa de cercanía en 16 pasos, de modo que los objetos cercanos cubren a los lejanos y los bordes no se rompen. Detalles, ajustes y modos de fallo: 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);
// cada fotograma: portal.update(camera);
examples/portal.html es una demostración de un solo archivo: sirve una carpeta con la imagen, su mapa de cercanía, portal.js y la página, abre portal.html?pic=<archivo>&near=<archivo>, y mueve el puntero.
Verifícalo de la forma en que se verá: mantén la cámara en las posiciones más a la izquierda, derecha, arriba y abajo que el sitio realmente usa (para una verificación automatizada, la demostración acepta window.__view = [x, y]) y mira cada una:
- ¿No se ve ninguna profundidad? La primera versión de este efecto en un sitio real era demasiado sutil: baja
uQ.y(0.6 → 0.4). - ¿Los objetos cercanos se mueven más contra el marco, o el cielo se desplaza? La profundidad está invertida (se usó distancia como cercanía).
- ¿Manchas u objetos duplicados en movimientos grandes? Una imagen única no tiene nada detrás de sus objetos cercanos. Mantén los movimientos de la cámara pequeños, o suavízalos (
uEase), o pinta una capa posterior (references/placing.md).
2b. Colocar objetos en la imagen
<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
Los píxeles son los de la propia imagen (--norm para 0..1). La salida es JSON en el espacio de cámara de three.js (cámara en el origen mirando hacia -Z, metros). flatness_rms_m indica qué tan plana es realmente la región: unos pocos centímetros en una pared a 40 m de distancia es plano. Elige las esquinas dentro de los bordes propios del panel (no una caja alrededor) y el cartel sigue la forma real del panel en lugar de verse torcido. Reconstruir toda la imagen como una superficie 3D, bordes rotos, capas posteriores: references/placing.md.
Reglas
- Licencias: El código y los pesos de MoGe-2 son MIT. Varios modelos de profundidad populares no están autorizados para uso comercial (consulta references/setup.md): verifica antes de cambiar de modelo para un cliente o un portafolio que vende trabajo.
- La licencia de la imagen aún se aplica a todo lo que se derive de ella.
- Máscaras en alfa: si una imagen lleva una máscara en su canal alfa (agua, cielo), guarda el WebP sin pérdida con RGB exacto (
cwebp -lossless -exact, Pillowexact=True). La pérdida con alfa pone a cero el color bajo los píxeles transparentes y lo difumina. - Pregunta antes de descargar nada (paquetes, pesos), indicando qué, de dónde y cuánto pesa.