데이터스미스 익스포트 SDK 가이드라인 | 언리얼 엔진 5.4 문서

이 가이드의 대상

이 가이드는 데이터스미스 프레임워크를 사용하여 서드파티 디자인 애플리케이션에서 언리얼 엔진으로 씬을 익스포트하려는 3D 애플리케이션 개발자를 대상으로 합니다.

이 가이드는 사용자가 다음 조건을 충족한다고 가정합니다.

숙련된 C++ 프로그래머입니다.
3D 애플리케이션 개발에 익숙합니다.
서드파티 3D 애플리케이션에서 언리얼 엔진 또는 트윈모션으로 모델을 익스포트하는 함수 기능을 개발하고 있습니다.
언리얼 엔진의 작동 방식에 익숙하지는 않지만 배워보려고 합니다.

학습 내용:

이 페이지에서는 데이터스미스 SDK를 활용하여 다른 디자인 애플리케이션에서 언리얼 엔진으로 3D 모델을 익스포트할 때 참고할 수 있는 다양한 가이드라인 및 모범 사례를 살펴봅니다. 크게는 다음과 같이 나뉩니다.

데이터스미스의 디자인 철학
언리얼 엔진의 데이터 모델 및 구조
데이터스미스 익스포터의 UX 가이드라인과 익스포트 프로세스 주요 단계별 체크리스트
다양한 시나리오별로 유용한 API 호출 및 코드 샘플

다운로드 및 전제 조건

이 섹션에는 다음이 포함됩니다.

필수 다운로드 목록 및 출처
시작하는 데 필요한 데이터스미스 및 언리얼 엔진 지식 개요 및 심화 학습 리소스 링크

언리얼 엔진 및 데이터스미스 SDK 다운로드

언리얼 엔진을 언리얼 엔진 GitHub Repository에서 다운로드한 경우 데이터스미스 SDK가 함께 포함되어 있습니다.

GitHub에서 언리얼 엔진 소스 코드를 다운로드 하려면 이 가이드를 따라 GitHub Repository에 액세스를 요청해야 합니다. 액세스 권한이 없는 경우 404 오류가 발생합니다.

언리얼 엔진 소스 코드를 다운로드하면 다음 경로에서 데이터스미스 SDK를 찾을 수 있습니다.

\Engine\Source\Programs\Enterprise\Datasmith\DatasmithSDK\

Documentation 폴더에는 샘플 프로젝트와 함께 개발 환경을 환경설정하는 방법에 대한 지침이 포함되어 있습니다.

언리얼 엔진을 에픽게임즈 런처에서 다운로드 및 설치한 경우 언리얼 엔진 GitHub Repository의 이 폴더에서 데이터스미스 SDK를 별도로 다운로드해야 합니다.

에픽게임즈는 Revit, SketchUp 및 3ds Max 등 일부 디자인 애플리케이션용 데이터스미스 익스포트 플러그인을 개발했습니다. 이러한 플러그인을 작업에 샘플로 참고할 수 있습니다.

데이터스미스 익스포트 플러그인 소스 코드는 에픽게임즈 GitHub Repository의 다음 경로에서 액세스할 수 있습니다.

\Engine\Source\Programs\Enterprise\Datasmith\

데이터스미스의 이해

데이터스미스는 다양한 디자인 애플리케이션에서 사전에 제작된 씬을 언리얼 엔진으로 가져오는 툴과 플러그인의 모음입니다. 데이터스미스는 FBX 또는 OBJ 같은 다른 일반적인 파일 포맷의 한계를 극복하기 위해 디자인되었습니다.

데이터스미스에서는 다음과 같은 작업을 수행할 수 있습니다.

대규모 메시 처리
언리얼 엔진에서 사용하는 다음과 같은 데이터 저장
- LOD
- 콜리전
- 라이트
- 오브젝트 계층구조
- 메타데이터
언리얼 엔진에서 처리하는 2의 제곱수 포맷으로 텍스처 파일 리포맷

데이터스미스의 특징 및 함수 기능에 대한 자세한 내용은 데이터스미스 개요 페이지를 참고하세요.

데이터 익스포트는 다음과 같은 두 단계로 진행됩니다.

디자인 애플리케이션을 파싱한 후 DatasmithCore API를 사용하여 DatasmithScene 을 구성합니다.
DatasmithExporter API를 사용하여 디스크에 씬을 익스포트합니다.

이러한 API를 사용하는 방법은 다음 문서를 참고하세요.

언리얼 엔진 데이터 모델

데이터스미스 익스포터를 작성하기 전에 언리얼 엔진이 정보를 어떻게 저장 및 구조화하는지 알아두는 것이 좋습니다.

언리얼 엔진은 프로젝트로 작동합니다. 언리얼 프로젝트는 하나 이상의 레벨(Level)을 포함하며, 레벨에는 하나 이상의 액터(Actor)가 포함됩니다. 액터는 위치, 회전 및 스케일을 갖습니다. 또한 서로 다른 레이어에 존재하면서 표시되거나, 숨겨지거나, 애니메이션을 가질 수도 있습니다.

각 액터는 하나 이상의 컴포넌트(Component)를 가지며, 다음이 될 수 있습니다.

스태틱 메시(Static Mesh) 같은 지오메트릭 에셋(Geometric Asset)
라이트(Light)
카메라(Camera) 등

스태틱 메시는 마스터 머티리얼(Master Material) 또는 머티리얼 인스턴스(Material Instance)를 레퍼런스합니다. 반면에 머티리얼 에셋은 텍스처 에셋(Texture Asset)을 레퍼런스합니다.

단일 스태틱 메시는 다수의 액터에 의해 레퍼런스될 수 있습니다. 이것을 지오메트리 인스턴스화(geometry instantiation)라고 합니다.

이 다이어그램은 언리얼 엔진의 액터, 컴포넌트 및 다양한 에셋 타입 간의 관계를 설명합니다. 이미지를 클릭하면 전체 크기로 표시됩니다.

데이터스미스 디자인 철학

