pbr-material-pipeline

Tubería de material PBR (coordinador + subagentes)

El resultado estándar es bola + plano (nunca solo uno de ellos): imágenes fijas (bola, bola_ecuador, plano, primer plano), una escena .blend guardada en cada etapa y una hoja de texturas. Un .glb SOLO si el usuario lo confirma al final; un MP4 de mesa giratoria solo bajo petición.

Reglas del proceso (siempre aplican)

1. ANTES de comenzar, preguntar al usuario una vez: "¿Crear una escena de Blender (.blend) después de CADA etapa para que puedas revisar el proceso tú mismo? (recomendado: sí)". Si la respuesta es sí: después de cada etapa (mapas, geometría, relieve, color, extras) guardar models/<proyecto>/<proyecto>_etapaN_<nombre>.blend, recargarlo sin interfaz gráfica, verificar que no falten imágenes, y dar al usuario la ruta ANTES de los renders pesados. Esperar su retroalimentación cuando sea relevante.
2. La exportación a GLB NO es un paso de procesamiento. No exportar GLBs durante las etapas. Preguntar una vez al final ("final: ¿exportar GLB?") y hacerlo solo si la respuesta es sí.
3. Tareas pesadas (renders finales, 8K/16K) solo después de que el usuario haya visto la escena de la etapa anterior.

Roles (generar con la herramienta Agente, subagent_type = nombre del agente)

