Blender Sculpt

Skill: Blender Sculpting (Procedurale)

Sei un esperto di sculpting 3D in Blender via Python. Deformi mesh con brush personalizzati, KDTree spatial queries e displacement.

---

Connessione — MCP (predefinito)

mcp__Blender__execute_blender_code(code="""
import bpy, bmesh, math
from mathutils import Vector
from mathutils.kdtree import KDTree
# ... codice ...
result = {"ok": True}
""")

mcp__Blender__get_screenshot_of_window_as_image()
mcp__Blender__render_viewport_to_path(output_path="/sculpt.png")

---

Visual Loop

1. execute_blender_code(mesh_base_code)       ← crea primitiva + remesh
2. execute_blender_code(sculpt_code)          ← applica brush
3. get_screenshot_of_window_as_image()        ← analisi rapida viewport
4. execute_blender_code(fix_code)             ← raffina → itera
5. render_viewport_to_path("final.png")       ← render finale

---

IL PRINCIPIO — Sculpting Procedurale vs. Sculpt Mode

Blender ha due approcci:

| | Sculpt Mode (operatori) | Sculpting Procedurale (Python) | |-|------------------------|-------------------------------| | Controllo | Limitato da Claude | Totale — ogni vertice | | Riproducibilità | No | Sì — deterministico | | Falloff | Preset fissi | Personalizzabile | | Spatial query | Manuale | KDTree O(log n) | | Iterabilità | Difficile | Facile |

Usa Sculpt Mode solo per operazioni globali (remesh, smooth, dyntopo setup). Usa Python per tutto il resto — brush, displacement, deformazioni specifiche.

---

SETUP MESH — Prima di Sculpting

La mesh di partenza determina la qualità del risultato. Regola: più poligoni = più dettaglio, ma con costo. Bilanciare sempre.

import bpy, math

def sculpt_base_sphere(name="SculptObj", radius=0.12,
                        segments=64, rings=48):
    """
    Sfera UV — punto di partenza ottimale per oggetti organici.
    segments=64, rings=48 → ~6000 vertici, buon punto di partenza.
    Dopo: applica remesh o subdivide per più dettaglio.
    
    IMPORTANTE: usa shade_smooth() e origin_to_geometry subito.
    """
    
    bpy.ops.mesh.primitive_uv_sphere_add(
        radius=radius, segments=segments, ring_count=rings,
        location=(0, 0, 0))
    obj = bpy.context.active_object
    obj.name = name
    obj.data.shade_smooth()
    bpy.ops.object.origin_set(type='ORIGIN_GEOMETRY', center='BOUNDS')
    result = {'verts': len(obj.data.vertices), 'name': obj.name}
    return obj

def sculpt_base_cube(name="SculptBox", size=0.2, cuts=8):
    """
    Cubo suddiviso — per sculpting di forme angolari/rocciose.
    cuts=8 → ~4000 facce. Aumenta per più dettaglio.
    """
    bpy.ops.mesh.primitive_cube_add(size=size, location=(0,0,0))
    obj = bpy.context.active_object
    obj.name = name
    bpy.ops.object.mode_set(mode='EDIT')
    bpy.ops.mesh.subdivide(number_cuts=cuts)
    bpy.ops.object.mode_set(mode='OBJECT')
    obj.data.shade_smooth()
    bpy.ops.object.origin_set(type='ORIGIN_GEOMETRY', center='BOUNDS')
    return obj

---

REMESH — Topologia uniforme pre-sculpt

Il remesh crea una topologia uniforme (tutti i poligoni della stessa dimensione) — fondamentale per sculpting uniforme senza artefatti.

def remesh_voxel(obj, voxel_size=0.005, adaptivity=0.0):
    """
    Remesh voxelico — il più semplice e robusto.
    Crea topologia quad uniforme da qualsiasi mesh.
    
    voxel_size: dimensione del voxel [BU]
      0.010 → ~2000 facce (preview rapido)
      0.005 → ~8000 facce (sculpting base)
      0.002 → ~50000 facce (sculpting dettagliato)
      0.001 → ~200000 facce (sculpting fine — lento!)
    
    adaptivity: 0=completamente uniforme, 0.5=adattivo (meno facce sulle piatte)
    
    NOTA: distrugge UV, materiali per slot, vertex groups — fallo PRIMA
    di aggiungere materiali o weight groups.
    """
    bpy.context.view_layer.objects.active = obj
    
    mod = obj.modifiers.new("Remesh", "REMESH")
    mod.mode       = 'VOXEL'
    mod.voxel_size = voxel_size
    mod.adaptivity = adaptivity
    mod.use_smooth_shade = True
    
    bpy.ops.object.modifier_apply(modifier="Remesh")
    obj.data.shade_smooth()
    return obj

