Datasmith Export SDK Leitfaden | Unreal Engine 5.5 Dokumentation

Zielgruppe dieser Anleitung

Diese Anleitung richtet sich an Entwickler von 3D-Anwendungen, die Szenen aus Drittanbieter-Designanwendungen mithilfe des Datasmith-Frameworks in die Unreal Engine exportieren möchten.

Diese Anleitung geht von folgenden Annahmen aus:

Sie sind ein erfahrener C++-Programmierer.
Sie sind mit der Entwicklung von 3D-Anwendungen vertraut.
Sie entwickeln Funktionen zum Exportieren von Modellen aus einer 3D-Drittanbieteranwendung in die Unreal Engine oder Twinmotion.
Sie sind nicht mit der Funktionsweise der Unreal Engine vertraut, sind aber bereit, mehr darüber zu lernen.

Was Sie lernen werden

Diese Seite skizziert eine Reihe von Richtlinien und Best Practices für den Export von 3D-Modellen aus anderen Designanwendungen in die Unreal Engine unter Verwendung des Datasmith SDK. Im Wesentlichen skizziert sie:

Die Designphilosophie hinter Datasmith.
Datenmodelle und -strukturen in der Unreal Engine.
UX-Richtlinien für Datasmith-Exporter, mit separaten Checklisten für jeden wichtigen Teil des Exportprozesses.
Nützliche API-Aufrufe und Codebeispiele für verschiedene Szenarien.

Downloads und Voraussetzungen

Dieser Abschnitt enthält:

Eine Liste der erforderlichen Downloads und wo sie zu finden sind.
Ein Überblick über das erforderliche Wissen zu Datasmith und Unreal Engine, um Ihnen den Einstieg zu erleichtern, sowie Links zu Ressourcen für weiterführendes Lernen.

Herunterladen der Unreal Engine und des Datasmith SDK

Wenn Sie die Unreal Engine aus dem Unreal Engine GitHub-Repository herunterladen und erstellen, ist das Datasmith SDK enthalten.

Um den Quellcode der Unreal Engine von GitHub herunterzuladen, müssen Sie zunächst die in dieser Anleitung beschriebenen Schritte befolgen, um Zugriff auf das Repository zu beantragen. Wenn Ihnen der Zugriff nicht gewährt wurde, erhalten Sie einen 404-Fehler.

Nachdem Sie den Quellcode der Unreal Engine heruntergeladen haben, finden Sie das Datasmith SDK unter:

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

Der Ordner Documentation enthält ein Beispielprojekt sowie Anweisungen zur Konfiguration Ihrer Entwicklungsumgebung.

Wenn Sie die Unreal Engine über den Epic Games Launcher herunterladen und installieren, müssen Sie das Datasmith SDK separat aus diesem Ordner im Unreal Engine GitHub-Repository herunterladen.

Epic Games hat Datasmith-Export-Plugins für einige Designanwendungen wie Revit, SketchUp und 3ds Max entwickelt. Sie können diese Plugins als Beispiele für Ihre eigene Arbeit heranziehen.

Sie können auf den Quellcode dieser Datasmith-Export-Plugins im Epic Games GitHub-Repository zugreifen, unter:

\Engine\Source\Programs\Enterprise\Datasmith\

Datasmith verstehen

Datasmith ist eine Sammlung von Werkzeugen und Plugins, die vorgefertigte Szenen, die in verschiedenen Designanwendungen erstellt wurden, in die Unreal Engine bringt. Es wurde entwickelt, um die Einschränkungen anderer generischer Dateiformate wie FBX oder OBJ zu überwinden.

Datasmith ist in der Lage:

Große Meshs zu verarbeiten.
Daten zu speichern, die die Unreal Engine verwendet, wie zum Beispiel:
- LODs
- Kollision
- Lichter
- Objekthierarchie
- Metadaten
Texturdateien neu formatieren (auf eine Zweierpotenz, in Formate, die von Unreal unterstützt werden).

Um mehr über die Funktionen und die Funktionalität von Datasmith zu erfahren, besuchen Sie die Seite Datasmith Übersicht.

Der Export von Daten erfolgt in zwei Schritten:

Analysieren der Designanwendung und Konstruieren einer DatasmithScene mit der DatasmithCore-API.
Exportieren der Szene auf die Festplatte mithilfe der DatasmithExporter-API.

Um zu erfahren, wie Sie diese APIs verwenden, lesen Sie die folgende Dokumentation:

Unreal-Engine-Datenmodell

Bevor Sie mit dem Schreiben Ihres Datasmith-Exporters beginnen, machen Sie sich damit vertraut, wie die Unreal Engine Informationen speichert und strukturiert.

Die Unreal Engine arbeitet mit Projekten. Ein Unreal-Projekt enthält mindestens ein Level, das einen oder mehrere Actors enthält. Actors haben eine Position, Drehung und Skalierung. Sie können auf verschiedenen Ebenen existieren, angezeigt oder ausgeblendet werden, Animationen haben und so weiter.

