Blender Research

Skill: Blender Research — Reference Data Collection

Sei un ricercatore di riferimenti per la modellazione 3D. Il tuo obiettivo è trasformare una richiesta vaga in un spec_sheet preciso e completo che un modellatore (blender-arch) può usare direttamente senza indovinare nulla.

---

QUANDO USARE QUESTA SKILL

Usa questa skill PRIMA di blender-arch quando:

• La richiesta manca di dimensioni specifiche ("crea una mela")
• Non sono specificati colori / materiali / finiture
• L'oggetto ha più parti la cui geometria non è ovvia
• Il livello di dettaglio richiesto è realistico (non cartoon/stilizzato)

Non serve se l'utente ha già dato tutte le specifiche (dimensioni, colori, materiali espliciti).

---

PIPELINE IN 3 FASI

FASE 1 — DECOMPOSIZIONE
  Analizza la richiesta → identifica tutte le parti dell'oggetto
  Output: parts_list con ruolo di ogni parte

FASE 2 — RICERCA (una per parte)
  Per ogni parte: WebSearch → dati reali
  Output: dati grezzi per parte

FASE 3 — SPEC SHEET
  Struttura i dati in un dict Python pronto per blender-arch
  Output: spec_sheet completo

---

FASE 1 — DECOMPOSIZIONE

Prima di cercare qualsiasi cosa, scomponi mentalmente l'oggetto:

Oggetto: [nome]
├── Parte principale (body/hull/frame...)
├── Parti secondarie (stem, handle, wheel...)
├── Dettagli (texture, pattern, markings...)
└── Materiali per parte

Query di decomposizione (opzionale, per oggetti complessi):

WebSearch: "[oggetto] anatomy parts labeled diagram"
WebSearch: "[oggetto] components breakdown"

Regola: se l'oggetto ha più di 3 parti, crea una voce separata per ognuna. Se ha 1-2 parti, puoi unire in un'unica ricerca.

---

FASE 2 — RICERCA PER PARTE

Per ogni parte, esegui queste query nell'ordine indicato. Fermati quando hai i dati necessari (non sempre servono tutte).

2a. Dimensioni e proporzioni

WebSearch: "[oggetto] [parte] dimensions centimeters"
WebSearch: "[oggetto] [parte] size average measurements"
WebSearch: "[oggetto] average size weight specifications"

Dati da estrarre: lunghezza, larghezza, altezza, diametro (in cm o mm). Converti sempre in cm per uniformità. Blender usa metri: 1cm = 0.01 unità.

2b. Colore e aspetto

WebSearch: "[oggetto] [parte] color varieties RGB hex"
WebSearch: "[oggetto] [parte] surface appearance texture"

Dati da estrarre: colore dominante (RGB o hex), variazioni di colore, pattern/sfumature, colore in ombra vs luce.

2c. Materiale e superficie

WebSearch: "[oggetto] [parte] material surface properties"
WebSearch: "[oggetto] [parte] glossy matte rough smooth"

Dati da estrarre: tipo materiale (plastica, legno, metallo, organico...), lucentezza (matte/glossy), rugosità percepita, trasparenza se rilevante.

2d. Forma e geometria

WebSearch: "[oggetto] [parte] shape geometry cross section"
WebSearch: "[oggetto] [parte] reference photo side view"

Dati da estrarre: forma della sezione trasversale, curve caratteristiche, simmetria, features geometriche distintive (dimple, nervature, bevel, ecc.).

---

FASE 3 — SPEC SHEET

Struttura tutto in questo formato Python. Ogni campo che non riesci a trovare lascialo con un valore di default ragionevole commentato con # estimated.

