3D 요소

3D 요소는 프로젝트에서 3차원 객체를 나타내며, 가져온 3D 모델, 기본 기하학 프리미티브, 2D 형태에서 추출된 형태, 3D 텍스트 및 불리언 연산 결과를 포함합니다.

3D 요소는 기본 요소 및 보기 요소에서 공통 필드를 공유하며, 추가적인 3D 전용 속성을 도입합니다.

기본 필드

3D 변환 필드

표준 2D 변환 속성(x, y, 회전, scaleX, scaleY) 외에도, 3D 요소는 3차원 위치 지정 및 회전을 위한 추가 변환 속성을 지원합니다:

기하학 유형

geometryType 필드는 기본 3D 기하학의 유형을 지정합니다. 사용 가능한 유형은 카테고리별로 정리되어 있으며(nodeType이 "geometry" 또는 "primitive"일 때 category 필드를 통해 지정됨):

참고: nodeType: "primitive"는 "geometry"의 별칭입니다. 두 가지 모두 지원되며 동일하게 작동합니다.

기본 형태 (category: "basic"):

• cube - 여섯 면의 상자
• sphere - 구형 기하학
• cylinder - 원통형 기하학
• cone - 원뿔형 기하학
• torus - 도넛 모양의 기하학
• capsule - 알약 모양의 기하학
• disc - 평면 원형 디스크

다각형 (category: "polyhedron"):

• pyramid - 네 면의 피라미드
• octahedron - 여덟 면의 다각형
• icosahedron - 스무 면의 다각형
• dodecahedron - 열두 면의 다각형
• hexPrism - 여섯 면의 프리즘
• triangle - 삼각형 프리즘

매개변수 노드 유형

매개변수 노드(nodeType: "parametric")는 기하학을 절차적으로 생성합니다:

압출 (category: "extrusion"):

• 깊이와 베벨링을 통해 Z축을 따라 2D 형태를 압출합니다.

선반 (category: "lathe"):

• 축을 중심으로 2D 프로필을 회전시켜 원통형 객체를 생성합니다.

스윕 (category: "sweep"):

• 3D 경로를 따라 2D 프로필을 스윕하여 튜브형 또는 레일 기반 형태를 생성합니다.

곡선 노드 유형

곡선 노드(nodeType: "curve")는 3D 곡선과 경로를 생성합니다:

나선 (category: "helix"):

• 구성 가능한 반지름과 피치를 가진 나선형 곡선

토러스 매듭 (category: "torusKnot"):

• 토러스 표면에서의 수학적 매듭 곡선

사용자 정의 (category: "custom"):

• 사용자 정의 곡선 경로

위상 노드 유형

위상 연산(불리언, 배열, 미러, 복합)은 편집기 내에서 수행되며 표준 기하학 출력을 생성합니다. 이러한 연산은 편집 시간에 적용되며 렌더 API에서 특별한 처리가 필요하지 않습니다.

형태 압출

3D 요소는 2D 형태를 압출하여 생성할 수 있습니다. 편집기에서 2D 형태 요소를 3D로 변환하면 다음과 같은 추가 필드를 가진 새로운 type: "3D" 요소가 생성됩니다:

3D 텍스트

3D 요소는 깊이와 베벨링을 가진 3차원 텍스트도 나타낼 수 있습니다:

재료 및 텍스처

3D 요소는 포괄적인 텍스처 지원을 갖춘 PBR(물리 기반 렌더링) 재료 시스템을 사용합니다:

material 객체는 다음을 포함합니다:

physicalMaterialData - PBR 재료 속성:

• color (string) - 16진수 형식의 기본 색상, 기본값: '#818cf8'
• roughness (number) - 표면 거칠기, 0-1, 기본값: 0.4
• metalness (number) - 금속성 속성, 0-1, 기본값: 0.0
• opacity (number) - 재료 불투명도, 0-1, 기본값: 1.0
• transmission (number) - 유리 같은 재료의 빛 투과율, 0-1, 기본값: 0.0
• ior (number) - 굴절률, 일반적으로 1.0-2.5, 기본값: 1.5
• clearcoat (number) - 클리어 코팅 층 강도, 0-1, 기본값: 0.0
• clearcoatRoughness (number) - 클리어 코트 거칠기, 0-1, 기본값: 0.0
• sheen (number) - 직물 같은 광택 효과, 0-1, 기본값: 0.0
• sheenRoughness (number) - 광택 거칠기, 0-1, 기본값: 0.0
• sheenColor (string) - 광택 색상
• thickness (number) - 투과를 위한 재료 두께

materialXPath (string) - 선택적 MaterialX 프리셋 경로:

• 예시: 'StandardSurface/standard_surface_gold.mtlx', 'StandardSurface/standard_surface_brass_tiled.mtlx'
• 로드 시, 프리셋 값으로 physicalMaterialData를 덮어씁니다.

텍스처 맵 - 재료 객체는 텍스처 맵 URL을 포함할 수 있습니다:

• colorMap - 기본 색상/확산 텍스처
• normalMap - 표면 세부 사항을 위한 노멀 맵
• roughnessMap - 거칠기 텍스처
• metalnessMap - 금속성 텍스처
• aoMap - 주변 차폐 맵
• emissiveMap - 발광/빛나는 텍스처

텍스처 맵은 최적의 성능을 위해 TSL(Three.js Shading Language) 함수를 사용하여 적용됩니다.

glTF 모델 및 애니메이션

nodeType: "model" 또는 nodeType: "import"가 있는 3D 요소는 가져온 3D 모델을 나타냅니다:

참고: nodeType: "import"는 "model"의 별칭입니다. 두 가지 모두 지원되며 동일하게 작동합니다.

• source.url을 사용하여 원격 glTF/glb/FBX 파일의 URL을 지정합니다.
• 엔진은 sourceId를 사용하여 모델을 가져오고 캐시합니다.
• 모델에 애니메이션이 포함된 경우, animation.currentIndex를 사용하여 재생할 애니메이션을 선택합니다.
• 애니메이션 속성: currentIndex (number), speed (number, 기본값 1.0), loop (boolean, 기본값 true)
• 모델은 더 작은 파일 크기를 위해 DRACO 압축을 지원합니다.
• sizeParams는 모델 치수를 위한 width, height, depth를 포함합니다.

예시

기본 큐브

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

압출된 형태

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

애니메이션이 있는 glTF 모델

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

노트

• 3D 요소는 기존 2D 렌더링 파이프라인과 완전히 통합됩니다. 동일한 프로젝트에서 2D 및 3D 요소를 혼합할 수 있습니다.
• 카메라는 픽셀 완벽한 원근 투영을 사용하여 z=0에서 하나의 세계 단위가 하나의 픽셀에 해당하도록 보장합니다.
• 3D 변환의 경우, 좌표계는 표준 3D 관례를 따릅니다: X (오른쪽), Y (위쪽), Z (뷰어 쪽).
• 재료 및 텍스처 속성은 일반적으로 편집기에 의해 설정됩니다. JSON을 수동으로 작성하는 경우, 사용 가능한 재료에 대한 MaterialX 프리셋 문서를 참조하십시오.
• 편집기는 3D 장면 내에서 Light3D 및 Particle3D 요소도 생성할 수 있습니다. 이러한 요소는 편집기에서 생성되며 수동으로 구성할 필요가 없습니다.