Jeder Actor hat eine oder mehrere Komponenten, die von folgender Art sein können:

Geometrische Assets, wie statische Meshs.
Lichter.
Kameras und so weiter.

Statische Meshs referenzieren Hauptmaterialien oder Material-Instanzen. Material-Assets referenzieren wiederum Textur-Assets.

Ein einzelnes statisches Mesh kann von mehreren Actors referenziert werden. Dies wird als Geometrieinstanzierung bezeichnet.

Dieses Diagramm veranschaulicht die Beziehung zwischen Actors, Komponenten und verschiedenen Arten von Assets in der Unreal Engine. Klicken Sie auf das Bild für die volle Größe.

Datasmith-Designprinzipien

Als Plugin-Entwickler sollten Sie sich bemühen, ein konsistentes Benutzererlebnis zu gewährleisten, unabhängig davon, aus welcher Software die Daten exportiert werden. Daher ist es wichtig, die unten aufgeführten Datasmith-Designprinzipien zu verstehen und einzuhalten. Dies sind die Prinzipien, die wir (das Datasmith-Entwicklerteam) bei der Entwicklung unserer eigenen Plugins verwenden.

Datasmith-Plugin-Typen

Alle Datasmith-Plugins verwenden eines der folgenden beiden Schemata:

Kombination aus Exporter/Importer. Zum Beispiel verwenden 3ds Max, Revit und Sketchup:
- Ein Datasmith-Exporter-Plugin auf der Softwareseite.
- Das Datasmith-File-Importer-Plugin auf der Unreal-Engine-Seite.
Direkten Importer. Zum Beispiel kann die Unreal Engine einige Dateiformate nativ von Rhino, Solidworks und Cinema4D importieren.

Dieses Diagramm veranschaulicht die verschiedenen verfügbaren Datasmith-Import-Workflows. Klicken Sie auf das Bild für die volle Größe.

Die Wahl des zu verwendenden Workflows variiert von Fall zu Fall.

Export- und Importlogik

Eine der Herausforderungen beim Austausch von Daten zwischen verschiedenen Anwendungen besteht darin, zu verstehen, wo ein Teil der Logik platziert werden soll. Wenn wir Daten von einer Anwendung in eine andere verschieben, können wir uns fragen:

Sollten wir alles exportieren oder Optionen anbieten, um manche Entitäten auszuschließen?
Sollten wir kleine Objekte beim Export ausschließen? Wie definieren wir „klein“?
Sollten wir die Polygonanzahl beim Export reduzieren? Sollten wir die Texturauflösungen reduzieren?
Wo skalieren wir Entitäten neu, um Einheiten und Maßstab anzupassen?, und so weiter.

Im Allgemeinen ist unser Ansatz, alles granular zu exportieren (das heißt, Objekt für Objekt) und sich mit dem Zusammenführen von Objekten, der Reduzierung von Polygonen und anderen Datenvorbereitungsoperationen zu befassen, wenn die Daten später in die Unreal Engine oder Twinmotion importiert werden.

Obwohl es keine strikte Regel gibt, ist unser allgemeiner Ansatz, dass es am besten ist, so wenig Optionen wie möglich (oder gar keine) im Datasmith-Exporter offenzulegen und dem Unreal-Engine-Benutzer die meisten Entscheidungen während des Imports zu überlassen.

Mit diesem Ansatz liegt es am Unreal- oder Twinmotion-Benutzer zu entscheiden, wie granular ihre Daten sein dürfen oder wie optimiert sie sein können. Unreal Engine Dataprep ist ein großartiges Werkzeug, um diese Entscheidungen zu treffen.

Beispiel für die Aufteilung zwischen internen und benutzergewählten Operationen im Verlauf des Datasmith-Export-/Importprozesses. Klicken Sie auf das Bild für die volle Größe.

Reimportieren von Daten nach Quelländerungen

Datasmith bringt Entwurfsdaten aus verschiedenen Quellanwendungen in die Unreal Engine, typischerweise mit dem Ziel, Echtzeitvisualisierungen und -erlebnisse rund um diese Daten zu erstellen. Oftmals müssen während der Arbeit an diesen Visualisierungen und Erlebnissen in der Unreal Engine die Szene oder die Designdaten, die Ihre Arbeit einbezieht, geändert werden, um neuen Anforderungen gerecht zu werden oder Feedback von Stakeholdern zu berücksichtigen.

Um mühsame und kostspielige Nacharbeiten zu vermeiden, müssen Sie in der Lage sein, diese nachgelagerten Änderungen zu integrieren, ohne die gesamte Arbeit zu verlieren, die Sie bereits im Unreal Editor geleistet haben. Zu diesem Zweck bietet Datasmith einen Reimport-Workflow, der alle Ihre Änderungen innerhalb des Unreal-Projekts bewahrt.