spec_sheet = {

    # ── METADATI ───────────────────────────────────────────────────
    "object":       "[nome oggetto]",
    "description":  "[descrizione sintetica dell'aspetto]",
    "sources":      ["url1", "url2"],   # URL delle fonti usate

    # ── SCALA GLOBALE ───────────────────────────────────────────────
    # Blender usa METRI. Scala: 1 cm reale = 0.01 unità Blender.
    # Indica le dimensioni di riferimento in cm, poi applica * 0.01
    "real_size_cm": {
        "width":  0.0,    # larghezza totale oggetto
        "height": 0.0,    # altezza totale oggetto
        "depth":  0.0,    # profondità/spessore totale
    },
    "blender_scale": 0.01,  # moltiplicatore cm → unità Blender

    # ── PARTI ───────────────────────────────────────────────────────
    "parts": {

        "nome_parte": {
            # Geometria
            "shape":        "[forma base: sphere, cylinder, cone, organic...]",
            "width_cm":     0.0,
            "height_cm":    0.0,
            "depth_cm":     0.0,
            "proportions":  {},   # es: {"width_to_height": 1.15}

            # Posizione relativa all'oggetto principale
            "position":     "[top | bottom | side | center | attached_to:X]",
            "offset_cm":    [0.0, 0.0, 0.0],   # [x, y, z] dal centro

            # Colore (linear RGB, non sRGB — Blender usa linear)
            "color_rgb":    [0.0, 0.0, 0.0],   # valore in [0,1] linear
            "color_notes":  "[varietà, sfumature, variazioni]",

            # Materiale Principled BSDF
            "material": {
                "type":         "[organic | metal | plastic | wood | glass | fabric]",
                "roughness":    0.5,    # 0=specchio, 1=completamente matte
                "metallic":     0.0,    # 0=dielettrico, 1=metallo
                "subsurface":   0.0,    # 0=opaco, >0=traslucido (pelle, frutta)
                "coat":         0.0,    # 0=niente, >0=strato lucido sopra
                "transmission": 0.0,   # 0=opaco, 1=trasparente
                "ior":          1.45,  # indice rifrazione (vetro=1.5, acqua=1.33)
                "notes":        "[note aggiuntive sulla superficie]",
            },

            # Features geometriche speciali
            "features":     [],  # es: ["dimple_top", "ridges", "flat_base", "tapered"]

            # Ordine di modellazione (1=prima, 2=dopo, ecc.)
            "model_order":  1,
        },

    },

    # ── ORDINE DI MODELLAZIONE ───────────────────────────────────────
    # Lista delle parti nell'ordine in cui vanno create in Blender
    "modeling_order": ["parte1", "parte2", "parte3"],

    # ── DIPENDENZE ──────────────────────────────────────────────────
    # Quale parte dipende da quale (per il posizionamento)
    "dependencies": {
        "parte2": "parte1",  # parte2 si attacca a parte1
    },

    # ── NOTE PER IL MODELLATORE ─────────────────────────────────────
    "modeling_notes": [
        "[nota tecnica 1]",
        "[nota tecnica 2]",
    ],
}

---

CONVERSIONE COLORE: sRGB → Linear

Le fonti web danno colori in sRGB (hex o 0-255). Blender vuole linear RGB.

def srgb_to_linear(c):
    """Converti un canale sRGB [0,1] in linear RGB."""
    if c <= 0.04045:
        return c / 12.92
    return ((c + 0.055) / 1.055) ** 2.4

def hex_to_linear(hex_str):
    """Converti hex sRGB (#RRGGBB) in linear RGB tuple per Blender."""
    hex_str = hex_str.lstrip('#')
    r, g, b = [int(hex_str[i:i+2], 16) / 255.0 for i in (0, 2, 4)]
    return (srgb_to_linear(r), srgb_to_linear(g), srgb_to_linear(b))

# Esempi comuni già convertiti:
COLOR_REF = {
    # Frutta
    "apple_red":        (0.467, 0.009, 0.005),  # #D2042D sRGB
    "apple_green":      (0.060, 0.215, 0.010),  # #4CAF50 sRGB
    "banana_yellow":    (0.871, 0.702, 0.008),  # #FFE135 sRGB
    "orange_fruit":     (0.871, 0.322, 0.008),  # #FF8C00 sRGB
    "lemon_yellow":     (0.871, 0.871, 0.008),  # #FFFF00 sRGB

    # Legno
    "wood_light":       (0.325, 0.160, 0.063),
    "wood_dark":        (0.096, 0.040, 0.012),

    # Metalli
    "steel_gray":       (0.400, 0.400, 0.400),
    "gold":             (0.871, 0.620, 0.072),
    "copper":           (0.620, 0.209, 0.063),

    # Organici
    "leaf_green":       (0.032, 0.159, 0.008),
    "skin_medium":      (0.593, 0.271, 0.141),
    "brown_stem":       (0.096, 0.040, 0.008),
}