플러그인 개발자는 데이터가 어떤 소프트웨어에서 익스포트되든 일관적인 사용자 경험을 제공하기 위해 노력해야 합니다. 따라서 아래에 설명되어 있는 데이터스미스의 디자인 철학을 이해 및 준수하는 것이 중요합니다. 다음은 에픽게임즈 데이터스미스 개발 팀이 자체 플러그인을 개발할 때 준수하는 철학입니다.

데이터스미스 플러그인 타입

모든 데이터스미스 플러그인은 다음 과 같은 두 스킴 중 하나를 사용합니다.

익스포터/임포터 조합. 예를 들어 3ds Max, Revit 및 Sketchup은 다음을 사용합니다.
- 소프트웨어 측의 데이터스미스 익스포터 플러그인
- 언리얼 엔진 측의 데이터스미스 파일 임포터 플러그인
다이렉트 임포터. 예를 들어 언리얼 엔진은 Rhino, Solidworks 및 Cinema4D의 네이티브 포맷 파일을 임포트할 수 있습니다.

이 다이어그램은 사용 가능한 데이터스미스 임포트 워크플로를 설명합니다. 이미지를 클릭하면 전체 크기로 표시됩니다.

어떤 워크플로를 사용할지는 경우에 따라 다릅니다.

익스포트 및 임포트 로직

서로 다른 애플리케이션 간에 데이터를 교환할 때 발생할 수 있는 난관 중 하나는 바로 로직 일부를 어디에 둘지 이해하는 것입니다. 한 애플리케이션에서 다른 애플리케이션으로 데이터를 트랜슬레이션할 때는 다음과 같은 사항을 확인해야 합니다.

전부 익스포트할지 또는 일부 엔티티를 제외할 옵션을 제공할지 여부
익스포트할 때 소규모 오브젝트를 제외해야 할지 여부 및 '소규모'의 정의
익스포트할 때 폴리곤 수를 줄여야 할지 또는 텍스처 해상도를 줄여야 할지 여부
유닛과 스케일을 맞추려면 어디서 엔티티를 리스케일링해야 할지 등

일반적으로 에픽게임즈의 접근법은 모든 것을 세분화된 방식으로, 즉 오브젝트별로 익스포트하고 나중에 데이터를 언리얼 엔진 또는 트윈모션으로 임포트할 때 오브젝트를 병합하고, 폴리곤을 축소하고, 기타 데이터 준비 작업을 처리하는 것입니다.

엄격한 규칙은 없지만, 에픽게임즈의 일반적인 접근법은 데이터스미스 익스포터에 노출되는 옵션 수를 최소한으로만 갖추거나 아예 없애 언리얼 엔진 사용자가 임포트 과정에서 대부분의 결정을 내릴 수 있도록 하는 것입니다.

이 같은 접근법으로는 데이터가 세분화 및 최적화되는 정도를 언리얼 엔진 또는 트윈모션 사용자가 결정하게 됩니다. 언리얼 엔진의 데이터프렙은 이러한 결정을 내리는 데 유용한 툴입니다.

데이터스미스 익스포트/임포트 과정에서 내부 연산과 사용자 선택 연산을 나눠본 예시입니다. 이미지를 클릭하면 전체 크기로 표시됩니다.

소스 변경 후 데이터 리임포트하기

데이터스미스의 역할은 다양한 소스 프로그램에서 언리얼 엔진으로 디자인 데이터를 가져오는 것으로, 보통 해당 데이터를 활용하여 리얼타임 시각화 및 경험을 빌드합니다. 언리얼 엔진에서 시각화와 경험을 만드는 동안 새로운 요구 사항을 충족하거나 관계자의 의견을 반영하기 위해 작업에 포함되는 씬 또는 디자인 데이터를 변경해야 하는 경우가 종종 있습니다.

힘들고 비용이 많이 드는 재작업을 피하려면 언리얼 에디터에서 지금까지 해 온 작업을 잃지 않고 상향식 변경사항을 통합할 수 있어야 합니다. 이를 위해 데이터스미스는 언리얼 프로젝트에서 발생한 변경사항을 모두 보존해 주는 리임포트 워크플로를 제공합니다.

데이터스미스 SDK 측면에서 데이터를 리임포트한다는 것은 다음과 같은 두 가지를 의미합니다.

엔티티는 영구적인 고유 식별자를 갖춰야 합니다. 여러 오브젝트가 동일한 이름을 가질 수도 있으므로 오브젝트의 이름에 의존하는 것은 좋은 전략이 아닙니다.
엔티티는 최대한 높은 퍼포먼스로 데이터를 리임포트할 수 있는 해시 값으로 저장되어야 합니다.

데이터스미스 엔티티가 생성되는 시점에 오브젝트의 데이터를 기반으로 고유한 수치가 생성됩니다. 예를 들어 두 메시가 동일한 것인지 빠르게 결정하려면 시간이 오래 걸리는 알고리즘을 사용하여 일일이 직접 대조할 수도, 버텍스, 페이스 및 UV 수를 바탕으로 수치 값을 계산할 수도 있습니다. 이러한 두 값만 대조하면 메시가 동일한지 여부를 한층 빠르게 확인할 수 있습니다.

그 예시가 이 페이지의 아래에 설명되어 있습니다.

환경 및 라이팅

언리얼 엔진을 렌더링 엔진으로 생각하고 모델과 함께 카메라, 환경 및 배경 같은 환경 세팅을 모두 익스포트할 것이라고 기대할 수도 있지만, 일반적으로 이러한 예술적 결정들은 데이터를 엔진으로 임포트한 후 언리얼 엔진 또는 트윈모션 사용자가 결정하는 것이 가장 좋습니다.

가장 중요한 부분은 바로 지오메트리, 머티리얼, 라이트 및 메타데이터 같은 모델 엘리먼트를 임포트하는 것입니다. 일단 데이터가 언리얼 엔진 또는 트윈모션으로 임포트되고 나면 머티리얼을 변경하고, 라이팅을 조정하고, 다른 예술적인 작업을 수행할 수 있습니다.

