CommunityImagegithub.com

reconstruction-scène-photo

Reconstruire une photo de référence en scène Blender qui se lit comme une photographie depuis le même appareil photo, en utilisant un harnais multi-agents avec des domaines dédiés, une boucle rendu-et-comparaison, un ordre de fidélité fixe, éclairage et matériaux mesurés depuis la photo (soleil via ombres, ombre hors champ, finition capteur, vérifications d'albédo), une règle de maillage réel (pas de primitives pour les objets complexes) et une liste classée de techniques de génération de code pour bâtiments organiques détaillés (section 7). Utiliser quand l'utilisateur demande des bâtiments générés par code, ou quand il demande de recréer, reconstruire ou faire correspondre une photo ou image de référence en 3D, pour améliorer la fidélité ou le réalisme d'une scène générée, ou pour configurer des agents afin de construire une scène en parallèle.

Qu'est-ce que reconstruction-scène-photo ?

Cette compétence fournit une méthodologie complète pour reconstruire une photo de référence sous forme de scène Blender 3D, avec une fidélité photoréaliste. Elle utilise un harnais multi-agents où chaque agent possède un domaine spécifique (éclairage, rue, bâtiments, éléments principaux, accessoires) et suit un ordre de fidélité fixe en six étapes (lecture, silhouette, proportion, couleur, petites pièces, variation et usure). La méthodologie comprend une boucle de rendu et comparaison rigoureuse qui force l'agent à comparer chaque changement avec la photo originale, une règle de maillage réel interdisant les primitives pour les objets complexes (obligeant l'utilisation de maillages réels issus de bibliothèques ou de générateurs comme Meshy/Tripo), et des outils de mesure précis pour extraire l'éclairage et les matériaux de la photo (soleil via ombres, ombre hors champ, finition capteur, vérifications d'albédo). La compétence est conçue pour fonctionner avec Blender 5.1+, Cycles, Python (numpy, opencv, pillow), et un runtime d'agent capable de lancer des sous-agents. Le code de la compétence détaille les étapes de configuration (résolution de la caméra, mesure des ancres, inventaire des objets, écriture de AGENTS.md), le partage de domaine entre agents (un domaine par module, croisement via ctx, règles strictes de lecture/écriture), et le processus d'intégration (constructions par vagues, rapports de fin, revue par le meneur sans lire d'abord les rapports).

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/liangjunglj-cpu/ginkgo-skills/tree/main/skills/photo-scene-reconstruction

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

Reconstruction de scène photo

Cette méthode a été développée sur trois projets en novembre 2026 : une photo de rue avec un tramway (Fribourg), une place avec une fontaine gothique (le Fischbrunnen, Fribourg) et trois dioramas de ville, boutique et port générés par code. Les exemples ci-dessous en sont tirés. Le harnais générique (appareil photo, orchestrateur, outils de rendu et comparaison) se trouve dans harness/ à côté de ce fichier : copier harness/blender et harness/tools dans un nouveau dossier d'exécution. Les noms d'outils ci-dessous qui ne sont pas dans harness/ (par exemple facade_solve.py) sont des sondes par domaine écrites par chaque exécution ; leur objectif est décrit là où ils sont nommés.

Prérequis : Blender (écrit pour 5.1, Cycles), Python avec numpy, opencv et pillow pour les outils 2D (tools/py.sh les exécute avec uv), et un runtime d'agent qui peut démarrer des sous-agents.

L'utilisateur juge la fidélité à l'œil, côte à côte avec la photo. Tout ce qui suit existe pour rendre cette comparaison bon marché, fréquente et honnête.

0. Le meneur installe avant que tout agent ne démarre

Le meneur (la session principale) fait ces choses seul. Les agents démarrent seulement quand tout est fait.

  1. Dossier d'exécution. <runs>/<scene>/ avec ref/photo.jpg, blender/, tools/, layout/, gen/, renders/, work/, final/. Copier lib.py, arch.py, assets.py, render.py, build_scene.py et les outils génériques (cam.py, vp.py, solve_cam.py, iterate.sh, overlay.py, edges.py, pair.py, crop.py, stats.py, py.sh, fetch_polyhaven.py, fetch_ph_model.py) depuis harness/.

  2. Résoudre la caméra avec tools/vp.py. Trouver le point de fuite vertical et un point de fuite horizontal le long de la façade principale. tools/solve_cam.py obtient ensuite :

    • la distance focale, à partir des deux directions à angle droit (ne pas supposer d'objectif) ;
    • l'inclinaison, à partir du point de fuite vertical ;
    • le lacet, choisi de sorte que la façade s'aligne sur le monde +X.

    Écrire le résultat dans layout/camera.json. La caméra est ensuite figée pour toute l'exécution.

  3. Mesurer les ancres avec tools/cam.py :

    • on_z touche un plan horizontal, on_y un plan vertical, project donne un pixel, et ray donne un rayon de vision.
    • Mesurer les lignes de sol, les plans de façade et la distance de chaque repère.
    • Écrire les premières estimations du meneur dans le livre de règles comme valeurs de départ.
    • À angles rasants, un pixel d'une ligne de sol peut représenter un demi-mètre de profondeur. Préférer les hauteurs et largeurs de choses connues (porte 2,1 m, œil 1,6 m, bordure 0,12 m) à des points de sol uniques.
  4. Inventaire des objets. Lister chaque objet visible sur la photo et le marquer comme scripté ou maillage (section 3). Cette liste décide de la répartition des domaines et des récupérations d'actifs numériques.

  5. Écrire AGENTS.md pour l'exécution : objectif, repère mondial, ancres, table des domaines, règles dures, la boucle, l'ordre de travail, la règle de finition.

1. Propriété des domaines (comment les agents partagent une scène)

Division de la scène

  • Un domaine = un module avec build(L, ctx) + un fichier layout/<domain>.json + un préfixe pour tout nouveau fichier (tools/<domain>_*.py, tex/<domain>_*, gen/<domain>_*).
  • Diviser par zone d'écran et type de travail, pas par nombre d'objets. Une bonne division donne à chaque agent une région qu'il peut recadrer et juger seul. Fribourg en a utilisé cinq : éclairage, rue, bâtiments de gauche, façade principale, accessoires.
  • L'éclairage est toujours son propre domaine et possède ciel, exposition, gestion des couleurs et l'étalonnage. Aucun autre agent ne touche à l'exposition pour rendre son propre matériau correct.
  • L'élément principal (ce sur quoi l'œil se pose) a un domaine pour lui-même.
  • Quatre à six domaines. Moins, et les agents entrent en collision dans un fichier ; plus, et le meneur ne peut pas les revoir.

Contrats

  • build_scene.py orchestre seulement : fusionner layout/*.json dans L, créer la caméra, appeler chaque module dans un ordre fixe, sauvegarder. Aucune géométrie n'y vit.
  • Chaque agent peut LIRE n'importe quelle clé de layout et peut ÉCRIRE seulement son propre fichier de layout et module.
  • Les aides partagés (lib.py, arch.py, assets.py, cam.py, iterate.sh) sont figés. Un agent qui a besoin d'un aide modifié le copie dans son propre module sous un nouveau nom. assets.py contient les étapes d'ajustement de maillage afin que chaque domaine ajuste les maillages de la même manière :
    • import_gltf importe et définit la rotation XYZ ;
    • world_bounds calcule les limites à partir des sommets ;
    • fit met à l'échelle pour une hauteur ou largeur mesurée, pivote, et abaisse le sommet le plus bas sur son support.
  • Le domaine qui mesure une ancre la possède. Les ancres du meneur sont des valeurs de départ. Le domaine propriétaire les affine et publie le résultat dans son fichier de layout, par exemple L['facade']['plane_y'] ou L['fountain']['centre']. Chaque autre domaine lit la valeur depuis L et ne copie jamais le nombre dans son propre code, de sorte qu'un raffinement parvienne à tout le monde à la prochaine construction.
  • Stocker les mesures en pixels photo à côté des valeurs monde dérivées (par exemple facade.px à côté de facade.sec). Un script de résolution (tools/facade_solve.py) transforme les pixels en nombres monde et les écrit dans le layout. Remesurer signifie alors éditer un pixel et relancer le solveur, pas éditer les coordonnées à la main.
  • Les noms que d'autres modules importent sont listés dans le livre de règles avec la règle "ajouter de nouvelles fonctions, ne jamais changer celles-ci". Les valeurs inter-domaines transitent par ctx (par exemple ctx['track_x']), pas par des éditions.
  • build(L, ctx) doit fonctionner à tout moment. Chaque agent reconstruit toute la scène, donc un module cassé bloque tout le monde. Vérifier la syntaxe avant de sauvegarder une édition risquée.

Exécution des agents

  • Chaque agent construit dans son propre work/<domain>.blend ; les rendus sont sérialisés par work/.gpu_lock (un verrou de plus de 6 minutes est périmé). only= ignore les autres domaines pour la rapidité ; utiliser la scène complète quand on juge la couleur, car les voisins réfléchissent la lumière.
  • Au maximum deux ou trois agents qui rendent à la fois. Plusieurs processus Blender ont fait passer le fichier d'échange Windows au-delà de 50 Go et ont rempli C:. Supprimer le work/<domain>.blend d'un agent dès qu'il termine. Attendre un identifiant de processus spécifique, jamais "aucun Blender en cours d'exécution".
  • Exécuter par vagues. Vague 1 concerne les domaines qui créent la géométrie (par exemple sol, façade et élément principal), au maximum trois à la fois. Vague 2 concerne l'éclairage et le domaine organique ou de mobilier, qui ont besoin de la géométrie pour s'éclairer, s'ombrer et croître. Un éclairage évalué sur une géométrie inachevée est un travail gaspillé.
  • Garder la machine éveillée (request_keep_awake) avant toute vague. Lorsque le PC s'est mis en veille, les rendus ont gelé pendant neuf heures.
  • Tours. Après chaque vague ou tour, le meneur construit le fichier main, évalue le rendu par rapport à la photo à l'œil, et écrit les pires différences comme briefs du tour suivant. Les notes de l'utilisateur sur une feuille de comparaison envoyée, par exemple "texture plus rugueuse" ou "éclairage semble artificiel", deviennent un tour en soi.
  • Chaque agent conserve ses trois derniers ensembles de prévisualisation dans renders/ et supprime les plus anciens de son propre préfixe.
  • Les agents ne dépensent jamais de crédits payants. Ils signalent ce qu'un actif numérique généré corrigerait, avec le recadrage photo à utiliser ; le meneur le présente à l'utilisateur avec le coût.
  • Les agents ne valident pas, ne touchent pas à git et n'écrivent pas en dehors du dossier d'exécution.

Brief de l'agent (ce que le meneur envoie)

Garder court ; le livre de règles porte le reste.

  • "Lire AGENTS.md d'abord." Ensuite : votre domaine, votre module et fichier de layout, votre région photo en pixels.
  • Ce qui est déjà là et ce qui ne va pas (nommer les trois pires différences avec la photo).
  • La liste de maillages pour ce domaine depuis l'inventaire, déjà récupérés dans gen/.
  • La règle de finition et le format de rapport (ci-dessous).

Finition et intégration

  • Un agent s'arrête quand sa zone tient dans un recadrage 960 px à côté de la photo, ou après environ 12 itérations.
  • Rapport final, moins de 250 mots : ce qui a changé, ce qui diffère encore de la photo, où un actif numérique généré aiderait, le tag du dernier rendu.
  • Le meneur construit ensuite work/main.blend à partir de tous les modules, effectue le rendu du cadre complet, et l'évalue par rapport à la photo sans lire d'abord les rapports des agents. Les rapports décrivent les intentions ; l'image est la preuve. Les différences deviennent les briefs du tour suivant.
  • Les ambiances et effets d'éclairage sont appliqués ensuite comme une superposition non destructive sur main.blend afin qu'un changement d'aspect ne perturbe jamais la fidélité approuvée. L'exécution du tram a utilisé blender/mood.py sur main.blend. Fischbrunnen fusionne profondément mood/<variant>.json (écrit par tools/mood_make.py) sur les layouts quand FB_MOOD est défini ; il prend une liste séparée par des virgules, par exemple warm_a,film. Utiliser la forme Fischbrunnen : l'ambiance se reconstruit via les mêmes modules et ne nécessite pas de second fichier de scène.

2. Ordre de fidélité et la boucle

La boucle, à chaque changement

tools/iterate.sh <domaine> <n> [largeur=480] [échantillons=24] [seulement=a,b] [x0 y0 x1 y1]

Il construit, effectue le rendu, et écrit ovl_* (photo | rendu | fusion 50%) et edg_* (contours de la photo en rouge sur le rendu avec une grille de pixels). Avec une boîte en pixels photo, il effectue le rendu uniquement de cette région et écrit crop_* (recadrage photo | recadrage rendu, agrandi) ; à une largeur de 960, cela prend environ 25 s. Ouvrir les images et les regarder. Ne jamais signaler un changement comme une amélioration sans avoir vu la comparaison.

Travailler dans cet ordre ; ne pas sauter d'étape

Chaque étape a une porte. Du détail ajouté avant qu'une porte antérieure ne soit passée est gaspillé, car il bouge quand l'erreur antérieure est corrigée.

étapequoi faireporte avant de passer à la suite
1. LectureAgrandir le recadrage photo de votre zone. Écrire ce qui s'y trouve réellement : comptages, matériaux, ce qui touche quoi.Une liste écrite existe ; chaque élément est dans l'inventaire.
2. SilhouettePlacer les masses à partir des mesures de cam.py.Les contours se situent sur les arêtes rouges dans edg_* à quelques pixels près à 960 de large.
3. ProportionOuvertures, lignes de sol, travées, comptages de répétition.Les bords des fenêtres et portes s'alignent avec les bords de la photo ; les comptages correspondent.
4. CouleurCouleurs de base des matériaux mesurées par rapport à la photo, scène complète construite, exposition du domaine d'éclairage inchangée. Comparer les versions de matériaux comme albédo (section 4.2).tools/stats.py et la vérification de région du domaine sont proches de la photo, et la fusion 50% ne montre pas de zones teintées.
5. Petites piècesGarnitures, fixations, câbles, enseignes, gouttières, lampes, encombrement de rue. Maillages selon section 3.Chaque élément d'inventaire pour la zone existe dans le recadrage.
6. Variation et usureChanfreins, variation de couleur, taches sous les rebords, traînées, usure du sol, ondulation et reflets du verre.Le recadrage passe le test de détection CG ci-dessous, et le test d'énergie de texture (section 4.3) est proche de la photo.

Règles qui s'appliquent à chaque étape :

  • Dimensions réelles, en millimètres pour les motifs. Mesurer avec cam.py ; ne pas deviner.
  • Rien ne flotte ni ne s'interpénètre. Les choses se tiennent sur le sol ou sont fixées à un mur.
  • Un changement par itération pour traquer une différence, afin que la comparaison montre ce que le changement a fait.

Test de détection CG (après chaque rendu : "qu'est-ce qui me dit encore que c'est de la CG ?")

indicecorrection habituelle
Bords parfaitement netsChanfrein ou biseau, 2 à 10 mm sur les parties construites
Surface plane unieVariation de couleur mesurée, taches, traînées, texture à l'échelle réelle
Répétition visibleVariation par instance de ton, rotation, usure
Ombre de contact manquanteVérifier que l'objet touche le sol ; vérifier l'éclairage et le débruitage
Verre sans rien derrière ou reflétéPlan intérieur ou teinte, réflexion réelle, légère ondulation
Échelle de texture erronéeRemesurer le motif en millimètres sur la photo
Objet en forme de primitiveRemplacer par un maillage réel (section 3)
Sol trop propreUsure, flaques d'humidité, feuilles, joints

Après que l'utilisateur approuve la fidélité

Alors seulement, faire ceci, dans l'ordre :

  1. Passage réalisme : chanfreins, verre et usure du sol. L'exécution du tram l'a fait comme un module (un module weather) ; Fischbrunnen l'a fait dans chaque domaine. Les deux fonctionnent, mais un domaine doit posséder chaque surface.
  2. Qualité de rendu : suréchantillonnage 2160 px et débruitage précis.
  3. Finition capteur (section 4.1).
  4. Vues de preuve depuis d'autres angles (un proof.py qui rend des caméras supplémentaires).
  5. Ambiances d'éclairage.
  6. Film (section 5).

Envoyer une feuille photo-ver-s-rendu à chacun de ces points de contrôle et attendre l'utilisateur.

3. Maillages : pas de primitives pour les objets complexes

Règle : les objets complexes ne sont jamais construits à partir de simples primitive géométriques. Utiliser un maillage réel existant à la place.

Ce qui compte

  • La géométrie scriptée est autorisée pour l'architecture et l'infrastructure : murs, dalles, toits, cadres de fenêtres et de portes, corniches et garnitures profilées, bordures, pavés, rampes, poteaux, fils, panneaux plats.
  • Un maillage réel est requis pour tout ce qui est organique ou en forme d'objet : arbres, arbustes, plantes en pot, personnes, véhicules, vélos, chaises, tables, bancs, jardinières, parasols, lampes ayant des formes sculptées, ornements sculptés, statues, tissus plissés.
  • Test : si une personne décrirait votre construction comme "une sphère sur un bâton", "une boîte avec quatre pieds" ou "un cylindre", c'est un substitut primitif et ce n'est pas autorisé, même comme espace réservé dans un rendu envoyé à l'utilisateur.

Échelle d'approvisionnement (s'arrêter au premier qui convient)

  1. Votre propre bibliothèque de maillages. Tenir un index (catégorie, taille, nombre de triangles, chemin, licence) de tous les maillages d'accessoires que les projets antérieurs ont produits ou téléchargés, et le chercher en premier. La réutilisation surpasse l'achat.
  2. Poly Haven CC0, gratuit : tools/fetch_ph_model.py <id> (glTF 2k dans gen/ph/<id>/), textures et ciels via tools/fetch_polyhaven.py <id>. Garder les téléchargements sous environ 150 Mo par agent.
  3. Maillage généré, payant, seulement via le meneur et seulement après que l'utilisateur a vu le coût : Meshy pour les accessoires souples ou organiques et les ornements, Tripo H3.1 détaillé pour les éléments principaux en surface dure. Préparer et ajuster le maillage en trois étapes :
    • Nettoyer le recadrage. Rogner l'objet de la photo (gen/meshy_refs/<name>_crop.jpg). Exécuter un passage bon marché d'édition d'image pour enlever les occluseurs, finir les parties coupées et donner un arrière-plan uni, sauvegardant <name>_clean.png. Alors seulement appeler image-vers-3D. Sur l'exécution de la fontaine, cela a rendu toutes les quatre statues et la verrière utilisables du premier coup.
    • Décimer une fois, hors ligne, dans gen/<domain>_meshes.blend avec un...

Skills associés