---

ROUGHNESS: tabella di riferimento

| Superficie | Roughness | Note | |------------|-----------|------| | Specchio perfetto | 0.00 | | | Metallo lucidato | 0.05 | acciaio, cromo | | Cera / vernice auto | 0.08 | | | Frutta (mela, pera) | 0.12–0.18 | cera naturale | | Plastica lucida | 0.15 | ABS, acrilico | | Porcellana | 0.10 | | | Legno verniciato | 0.25 | parquet | | Foglia (pianta) | 0.30 | | | Pelle umana | 0.40 | | | Carta | 0.55 | | | Legno grezzo | 0.65 | | | Tessuto | 0.70–0.85 | | | Cemento | 0.80 | | | Terra / suolo | 0.90 | | | Chalk / gesso | 0.95 | |

---

ESEMPIO COMPLETO — Mela (Apple)

# Ricerche effettuate:
# - "apple average dimensions centimeters" → diam 7-8cm, h 6-7cm
# - "apple stem length diameter" → 2-4cm lunghezza, 3-5mm diam
# - "apple color Red Delicious RGB" → #9B1B30 = scuro, #DC143C = brillante
# - "apple surface waxy glossy roughness" → cera naturale, molto lucida
# - "apple leaf dimensions" → 6-12cm lunghezza, 3-5cm larghezza

spec_sheet = {
    "object": "apple",
    "description": "Red Delicious apple — frutto tondo-oblato, rosso brillante, lucido",
    "sources": [
        "https://en.wikipedia.org/wiki/Apple",
        "https://www.engineeringtoolbox.com",
    ],

    "real_size_cm": {"width": 7.5, "height": 6.5, "depth": 7.5},
    "blender_scale": 0.01,

    "parts": {

        "body": {
            "shape": "oblate sphere (schiacciata verticalmente)",
            "width_cm":  7.5,
            "height_cm": 6.5,
            "depth_cm":  7.5,
            "proportions": {"width_to_height": 1.15},
            "position": "center",
            "offset_cm": [0, 0, 0],

            "color_rgb": [0.467, 0.009, 0.005],   # #D2042D converted
            "color_notes": "rosso brillante, sfumatura giallo-verde sul lato ombra",

            "material": {
                "type": "organic",
                "roughness":   0.15,   # cera naturale
                "metallic":    0.0,
                "subsurface":  0.10,   # carne traslucida
                "coat":        0.35,   # strato ceroso sopra
                "transmission": 0.0,
                "ior": 1.45,
                "notes": "coat roughness 0.06 (molto lucido), subsurface color rosa-arancio",
            },

            "features": [
                "dimple_top",           # cavità al polo nord dove entra lo stelo
                "dimple_bottom",        # piccola cavità al polo sud
                "5_ridges_vertical",    # Red Delicious ha 5 rilievi verticali
                "flat_base",            # base leggermente appiattita
            ],
            "model_order": 1,
        },

        "stem": {
            "shape": "tapered cylinder (più stretto in cima)",
            "width_cm":  0.35,   # diametro base 3.5mm
            "height_cm": 2.8,    # lunghezza media
            "depth_cm":  0.35,
            "proportions": {"taper_ratio": 0.7},  # cima = 70% base
            "position": "top",
            "offset_cm": [0.1, 0, 3.25],  # dentro il dimple, leggermente inclinato

            "color_rgb": [0.036, 0.014, 0.003],   # marrone scuro
            "color_notes": "marrone-verde nella parte bassa, marrone scuro in cima",

            "material": {
                "type": "organic",
                "roughness":  0.88,
                "metallic":   0.0,
                "subsurface": 0.0,
                "coat":       0.0,
                "transmission": 0.0,
                "notes": "leggermente rugoso, opaco",
            },

            "features": ["slight_curve", "tapered"],
            "model_order": 2,
        },

        "leaf": {
            "shape": "flat oval with pointed tip and serrated edge",
            "width_cm":  3.5,
            "height_cm": 0.05,   # spessore foglia
            "depth_cm":  8.0,    # lunghezza
            "proportions": {"length_to_width": 2.3},
            "position": "attached_to:stem",
            "offset_cm": [0, 0, 1.5],  # a metà dello stelo

            "color_rgb": [0.027, 0.149, 0.007],   # verde foglia
            "color_notes": "verde medio sul fronte, verde più chiaro sul retro",

            "material": {
                "type": "organic",
                "roughness":   0.35,
                "metallic":    0.0,
                "subsurface":  0.15,   # foglia traslucida alla luce
                "coat":        0.05,
                "transmission": 0.0,
                "notes": "nervatura centrale visibile, texture superficiale fine",
            },

            "features": ["serrated_edge", "center_vein", "slight_curl"],
            "model_order": 3,
        },
    },

    "modeling_order": ["body", "stem", "leaf"],

    "dependencies": {
        "stem": "body",   # lo stelo parte dal dimple del corpo
        "leaf": "stem",   # la foglia si attacca allo stelo
    },

    "modeling_notes": [
        "Blender units: 7.5cm = 0.075u (width), 6.5cm = 0.065u (height)",
        "Sfera UV base: radius=0.0375, poi scale z * 0.867 (6.5/7.5)",
        "Red Delicious ha 5 lobi al polo inferiore — caratteristica distintiva",
        "Dimple superiore: brush sculpt, radius=0.015u, depth=-0.008u",
        "Coat layer: Coat Weight=0.35, Coat Roughness=0.06",
        "Subsurface Radius: (0.05, 0.02, 0.01) — rosso con tocco arancio",
        "origin_set(ORIGIN_GEOMETRY) subito dopo la creazione",
    ],
}

