# Blender Sculpt

> >

- **Type:** Skill
- **Install:** `agentstack add skill-max-786-claude-3d-harness-blender-sculpt`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [MAX-786](https://agentstack.voostack.com/s/max-786)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [MAX-786](https://github.com/MAX-786)
- **Source:** https://github.com/MAX-786/claude-3d-harness/tree/main/library/gaius/blender-sculpt

## Install

```sh
agentstack add skill-max-786-claude-3d-harness-blender-sculpt
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)

```python
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.

```python
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.

```python
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.

```python
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:

```python
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

```python
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.

2. **Ordine brush**: forma globale → forma media → dettaglio fine.
   Non iniziare con il dettaglio (rughe) prima di aver definito la forma (schiacciamento, dimple).

3. **`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.

4. **`safe_place()` dopo ogni sessione di sculpt** — mai leggere `obj.location`
   per determinare la posizione dei vertici. Usa sempre world bounds.

5. **`view_layer.update()`** prima di qualsiasi calcolo con `matrix_world`.

6. **Noise displacement DOPO smooth** — il pattern è:
   `forma base → smooth leggero → noise fine → smooth leggerissimo finale`.

7. **ShaderNodeMixRGB è deprecato** in Blender 5.x → usa `ShaderNodeMix`
   con `data_type='RGBA'`, Color A = `inputs[6]`, Color B = `inputs[7]`, output = `outputs[2]`.

8. **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` | make_apple / make_pear + mat_organic |
| `roccia / asteroide / pietra` | make_rock + displace_noise multi-scala |
| `terreno / paesaggio` | make_terrain + noise3d heightmap |
| `ruga / piega / cuciture` | crease() + displace_wave |
| `dimple / fossetta / ombelico` | brush(..., 'sharp', negativo) |
| `pelle / organico / SSS` | displace_noise fine + mat_organic |
| `smooth / leviga / artefatti` | smooth_pass / global_smooth |
| `animabile / morphing` | sculpt_to_shape_key |
| `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](https://github.com/MAX-786)
- **Source:** [MAX-786/claude-3d-harness](https://github.com/MAX-786/claude-3d-harness)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-max-786-claude-3d-harness-blender-sculpt
- Seller: https://agentstack.voostack.com/s/max-786
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.