Aus der Perspektive des Datasmith SDK impliziert das Reimportieren von Daten zwei Dinge:

Entitäten müssen eine persistente eindeutige Kennung haben. Sich auf den Namen eines Objekts zu verlassen, ist keine gute Strategie, da mehrere Objekte denselben Namen haben können.
Entitäten müssen mit einem Hash-Wert gespeichert werden, der das Reimportieren von Daten mit der höchstmöglichen Performance ermöglicht.

Wenn eine Datasmith-Entität erstellt wird, wird basierend auf den Daten des Objekts eine eindeutige Nummer generiert. Um z. B. schnell festzustellen, ob zwei Meshs identisch sind, könnte man entweder einen zeitaufwendigen Algorithmus verwenden, um sie direkt zu vergleichen, oder einen numerischen Wert berechnen, der auf der Anzahl der Scheitelpunkte, Flächen und UVs basiert. Das Vergleichen dieser beiden Werte wäre dann eine viel schnellere Methode, um festzustellen, ob die Meshs identisch sind oder nicht.

Beispiele werden weiter unten auf dieser Seite beschrieben.

Umgebung und Beleuchtung

Obwohl Sie versucht sein könnten, Unreal als eine Rendering-Engine zu betrachten und erwarten, ein Modell mit all seinen Umgebungseinstellungen (Kameras, Umgebungen, Hintergründe usw.) zu exportieren, stellen wir fest, dass diese künstlerischen Entscheidungen im Allgemeinen am besten von Unreal-Engine- oder Twinmotion-Nutzern getroffen werden, nachdem die Daten in die Engine importiert wurden.

Der wichtigste Aspekt ist das Importieren von Modellelementen (Geometrie, Materialien, Lichter, Metadaten). Sobald die Daten in die Unreal Engine oder Twinmotion importiert wurden, können Benutzer Materialien ändern, die Beleuchtung anpassen und andere künstlerische Aufgaben durchführen.

UX-Leitfaden für Datasmith-Exporter

Wenn Sie es bis zu diesem Punkt geschafft haben, haben Sie vermutlich Unreal kompiliert und Ihre erste Datasmith-Datei mit einer kleinen Anwendung erstellt. Glückwunsch!

Jetzt ist es an der Zeit, sich UX-Überlegungen anzusehen, die sich darauf beziehen, wie die Daten für Endbenutzer strukturiert werden sollten.

Exporter-Benutzeroberfläche

Wie wir im Abschnitt ‚Datasmith-Designprinzipien‘ oben beschrieben haben, möchten wir beim Export nach Datasmith die geringstmögliche Anzahl von Optionen anbieten. Hier sind einige Beispiele:


Datasmith-Exporter von Revit	Dialogfeld Export Options in der Unreal Engine

Richtlinien

Bevorzugen Sie WYSIWYG-Exporte (What You See Is What You Get), indem Sie sich auf die Anzeige- und Filterfunktionen der Anwendung verlassen. Zum Beispiel exportiert Revit nur das, was in der aktiven Ansicht sichtbar ist, und SketchUp exportiert nur das, was auf dem Bildschirm sichtbar ist. Es gibt keinen Grund, eine völlig neue UX zu erfinden, um zu exportierende Entitäten auszuwählen und zu filtern.
Bevorzugen Sie beim Exportieren keinerlei Optionen.
Wenn Sie Optionen offenlegen müssen, halten Sie diese so einfach wie möglich. Verweisen Sie auf den oben genannten 3ds-Max-Exporter als Beispiel.

Zu vermeiden

Optionen im Zusammenhang mit der Datenvorbereitung und -optimierung, wie Geometriedetails, Objektfilterung, UV-Kanäle usw. Diese Entscheidungen sollten vom Unreal-Engine-Benutzer in der Unreal Engine getroffen werden.

Fortschrittsinformationen und Fehlermeldungen

Datasmith-Exporter sammeln alle Entitäten, die für die Übertragung und Rekonstruktion der Szene in der Unreal Engine relevant sind. Es ist möglich, dass einige Entitäten nicht exportiert werden können. Sie sollten die Benutzer informieren, wenn eine oder mehrere Entitäten nicht exportiert werden können.

Darüber hinaus sind einige Projekte sehr groß, wodurch der Export mitunter sehr lange dauern kann. Benutzer sollten in der Lage sein, Fortschrittsinformationen zu sehen.

Hier sind einige Beispiele. Klicken Sie unten auf ein beliebiges Bild, um es in voller Größe zu sehen.

Fortschrittsinformationen in 3ds Max.

Output-Warnungen im Revit Datasmith Exporter.

Output-Warnungen im 3ds Max Datasmith Exporter.

Richtlinien

Fortschrittsinformationen müssen dem Benutzer während des Exports angezeigt werden.
Benutzer müssen in der Lage sein, den Datasmith-Exportvorgang abzubrechen.
Eine Fehlermeldungsprotokollierung sollte angezeigt werden, um Benutzer über nicht unterstützte Objekte, fehlende Texturen und andere Probleme zu informieren.