데이터스미스 익스포터 UX 가이드라인

이 단계까지 왔다면 언리얼 엔진을 컴파일하고 작은 애플리케이션으로 첫 데이터스미스 파일을 생성했을 가능성이 높습니다. 축하합니다!

이제 최종 사용자를 위한 데이터 구조화 방법과 관련된 UX 고려 사항을 살펴보겠습니다.

익스포터 UI

위의 데이터스미스 디자인 철학 섹션에서 설명했듯이 데이터스미스로 익스포트할 때는 최소한의 옵션만 제공하는 것이 좋습니다. 다음은 몇 가지 예시입니다.


Revit의 데이터스미스 익스포터	언리얼 엔진의 익스포트 옵션 대화창

가이드라인

애플리케이션의 뷰 및 필터링 기능에 따라 WYSIWYG(What You See Is What You Get) 익스포트 방식을 제공합니다. 예를 들어 Revit은 활성 뷰에서 표시되는 엔티티만 익스포트하며, SketchUp은 화면에 표시되는 엔티티만 익스포트합니다. 익스포트할 엔티티만 선택 및 필터링하는 UX를 굳이 새로 개발할 이유는 없습니다.
익스포트 시 아무 옵션도 제공하지 않습니다.
옵션을 노출하는 경우에는 최대한 단순화합니다. 위의 3ds Max 익스포터를 예시로 참고하세요.

피해야 할 사항

지오메트리 디테일, 오브젝트 타입 필터링, UV 채널 같은 데이터 준비 및 최적화 관련 옵션은 노출을 피해야 합니다. 이러한 옵션은 언리얼 엔진 사용자가 언리얼 엔진에서 결정하도록 해야 합니다.

진행률 정보 및 오류 메시지

데이터스미스 익스포터는 언리얼 엔진에서 씬을 전송하고 재구성하는 것과 관련된 모든 엔티티를 수집합니다. 그중 일부 엔티티가 익스포트되지 않을 수도 있습니다. 따라서 하나 이상의 엔티티가 익스포트될 수 없는 경우 사용자에게 알려야 합니다.

또한 규모가 매우 큰 프로젝트의 경우 익스포트하는 데 시간이 오래 걸릴 수도 있습니다. 따라서 진행률 정보를 확인할 수 있어야 합니다.

다음은 몇 가지 예시입니다. 아래 이미지를 클릭하면 전체 크기로 확인할 수 있습니다.

3ds Max의 진행률 정보

Revit 데이터스미스 익스포터의 출력 경고입니다.

3ds Max 데이터스미스 익스포터의 출력 경고입니다.

가이드라인

진행률 정보는 익스포트 중에 사용자에게 표시되어야 합니다.
사용자는 데이터스미스 익스포트 프로세스를 취소할 수 있어야 합니다.
사용자에게 미지원 오브젝트, 텍스처 누락 및 다른 문제를 알려주는 오류 메시지 로그가 표시되어야 합니다.

제공하면 유용한 사항

배치 프로세스 및 스크립팅을 요구하는 사용자가 종종 있습니다. 예를 들어 SketchUp, 3ds Max 또는 Revit 사용자는 네이티브 애플리케이션 스크립팅 언어를 사용하여 데이터스미스로 일괄 익스포트할 수 있습니다.

피해야 할 사항

오류 또는 경고가 발생할 때마다 익스포트 프로세스를 중단하는 연속적인 모달 대화창(확인/취소 창)은 구현하지 않도록 합니다.

유용한 API 호출

코드 예시

구현 예시는 언리얼 엔진 GitHub Repository의 다음 파일을 참고하세요.

/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpExporter.cpp

익스포트된 파일 및 폴더 구조

데이터스미스 '파일'은 다음과 같은 두 부분으로 구성됩니다.

XML 데이터 구조를 사용하는 .udatasmith 파일
.udatasmith 파일과 관련된 에셋을 모두 포함하는 '사이드카 폴더'(연관 폴더)

Example sidecar folder for an .udatasmith file

연관 폴더가 있는 익스포트 파일의 예시입니다.

필수로 갖춰야 하는 사항

[filename].udatasmith 파일 하나와 연관된 [filename]_Assets 폴더 하나
[filename]_Assets 폴더에 저장된 모든 관련 에셋
에셋은 상대적 경로를 사용하여 .udatasmith 파일의 XML 구조에서 레퍼런스됩니다.

피해야 할 사항

에셋을 절대 경로로 레퍼런스하면 안 됩니다.
에셋이 포함된 추가 폴더 및 서브폴더를 생성하면 안 됩니다. 다음은 잘못된 익스포트의 예시입니다.

Textures 폴더가 데이터스미스 프로젝트 파일 외부에 있습니다. 잘못된 경로입니다.

데이터스미스 파일 헤더

에픽게임즈는 헤더 정보를 사용하여 데이터의 출처를 파악합니다. 에픽게임즈의 원격 분석은 어떤 타입의 파일을 어떤 소스에서 가져왔는지에 대한 통계만 수집합니다.

다음은 데이터스미스 파일의 헤더 예시입니다.


    <DatasmithUnrealScene>
    	<Version>0.24</Version>
    	<SDKVersion>4.25</SDKVersion>
    	<Host>Revit</Host>
    	<Application Vendor="Autodesk Inc." ProductName="Revit" ProductVersion="2018"/>
    	<User ID="1e8adca84ffe2d4d625d54b63fba876d" OS="Windows 10 (Release 1709)"/>

필수로 갖춰야 하는 사항

데이터스미스 정보는 위 예시와 비슷하게 적절히 설정되어야 합니다.

유용한 API 호출

코드 예시

구현 예시는 언리얼 엔진 GitHub Repository의 다음 파일을 참고하세요.

/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpExporter.cpp

스태틱 메시 에셋

