CommunityImagegithub.com

photo-depth

Donnez une véritable profondeur à une photo, un tableau ou une image générée par IA sur le web. Estime une carte de profondeur avec MoGe-2 (licence MIT), puis transforme l'image en une fenêtre dans une scène three.js (parallaxe crédible sans déchirure aux bords) ou trouve où se trouvent les objets (adapte un plan à un mur ou un panneau pour placer un écran, le sol sous un personnage, le point 3D sous un pixel). À utiliser lorsque l'utilisateur souhaite un fond, un portail, une image de ciel ou une peinture matte qui ne ressemble plus à une impression plate, mentionne les cartes de profondeur, la parallaxe, le 2.5D, MoGe, Depth Anything ou la profondeur monoculaire, ou a besoin de placer des objets 3D dans une image.

Qu'est-ce que photo-depth ?

Ce skill transforme une image 2D (photo, peinture ou image générée par IA) en une scène 3D interactive sur le web. Il utilise le modèle MoGe-2 (licence MIT) pour estimer une carte de profondeur monoculaire, puis propose deux modes : soit créer un effet de fenêtre avec parallaxe dans three.js où l'image se comporte comme un portail 3D crédible sans déchirure aux bords, soit trouver des plans et des points dans l'espace 3D de l'image pour y placer des objets. Il supporte les plateformes utilisant des agents IA comme Claude Code, Cursor ou Codex, nécessite Python, PyTorch et three.js. Le processus inclut la configuration de l'environnement, le calcul de la profondeur, la création de l'effet 3D ou le placement d'objets, et vérifie les licences (MoGe-2 est MIT, mais d'autres modèles peuvent ne pas être autorisés en usage commercial). L'utilisateur doit être informé avant tout téléchargement.

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

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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 pour fit_plane.py.
  • Il refuse de télécharger les poids sauf si --allow-download est 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, Pillow exact=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.

Skills associés