Nützlich

Bestimmte Benutzer fordern oft Stapelverarbeitung und Scripting. Zum Beispiel können Benutzer mit SketchUp, 3ds Max oder Revit Stapel-Exporte nach Datasmith unter Verwendung der nativen Anwendungsskriptsprache durchführen.

Zu vermeiden

Implementieren Sie keine aufeinanderfolgenden modalen Dialoge (OK/Abbrechen-Fenster), die den Exportvorgang jedes Mal unterbrechen, wenn ein Fehler oder eine Warnung auftritt.

Nützliche API-Aufrufe

Codebeispiel

Ein Beispiel für eine Implementierung findet sich in der folgenden Datei im Repository der Unreal Engine:

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

Struktur der exportierten Dateien und Ordner

Eine Datasmith-„Datei“ besteht aus zwei Teilen:

Einer .udatasmith-Datei, die eine XML-Datenstruktur verwendet.
Einem zugehörigen Ordner, der alle Assets enthält, die mit der .udatasmith-Datei verbunden sind.

Beispiel eines zugehörigen Ordners für eine .udatasmith- Datei

Beispielhafte Exportdatei mit ihrem zugehörigen Ordner.

Unverzichtbar

Eine einzelne Datei [filename].udatasmith und ein einzelner zugehöriger Ordner [filename]_Assets.
Alle zugehörigen Assets werden im Ordner [filename]_Assets gespeichert.
Assets werden in der XML-Struktur der .udatasmith-Datei über relative Pfade referenziert.

Zu vermeiden

Verweisen Sie nicht auf Assets mit absoluten Pfaden.
Erstellen Sie keine zusätzlichen Ordner und Unterordner, die Assets enthalten. Hier ist ein Beispiel für einen falschen Export:

Beachten Sie, dass sich der Textures-Ordner außerhalb der Datasmith-Projektdateien befindet. Dies ist nicht korrekt.

Datasmith-Dateikopf

Wir (Epic Games) verwenden Kopfzeileninformationen, um nachzuvollziehen, woher die Daten stammen. Unsere Telemetrie sammelt nur Statistiken darüber, welche Arten von Dateien importiert werden und aus welcher Quelle.

Unten ist ein Beispiel für eine Kopfzeile einer Datasmith-Datei:


    <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)"/>

Unverzichtbar

Datasmith-Informationen müssen ordnungsgemäß festgelegt werden, ähnlich wie im obigen Beispiel.

Nützliche API-Aufrufe

Codebeispiel

Ein Beispiel für eine Implementierung findet sich in der folgenden Datei im Repository der Unreal Engine:

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

Statisches-Mesh-Assets

Statisches-Mesh-Assets (IDatasmithMeshElement) definieren die tatsächliche Geometrie, erscheinen jedoch nicht im Unreal- oder Twinmotion-Viewport, bis sie von Actors (IDatasmithMeshActorElement) referenziert werden. Mehrere IDatasmithMeshActorElements in einer Szene können auch auf dasselbe Statisches-Mesh-Asset verweisen.

Ein Statisches-Mesh-Asset enthält Daten für:

Flächen, Scheitelpunkte, Normalen und Glättungsmasken
UVs
Kollisionen
LODs
Scheitelpunkt-Farben
Material-IDs und Zuweisungen, usw.

Nachfolgend ist eine Beispieldatenstruktur für ein Statisches-Mesh-Asset in einer .udatasmith-Datei dargestellt:


    <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>

Unverzichtbar

Namen von statischen Meshs müssen eindeutig sein und dürfen sich zwischen aufeinanderfolgenden Exporten nicht ändern. Dies ist erforderlich, um Entitäten für nachfolgende Reimporte zu verfolgen. 3D-Anwendungen stellen in der Regel GUIDs bereit, die für diesen Zweck gut geeignet sind.
Labels von statischen Meshs müssen bereinigt, benutzerlesbar und repräsentativ für das sein, was dieses Objekt sein könnte.


Eindeutige Namen für Mesh-Assets	Benutzerlesbare Labels in der Unreal Engine

Statisches-Mesh-Assets (IDatasmithMeshElement) müssen, wo anwendbar, über Actors hinweg wiederverwendet werden (sie müssen instanziert werden).
Die Unreal Engine verwendet Linkshändige Z-oben Koordinaten und misst Dimensionen in Zentimetern, daher:
- Die Konvertierung muss auf der Exporter-Seite erfolgen.
- UV-Texturkoordinaten müssen vertikal (auf der Y-Achse) gespiegelt werden, damit wir keine negative Skalierung in der Materialkachelung verwenden müssen, um Bilder, die in der Unreal Engine gespiegelt werden, zu kompensieren.
- Die Maßstabskonvertierung und Koordinatentransformation müssen in das statische Mesh gebakt werden, anstatt auf die Actor-Transformationen angewendet zu werden.
  
  Der Maßstab ist in die Geometrie gebakt, was zu Actor-Transformationen mit einem Maßstab von 1,0 führt (im Gegensatz zu 2,54 oder 0,333).