스태틱 메시 에셋(IDatasmithMeshElement)은 실제 지오메트리를 정의하지만 액터(IDatasmithMeshActorElement)에 의해 레퍼런스되기 전까지는 언리얼 엔진 도는 트윈모션의 뷰포트에 표시되지 않습니다. 또한 씬에 포함되어 있는 여러 IDatasmithMeshActorElement 를 동일한 스태틱 메시 에셋에 지정할 수도 있습니다.

스태틱 메시 에셋에는 다음과 같은 데이터가 저장됩니다.

페이스, 버텍스, 노멀 및 스무딩 마스크
UV
콜리전
LOD
버텍스 컬러
머티리얼 ID 및 할당 등

다음은 .udatasmith 파일 내 스태틱 메시 에셋의 데이터 구조 예시입니다.


    <StaticMesh name="c96130816d3eee95f82a6c00e553f491" label="Walls_Basic_Wall_Exterior_-_Insulation_on_Masonry">
      <file path="rac_advanced_sample_project-3DView-{3D}_Assets/c96130816d3eee95f82a6c00e553f491.udsmesh"/>
      <Size a="5922000.0" x="855.299927" y="30.300011" z="1139.999878"/>
      <LightmapCoordinateIndex value="-1"/>
      <LightmapUV value="-1"/>
      <Hash value="c0e8334d671cf30ef8ff8a67aa4da25b"/>
      <Material id="9" name="e72f7720bfd15817d3789377231c9646"/>
      <Material id="10" name="5d261e4bd619e79ebea1cfcc1d1a8d8e"/>
      <Material id="11" name="13b3765549b7832c6bc26e8922497ced"/>
    </StaticMesh>

필수로 갖춰야 하는 사항

스태틱 메시 이름 은 고유해야 하며 연속된 익스포트에서도 변경되면 안 됩니다. 이 이름은 다음 번 리임포트에서 엔티티를 트래킹하는 데 필요합니다. 3D 애플리케이션은 보통 이를 위한 GUID를 제공합니다.
스태틱 메시 라벨 은 새니타이즈되어야 하며, 사용자가 읽을 수 있어야 하고, 해당 오브젝트가 무엇인지 나타낼 수 있어야 합니다.


메시 에셋의 고유 이름	언리얼 엔진에서 사용자가 읽을 수 있는 라벨

스태틱 메시 에셋(IDatasmithMeshElement)은 적용 가능한 액터에 걸쳐 재사용되어야 하며 인스턴스화되어야 합니다.
언리얼 엔진은 왼손 Z 상향 좌표를 사용하여 치수를 cm 단위로 측정합니다.
- 따라서 변환은 익스포터 측에서 이루어져야 합니다.
- UV 텍스처 좌표는 세로(Y축 기준)로 플립되어야 하며, 이를 통해 언리얼 엔진에서 플립되는 이미지에 대응하기 위해 머티리얼을 타일링할 때 음수 스케일을 방지할 수 있습니다.
- 스케일 변환 및 좌표 트랜스포메이션은 액터 트랜스폼에 적용되는 것이 아니라 스태틱 메시에 구워져야 합니다.
  
  스케일은 지오메트리에 구워지고, 결과적으로 액터 트랜스폼이 1.0 스케일로 설정됩니다(2.54 또는 0.333과 반대).
- 메시 피벗은 0, 0, 0이 되지 않도록 메시에서 계산되어야 합니다.
  
  왼쪽: 오브젝트에 정렬된 메시 피벗(올바름). 오른쪽: 0, 0, 0 피벗(잘못됨)
- 트라이앵글은 스무딩 마스크와 셰이딩이 올바르게 작동할 수 있도록 결합되어야 합니다.
  
  스무딩, 노멀 등이 지오메트리에 올바르게 설정되어 있습니다.

제공하면 유용한 사항

추가 LOD 지정
콜리전 메시 지정
라이트 맵 UV 채널 지정(언랩)

피해야 할 사항

고유하지 않고 익스포트 전반에 걸쳐 반복되는 스태틱 메시 이름. 사용자 지정 오브젝트 이름은 사용하면 안 됩니다.
유닛 리스케일링은 액터 트랜스폼에 저장하면 안 됩니다.
피벗을 0, 0, 0에 두면 안 됩니다.
하나로 결합해야 하는 수천 개의 스태틱 메시 액터를 익스포트하면 안 됩니다. 예를 들어 박스 는 보통 여섯 개의 페이스를 가진 단일 메시이며, 각각 페이스를 하나씩 갖춘 개별 메시 6개가 아닙니다.

유용한 API 호출

코드 예시

구현 예시는 언리얼 엔진 GitHub Repository의 다음 파일을 참고하세요.

/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpExporter.cpp

스태틱 메시 액터

스태틱 메시 액터(IDatasmithMeshActorElements)는 실제 지오메트리를 정의하지 않으며 스태틱 메시 에셋(IDatasmithMeshElement)을 가리킵니다. 여러 IDatasmithMeshActorElements 가 동일한 스태틱 메시를 레퍼런스할 수도 있습니다.

다음은 .udatasmith 파일 내 스태틱 메시 액터의 데이터 구조 예시입니다.


    <ActorMesh name="1" label="Teapot001" layer="0">
	    <mesh name="1"/>
	    <Transform tx="16.825752" ty="-18.789846" tz="0.0" sx="1.0" sy="1.0" sz="1.0" qx="0.0" qy="0.0" qz="0.0" qw="1.0" qhex="0000008000000000000000800000803F"/>
	    <tag value="Max.superclassof: GeometryClass" />
	    <tag value="Max.classof: Teapot" />
	    <tag value="Max.handle: 1" />
	    <tag value="Max.isGroupHead: false" />
	    <tag value="Max.isGroupMember: false" />
	    <tag value="Max.parent.handle: 0" />
    </ActorMesh>

    <ActorMesh name="2" label="Teapot002" layer="0">
	    <mesh name="1"/>
	    <Transform tx="16.825752" ty="35.718727" tz="0.0" sx="1.0" sy="1.0" sz="1.0" qx="0.0" qy="0.0" qz="0.0" qw="1.0" qhex="0000008000000000000000800000803F"/>
	    <tag value="Max.superclassof: GeometryClass" />
	    <tag value="Max.classof: Teapot" />
	    <tag value="Max.handle: 2" />
	    <tag value="Max.isGroupHead: false" />
	    <tag value="Max.isGroupMember: false" />
	    <tag value="Max.parent.handle: 0" />
    </ActorMesh>