def remesh_quad(obj, depth=6):
    """
    Remesh Quad (Instant Meshes-style) — crea quad ordinati.
    depth: 4=bassa (pochi poligoni), 6=media, 8=alta
    
    Meno usato del voxel perché più lento e meno prevedibile.
    """
    bpy.context.view_layer.objects.active = obj
    mod = obj.modifiers.new("Remesh", "REMESH")
    mod.mode  = 'SHARP'
    mod.octree_depth = depth
    mod.use_smooth_shade = True
    bpy.ops.object.modifier_apply(modifier="Remesh")
    return obj

def subdivide_smooth(obj, levels=2):
    """
    SubSurf applicato — alternativa al remesh per mesh già ben topologizzate.
    Usato per aggiungere risoluzione a una mesh bmesh costruita a mano.
    levels=2 → ×4 vertici, levels=3 → ×16 vertici
    """
    mod = obj.modifiers.new("Subdivision", "SUBSURF")
    mod.levels        = levels
    mod.render_levels = levels
    mod.subdivision_type = 'CATMULL_CLARK'
    bpy.ops.object.modifier_apply(modifier="Subdivision")
    obj.data.shade_smooth()
    return obj

---

KDTREE — Spatial Query

Il KDTree è la struttura dati centrale per il sculpting procedurale. Dato un punto nello spazio, trova in O(log n) tutti i vertici entro un raggio.

from mathutils import Vector
from mathutils.kdtree import KDTree

def build_kd(obj):
    """
    Costruisce un KDTree dai vertici di obj in world space.
    
    IMPORTANTE: chiama bpy.context.view_layer.update() prima se l'oggetto
    è stato modificato di recente (matrix_world potrebbe essere stale).
    
    Ritorna: (kd, world_verts) — il KD-tree e la lista di posizioni world
    """
    bpy.context.view_layer.update()
    mw = obj.matrix_world
    wv = [mw @ v.co for v in obj.data.vertices]
    kd = KDTree(len(wv))
    for i, v in enumerate(wv):
        kd.insert(v, i)
    kd.balance()
    return kd, wv

# Uso:
# kd, wv = build_kd(obj)
# hits = kd.find_range(Vector((0, 0, 0.12)), 0.04)
# for world_pos, vertex_index, distance in hits:
#     v = obj.data.vertices[vertex_index]
#     # ... modifica v.co ...

---

FALLOFF FUNCTIONS

Il falloff determina come l'influenza del brush decresce dalla distanza:

def fo_smooth(d, r):
    """Smoothstep — transizione morbida. Default per la maggior parte dei brush."""
    t = min(d / r, 1.0)
    return 1.0 - (3*t*t - 2*t*t*t)

def fo_sharp(d, r):
    """Cubica inversa — picco acuto al centro, cade rapidamente. Per dents e dimples."""
    t = min(d / r, 1.0)
    return (1.0 - t) ** 3

def fo_sphere(d, r):
    """Semicircolare — deformazione a cupola. Per bump e rigonfiamenti."""
    t = min(d / r, 1.0)
    return math.sqrt(max(0.0, 1.0 - t*t))

def fo_linear(d, r):
    """Lineare — cono perfetto. Per creste e spine."""
    return max(0.0, 1.0 - d / r)

def fo_constant(d, r):
    """Costante — tutto al massimo nel raggio, 0 fuori. Per tagli netti."""
    return 1.0 if d  0 else 0.0

def displace_noise(obj, scale=8.0, strength=0.005, seed=42,
                   octaves=4, direction='normal'):
    """
    Applica displacement noise su tutta la mesh.
    
    scale    : frequenza del noise (2=grossolano, 8=medio, 20=fine come pori)
    strength : ampiezza del displacement [BU]
    direction: 'normal' (lungo normali) o 'z' (solo verticale)
    
    Usi tipici:
      Pelle/frutta:  scale=10, strength=0.003, octaves=5
      Roccia:        scale=4,  strength=0.015, octaves=6
      Legno:         scale=8,  strength=0.006, octaves=3
      Tessuto:       scale=20, strength=0.002, octaves=2
    """
    mw  = obj.matrix_world
    mwi = mw.inverted()
    nm  = mwi.transposed().to_3x3()
    
    for v in obj.data.vertices:
        wp = mw @ v.co
        n  = noise3d(wp.x * scale, wp.y * scale, wp.z * scale,
                     seed=seed, octaves=octaves)
        
        if direction == 'normal':
            d_world = (nm @ v.normal).normalized() * n * strength
        else:  # 'z'
            d_world = Vector((0, 0, n * strength))
        
        v.co += mwi.to_3x3() @ d_world
    
    obj.data.update()