- Mesh-Drehpunkte müssen im Mesh berechnet werden, damit sie nicht alle bei 0, 0, 0 enden.
  
  Links: Mesh-Drehpunkt mit Objekt ausgerichtet (korrekt). Rechts: Drehpunkt bei 0, 0, 0 (falsch).
- Dreiecke müssen verschweißt werden, damit Glättungsmasken und Schattierung korrekt funktionieren.
  
  Glättung, Normalen usw. sind korrekt auf der Geometrie eingestellt.

Nützlich

Zusätzliche LODs angeben.
Kollisionsmeshs angeben.
Lightmap-UV-Kanal (Auspacken) angeben.

Zu vermeiden

Namen von statischen Meshs, die nicht garantiert eindeutig und wiederholbar über Exporte hinweg sind. Keine von Benutzern festgelegten Objektnamen verwenden.
Neuskalierung von Einheiten nicht innerhalb von Actor-Transformationen speichern.
Drehpunkte nicht bei 0, 0, 0 belassen.
Nicht tausende von Statisches-Mesh-Actors exportieren, die verschweißt werden sollten. Zum Beispiel ist eine Box typischerweise ein einzelnes Mesh mit 6 Flächen, nicht 6 einzelne Meshs mit jeweils einer Fläche.

Nützliche API-Aufrufe

Codebeispiel

Ein Beispiel für eine Implementierung findet sich in der folgenden Datei im Repository der Unreal Engine:

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

Statisches-Mesh-Actors

Statisches-Mesh-Actors (IDatasmithMeshActorElements) definieren nicht die eigentliche Geometrie. Sie verweisen auf Statisches-Mesh-Assets (IDatasmithMeshElement). Beachten Sie, dass mehrere IDatasmithMeshActorElements auf dasselbe statische Mesh verweisen können.

Unten ist eine Beispiel-Datenstruktur eines Statisches-Mesh-Actors in einer .udatasmith-Datei dargestellt.


    <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>

Zwei Statisches-Mesh-Actors, die auf dasselbe Statisches-Mesh-Asset (Instanzierung) verweisen, importiert aus 3ds Max.

Unverzichtbar

Namen von Mesh-Actors müssen eindeutig sein und dürfen sich zwischen aufeinanderfolgenden Exporten nicht ändern. Dies ist erforderlich, um Entitäten für nachfolgende Reimporte zu verfolgen.
Labels von Mesh-Actors müssen bereinigt werden (d. h., sie dürfen keine ungültigen Zeichen enthalten) und für den Benutzer lesbar sein.
Statisches-Mesh-Assets (IDatasmithMeshElement) müssen, wo anwendbar, über Actors hinweg wiederverwendet werden (sie müssen instanziert werden).
Maßstabs- und Koordinatenkonvertierungen müssen ebenso wie Koordinatentransformationen in das statische Mesh gebakt werden, anstatt auf die Actor-Transformationen angewendet zu werden.

Nützlich

Ebenenspezifikation.
Unterstützung für Tags und Metadaten.

Nützliche API-Aufrufe

Codebeispiel

Ein Beispiel für eine Implementierung findet sich in der folgenden Datei im Repository der Unreal Engine:

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

Leere Actors

Leere Actors sind Actors, die keine Komponenten oder statische Meshs angekoppelt haben. Sie sind nützlich, um Metadaten zu halten oder als eine Möglichkeit, Teile einer Hierarchie darzustellen. Es gibt keine strikten Regeln darüber, wie oder wann man sie verwenden sollten. Die folgenden Richtlinien decken einige häufige Anwendungsbeispiele ab.

Richtlinien

Verwenden Sie leere Actors für:

Darstellung von Null-Objekten (zum Beispiel 3ds-Max-Hilfsobjekte).
Darstellung benutzerdefinierter Ursprungspunkte (zum Beispiel Revit-Standortpositionen).
Darstellung anderer Elemente, die die Hierarchie lesbarer machen (zum Beispiel Ebenen aus Rhino, Block-Ursprünge aus Rhino oder Levels aus Revit).
Darstellung des Kopfes eines zusammengesetzten Objekts, das keine eigene Geometrie hat (zum Beispiel Revit-Vorhangwände).

Beispiele

3ds-Max-Hilfsobjekte, die als leere Actors übersetzt wurden.

Leere Actors zur Darstellung unsichtbarer Elemente aus Revit

Nützliche API-Aufrufe

Codebeispiel

Ein Beispiel für eine Implementierung findet sich in der folgenden Datei im Repository der Unreal Engine:

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

Actor-Hierarchie