Two Static Mesh Actors referencing the same Static Mesh Asset (instancing) imported from 3ds Max.

3ds Max에서 임포트된 동일한 스태틱 메시 에셋(인스턴싱)을 레퍼런스하는 두 스태틱 메시 액터입니다.

필수로 갖춰야 하는 사항

메시 액터 이름 은 고유해야 하며 연속된 익스포트에서도 변경되면 안 됩니다. 이 이름은 다음 번 리임포트에서 엔티티를 트래킹하는 데 필요합니다.
메시 액터 라벨 은 은 새니타이즈되어야 하며(유효하지 않은 문자가 포함되면 안 됨) 사용자가 읽을 수 있어야 합니다.
스태틱 메시 에셋(IDatasmithMeshElement)은 적용 가능한 액터에 걸쳐 재사용되어야 하며 인스턴스화되어야 합니다.
스케일 및 좌표 변환과 좌표 트랜스포메이션은 액터 트랜스폼에 적용되는 것이 아니라 스태틱 메시에 구워져야 합니다.

제공하면 유용한 사항

레이어 사양
태그 및 메타데이터 지원

유용한 API 호출

코드 예시

구현 예시는 언리얼 엔진 GitHub Repository의 다음 파일을 참고하세요.

/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpComponent.cpp

빈 액터

빈 액터는 어태치된 컴포넌트 또는 스태틱 메시가 없는 액터를 가리킵니다. 메타데이터를 포함하거나 계층구조의 일부를 나타내는 수단으로 유용합니다. 빈 액터를 언제, 어떻게 사용해야 하는지에 대한 엄격한 규칙은 없습니다. 아래의 가이드라인은 일반적인 용례를 몇 가지 다룹니다.

가이드라인

빈 액터를 사용하는 경우는 다음과 같습니다.

3ds Max 헬퍼 오브젝트 같은 null 오브젝트 표현
Revit 사이트 위치 같은 커스텀 원점 표현
그 외 Rhino의 레이어, Rhino의 블록 원점 또는 Revit의 레벨 같은 계층구조의 가독성을 높여주는 엘리먼트 표현
Revit의 커튼 벽 같은 자체 지오메트리가 없는 컴파운드 오브젝트의 헤드 표현

예시

3ds Max Helper objects translated as Empty Actors

빈 액터로 트랜슬레이션된 3ds Max 헬퍼 오브젝트입니다.

Empty Actors used to represent invisible elements from Revit

Revit의 투명 엘리먼트 표현에 사용되는 빈 액터입니다.

유용한 API 호출

코드 예시

구현 예시는 언리얼 엔진 GitHub Repository의 다음 파일을 참고하세요.

/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpComponent.cpp

액터 계층구조

언리얼 엔진은 다른 3D 애플리케이션과 마찬가지로 부모/자손 계층구조를 지원합니다.

다음은 .udatasmith 파일 내 부모/자손 관계의 예시입니다.


    <ActorMesh name="3" label="Box001" layer="0">
		    <mesh name="3"/>
		    <Transform .../>
		    <children visible="true"  selector="false" selection="-1">
			    <ActorMesh name="5" label="Box002" layer="0">
				    <mesh name="5"/>
				    <Transform ..."/>
				    <children visible="true"  selector="false" selection="-1">

가이드라인

자신의 애플리케이션 데이터 모델을 반영한 액터 계층구조를 사용하세요.

3ds Max 계층구조는 언리얼 엔진으로 있는 그대로 트랜슬레이션됩니다.
Revit 레벨이 추가 부모 액터로 익스포트된 경우와 같이 애플리케이션의 데이터 모델과 관련된 정보를 저장해야 하는 경우에는 빈 액터를 추가로 삽입합니다.

계층구조에 추가된 Revit 레벨은 최종 사용자가 탐색하는 데 유용하게 사용할 수 있습니다.

피해야 할 사항

최종 사용자가 탐색하기 쉬운 계층구조를 만들려면 꼭 필요한 경우에만 빈 액터를 스태틱 메시 액터의 부모로 사용해야 합니다. 빈 액터가 너무 많으면 계층구조가 복잡해지고 트윈모션과 언리얼 엔진 모두에서 가독성 및 사용성이 떨어집니다.


빈 액터가 너무 많습니다.	빈 액터가 꼭 필요한 경우에만 사용되었습니다.

유용한 API 호출

IDatasmithActorElement::AddChild

코드 예시

구현 예시는 언리얼 엔진 GitHub Repository의 다음 파일을 참고하세요.

/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpComponent.cpp

컴포넌트로서의 액터

Revit 또는 Archicad 같은 애플리케이션에서는 일반적으로 오브젝트가 여러 서브 엘리먼트를 갖습니다. 예를 들어 커튼 벽은 보통 패널과 멀리언으로 빌드되며, 레일링은 보통 레일과 밸러스터로 빌드됩니다.

Revit의 커튼 벽과 레일은 패널, 멀리언, 밸러스터, 핸드레일 같은 서브 엘리먼트를 포함하는 특수한 오브젝트입니다.

각 엘리먼트를 개별 스태틱 메시 액터로 익스포트할 수도 있지만 이 경우 오브젝트를 너무 많이 익스포트하게 되고 언리얼 엔진의 '월드 아웃라이너(World Outliner)'가 아래와 같이 매우 복잡해지게 됩니다.

각 패널과 멀리언을 하나의 스태틱 메시 액터로 익스포트한 커튼 벽입니다. '월드 아웃라이너'에 액터가 상당히 많이 표시된 것을 볼 수 있습니다. 이미지를 클릭하면 전체 크기로 표시됩니다.

