Elemento 3D

Un elemento 3D rappresenta oggetti tridimensionali nel tuo progetto, inclusi modelli 3D importati, primitive geometriche di base, forme estruse da forme 2D, testo 3D e risultati di operazioni booleane.

Gli elementi 3D condividono i campi comuni da Elemento di Base e Elemento di Vista, introducendo anche proprietà aggiuntive specifiche per il 3D.

Campi di Base

Campi di Trasformazione 3D

Oltre alle proprietà di trasformazione 2D standard (x, y, rotazione, scalaX, scalaY), gli elementi 3D supportano proprietà di trasformazione aggiuntive per il posizionamento e la rotazione tridimensionale:

Tipi di Geometria

Il campo geometryType specifica il tipo di geometria 3D di base. I tipi disponibili sono organizzati per categoria (specificata tramite il campo category quando nodeType è "geometry" o "primitive"):

Nota: nodeType: "primitive" è un alias per "geometry". Entrambi sono supportati e si comportano in modo identico.

Forme di Base (category: "basic"):

• cube - Cubo a sei facce
• sphere - Geometria sferica
• cylinder - Geometria cilindrica
• cone - Geometria conica
• torus - Geometria a forma di ciambella
• capsule - Geometria a forma di pillola
• disc - Disco circolare piatto

Poliedri (category: "polyhedron"):

• pyramid - Piramide a quattro facce
• octahedron - Poliedro a otto facce
• icosahedron - Poliedro a venti facce
• dodecahedron - Poliedro a dodici facce
• hexPrism - Prisma a sei facce
• triangle - Prisma triangolare

Tipi di Nodi Parametrici

I nodi parametrici (nodeType: "parametric") generano geometria in modo procedurale:

Estrusione (category: "extrusion"):

• Estrae forme 2D lungo l'asse Z con profondità e smussatura

Tornitura (category: "lathe"):

• Ruota un profilo 2D attorno a un asse per creare oggetti cilindrici

Sweep (category: "sweep"):

• Sposta un profilo 2D lungo un percorso 3D per creare forme tubolari o basate su rotaie

Tipi di Nodi Curva

I nodi curva (nodeType: "curve") creano curve e percorsi 3D:

Elica (category: "helix"):

• Curve a spirale elicoidale con raggio e passo configurabili

Nodo Torus (category: "torusKnot"):

• Curve di nodo matematico sulla superficie di un toro

Personalizzato (category: "custom"):

• Percorsi di curva definiti dall'utente

Tipi di Nodi Topologici

Le operazioni topologiche (boolean, array, specchio, composto) vengono eseguite all'interno dell'editor e producono output di geometria standard. Queste operazioni vengono applicate in fase di modifica e non richiedono una gestione speciale nell'API di rendering.

Estrusione di Forma

Gli elementi 3D possono essere creati estraendo forme 2D. Quando converti un elemento di forma 2D in 3D nell'editor, genera un nuovo elemento type: "3D" con i seguenti campi aggiuntivi:

Testo 3D

Gli elementi 3D possono anche rappresentare testo tridimensionale con profondità e smussatura:

Materiali e Texture

Gli elementi 3D utilizzano un sistema di materiali PBR (Physically Based Rendering) con supporto completo per le texture:

L'oggetto material contiene:

physicalMaterialData - Proprietà del materiale PBR:

• color (stringa) - Colore di base in formato esadecimale, predefinito: '#818cf8'
• roughness (numero) - Ruvidità della superficie, 0-1, predefinito: 0.4
• metalness (numero) - Proprietà metallica, 0-1, predefinito: 0.0
• opacity (numero) - Opacità del materiale, 0-1, predefinito: 1.0
• transmission (numero) - Trasmissione della luce per materiali simili al vetro, 0-1, predefinito: 0.0
• ior (numero) - Indice di rifrazione, tipicamente 1.0-2.5, predefinito: 1.5
• clearcoat (numero) - Intensità dello strato di rivestimento trasparente, 0-1, predefinito: 0.0
• clearcoatRoughness (numero) - Ruvidità del rivestimento trasparente, 0-1, predefinito: 0.0
• sheen (numero) - Effetto lucido simile a tessuto, 0-1, predefinito: 0.0
• sheenRoughness (numero) - Ruvidità del lucido, 0-1, predefinito: 0.0
• sheenColor (stringa) - Colore della tinta lucida
• thickness (numero) - Spessore del materiale per la trasmissione

materialXPath (stringa) - Percorso del preset MaterialX opzionale:

• Esempi: 'StandardSurface/standard_surface_gold.mtlx', 'StandardSurface/standard_surface_brass_tiled.mtlx'
• Quando caricato, sovrascrive physicalMaterialData con valori preimpostati

Texture Maps - L'oggetto materiale può contenere URL di mappe di texture:

• colorMap - Texture di colore di base/diffusa
• normalMap - Mappa normale per dettagli superficiali
• roughnessMap - Texture di ruvidità
• metalnessMap - Texture di metallicità
• aoMap - Mappa di occlusione ambientale
• emissiveMap - Texture emittente/che brilla

Le mappe di texture vengono applicate utilizzando funzioni TSL (Three.js Shading Language) per prestazioni ottimali.

Modelli e Animazioni glTF

Gli elementi 3D con nodeType: "model" o nodeType: "import" rappresentano modelli 3D importati:

Nota: nodeType: "import" è un alias per "model". Entrambi sono supportati e si comportano in modo identico.

• Usa source.url per specificare l'URL del file glTF/glb/FBX remoto
• Il motore recupererà e memorizzerà nella cache il modello utilizzando sourceId
• Se il modello contiene animazioni, usa animation.currentIndex per selezionare quale animazione riprodurre
• Proprietà di animazione: currentIndex (numero), speed (numero, predefinito 1.0), loop (booleano, predefinito true)
• I modelli supportano la compressione DRACO per dimensioni di file più piccole
• sizeParams contiene width, height, depth per le dimensioni del modello

Esempi

Cubo di Base

 
{
  "id": "3d-cube-001",
  "type": "3D",
  "start": 0,
  "duration": 5,
  "trackIndex": 0,
  "x": 540,
  "y": 540,
  "z": 0,
  "width": 200,
  "height": 200,
  "anchorX": 100,
  "anchorY": 100,
  "rotation": 0,
  "rotationX": 30,
  "rotationY": 45,
  "scaleX": 1,
  "scaleY": 1,
  "scaleZ": 1,
  "alpha": 1,
  "ext": "geometry",
  "nodeType": "geometry",
  "category": "basic",
  "geometryType": "cube",
  "material": {
    "physicalMaterialData": {
      "color": "#4A90E2",
      "roughness": 0.4,
      "metalness": 0.0
    }
  }
}

Forma Estrusa

 
{
  "id": "3d-extrusion-001",
  "type": "3D",
  "start": 0,
  "duration": 5,
  "trackIndex": 0,
  "x": 540,
  "y": 540,
  "z": 0,
  "width": 300,
  "height": 300,
  "anchorX": 150,
  "anchorY": 150,
  "rotation": 0,
  "rotationX": 0,
  "rotationY": 0,
  "scaleX": 1,
  "scaleY": 1,
  "scaleZ": 1,
  "alpha": 1,
  "ext": "parametric",
  "nodeType": "parametric",
  "category": "extrusion",
  "shapeSizeX": 300,
  "shapeSizeY": 300,
  "shapeExtrusion": 100,
  "material": {
    "physicalMaterialData": {
      "color": "#FF6B6B",
      "roughness": 0.3,
      "metalness": 0.1
    }
  },
  "extrusionSource": {
    "shapeType": "SHAPE_STAR",
    "starPoints": 5,
    "starInnerRadius": 0.4
  }
}

Modello glTF con Animazione

 
{
  "id": "3d-model-001",
  "type": "3D",
  "start": 0,
  "duration": 10,
  "trackIndex": 0,
  "x": 540,
  "y": 540,
  "z": -200,
  "width": 400,
  "height": 400,
  "anchorX": 200,
  "anchorY": 200,
  "rotation": 0,
  "rotationX": 0,
  "rotationY": 0,
  "scaleX": 1,
  "scaleY": 1,
  "scaleZ": 1,
  "alpha": 1,
  "ext": "glb",
  "nodeType": "model",
  "sourceId": "cached-model-123",
  "source": {
    "url": "https://example.com/models/animated_character.glb"
  },
  "animation": {
    "currentIndex": 0,
    "speed": 1.0,
    "loop": true
  },
  "sizeParams": {
    "width": 2,
    "height": 2,
    "depth": 2
  },
  "originalWidth": 2,
  "originalHeight": 2,
  "originalDepth": 2
}

Note

• Gli elementi 3D si integrano completamente con l'attuale pipeline di rendering 2D. Puoi mescolare elementi 2D e 3D nello stesso progetto.
• La telecamera utilizza una proiezione prospettica pixel-perfect, assicurando che a z=0, un'unità del mondo corrisponda a un pixel.
• Per le trasformazioni 3D, il sistema di coordinate segue le convenzioni 3D standard: X (destra), Y (alto), Z (verso l'osservatore).
• Le proprietà di materiale e texture sono tipicamente impostate dall'editor. Se stai scrivendo a mano JSON, fai riferimento alla documentazione del preset MaterialX per i materiali disponibili.
• L'editor può anche generare elementi Light3D e Particle3D all'interno delle scene 3D. Questi sono generati dall'editor e non devono essere costruiti manualmente.