blender-automation

Files (1)

• SKILL.md

SKILL.md (first lines)

# Blender Headless Automation & Asset Pipeline (`bpy`)

Guía técnica especializada para operar Blender 5.x / 4.x en modo headless (`blender -b -P script.py`) dentro del ecosistema JarBees, transformando modelos 3D existentes (`.glb`) mediante Python determinista sin depender de generación de geometría descontrolada con IA.

---

## 1. Reglas de Ejecución Headless

### 1.1 Invocación por Línea de Comandos
Blender headless se invoca siempre con `-b` (background) y `-P` (ejecutar script Python):
```powershell
& "C:\Program Files\Blender Foundation\Blender 5.2\blender.exe" -b --python-exit-code 1 -P script.py -- --input "model.glb" --output "model_weathered.glb"
```
* **`--python-exit-code 1`**: Garantiza que si el script de Python lanza una excepción, el proceso Blender termine con código de error `1`, permitiendo al backend capturar fallos.
* **Separador `--`**: Todos los argumentos posteriores al `--` son accesibles en Python mediante `sys.argv[sys.argv.index('--') + 1:]`.

### 1.2 Limpieza de Escena Inicial Obligatoria
Al iniciar en modo headless, Blender puede cargar la escena de fábrica (cubo, cámara, luz). Siempre resetear la escena antes de importar:
```python
import bpy

# Limpiar objetos existentes de forma segura
bpy.ops.wm.read_factory_settings(use_empty=True)
```

---

## 2. Inspección de Modelos GLB / glTF

Antes de aplicar cualquier modificación, se debe inspeccionar el modelo para conocer sus dimensiones, topología y slots de materiales:

```python
import bpy
from mathutils import Vector

def inspect_scene(glb_path: str) -> dict:
    bpy.ops.wm.read_factory_settings(use_empty=True)
    bpy.ops.import_scene.gltf(filepath=glb_path)
    
    mesh_objects = [obj for obj in bpy.data.objects if obj.type == 'MESH']
    total_vertices = sum(len(obj.data.vertices) for obj in mesh_objects)
    total_triangles = sum(len(obj.data.polygons) for obj in mesh_objects)
    
    # Bounding Box unificado
    min_coord = Vector((float('inf'), float('inf'), float('inf')))
    max_coord = Vector((float('-inf'), float('-inf'), float('-inf')))
    
    for obj in mesh_objects:
        for corner in obj.bound_box:
            world_corner = obj.matrix_world @ Vector(corner)
            min_coord.x = min(min_coord.x, world_corner.x)
            min_coord.y = min(min_coord.y, world_corner.y)
            min_coord.z = min(min_coord.z, world_corner.z)
            max_coord.x = max(max_coord.x, world_corner.x)
            max_coord.y = max(max_coord.y, world_corner.y)
            max_coord.z = max(max_coord.z, world_corner.z)
            
    dimensions = max_coord - min_coord
    center = (max_coord + min_coord) / 2.0
    
    return {
        "meshes": [obj.name for obj in mesh_objects],
        "materials": [mat.name for mat in bpy.data.materials if mat],
        "total_vertices": total_vertices,
        "total_triangles": total_triangles,
        "bounding_box": {
            "width": dimensions.x,
            "depth": dimensions.y,
            "height": dimensions.z,
            "center": [center.x, center.y, center.z]
        }
    }
```

---

## 3. Manipulación de Materiales PBR (Shader Nodes en Principled BSDF)

### 3.1 Pátina de Desgaste y Musgo Procedural
Para aplicar musgo o suciedad sin destruir la textura original:
1. Localizar el nodo `BSDF_PRINCIPLED`.
2. Conservar el mapa base (`TEX_IMAGE`) conectado a `Base Color`.
3. Intercalar un nodo `ShaderNodeMixRGB` (o `ShaderNodeMix` en Blender 4/5):
   * **Color A**: La textura original.
   * **Color B**: Color de musgo / pátina (ej. `#3a5323` verde musgo, `#2e251a` tierra).
   * **Fac**: Una combinación de:
     - Vector Normal hacia arriba (+Z) para musgo que crece en superficies horizontales superiores.
     - Gradiente de Altura Z (para concentrar suciedad y humedad en la base).
     - Ruido procedural (`ShaderNodeTexNoise`) para bordes orgánicos e irregulares.

```python
def add_procedural_moss(mat, moss_color=(0.22, 0.35, 0.12, 1.0), coverage=0.4):
    if not mat.use_nodes:
        mat.use_nodes = True
    tree = mat.node_tree
    nodes = tree.nodes
    links = tree.links
    
    principled = next((n for n in nodes if n.type == 'BSDF_PRINCIPLED'), None)
    if not principled:
        return
        
    # Obtener lo que esté conectado a Base Color
    original_input = None
    if principled.inputs['Base Color'].is_linked:
        original_input = principled.inputs['Base Color'].links[0].from_socket
        
    # Crear nodo Mix (Color)
    mix_node = nodes.new(type='ShaderNodeMix')
    mix_node.data_type = 'RGBA'
    mix_node.blend_type = 'MIX'
    
    # Crear nodo de Textura de Ruido para borde orgánico
    noise_node = nodes.new(type='ShaderNodeTexNoise')
    noise_node.inputs['Scale'].default_value = 15.0
    noise_node.inputs['Detail'].default_value = 4.0
    
    # Crear ColorRamp para contrastar la máscara
    ramp_node = nodes.new(type='ShaderNodeValToRGB')

From ifernandez89/productos_crud_bkd, MIT.

More from ifernandez89/productos_crud_bkd