가능하다면 서브 엘리먼트를 액터 컴포넌트로 익스포트하는 것도 고려해 볼 수 있습니다. 예를 들어 커튼 벽 오브젝트는 다음과 같은 액터 및 컴포넌트 계층구조를 사용하여 익스포트할 수 있습니다.

커튼 벽 오브젝트 → 빈 액터.
- 패널 → 스태틱 메시 액터 컴포넌트
- 패널 → 스태틱 메시 액터 컴포넌트
- 멀리언 → 스태틱 메시 액터 컴포넌트
- 멀리언 → 스태틱 메시 액터 컴포넌트

커튼 벽을 빈 액터로 익스포트하고 각 패널과 멀리언을 스태틱 메시 액터 컴포넌트로 익스포트하여 월드 뷰 계층구조가 매우 간소화되었습니다. 이미지를 클릭하면 전체 크기로 표시됩니다.

.udatasmith 파일에서 계층구조는 다음과 유사하게 구성됩니다.


    <Actor name="..." label="Walls_Curtain_Wall_Exterior_Curtain_Wall" layer="Walls">
	    <Transform .../>
	    <children visible="true"  selector="false" selection="-1">
		    <ActorMesh name="..." label="Curtain_Panels" layer="Curtain Panels" component="true">
			    <mesh name="..."/>
			    <Transform .../>
		    </ActorMesh>
		    <ActorMesh name="..." label="Curtain_Panels" layer="Curtain Panels" component="true">
			    <mesh name=">
			    <Transform .../>
		    </ActorMesh>
		    <ActorMesh name="label="Curtain_Panels" layer="Curtain Panels" component="true">
			    <mesh name="..."/>
			    <Transform .../>
		    </ActorMesh>

가이드라인

스태틱 메시 액터 컴포넌트를 사용하여 커튼 벽 패널, 밸러스터, 이와 유사한 컴파운드 오브젝트 같은 자손 오브젝트를 나타낼 수 있습니다.
계층구조(IDatasmithActorElement::AddChild)와 컴포넌트 플래그(IDatasmithActorElement::SetIsAComponent)를 모두 설정한 경우에만 올바르게 작동합니다.

유용한 API 호출

코드 예시

구현 예시는 언리얼 엔진 GitHub Repository의 다음 파일을 참고하세요.

/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpComponent.cpp

액터 레이어

언리얼 엔진은 다른 3D 애플리케이션과 마찬가지로 레이어 개념을 지원합니다. 레이어란 씬의 시각적 계층구조 내 액터의 위치를 나타내는 액터 프로퍼티입니다.

아래 예시는 .udatasmith 파일에서 가능한 레이어의 활용을 보여줍니다.


    <ActorMesh name="2" label="Sphere001" layer="Layer002">
    ...
    </ActorMesh>
    <ActorMesh name="3" label="Box001" layer="Layer004">
    ...
    </ActorMesh>

가이드라인

소스 애플리케이션이 레이어를 사용하는 경우 언리얼 엔진에서 레이어로 트랜슬레이션해야 합니다.
소스 애플리케이션이 레이어를 사용하지 않는 경우 언리얼 엔진 레이어로 트랜슬레이션할 수 있는 다른 데이터가 있는지 고려해 보세요. 예를 들어 Revit은 레이어를 사용하지 않지만 엔티티를 카테고리로 분류합니다.

Revit 카테고리에서 파생된 레이어에 임포트된 Revit 엔티티입니다.

제한 사항

레이어 이름은 고유해야 합니다.
언리얼 엔진은 중첩된 레이어를 지원하지 않습니다.


3ds Max의 중첩된 레이어입니다.	언리얼 엔진으로 임포트된 동일한 레이어입니다. 플랫 레이어 계층구조를 확인하세요.

유용한 API 호출

IDatasmithActorElement::SetLayer

코드 예시

구현 예시는 언리얼 엔진 GitHub Repository의 다음 파일을 참고하세요.

/Engine/Source/Programs/Enterprise/Datasmith/DatasmithMaxExporter/Private/DatasmithMaxSceneExporter.cpp

액터 태그

언리얼 엔진은 액터에 대한 사용자 정의 태그를 지원합니다. 데이터스미스는 액터 태그를 사용하여 소스 애플리케이션에서의 데이터 구조화 방식을 설명하는 기술적 정보를 저장합니다. 언리얼 엔진 사용자는 이 액터 태그를 통해 Python, 블루프린트 유틸리티 또는 비주얼 데이터프렙 등으로 스크립팅 연산을 수행합니다.

다음은 3ds Max에서 익스포트된 .udatasmith 파일 내 스태틱 메시 액터 태그의 사용 예시입니다.


    <ActorMesh ...>
	    <mesh name="a8f655367fcc240a8c9eb8d847d58463"/>
	    <Transform .../>
	    <tag value="Revit.Element.Id.186551" />
	    <tag value="Revit.Element.UniqueId.07ae6064-8e02-489e-896d-f7554545ebb2-0002d8b7" />
	    <tag value="Revit.DB.FamilyInstance.Mirrored.True" />
	    <tag value="Revit.DB.FamilyInstance.HandFlipped.False" />
	    <tag value="Revit.DB.FamilyInstance.FaceFlipped.True" />
	    <tag value="Revit.Host.Id.156316" />
	    <tag value="Revit.Host.UniqueId.9e597f98-694d-4ada-b8ef-0e7459e0b930-0002629c" />
    </ActorMesh>
    <ActorMesh name="1" label="Teapot001" layer="0">
	    <mesh name="1"/>
	    <Transform .../>
	    <tag value="Max.superclassof: GeometryClass" />
	    <tag value="Max.classof: Teapot" />
	    <tag value="Max.handle: 1" />
	    <tag value="Max.isGroupHead: false" />
	    <tag value="Max.isGroupMember: false" />
	    <tag value="Max.parent.handle: 0" />
    </ActorMesh>