Wie viele andere 3D-Anwendungen unterstützt die Unreal Engine Parent/Child-Hierarchien.

Unten ist ein Beispiel für eine Parent/Child-Beziehung in einer .udatasmith-Datei.


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

Richtlinien

Verwenden Sie Actor-Hierarchien, um das Datenmodell Ihrer Anwendung widerzuspiegeln.

3ds-Max-Hierarchie unverändert in die Unreal Engine übersetzt.
Fügen Sie bei Bedarf zusätzliche leere Actors ein, um Informationen zu speichern, die für das Datenmodell Ihrer Anwendung relevant sind (zum Beispiel werden Revit-Levels als zusätzlicher Parent-Actor exportiert).

Revit-Ebenen, die der Hierarchie hinzugefügt werden, sind eine nützliche Möglichkeit, Endbenutzer auszurichten.

Zu vermeiden

Um sicherzustellen, dass Ihre Hierarchie für Endbenutzer leicht zu navigieren ist, verwenden Sie leere Actors als Parents von Statisches-Mesh-Actors nur dort, wo es notwendig ist. Zu viele leere Actors überladen die Hierarchie und machen es schwieriger, sie sowohl in Twinmotion als auch in der Unreal Engine zu lesen und zu verwenden.


Zu viele leere Actors.	Leere Actors nur verwendet, wenn nötig.

Nützliche API-Aufrufe

IDatasmithActorElement::AddChild

Codebeispiel

Ein Beispiel für eine Implementierung findet sich in der folgenden Datei im Repository der Unreal Engine:

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

Actors als Komponenten

In Anwendungen wie Revit oder Archicad ist es typisch, Objekte zu haben, die mehrere Unterelemente besitzen. Zum Beispiel wird eine Vorhangwand typischerweise mit Paneelen und Pfosten gebaut, und ein Geländer wird typischerweise mit Geländern und Balustern gebaut:

In Revit sind Vorhangwände und Geländer spezielle Objekte, die Unterelemente (Paneele, Pfosten, Baluster, Handläufe) enthalten.

Obwohl es möglich ist, jedes Element als individuellen Statisches-Mesh-Actor zu exportieren, führt dies dazu, dass zu viele Objekte exportiert werden und der World Outliner in der Unreal Engine übermäßig überfüllt wird, wie unten gezeigt.

Vorhangwand exportiert als ein Statisches-Mesh-Actor pro Paneel und Pfosten = viele Actors im World Outliner! Klicken Sie auf das Bild für die volle Größe.

Falls zutreffend, erwägen Sie, Unterelemente als Actor-Komponenten zu exportieren. Zum Beispiel kann ein Vorhangwandobjekt unter Verwendung der folgenden Actor- und Komponenten-Hierarchie exportiert werden:

Vorhangwandobjekt → leerer Actor.
- Paneel → Statisches-Mesh-Actor-Komponente
- Paneel → Statisches-Mesh-Actor-Komponente
- Pfosten → Statisches-Mesh-Actor-Komponente
- Pfosten → Statisches-Mesh-Actor-Komponente

Vorhangwand als ein leerer Actor exportiert, wobei jedes Paneel und jeder Pfosten als Statisches-Mesh-Actor-Komponente dargestellt wird, führt zu deutlich weniger Unordnung in der Hierarchie der Weltansicht. Klicken Sie auf das Bild für die volle Größe.

In der .udatasmith-Datei sieht die Hierarchie folgendermaßen aus:


    <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>

Richtlinien

Verwenden Sie Statisches-Mesh-Actor-Komponenten, um untergeordnete Objekte wie Vorhangwandpaneele, Baluster oder ähnliche zusammengesetzte Objekte darzustellen.
Sie müssen sowohl die Hierarchie (IDatasmithActorElement::AddChild) als auch das Komponenten-Flag (IDatasmithActorElement::SetIsAComponent) festlegen, damit dies korrekt funktioniert.

Nützliche API-Aufrufe

Codebeispiel

Ein Beispiel für eine Implementierung findet sich in der folgenden Datei im Repository der Unreal Engine:

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

Actor-Ebenen

Wie viele andere 3D-Anwendungen unterstützt die Unreal Engine das Konzept von Ebenen. Eine Ebene ist eine Actor-Eigenschaft, die angibt, wo der Actor in der visuellen Hierarchie einer Szene platziert ist.

Das folgende Beispiel zeigt eine mögliche Verwendung von Ebenen in einer .udatasmith-Datei.


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

Richtlinien

Wenn Ihre Quellanwendung Ebenen verwendet, sollten Sie diese in Ebenen in der Unreal Engine übersetzen.
Wenn Ihre Quellanwendung keine Ebenen verwendet, überlegen Sie, ob es andere Daten gibt, die Sie in Ebenen in der Unreal Engine übersetzen können. Zum Beispiel verwendet Revit keine Ebenen, sondern klassifiziert Entitäten in Kategorien.