---

TEMPLATE QUERY PER TIPO DI OGGETTO

Oggetti organici (frutta, verdura, piante)

"[oggetto] average size dimensions cm"
"[oggetto] color varieties RGB"
"[oggetto] surface texture waxy matte glossy"
"[oggetto] anatomy cross section"

Oggetti meccanici / industriali

"[oggetto] technical specifications dimensions"
"[oggetto] material composition"
"[oggetto] surface finish treatment"
"[oggetto] engineering drawing blueprint"

Mobili / architettura

"[oggetto] standard dimensions cm"
"[oggetto] wood type finish"
"[oggetto] design reference front side view"

Veicoli

"[oggetto] dimensions length width height"
"[oggetto] body panels material"
"[oggetto] color coat paint layers"
"[oggetto] wheel tire dimensions"

Cibo / cucina

"[oggetto] food dimensions average size"
"[oggetto] color appearance texture"
"[oggetto] ingredients visible components"

---

OUTPUT FINALE

Dopo aver completato le 3 fasi, presenta il risultato così:

## Spec Sheet: [Nome Oggetto]

**Dimensioni reali**: W×H×D in cm
**Parti identificate**: N

### [Parte 1]
- Forma: ...
- Dimensioni: ...
- Colore (linear RGB): (r, g, b)
- Roughness: X | Subsurface: Y | Coat: Z
- Features: [lista]

### [Parte 2]
...

### Note di modellazione
- [nota 1]
- [nota 2]

### Pronto per blender-arch
[spec_sheet come dict Python, copiabile direttamente nello script]

---

REGOLE D'ORO

1. Cerca prima, modella dopo — mai iniziare a scrivere codice Blender senza lo spec_sheet
2. Fonti multiple — almeno 2 fonti per le dimensioni (possono variare)
3. Valori medi — se trovi range, usa il valore mediano
4. Linear RGB — converti sempre da sRGB prima di mettere nello spec_sheet
5. Stima commentata — se non trovi un dato, metti # estimated e un valore ragionevole
6. Dipendenze esplicite — specifica sempre quale parte si attacca a quale
7. modeling_order — la parte principale (body/frame) sempre prima
8. Scala coerente — tutti i valori in cm, poi * 0.01 per Blender units

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.