Reconstrucción de escena fotográfica
Este método se desarrolló en tres proyectos en noviembre de 2026: una foto callejera con un tranvía (Friburgo), una
plaza con una fuente gótica (la Fischbrunnen, Friburgo) y tres dioramas urbanos, de tiendas y de puerto generados con código. Los ejemplos a continuación provienen de ellos. El arnés genérico (cámara, orquestador, herramientas de renderizado y comparación) se encuentra en harness/ junto a este archivo: copia harness/blender y harness/tools en una nueva carpeta de ejecución.
Los nombres de herramientas escritos a continuación que no están en harness/ (por ejemplo facade_solve.py) son sondas por dominio que cada ejecución escribe por sí misma; su propósito se describe donde se nombran.
Requisitos: Blender (escrito para la versión 5.1, Cycles), Python con numpy, opencv y pillow para las herramientas 2D
(tools/py.sh las ejecuta con uv), y un entorno de ejecución de agente que pueda iniciar subagentes.
El usuario juzga la fidelidad visualmente, lado a lado con la foto. Todo lo que sigue existe para hacer esa comparación barata, frecuente y honesta.
0. El líder configura antes de que cualquier agente comience
El líder (la sesión principal) hace esto solo. Los agentes comienzan solo cuando todo está listo.
-
Carpeta de ejecución.
<runs>/<escena>/conref/photo.jpg,blender/,tools/,layout/,gen/,renders/,work/,final/. Copialib.py,arch.py,assets.py,render.py,build_scene.pyy las herramientas genéricas (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) desdeharness/. -
Resolver la cámara con
tools/vp.py. Encuentra el punto de fuga vertical y un punto de fuga horizontal a lo largo de la fachada principal.tools/solve_cam.pyobtiene entonces:- la distancia focal, a partir de que las dos direcciones están en ángulo recto (no asumas una lente);
- el cabeceo, a partir del punto de fuga vertical;
- el guiñada, elegido para que la fachada corra a lo largo del eje X del mundo.
Escribe el resultado en
layout/camera.json. La cámara se congela entonces para toda la ejecución. -
Medir anclajes con
tools/cam.py:on_zgolpea un plano horizontal,on_yun plano vertical,projectda un píxel, yrayda un rayo de vista.- Mide las líneas del suelo, los planos de la fachada y la distancia de cada punto de referencia.
- Escribe las primeras estimaciones del líder en el libro de reglas como valores iniciales.
- En ángulos rasantes, un píxel de una línea del suelo puede ser medio metro de profundidad. Prefiere las alturas y anchos de cosas conocidas (puerta 2.1 m, ojo 1.6 m, bordillo 0.12 m) sobre puntos de suelo individuales.
-
Inventario de objetos. Enumera cada objeto visible en la foto y márcalo como scripted o malla (sección 3). Esta lista decide la división de dominios y las obtenciones de activos.
-
Escribir
AGENTS.mdpara la ejecución: objetivo, marco mundial, anclajes, tabla de dominios, reglas estrictas, el bucle, el orden de trabajo, la regla de finalización.
1. Uso de dominio (cómo los agentes comparten una escena)
Dividir la escena
- Un dominio = un módulo con
build(L, ctx)+ un archivolayout/<dominio>.json+ un prefijo de archivo para cualquier cosa nueva (tools/<dominio>_*.py,tex/<dominio>_*,gen/<dominio>_*). - Dividir por área de pantalla y tipo de trabajo, no por recuento de objetos. Una buena división le da a cada agente una región que puede recortar y juzgar solo. Friburgo usó cinco: luz, calle, edificios izquierdos, fachada principal, accesorios.
- La luz es siempre su propio dominio y posee cielo, exposición, gestión de color y la gradación. Ningún otro agente toca la exposición para hacer que su propio material se vea bien.
- El elemento principal (aquello en lo que el ojo se posa) obtiene un dominio para sí mismo.
- De cuatro a seis dominios. Menos y los agentes chocan dentro de un archivo; más y el líder no puede revisarlos.
Contratos
build_scene.pysolo orquesta: fusionalayout/*.jsonenL, crea la cámara, llama a cada módulo en un orden fijo, guarda. No hay geometría allí.- Cada agente puede LEER cualquier clave de diseño y solo puede ESCRIBIR en su propio archivo de diseño y módulo.
- Los ayudantes compartidos (
lib.py,arch.py,assets.py,cam.py,iterate.sh) están congelados. Un agente que necesita un ayudante modificado lo copia en su propio módulo bajo un nuevo nombre.assets.pycontiene los pasos de ajuste de malla para que cada dominio ajuste mallas de la misma manera:import_gltfimporta y establece la rotación XYZ;world_boundscalcula los límites a partir de vértices;fitescala a una altura o ancho medido, gira en guiñada y baja el vértice más bajo sobre su soporte.
- El dominio que mide un anclaje lo posee. Los anclajes del líder son valores iniciales. El dominio propietario
los refina y publica el resultado en su archivo de diseño, por ejemplo
L['facade']['plane_y']oL['fountain']['centre']. Cada otro dominio lee el valor deLy nunca copia el número en su propio código, por lo que un refinamiento llega a todos en la próxima compilación. - Almacena las mediciones en píxeles de la foto junto a los valores mundiales derivados (por ejemplo
facade.pxjunto afacade.sec). Un script de resolución (tools/facade_solve.py) convierte píxeles en números mundiales y los escribe en el diseño. Volver a medir entonces significa editar un píxel y volver a ejecutar el solucionador, no editar coordenadas a mano. - Los nombres que otros módulos importan se enumeran en el libro de reglas con la regla "añade nuevas funciones, nunca cambies
estas". Los valores entre dominios viajan a través de
ctx(por ejemploctx['track_x']), no a través de ediciones. build(L, ctx)debe funcionar en todo momento. Cada agente reconstruye toda la escena, por lo que un módulo roto bloquea a todos. Verifica la sintaxis antes de guardar una edición arriesgada.
Ejecutar los agentes
- Cada agente construye en su propio
work/<dominio>.blend; los renderizados se serializan mediantework/.gpu_lock(un bloqueo de más de 6 minutos está obsoleto).only=omite otros dominios para mayor velocidad; usa la escena completa al juzgar el color, porque los vecinos rebotan luz. - A lo sumo dos o tres agentes que renderizan a la vez. Varios procesos de Blender llevaron el archivo de paginación de Windows
a más de 50 GB y llenaron C:. Elimina el
work/<dominio>.blendde un agente tan pronto como termine. Espera a un ID de proceso específico, nunca a "no Blender ejecutándose". - Ejecutar en oleadas. La oleada 1 son los dominios que hacen geometría (por ejemplo, suelo, fachada y el elemento principal), a lo sumo tres a la vez. La oleada 2 es la luz y el dominio orgánico o de mobiliario, que necesitan la geometría para iluminar, sombrear y crecer sobre ella. La luz juzgada sobre geometría inacabada es trabajo desperdiciado.
- Mantener la máquina despierta (
request_keep_awake) antes de cualquier oleada. Cuando la PC se durmió por inactividad, los renderizados se congelaron durante nueve horas. - Rondas. Después de cada oleada o ronda, el líder construye
main, revisa el renderizado contra la foto visualmente y escribe las peores diferencias como las instrucciones de la siguiente ronda. Las notas del usuario en una hoja de comparación enviada, por ejemplo "textura más rugosa" o "la iluminación parece artificial", se convierten en una ronda propia. - Cada agente mantiene sus últimos tres conjuntos de vistas previas en
renders/y elimina los más antiguos de su propio prefijo. - Los agentes nunca gastan créditos pagados. Reportan lo que arreglaría un activo generado, con el recorte de la foto a utilizar; el líder lleva eso al usuario con el costo.
- Los agentes no hacen commit, no tocan git y no escriben fuera de la carpeta de ejecución.
Instrucción del agente (lo que envía el líder)
Mantenlo breve; el libro de reglas lleva el resto.
- "Lee
AGENTS.mdprimero." Luego: tu dominio, tu módulo y archivo de diseño, tu región de la foto en píxeles. - Qué ya está ahí y qué está mal (nombra las tres peores diferencias con la foto).
- La lista de mallas para ese dominio del inventario, ya obtenidas en
gen/. - La regla de finalización y el formato del informe (a continuación).
Finalización e integración
- Un agente se detiene cuando su área se mantiene en un recorte de 960 píxeles junto a la foto, o después de unas 12 iteraciones.
- Informe final, menos de 250 palabras: qué cambió, qué aún difiere de la foto, dónde ayudaría un activo generado, la etiqueta del último renderizado.
- El líder entonces construye
work/main.blenda partir de todos los módulos, renderiza el fotograma completo y lo revisa contra la foto sin leer primero los informes de los agentes. Los informes describen intenciones; la imagen es la evidencia. Las diferencias se convierten en las instrucciones de la siguiente ronda. - Los estados de ánimo y efectos de iluminación se aplican después como una superposición no destructiva en
main.blendpara que un cambio de aspecto nunca perturbe la fidelidad aprobada. La ejecución del tranvía usóblender/mood.pysobremain.blend. Fischbrunnen fusiona en profundidadmood/<variante>.json(escrito portools/mood_make.py) sobre los diseños cuandoFB_MOODestá configurado; toma una lista separada por comas, por ejemplowarm_a,film. Usa la forma Fischbrunnen: el estado de ánimo se reconstruye a través de los mismos módulos y no necesita un segundo archivo de escena.
2. Orden de fidelidad y el bucle
El bucle, en cada cambio
tools/iterate.sh <dominio> <n> [width=480] [spp=24] [only=a,b] [x0 y0 x1 y1]
Construye, renderiza y escribe ovl_* (foto | renderizado | mezcla al 50%) y edg_* (bordes de la foto en rojo sobre el
renderizado con una cuadrícula de píxeles). Con un recuadro en píxeles de la foto, renderiza solo esa región y escribe crop_*
(recorte de foto | recorte de renderizado, ampliado); a un ancho de 960, toma unos 25 segundos. Abre las imágenes y míralas.
Nunca reportes un cambio como una mejora sin haber visto la comparación.
Trabaja en este orden; no te adelantes
Cada etapa tiene una compuerta. El detalle añadido antes de que una compuerta anterior pase es desperdiciado, porque se mueve cuando el error anterior se corrige.
| etapa | qué hacer | compuerta antes de seguir |
|---|---|---|
| 1. Leer | Amplía el recorte de la foto de tu área. Escribe lo que realmente hay allí: recuentos, materiales, qué toca qué. | Existe una lista escrita; cada elemento está en el inventario. |
| 2. Silueta | Coloca masas a partir de las mediciones de cam.py. | Los contornos se encuentran en los bordes rojos en edg_* dentro de unos pocos píxeles a 960 de ancho. |
| 3. Proporción | Aberturas, líneas de suelo, bahías, conteos de repetición. | Los bordes de ventanas y puertas se alinean con los bordes de la foto; los conteos coinciden. |
| 4. Color | Colores base de materiales medidos contra la foto, escena completa construida, exposición del dominio de luz intacta. Compara versiones de material como albedo (sección 4.2). | tools/stats.py y las comprobaciones de región del dominio están cerca de la foto, y la mezcla al 50% no muestra parches teñidos. |
| 5. Piezas pequeñas | Molduras, fijaciones, cables, letreros, canalones, lámparas, desorden callejero. Mallas según la sección 3. | Cada elemento del inventario para el área existe en el recorte. |
| 6. Variación y desgaste | Chaflanes, variación de color, manchas debajo de los alféizares, rayas, desgaste del suelo, ondulaciones y reflejos de vidrio. | El recorte pasa la comprobación de aspecto CG a continuación, y la comprobación de energía de textura (sección 4.3) está cerca de la foto. |
Reglas que se aplican en cada etapa:
- Dimensiones del mundo real, en milímetros para patrones. Mide con
cam.py; no adivines. - Nada flota ni se interpenetra. Las cosas están en el suelo o fijadas a una pared.
- Un cambio por iteración cuando se persigue una diferencia, para que la comparación muestre lo que hizo el cambio.
Comprobación de aspecto CG (después de cada renderizado: "¿qué sigue diciéndome que esto es CG?")
| indicio | arreglo habitual |
|---|---|
| Bordes perfectamente afilados | Chaflán o bisel, de 2 a 10 mm en piezas construidas |
| Superficie plana de un solo color | Variación de color medida, manchas, rayas, textura a escala real |
| Repetición visible | Variación por instancia en tono, rotación, desgaste |
| Sombra de contacto faltante | Verifica que el objeto toque el suelo; verifica la luz y la eliminación de ruido |
| Vidrio sin nada detrás o reflejado | Plano interior o tinte, reflejo real, ligera ondulación |
| Escala de textura incorrecta | Vuelve a medir el patrón en milímetros a partir de la foto |
| Objeto con forma primitiva | Reemplazar con una malla real (sección 3) |
| Suelo demasiado limpio | Desgaste, parches húmedos, hojas, juntas |
Después de que el usuario aprueba la fidelidad
Solo entonces, haz esto, en orden:
- Pase de realismo: chaflanes, vidrio y desgaste del suelo. La ejecución del tranvía hizo esto como un módulo
(un módulo
weather); Fischbrunnen lo hizo dentro de cada dominio. Ambos funcionan, pero un dominio debe poseer cada superficie. - Calidad de renderizado: supermuestreo de 2160 px y eliminación de ruido precisa.
- Acabado de sensor (sección 4.1).
- Vistas de prueba desde otros ángulos (un
proof.pyque renderiza cámaras adicionales). - Estados de ánimo de iluminación.
- Película (sección 5).
Envía una hoja de foto versus renderizado en cada uno de estos puntos de control y espera al usuario.
3. Mallas: sin primitivas para objetos complejos
Regla: los objetos complejos nunca se construyen a partir de geometría primitiva simple. Usa una malla real existente en su lugar.
Qué cuenta
- La geometría con script está permitida para arquitectura e infraestructura: muros, losas, techos, marcos de ventanas y puertas, cornisas y molduras perfiladas, bordillos, pavimentos, rieles, postes, cables, letreros planos.
- Se requiere una malla real para todo lo orgánico o similar a un objeto: árboles, arbustos, plantas en maceta, personas, vehículos, bicicletas, sillas, mesas, bancos, jardineras, sombrillas, lámparas con cuerpos con forma, adornos esculpidos, estatuas, tela con pliegues.
- Prueba: si una persona describiría tu construcción como "una esfera en un palo", "una caja con cuatro patas" o "un cilindro", es un sustituto primitivo y no está permitido, ni siquiera como marcador de posición en un renderizado enviado al usuario.
Jerarquía de obtención (detente en el primero que encaje)
- Tu propia biblioteca de mallas. Mantén un índice (categoría, tamaño, recuento de triángulos, ruta, licencia) de cada malla de accesorio que proyectos anteriores produjeron o descargaron, y búscala primero. Reutilizar es mejor que comprar.
- Poly Haven CC0, gratuito:
tools/fetch_ph_model.py <id>(glTF 2k engen/ph/<id>/), texturas y cielos contools/fetch_polyhaven.py <id>. Mantén las descargas por debajo de unos 150 MB por agente. - Malla generada, de pago, solo a través del líder y solo después de que el usuario haya visto el costo: Meshy para
accesorios blandos u orgánicos y adornos, Tripo H3.1 detallado para elementos principales de superficie dura. Prepara y ajusta la
malla en tres pasos:
- Limpiar el recorte. Recorta el objeto de la foto (
gen/meshy_refs/<nombre>_crop.jpg). Realiza un pase de edición de imagen barato para eliminar oclusores, terminar partes cortadas y dar un fondo simple, guardando<nombre>_clean.png. Solo entonces llama a imagen a 3D. En la ejecución de la fuente, esto hizo que las cuatro estatuas y el dosel fueran utilizables en el primer intento. - Diezmar una vez, fuera de línea, en
gen/<dominio>_meshes.blendcon un
- Limpiar el recorte. Recorta el objeto de la foto (
...
[truncado para traducción]