Photo depth : une image qui se comporte comme un lieu
0. setup un environnement Python avec MoGe-2 (une fois ; demande avant téléchargement) scripts/setup.sh
1. depth image → carte de proximité (+ distance 16 bits, caméra, npz brut) scripts/depth.py
2a. window l'image comme une fenêtre dans three.js examples/portal.js
2b. place plans et points dans le propre 3D de l'image scripts/fit_plane.py
3. check regardez-la depuis les vues extrêmes que vous utiliserez vraiment
Les dossiers scripts/ et examples/ désignent les dossiers dans le répertoire propre de ce skill (${CLAUDE_SKILL_DIR}, pour un plugin ou un skill copié), pas le projet de l'utilisateur. Définissez S sur ce dossier scripts/ et exécutez "$S/depth.py" et les autres en utilisant le chemin complet.
0. Configuration (une fois)
Vérifiez d'abord : un environnement existant avec import moge fonctionnant peut être réutilisé (demandez à l'utilisateur où il en conserve un). Sinon, demandez à l'utilisateur avant de télécharger, en nommant ce qui est téléchargé : PyTorch et ses dépendances depuis PyPI (environ 1 Go installé), le code source de MoGe et deux petites bibliothèques depuis GitHub (commits épinglés, quelques Mo), puis les poids du modèle (environ 1,3 Go, Ruicheng/moge-2-vitl sur Hugging Face). Ensuite :
"$S/setup.sh" <dossier-pour-l-environnement> --yes
Détails, notes GPU et autres modèles : references/setup.md.
1. Profondeur
<env>/.venv/bin/python "$S/depth.py" image.jpg --out public/depth/ [--dist16] [--npz]
- Écrit toujours
<stem>-near.webp: proximité (disparité), 0 pour le ciel, 1 pour l'objet le plus proche, les bords proches sont étendus de 2 px pour qu'un bord d'objet bouge avec lui. 10-25 Ko pour une image de 1-2K. --dist16:<stem>-dist16.webp(distance logarithmique en 16 bits, R haut G bas, sans perte) et<stem>-camera.json(les intrinsèques estimées). Pour reconstruire l'image comme une surface.--npz: profondeur métrique brute pourfit_plane.py.- Il refuse de télécharger les poids sauf si
--allow-downloadest passé : demandez d'abord à l'utilisateur. - Il affiche la fraction valide, les percentiles de profondeur et le champ de vision estimé. Lisez-les : "20% valide" ou un champ de vision de 150° signifie que le modèle n'a pas compris l'image.
Relancez-le à chaque changement d'image : une carte de profondeur d'une version plus ancienne de l'image déplace chaque bord.
2a. La fenêtre
examples/portal.js est un matériau three.js autonome (copiez-le dans le projet). L'image est la scène vue depuis un point de repos (votre position de caméra par défaut). De n'importe où ailleurs, chaque pixel de la vitre montre ce qui se trouve le long de la ligne de vue à travers elle, trouvé en parcourant la carte de proximité en 16 étapes, de sorte que les objets proches recouvrent les objets lointains et que les bords ne se déchirent pas. Détails, réglages et modes d'échec : 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);
// chaque frame : portal.update(camera);
examples/portal.html est une démo en un seul fichier : servez un dossier avec l'image, sa carte de proximité, portal.js et la page, ouvrez portal.html?pic=<fichier>&near=<fichier>, et déplacez le pointeur.
Vérifiez-la comme elle sera vue : placez la caméra aux positions les plus à gauche, à droite, en haut et en bas que le site utilise réellement (pour une vérification automatisée, la démo honore window.__view = [x, y]) et regardez chacun :
- Pas de profondeur visible ? La première version de cet effet sur un vrai site était trop faible pour être remarquée : abaissez
uQ.y(0.6 → 0.4). - Les objets proches bougent le plus par rapport au cadre, ou le ciel nage ? La profondeur est inversée (distance utilisée comme proximité).
- Des traces ou des objets doubles pour de grands mouvements : une seule image n'a rien derrière ses objets proches. Gardez les mouvements de caméra petits, ou atténuez-les (
uEase), ou peignez une couche de fond (references/placing.md).
2b. Placer des objets dans l'image
<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
Les pixels sont ceux de l'image (--norm pour 0..1). La sortie est au format JSON dans l'espace caméra de three.js (caméra à l'origine regardant vers -Z, en mètres). flatness_rms_m indique à quel point la région est vraiment plate : quelques centimètres sur un mur à 40 m est plat. Choisissez des coins à l'intérieur des bords d'un panneau (pas une boîte autour de lui) et le panneau publicitaire suit la forme réelle du panneau au lieu d'être déséquilibré. Reconstruire toute l'image comme une surface 3D, bords déchirés, couches de fond : references/placing.md.
Règles
- Licences : Le code et les poids de MoGe-2 sont sous licence MIT. Plusieurs modèles de profondeur populaires ne sont pas autorisés pour un usage commercial (voir references/setup.md) : vérifiez avant de changer de modèle pour un client ou un portfolio qui vend des œuvres.
- La licence propre de l'image s'applique toujours à tout ce qui en est dérivé.
- Masques dans l'alpha : si une image porte un masque dans son canal alpha (eau, ciel), enregistrez le WebP sans perte avec exact RGB (
cwebp -lossless -exact, Pillowexact=True). L'alpha avec perte met à zéro la couleur sous les pixels transparents et la bave. - Demandez avant de télécharger quoi que ce soit (paquets, poids), en nommant quoi, d'où et combien.