액터 태그에 무엇을 넣어야 하는지에 대한 엄격한 규칙이 없지만 에픽게임즈에서는 소스 애플리케이션과 관련된 정보를 저장하는 방식으로 태그를 활용하고 있습니다.

예를 들어 3ds Max의 경우 태그를 사용하여 3ds Max에서의 오브젝트 타입 또는 그룹 소속 여부 등과 관련된 정보를 저장합니다.

Revit도 비슷한 방식을 채택하여 Revit 엔티티의 내부 구조를 설명하는 정보를 저장합니다.


Revit 액터 컴포넌트의 액터 태그입니다.	언리얼 엔진으로 임포트된 동일한 레이어입니다. 플랫 레이어 계층구조를 확인하세요.

가이드라인

임포트한 애플리케이션의 이름을 태그의 접두사로 사용합니다(예: Revit.TagName 또는 Max.TagName).
태그를 사용하여 소스 애플리케이션에서의 데이터 구조화 방식 관련 정보를 표시합니다. 다른 사용자 정의 데이터를 저장하는 용도로는 메타데이터를 사용합니다.

유용한 API 호출

코드 예시

구현 예시는 언리얼 엔진 GitHub Repository의 다음 파일을 참고하세요.

/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpComponent.cpp

메타데이터

데이터스미스는 엔티티에 BIM 정보 (또는 기타 커스텀 데이터)를 저장하는 데 사용할 수 있는 키/값 쌍을 전달합니다.

3ds Max metadata translated into Unreal Engine

3ds Max(왼쪽)에서 언리얼 엔진(오른쪽)으로 트랜슬레이션된 메타데이터

제한 사항

키/값 쌍은 스트링만 전달할 수 있습니다. 즉, 플로트와 유닛 등은 '10mm' 같은 스트링에 포함되어야('구워져야') 합니다.
계층구조 프로퍼티가 지원되지 않기 때문에 언더스코어 구분 기호( _ )를 사용하여 계층구조를 평탄화해야 합니다. 아래 Revit 샘플에서 볼 수 있듯이 Element 및 Type 프로퍼티의 그룹화 상태를 유지해야 하는 경우에는 텍스트 스트링을 연결하여 처리합니다.

A simulated flattened hierarchy using metadata from Revit

Revit의 메타데이터를 사용하는 평탄화 계층구조의 시뮬레이션입니다.

유용한 API 호출

코드 예시

구현 예시는 언리얼 엔진 GitHub Repository의 다음 파일을 참고하세요.

/Engine/Source/Programs/Enterprise/Datasmith/DatasmithMaxExporter/Private/DatasmithMaxSceneExporter.cpp

카메라 액터

데이터스미스는 언리얼 엔진에서 카메라를 생성할 수 있지만 사용 사례에 따라 3D 애플리케이션에서 카메라를 익스포트해야 할 수도, 하지 말아야 할 수도 있습니다. 3ds Max 물리적 카메라 같이 카메라를 명시적으로 설정할 때도 있고 Revit의 뷰, SketchUp의 북마크 같이 카메라가 다른 애플리케이션 개념에서 파생되기도 합니다.

언리얼 엔진 카메라와 관련하여 한 가지 고려해야 할 중요 사항으로는 카메라에는 다음과 같이 익스포트 시간에 설정해야 하는 물리적 기반의 특징이 있다는 것입니다.

센서 너비
종횡비
노출값
화이트 포인트
뎁스 오브 필드 등

다음은 .udatasmith 파일에서 태그와 특징을 갖춘 카메라 구현의 예시입니다.


    <Camera name="1856" label="PhysCamera001" layer="0">
		    <LookAt Actor="1857"/>
		    <Transform tx="706.201538" ty="468.560883" tz="0.0" sx="1.0" sy="1.0" sz="1.0" qx="0.0"     qy="0.0" qz="-0.758784" qw="0.651344" qhex="0000000000000000A33F42BF79BE263F"/>
		    <SensorWidth value="36.0"/>
		    <SensorAspectRatio value="1.333333"/>
		    <DepthOfField enabled="0"/>
		    <FocusDistance value="850.27594"/>
		    <FStop value="8.0"/>
		    <FocalLength value="40.0"/>
		    <LookAtRollAllowed enabled="0"/>
		    <Post>
			    <CameraISO value="5999.997559"/>
			    <ShutterSpeed value="59.999973"/>
			    <FStop value="8.0"/>
		    </Post>
		    <tag value="Max.superclassof: camera" />
		    <tag value="Max.classof: Physical" />
		    <tag value="Max.handle: 1856" />
		    <tag value="Max.isGroupHead: false" />
		    <tag value="Max.isGroupMember: false" />
		    <tag value="Max.parent.handle: 0" />
		    <tag value="Max.Target.handle: 1857" />
    </Camera>

언리얼 엔진의 시네 카메라 액터

가이드라인

뎁스 오브 필드, 노출 및 다른 포스트 프로세싱 세팅에 의해 정의되는 기타 포토그래픽 이펙트도 선택 사항입니다. 이러한 이펙트는 자체 데이터스미스 익스포트 컨텍스트에서 정의되어 있지 않을 수도 있는 소스 애플리케이션의 라이팅과 카메라 간의 긴밀한 관계가 필수적입니다.

제한 사항

언리얼 엔진은 왜곡된 카메라(2점 투시)를 지원하지 않습니다. 예를 들어 Revit은 카메라 시점을 바꾸는 '크롭된' 뷰를 가질 수 있지만, 데이터스미스와 언리얼 엔진은 이 같은 카메라 트랜스포메이션을 지원하지 않습니다.

유용한 API 호출

코드 예시

구현 예시는 언리얼 엔진 GitHub Repository의 다음 파일을 참고하세요.

/Engine/Source/Programs/Enterprise/Datasmith/DatasmithMaxExporter/Private/DatasmithMaxCameraExporter.cpp
/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpCamera.cpp

텍스처 에셋