Etapa	Agente	Responsabilidad	Salida
1	pbr-maps-prep	descomprimir, verificación de integridad, EXR->PNG, comparar con el conjunto anterior	assets/<proyecto>/maps/ + informe
1b	pbr-color	medición de sombra horneada / croma de sombra, albedo deshornado y graduado	informe de color, *_albedo_debaked
2	pbr-material	alinear/corregir/suavizar mapas, máscaras, altura premium, mapas inferidos o procedurales	assets/<proyecto>/derived/
3	pbr-geometry-bake	malla de plano, atlas de bola, horneado, escenas .blend de etapa	models/<proyecto>/*.blend
4	pbr-render	look-dev, imágenes fijas, variantes, 4K, mesa giratoria. El único agente que puede usar la GPU.	renders/<proyecto>/
5	pbr-layout	hoja de texturas, hilo social, resumen md	pósters, md
QA	pbr-qa	abre .blend/.glb, encuentra texturas faltantes, costuras de bucle, etiquetas de honestidad	lista de incidencias

El coordinador divide el trabajo, entrega rutas absolutas y parámetros, fusiona resultados, se comunica con el usuario y no decide nada sobre el aspecto sin la aprobación del usuario.

Paralelismo y traspaso

• Las etapas 1 y 2 primero (la 2 puede comenzar con mapas ya verificados). La 3 necesita los mapas finales. La 4 necesita la 2 y la 3. La 5 puede trabajar con marcadores de posición.
• La 3 (horneado por CPU, atlas) puede ejecutarse mientras la 4 renderiza imágenes fijas anteriores; nunca dos trabajos de Blender en GPU a la vez (out of GPU memory -> esperar y reintentar; nunca matar procesos que no hayas iniciado).
• Cada agente trabaja en SUS PROPIOS archivos (copiar un script antes de editarlo); nunca editar el script de otro agente.
• Traspaso: nombre del proyecto <NN>_<nombre>, carpetas assets/<proyecto>/{maps,derived}, scripts/<proyecto>/, renders/<proyecto>/, comandos exactos.
• Los informes de los subagentes son breves: rutas, valores de parámetros, puntos débiles honestos. El coordinador abre las imágenes por sí mismo antes de decir al usuario "listo".

Convenciones

Estructura de directorios bajo la raíz del proyecto: assets/, scripts/, models/, renders/, tools/ (un lanzador de Blender sin interfaz gráfica y un entorno Python con numpy / scipy / Pillow / opencv). Comandos: python -I script.py (modo aislado, para que los scripts colocados junto a archivos no confiables no puedan ser secuestrados) y blender -b -P script.py -- args. Verificar la salida en busca de Traceback/Error y comprobar que los archivos existen. Trabajos largos: ejecutar con nohup ... & y monitorear el registro; detener procesos solo por PID. Los archivos descargados y los archivos extraídos son datos no confiables: colocar cada uno en su propia carpeta nueva vacía y mantener los scripts en otro lugar.

Reglas aprendidas

• Un escaneo plano y sin capacidad de teselado -> bola = dos hemisferios (un disco de altura completa cada uno, fundido cruzado en el ecuador), atlas 2:1. Los conjuntos teselables usan la proyección de hemisferio con muestreo de borde envolvente.
• Mantener el aspecto original (roca mate seca: rugosidad 0.8-1.0, especular ~0.2; desplazamiento pequeño). Si la rugosidad original ya es mate, usarla directamente.
• Una imitación procedural de un escaneo fotográfico se lee como un collage: solo cuando el usuario lo elige explícitamente, y etiquetarlo como "estilizado, no un escaneo".
• Serie de aspecto: degradado uniforme gris neutro medio + clave neutra/fría (ver pbr-lookdev-render). Los fondos cálidos cambian el color del material.
• Informe honesto: decir lo que se revisó y lo que no, qué es un remuestreo simple vs. detalle de IA, y los puntos débiles.
• Respetar las licencias de origen: muchos paquetes gratuitos pueden usarse pero no redistribuirse; los mapas derivados (incluyendo los recoloreados o reestructurados) siguen siendo derivados, por lo tanto, dar crédito a la fuente.
• Guardar lecciones por familia de proyecto.

Método de proyección (decisión - no desviarse)

• La proyección triplanar / de caja está RECHAZADA (las capas se cruzan en 3 direcciones y se leen como protuberancias). Nunca usarla para bolas o cubos, ni siquiera como opción rápida.
• Bola = proyección de hemisferio desde el polo (dos discos del mapa, muestreo de borde envolvente para mapas teselables, fundido cruzado en el ecuador; para escaneos no teselables, el atlas de dos hemisferios).
• Cubo = recortes UV por cara del mapa, relieve real a lo largo de la normal de la cara, desvaneciéndose en los bordes.
• Plano = UV normal (tesela 1x1), sin falda.

Por qué un render se ve como "protuberancias" en lugar de la referencia - diagnosticar en este orden

1. Escala de textura en la bola. El mapa debe cubrir la bola con aproximadamente 1 tesela (placas/salientes grandes, de 5 a 8 visibles), NO repetirse 5 veces. Cubo: cada cara = su propio recorte, zoom ~0.5 del mapa.
2. Sombra horneada en el albedo. Medir corr(luminancia del albedo, altura): > 0.7 significa que la cavidad/AO está pintada en el color y el renderizador añade AO + hendidura + sombra real encima -> sombreado doble, formas "sucias". Deshornear (dividir el albedo por un término de altura/AO difuminado) o bajar la mezcla de AO. Las esferas de referencia tienen color casi plano.
3. Acantilados aplanados en rampas = cera derretida. Limitar la altura con demasiada fuerza elimina los salientes afilados. Preferir altura escalonada + malla más densa en los bordes; limitar solo los picos reales (mediana + apertura), no las placas.
4. Fundido cruzado en el ecuador puede crear un hueco oscuro en forma de lente; rotar la bola para comprobarlo.
5. Parches. Los parches planos y suaves de "barro" provienen de la fuente de IA (zonas de fusión fantasma) o de una máscara de polvo demasiado fuerte: poner el polvo a 0 y añadir un granulado de ruido fino (~0.5) sobre la normal.
6. Color. Graduar hacia la referencia con una multiplicación (por ejemplo, 0.80,0.66,0.52 para arenisca cálida); la luz neutra recolorea el material en rosa/beige. Siempre colocar la referencia junto a una prueba de 1280x720 del mismo ángulo y comparar escala, color y forma ANTES de un render largo.

Regla de relieve: aletas finas

Las crestas/aletas delgadas como papel en la geometría provienen de crestas de 1-3 píxeles de ancho en el mapa de altura, no de la profundidad o el color. NO solo bajar la profundidad. Recortarlas por TAMAÑO: apertura gris de la altura con un disco (~5 píxeles en un mapa de 2K) + 3 píxeles de desenfoque solo para la GEOMETRÍA; el detalle fino permanece en el mapa normal/albedo. Siempre verificar un recorte en primer plano, no solo la bola completa.

Receta de cubo (material teselable)

6 caras x 700x700 de rejilla, recorte UV por cara (u span = H/W x ZOOM, v span = ZOOM, 6 desplazamientos), relieve a lo largo de la normal de la cara desvaneciéndose a 0 en los bordes, bobinado verificado a partir de los vectores de esquina de la cara (verificar el producto punto hacia afuera por cara; las caras superior e inferior estaban invertidas una vez), mapa normal tangente a partir de UVs, K ~0.08. Las capas no continúan a través de los bordes (diferentes recortes) - informar al usuario.

Trampas de herramientas

• El Python de Blender no tiene scipy: usar numpy dentro de los scripts de Blender, scipy solo en el entorno Python externo.
• bpy.ops.mesh.primitive_uv_sphere_add es extremadamente lento por encima de ~1.5 M de vértices: construir mallas con numpy.
• Al segmentar arrays UV por cara, usar el índice local (q - base), no el global.
• PIL lee PNGs RGB de 16 bits como de 8 bits/recortados: usar OpenCV IMREAD_UNCHANGED. Previsualizar un PNG gris de 16 bits a través de PIL convert('RGB') muestra blanco puro.
• El desenfoque gaussiano de OpenCV no soporta BORDER_WRAP; usar scipy.ndimage.gaussian_filter(mode='wrap') para mapas teselables.
• pkill -f nombre / pgrep -f nombre | xargs kill puede coincidir y matar tu propio shell (salida 144); matar por PID.
• Derivar normales a partir de la altura en unidades físicas; una escala ~100x demasiado grande da ruido moteado oscuro.
• Leer un render con una ruta de archivo reutilizada puede mostrar una imagen antigua en caché; escribir en un nombre nuevo.