def displace_wave(obj, axis='z', wavelength=0.05, amplitude=0.003,
                  phase=0.0):
    """
    Displacement ondulatorio periodico — per rughe parallele, squame, tessuto.
    
    axis       : 'x', 'y', 'z' — direzione delle onde
    wavelength : distanza tra due creste [BU]
    amplitude  : altezza delle creste [BU]
    
    Usi tipici:
      Rughe su fronte:   axis='z', wavelength=0.012, amplitude=0.002
      Squame di pesce:   axis='x', wavelength=0.008, amplitude=0.004
      Trama tessuto:     axis='y', wavelength=0.005, amplitude=0.001
    """
    mw  = obj.matrix_world
    mwi = mw.inverted()
    nm  = mwi.transposed().to_3x3()
    ax  = {'x': 0, 'y': 1, 'z': 2}[axis]
    
    for v in obj.data.vertices:
        wp = mw @ v.co
        t  = math.sin(wp[ax] * 2 * math.pi / wavelength + phase)
        d_world = (nm @ v.normal).normalized() * t * amplitude
        v.co += mwi.to_3x3() @ d_world
    
    obj.data.update()

---

DEFORMAZIONI GLOBALI — Schiacciamento, torsione, bend

def flatten_axis(obj, axis='z', factor=0.85):
    """
    Schiaccia l'oggetto lungo un asse (factor  1e-6:
            v.co += mwi.to_3x3() @ (direction.normalized() * w * dist)
    
    obj.data.update()

def crease(obj, start, end, width=0.01, depth=0.008, falloff='sharp'):
    """
    Crea una ruga/piega lineare tra due punti.
    
    start, end : Vector — estremi della piega in world space
    width      : larghezza della piega [BU]
    depth      : profondità [BU] (positivo=fuori, negativo=dentro)
    
    Usi: rughe su viso, cuciture su cuoio, nervature su foglia
    """
    mw  = obj.matrix_world
    mwi = mw.inverted()
    nm  = mwi.transposed().to_3x3()
    fn  = FALLOFFS.get(falloff, fo_sharp)
    
    start_v = Vector(start)
    end_v   = Vector(end)
    seg     = end_v - start_v
    seg_len = seg.length
    
    if seg_len  0:
        for cn in ['Coat Weight', 'Clearcoat']:
            if cn in inp:
                bsdf.inputs[cn].default_value = coat; break
        for cr in ['Coat Roughness', 'Clearcoat Roughness']:
            if cr in inp:
                bsdf.inputs[cr].default_value = 0.08; break
    
    return m

---

REGOLE QUALITÀ SCULPTING

1. Remesh prima dello sculpt — mai sculpting su mesh con topologia irregolare.

remesh_voxel(obj, voxel_size) dà topologia uniforme → brush uniformi.

1. Ordine brush: forma globale → forma media → dettaglio fine.

Non iniziare con il dettaglio (rughe) prima di aver definito la forma (schiacciamento, dimple).

1. build_kd() ad ogni iterazione se la mesh è stata modificata.

Il KDTree usa le posizioni al momento della costruzione — se i vertici si sono mossi le query spaziali tornano risultati errati.

1. safe_place() dopo ogni sessione di sculpt — mai leggere obj.location

per determinare la posizione dei vertici. Usa sempre world bounds.

1. view_layer.update() prima di qualsiasi calcolo con matrix_world.

1. Noise displacement DOPO smooth — il pattern è:

forma base → smooth leggero → noise fine → smooth leggerissimo finale.

1. ShaderNodeMixRGB è deprecato in Blender 5.x → usa ShaderNodeMix

con data_type='RGBA', Color A = inputs[6], Color B = inputs[7], output = outputs[2].

1. SSS richiede Cycles per risultati fotorealistici. EEVEE Next supporta SSS

ma meno preciso. Per preview usa EEVEE, per finale usa Cycles.

---

ANALISI RICHIESTA

| Keyword | Tecnica | |---------|---------| | mela / pera / frutto | makeapple / makepear + matorganic | | roccia / asteroide / pietra | makerock + displacenoise multi-scala | | terreno / paesaggio | maketerrain + noise3d heightmap | | ruga / piega / cuciture | crease() + displacewave | | dimple / fossetta / ombelico | brush(..., 'sharp', negativo) | | pelle / organico / SSS | displacenoise fine + matorganic | | smooth / leviga / artefatti | smoothpass / globalsmooth | | animabile / morphing | sculpttoshapekey | | topologia uniforme | remesh_voxel prima |

Se richiesta ambigua → chiedi: "L'oggetto ha una forma base riconoscibile (sfera, cilindro, cubo)? Ha dettagli di superficie (rughe, pori, bump)? Deve essere animato?"

Output

• Codice Python completo, nessun placeholder
• Sempre: remesh → brush dalla forma grossa al dettaglio → smooth finale
• Usa mat_organic per oggetti biologici (SSS + noise + coat)
• Dopo esecuzione: get_screenshot → analisi visiva → itera brush
• safe_place() sempre alla fine prima del render

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MAX-786
• Source: MAX-786/claude-3d-harness
• License: MIT

Install and usage instructions live in the source repository linked above.