언리얼 엔진에서 텍스처는 단순한 컬러 정보가 아닌 그 이상을 나타냅니다. 텍스처가 샘플링되어 라이팅과 셰이딩에 올바른 영향을 미치려면 텍스처(텍스처 모드)에 의도하는 용도를 지정해야 합니다. 가능한 용도는 다음과 같습니다.

디퓨즈
스페큘러
노멀
NormalGreenInv
디스플레이스
기타
범프
IES

또한 이것은 라이트가 머티리얼(sRGB 및 RGB 커브)에 작용하는 방식에도 직접 영향을 미치기 때문에 컬러 스페이스(주로 감마 보정 또는 sRGB)도 지정해야 합니다.

다음은 .udatasmith 파일 내 텍스처 에셋 구현의 예시입니다.


    <Texture name="sitework_planting_gravel_mixed_0" texturemode="0" texturefilter="3" textureaddressx="0" textureaddressy="0" rgbcurve="-1.000000" srgb="0" file="rac_advanced_sample_project-3DView-{3D}_Assets/sitework.planting.gravel.mixed.png">

		    <Hash value="b10e41741cfee286a5fcf3b288de78f5"/>

    </Texture>

가이드라인

컬러 스페이스(감마/sRGB)는 텍스처의 의도된 용도를 기반으로 정확히 설정해야 합니다.
- sRGB 컬러 스페이스는 주로 알베도 텍스처를 위해 사용됩니다.
- 선형 컬러 스페이스는 주로 노멀, 높이 또는 범프 맵을 위해 사용됩니다.
텍스처 이름(파일 이름 아님)은 새니타이즈되어야 합니다(유효하지 않은 문자를 포함하지 않음).
텍스처는 나머지 에셋과 동일한 폴더에 둬야 합니다.

텍스처는 다른 에셋과 동일한 폴더에 익스포트해야 합니다.

피해야 할 사항

절대 경로를 사용하면 안 됩니다.
텍스처를 나머지 에셋과 다른 폴더에 두면 안 됩니다.
익스포트하는 동안에는 텍스처를 트랜스폼하지 않아도 됩니다. 데이터스미스 임포터가 트랜스폼을 처리합니다.
- DatasmithCore API를 사용하여 텍스처를 .uasset 파일로 변환하지 않아도 됩니다.
- 텍스처를 다른 포맷으로 리포맷, 리사이즈 또는 변환하지 않아도 됩니다.

이 이미지는 ``.uasset` 파일로 텍스처를 나타내는 잘못된 용례를 보여줍니다.

유용한 API 호출

코드 예시

구현 예시는 언리얼 엔진 GitHub Repository의 다음 파일을 참고하세요.

/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpMaterial.cpp

머티리얼

단순 PBR 익스포트

다음 예시는 텍스처를 데이터스미스 파일로 익스포트하여 알베도 맵과 하이트 맵이 포함된 기본적인 PBR 머티리얼을 생성하는 방법을 보여줍니다.

Rhino의 원본 머티리얼

이 예시는 Rhino의 다음 머티리얼을 사용합니다.

머티리얼 세팅은 다음과 같습니다.


알베도 맵	하이트 맵

데이터스미스 파일 결과물

데이터스미스 파일 결과물은 다음과 같습니다.


    <Texture name="c02622dee4b6e6e08265ed1a8ed947e3" label="ColorChecker_sRGB_from_Lab_D50" **texturemode="0"** texturefilter="3" textureaddressx="0" textureaddressy="0" rgbcurve="1.000000" **srgb="1"** file="rhino_diffuse_and_bump_Assets/ColorChecker_sRGB_from_Lab_D50.bmp">
		    <Hash value="2eac7dc7c873963f39791a4c7e9a6f74"/>
    </Texture>
    <Texture name="82c22916309f2f098d35b2856b2caf5c" label="Heightmap_normal" **texturemode="6"** texturefilter="3" textureaddressx="0" textureaddressy="0" rgbcurve="1.000000" **srgb="0"** file="rhino_diffuse_and_bump_Assets/Heightmap.png">
		    <Hash value="cafca7197e3f5a46480b09f329f9eabd"/>
    </Texture>

    <UEPbrMaterial name="90589c47f06eb971d548591f23c285af" label="Custom">
    		<Expressions>
			    <Texture Name="Diffuse_Map" PathName="c02622dee4b6e6e08265ed1a8ed947e3">
			    </Texture>
			    <Texture Name="Bump_Map" PathName="82c22916309f2f098d35b2856b2caf5c">
			    </Texture>
		    </Expressions>
		    <Input Name="BaseColor" expression="0" OutputIndex="0"/>
		    <Input Name="Normal" expression="1" OutputIndex="0"/>
		    <OpacityMaskClipValue value="0.3333"/>
    </UEPbrMaterial>

위 두 텍스처에서 texturemode 와 srgb 값이 서로 다르다는 것을 알 수 있습니다.

첫 번째 텍스처의 texturemode="0" 및 srgb="1"
두 번째 텍스처의 texturemode="6" 및 srgb="0"

언리얼 에디터에서 임포트

언리얼 엔진에서 임포터 머티리얼의 PBR 그래프는 다음과 같은 모습이 됩니다.

이미지를 클릭하면 전체 크기로 표시됩니다.

알베도 맵은 SRGB=1 로, 샘플러 타입은 Color 로 설정되어 있습니다. 이것은 데이터스미스 임포터에 의해 자동으로 구성된 것이며, 익스포트된 알베도 맵을 다음처럼 설정한 결과입니다.

texturemode="0" srgb="1"

Rhino에서 그레이스케일이었던 하이트 맵은 데이터스미스 임포터에 의해 노멀 맵으로 변환되었으며, 이것은 텍스처를 다음과 같이 세팅한 결과입니다.

texturemode="6" srgb="0"

유용한 API 호출

IDatasmithUEPbrMaterialElement
IDatasmithTextureElement:
- SetSRGB - EDatasmithColorSpace
- SetTextureMode - EDatasmithTextureMode