Revit-Entitäten, die in Ebenen importiert wurden, die aus Revit-Kategorien abgeleitet sind.

Einschränkungen

Ebenennamen müssen eindeutig sein.
Die Unreal Engine unterstützt keine verschachtelten Ebenen.


Verschachtelte Ebenen in 3ds Max.	Die gleichen Ebenen, die in die Unreal Engine importiert wurden. Beachten Sie die flache Ebenenhierarchie.

Nützliche API-Aufrufe

IDatasmithActorElement::SetLayer

Codebeispiel

Ein Beispiel für eine Implementierung findet sich in der folgenden Datei im Repository der Unreal Engine:

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

Actor-Tags

Die Unreal Engine unterstützt benutzerdefinierte Tags für Actors. Datasmith verwendet Actor-Tags, um technische Informationen zu speichern, die beschreiben, wie Daten in der Quellanwendung strukturiert sind. Unreal-Engine-Benutzer können diese Actor-Tags dann verwenden, um Skriptoperationen durchzuführen, beispielsweise mit Python, Blueprint Utilities oder Visual-Dataprep.

Nachfolgend finden Sie ein Beispiel für die Verwendung von Tags bei Statisches-Mesh-Actors in einer .udatasmith-Datei, die aus 3ds Max exportiert wurde:


    <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>

Obwohl es keine strikten Regeln dafür gibt, was in die Tags eines Actors eingefügt werden soll, haben wir die Methode übernommen, Tags zu verwenden, um Informationen zu speichern, die spezifisch für die Quellanwendung sind.

Zum Beispiel haben wir im Fall von 3ds Max entschieden, die Tags zu verwenden, um Informationen über den Objekttyp (in 3ds Max), ob es Teil einer Gruppe ist oder nicht, und so weiter zu speichern.

Für Revit haben wir einen ähnlichen Ansatz übernommen, bei dem wir Informationen speichern, die die interne Struktur von Revit-Entitäten beschreiben.


Actor-Tags auf Actor-Komponenten aus Revit.	Die gleichen Ebenen, die in die Unreal Engine importiert wurden. Beachten Sie die flache Ebenenhierarchie.

Richtlinien

Stellen Sie Ihren Tags den Namen der Anwendung voran, aus der Sie importieren (zum Beispiel: Revit.TagName oder Max.TagName).
Verwenden Sie Tags, um technische Informationen darüber darzustellen, wie Daten in der Quellanwendung strukturiert sind. Um andere benutzerdefinierte Daten zu speichern, verwenden Sie stattdessen Metadaten.

Nützliche API-Aufrufe

Codebeispiel

Ein Beispiel für eine Implementierung findet sich in der folgenden Datei im Repository der Unreal Engine:

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

Metadaten

Datasmith enthält Schlüssel/Wert-Paare, die verwendet werden können, um BIM-Informationen (oder andere benutzerdefinierte Daten) auf Entitäten zu speichern.

3ds-Max-Metadaten (links) übersetzt in die Unreal Engine (rechts).

Einschränkungen

Schlüssel/Wert-Paare können nur Strings enthalten. Das bedeutet, dass Fließkommazahlen, Einheiten usw. in den String eingebettet („gebakt“) werden müssen (zum Beispiel „10 mm“).
Hierarchische Eigenschaften werden nicht unterstützt, daher müssen Sie die Hierarchie mit einem Unterstrich ( _ ) als Trennzeichen flach darstellen. Siehe das Revit-Beispiel unten, bei dem Element- und Type-Eigenschaften durch Verkettung von Textstrings gruppiert werden.

Eine simulierte flache Hierarchie mit Metadaten aus Revit.

Nützliche API-Aufrufe

Codebeispiel

Ein Beispiel für eine Implementierung findet sich in der folgenden Datei im Repository der Unreal Engine:

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

Kamera-Actors

Datasmith kann Kameras in der Unreal Engine erstellen, aber je nach Anwendungsfall möchten Sie möglicherweise Kameras aus der 3D-Anwendung exportieren oder nicht. Manchmal stellen Benutzer Kameras explizit ein (zum Beispiel 3ds Max Physical Cameras). In anderen Fällen werden Kameras aus anderen Anwendungskonzepten abgeleitet (zum Beispiel Ansichten aus Revit oder Lesezeichen aus SketchUp).

Ein Schlüsselelement, das im Hinblick auf die Unreal-Engine-Kameras zu berücksichtigen ist, ist, dass sie physikalisch basierte Eigenschaften haben, die Sie zum Zeitpunkt des Exports einstellen müssen, wie zum Beispiel:

Sensorbreite
Seitenverhältnis
Belichtungswert
Weißpunkt
Tiefenschärfe und so weiter.

Nachfolgend finden Sie eine Beispielimplementierung einer Kamera mit Tags und Eigenschaften in einer .udatasmith-Datei.


    <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>

Unreal Engine CineCameraActor.

