Elemento 3D

Um elemento 3D representa objetos tridimensionais em seu projeto, incluindo modelos 3D importados, primitivas de geometria básica, formas extrudadas a partir de formas 2D, texto 3D e resultados de operações booleanas.

Os elementos 3D compartilham os campos comuns de Elemento Básico e Elemento de Visualização, enquanto também introduzem propriedades adicionais específicas para 3D.

Campos Básicos

Campos de Transformação 3D

Além das propriedades de transformação 2D padrão (x, y, rotação, escalaX, escalaY), os elementos 3D suportam propriedades de transformação adicionais para posicionamento e rotação tridimensionais:

Tipos de Geometria

O campo geometryType especifica o tipo de geometria 3D básica. Os tipos disponíveis são organizados por categoria (especificada através do campo category quando nodeType é "geometry" ou "primitive"):

Nota: nodeType: "primitive" é um alias para "geometry". Ambos são suportados e se comportam de forma idêntica.

Formas Básicas (category: "basic"):

• cube - Caixa de seis lados
• sphere - Geometria esférica
• cylinder - Geometria cilíndrica
• cone - Geometria cônica
• torus - Geometria em forma de donut
• capsule - Geometria em forma de pílula
• disc - Disco circular plano

Poliedros (category: "polyhedron"):

• pyramid - Pirâmide de quatro lados
• octahedron - Poliedro de oito faces
• icosahedron - Poliedro de vinte faces
• dodecahedron - Poliedro de doze faces
• hexPrism - Prisma de seis lados
• triangle - Prisma triangular

Tipos de Nós Paramétricos

Nós paramétricos (nodeType: "parametric") geram geometria proceduralmente:

Extrusão (category: "extrusion"):

• Extruda formas 2D ao longo do eixo Z com profundidade e chanfragem

Torno (category: "lathe"):

• Revolve um perfil 2D em torno de um eixo para criar objetos cilíndricos

Varredura (category: "sweep"):

• Varre um perfil 2D ao longo de um caminho 3D para criar formas tubulares ou baseadas em trilhos

Tipos de Nós de Curva

Nós de curva (nodeType: "curve") criam curvas e caminhos 3D:

Hélice (category: "helix"):

• Curvas espirais helicoidais com raio e passo configuráveis

Nó de Toróide (category: "torusKnot"):

• Curvas de nó matemático na superfície de um toróide

Personalizado (category: "custom"):

• Caminhos de curva definidos pelo usuário

Tipos de Nós de Topologia

Operações de topologia (booleanas, array, espelho, composto) são realizadas dentro do editor e produzem saída de geometria padrão. Essas operações são aplicadas no tempo de edição e não requerem tratamento especial na API de renderização.

Extrusão de Forma

Os elementos 3D podem ser criados pela extrusão de formas 2D. Quando você converte um elemento de Forma 2D para 3D no editor, ele gera um novo elemento type: "3D" com os seguintes campos adicionais:

Texto 3D

Os elementos 3D também podem representar texto tridimensional com profundidade e chanfragem:

Materiais e Texturas

Os elementos 3D usam um sistema de material PBR (Renderização Baseada em Física) com suporte abrangente para texturas:

O objeto material contém:

physicalMaterialData - Propriedades do material PBR:

• color (string) - Cor base em formato hex, padrão: '#818cf8'
• roughness (number) - Rugosidade da superfície, 0-1, padrão: 0.4
• metalness (number) - Propriedade metálica, 0-1, padrão: 0.0
• opacity (number) - Opacidade do material, 0-1, padrão: 1.0
• transmission (number) - Transmissão de luz para materiais semelhantes ao vidro, 0-1, padrão: 0.0
• ior (number) - Índice de refração, tipicamente 1.0-2.5, padrão: 1.5
• clearcoat (number) - Intensidade da camada de revestimento transparente, 0-1, padrão: 0.0
• clearcoatRoughness (number) - Rugosidade do revestimento transparente, 0-1, padrão: 0.0
• sheen (number) - Efeito de brilho semelhante a tecido, 0-1, padrão: 0.0
• sheenRoughness (number) - Rugosidade do brilho, 0-1, padrão: 0.0
• sheenColor (string) - Cor do tom do brilho
• thickness (number) - Espessura do material para transmissão

materialXPath (string) - Caminho de preset MaterialX opcional:

• Exemplos: 'StandardSurface/standard_surface_gold.mtlx', 'StandardSurface/standard_surface_brass_tiled.mtlx'
• Quando carregado, substitui physicalMaterialData com valores preset

Mapas de Textura - O objeto material pode conter URLs de mapas de textura:

• colorMap - Textura de cor base/difusa
• normalMap - Mapa normal para detalhes da superfície
• roughnessMap - Textura de rugosidade
• metalnessMap - Textura de metalicidade
• aoMap - Mapa de oclusão ambiental
• emissiveMap - Textura emissiva/brilhante

Os mapas de textura são aplicados usando funções TSL (Three.js Shading Language) para desempenho ideal.

Modelos e Animações glTF

Os elementos 3D com nodeType: "model" ou nodeType: "import" representam modelos 3D importados:

Nota: nodeType: "import" é um alias para "model". Ambos são suportados e se comportam de forma idêntica.

• Use source.url para especificar a URL do arquivo glTF/glb/FBX remoto
• O motor buscará e armazenará em cache o modelo usando sourceId
• Se o modelo contiver animações, use animation.currentIndex para selecionar qual animação reproduzir
• Propriedades de animação: currentIndex (number), speed (number, padrão 1.0), loop (boolean, padrão true)
• Modelos suportam compressão DRACO para tamanhos de arquivo menores
• sizeParams contém width, height, depth para dimensões do modelo

Exemplos

Cubo Básico

 
{
  "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 Extrudada

 
{
  "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
  }
}

Modelo glTF com Animação

 
{
  "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
}

Notas

• Os elementos 3D se integram totalmente com o pipeline de renderização 2D existente. Você pode misturar elementos 2D e 3D no mesmo projeto.
• A câmera usa projeção de perspectiva perfeita em pixels, garantindo que em z=0, uma unidade do mundo corresponda a um pixel.
• Para transformações 3D, o sistema de coordenadas segue as convenções 3D padrão: X (direita), Y (cima), Z (em direção ao visualizador).
• Propriedades de material e textura são tipicamente definidas pelo editor. Se você estiver escrevendo JSON manualmente, consulte a documentação do preset MaterialX para materiais disponíveis.
• O editor também pode gerar elementos Light3D e Particle3D dentro de cenas 3D. Estes são gerados pelo editor e não precisam ser construídos manualmente.