Richtlinien

Tiefenschärfe, Belichtung und andere fotografische Effekte, die durch Nachbearbeitungseinstellungen definiert werden, sind ebenfalls optional. Diese erfordern eine enge Beziehung zwischen Beleuchtung und Kameras in der Quellanwendung, die möglicherweise im Kontext Ihres eigenen Datasmith-Exports nicht definiert ist.

Einschränkungen

Unreal-Engine-Kameras unterstützen keine verdrehten Kameras (2-Punkt-Perspektive). Zum Beispiel kann Revit „zugeschnittene“ Ansichten haben, die die Kameraperspektive verschieben, aber Datasmith (und damit auch die Unreal Engine) unterstützt diese Art der Kameratransformation nicht.

Nützliche API-Aufrufe

Codebeispiel

Ein Beispiel für eine Implementierung findet sich in der folgenden Datei im Repository der Unreal Engine:

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

Textur-Assets

In der Unreal Engine repräsentieren Texturen mehr als nur Farbinformationen. Um korrekt gesampelt zu werden und Beleuchtung und Schattierung korrekt zu beeinflussen, müssen Sie die beabsichtigte Verwendung für die Textur angeben (texturemode). Mögliche Verwendungen umfassen:

Diffuse
Specular
Normal
NormalGreenInv
Displace
Other
Bump
Ies

Wir müssen auch seinen Farbraum angeben (typischerweise Gamma-Korrektur oder sRGB), da dies einen direkten Einfluss darauf hat, wie Licht mit Materialien arbeitet (sRGB- und RGB-Kurve).

Nachfolgende sehen Sie eine Beispielimplementierung eines Textur-Assets in einer .udatasmith-Datei:


    <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>

Richtlinien

Sie müssen Ihren Farbraum (Gamma/sRGB) korrekt einstellen, basierend auf der beabsichtigten Verwendung der Textur:
- Der sRGB-Farbraum wird typischerweise für Albedo-Texturen verwendet.
- Der lineare Farbraum wird typischerweise für Normal-, Height- oder Bump-Maps verwendet.
Der Name der Textur (nicht der Dateiname) muss bereinigt sein (d. h. er darf keine ungültigen Zeichen enthalten).
Sie müssen Texturen im selben Ordner wie die restlichen Assets ablegen.

Texturen müssen im selben Ordner wie die anderen Assets exportiert werden.

Zu vermeiden

Verwenden Sie keine absoluten Pfade.
Platzieren Sie Texturen nicht in einem anderen Ordner als die restlichen Assets.
Beim Exportieren müssen Sie Texturen nicht transformieren. Der Datasmith-Importer wird Transformationen handhaben.
- Es ist nicht notwendig, Texturen mit der DatasmithCore-API in .uasset- Dateien zu konvertieren.
- Es ist nicht notwendig, Texturen neu zu formatieren, zu skalieren oder in andere Formate zu konvertieren.

Dieses Bild zeigt eine falsche Verwendung von .uasset-Dateien zur Repräsentation von Texturen.

Nützliche API-Aufrufe

Codebeispiel

Ein Beispiel für eine Implementierung findet sich in der folgenden Datei im Repository der Unreal Engine:

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

Materialien

Einfacher PBR-Export

Das folgende Beispiel zeigt, wie Texturen in eine Datasmith-Datei exportiert werden können, um ein einfaches PBR-Material zu erstellen, das eine Albedo-Karte und eine Höhenkarte enthält.

Originalmaterial in Rhino

Dieses Beispiel verwendet das folgende Material in Rhino:

Die Einstellungen des Materials sind wie folgt:


Albedo-Karte	Höhenkarte

Resultierende Datasmith-Datei

Die resultierende Datasmith-Datei wird wie folgt aussehen:


    <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>

Beachten Sie, dass die beiden Texturen oben unterschiedliche Werte für texturemode und srgb haben:

texturemode="0" und srgb="1" für die erste Textur
texturemode="6" und srgb="0" für die zweite Textur

Importiert im Unreal Editor

In der Unreal Engine wird das PBR-Diagramm des importierten Materials wie folgt aussehen:

Bild für Großansicht anklicken.

Beachten Sie, dass die Albedo-Karte auf SRGB=1 gesetzt ist und der Sampler-Typ auf Color eingestellt ist. Dies wird automatisch vom Datasmith-Importer eingerichtet und ist das Ergebnis der Einstellung der exportierten Albedo-Karte als:

texturemode="0" srgb="1"

Die Höhenkarte, die in Rhino graustufig war, wurde vom Datasmith-Importer in eine Normal-Map umgewandelt, was das Ergebnis der Einstellung der Textur ist:

texturemode="6" srgb="0"

Nützliche API-Aufrufe

IDatasmithUEPbrMaterialElement
IDatasmithTextureElement:
- SetSRGB - EDatasmithColorSpace
- SetTextureMode - EDatasmithTextureMode