À qui s'adresse ce guide ?
Ce guide s'adresse aux développeurs d'applications 3D qui souhaitent exporter des scènes d'applications de conception tierces vers l'Unreal Engine à l'aide du framework Datasmith.
Dans ce guide, nous supposons que :
- vous êtes un programmeur C++ expérimenté ;
- vous êtes familiarisé avec le développement d'applications 3D ;
- vous développez des fonctionnalités permettant d'exporter des modèles d'une application 3D tierce vers l'Unreal Engine ou Twinmotion ;
- vous n'êtes pas familiarisé avec le fonctionnement d'Unreal Engine, mais souhaitez apprendre à l'utiliser.
Ce que vous allez apprendre
Dans ce guide, nous vous fournissons une série d'instructions et de recommandations pour exporter des modèles 3D d'autres applications de conception vers l'Unreal Engine à l'aide du SDK Datasmith. D'une manière générale, il présente :
- La philosophie de conception de Datasmith.
- Les modèles et structures de données de l'Unreal Engine.
- Les instructions UX pour les exportateurs Datasmith, avec des listes de vérification distinctes pour chaque partie principale du processus d'exportation.
- Les appels d'API utiles et des exemples de code pour différents scénarios.
Téléchargements et conditions préalables
Cette section contient :
- Une liste des téléchargements requis et leur emplacement.
- Un aperçu des connaissances requises sur Datasmith et l'Unreal Engine pour vous aider à démarrer, ainsi que des liens vers des ressources pour un apprentissage plus approfondi.
Télécharger l'Unreal Engine et le SDK Datasmith
Si vous téléchargez et créez l'Unreal Engine à partir du référentiel GitHub d'Unreal Engine, le SDK Datasmith est inclus avec celui-ci.
Pour télécharger le code source d'Unreal Engine depuis GitHub, vous devez tout d'abord suivre les étapes décrites dans ce guide pour demander l'accès au référentiel. Si l'accès ne vous a pas été accordé, une erreur 404 s'affiche.
Après avoir téléchargé le code source d'Unreal Engine, le SDK Datasmith se trouve à l'emplacement suivant :
\Engine\Source\Programs\Enterprise\Datasmith\DatasmithSDK\
Le dossier Documentation
contient un échantillon de projet, ainsi que des instructions sur la façon de configurer votre environnement de développement.
Si vous téléchargez et installez l'Unreal Engine depuis le lanceur Epic Games, vous devez télécharger le SDK Datasmith séparément depuis ce dossier dans le référentiel GitHub d'Unreal Engine.
Epic Games a développé des plug-ins d'exportation Datasmith pour certaines applications de conception, telles que Revit, SketchUp et 3ds Max. Vous pouvez vous utiliser ces plug-ins comme exemples pour votre propre travail.
Vous pouvez accéder au code source de ces plug-ins d'exportation Datasmith dans le référentiel GitHub d'Epic Games, à l'emplacement suivant :
\Engine\Source\Programs\Enterprise\Datasmith\
Comprendre Datasmith
Datasmith est une collection d'outils et de plug-ins qui intègre des scènes pré-construites créées dans diverses applications de conception dans l'Unreal Engine. Ce système a été conçu pour éviter les limites que présentent d'autres formats de fichiers génériques, tels que FBX ou OBJ.
Datasmith peut :
-
gérer des maillages volumineux ;
-
stocker les données utilisées par l'Unreal Engine, telles que :
-
LOD
-
Collision
-
Lumières
-
Hiérarchie des objets
-
Métadonnées
-
-
reformater les fichiers de texture (à la puissance 2, dans les formats gérés par Unreal).
Pour en savoir plus sur les fonctionnalités de Datasmith, consultez la page Présentation de Datasmith.
L'exportation des données s'effectue en deux étapes :
-
Analysez l'application de conception et construisez une scène DatasmithScene avec l'API DatasmithCore.
-
Exportez la scène sur le disque à l'aide de l'API DatasmithExporter.
Pour savoir comment utiliser ces API, consultez la documentation suivante :
Modèle de données d'Unreal Engine
Avant de commencer à écrire votre exportateur Datasmith, familiarisez-vous avec la manière dont l'Unreal Engine stocke et structure les informations.
L'Unreal Engine est basé sur des projets. Un projet Unreal contient au moins un [niveau]((building-virtual-worlds/level-editor), lequel comporte un ou plusieurs acteurs. Les acteurs ont une position, une rotation et une échelle. Ils peuvent exister sur différentes couches, être affichés ou masqués, disposer d'animations, etc.
Chaque acteur possède un ou plusieurs composants, qui peuvent être :
-
Des ressources géométriques, telles que les maillages statiques
-
Des lumières
-
Des caméras, etc.
Référence des maillages statiques Matériaux maîtres ou instances de matériaux. À leur tour, les ressources de matériau font référence aux ressources de texture.
Un seul maillage statique peut être référencé par plusieurs acteurs. C'est ce que l'on appelle l'« instanciation géométrique ».
Ce diagramme illustre la relation entre les acteurs, les composants et divers types de ressources dans l'Unreal Engine. Cliquez sur l'image pour l'afficher à sa taille réelle.
Principes de conception de Datasmith
En tant que développeur de plug-ins, vous devez vous efforcer de garantir une expérience utilisateur cohérente, quel que soit le logiciel à partir duquel les données sont exportées. Il est donc important de comprendre et de respecter les principes de conception de Datasmith décrits ci-dessous. Ce sont les principes que suit l'équipe de développeurs de Datasmith lors du développement de leurs propres plug-ins.
Types de plug-ins Datasmith
Tous les plug-ins Datasmith utilisent l'un des deux schémas suivants :
-
Combinaison exportateur/importateur. Par exemple, 3ds Max, Revit et Sketchup utilisent :
-
Un plug-in d'exportation Datasmith côté logiciel
-
Le plug-in Importateur de fichiers Datasmith côté Unreal Engine.
-
-
L'importateur direct. Par exemple, l'Unreal Engine peut importer certains formats de fichiers natifs vers Rhino, Solidworks et Cinema4D.
Ce diagramme illustre les différents flux de travail d'importation Datasmith disponibles. Cliquez sur l'image pour l'afficher à sa taille réelle.
Le choix du flux de travail se fait au cas par cas.
Logique d'exportation et d'importation
L'un des défis que présente l'échange de données entre différentes applications est de comprendre où placer une partie de la logique. Lorsque nous traduisons des données d'une application à une autre, nous pouvons nous poser les questions suivantes :
-
Devrions-nous tout exporter ou proposer des options pour exclure certaines entités ?
-
Devrions-nous exclure les petits objets lors de l'exportation ? Qu'entend-on par « petit » ?
-
Devrions-nous réduire le nombre de polygones lors de l'exportation ? Devrions-nous diminuer les résolutions de texture ?
-
Où pouvons-nous redimensionner les entités pour qu'elles correspondent aux unités et à l'échelle ?, etc.
D'une manière générale, notre approche consiste à tout exporter de manière granulaire (c'est-à-dire, objet par objet) et à gérer la fusion des objets, la réduction des polygones et d'autres opérations de préparation des données ultérieurement, lors de leur importation dans l'Unreal Engine ou Twinmotion.
Bien qu'il n'existe pas de règle stricte, il est selon nous préférable d'exposer le moins d'options possible (voire aucune) dans l'exportateur Datasmith et de laisser l'utilisateur d'Unreal Engine prendre la plupart des décisions lors de l'importation.
Grâce à cette approche, l'utilisateur d'Unreal ou de Twinmotion décide du degré de granularité ou d'optimisation de ses données. L'outil Dataprep d'Unreal Engine est optimal pour prendre ces décisions.
Exemple de division entre les opérations internes et sélectionnées par l'utilisateur au cours du processus d'exportation/importation de Datasmith. Cliquez sur l'image pour l'afficher à sa taille réelle.
Réimporter les données après des modifications de la source
Datasmith intègre des données de conception provenant de diverses applications sources à l'Unreal Engine, généralement dans le but de créer des visualisations et des expériences en temps réel autour de ces données. Souvent, lorsque vous travaillez sur la création de ces visualisations et expériences dans l'Unreal Engine, les données de scène ou de conception que votre travail intègre doivent changer afin de répondre à de nouvelles exigences ou d'intégrer les commentaires des parties prenantes.
Pour éviter des retouches laborieuses et coûteuses, vous devez être en mesure d'intégrer ces modifications en amont sans perdre tout le travail que vous avez effectué dans l'Unreal Editor. À cette fin, Datasmith propose un flux de travail de réimportation qui préserve toutes vos modifications au sein du projet Unreal.
Du point de vue du SDK Datasmith, la réimportation des données suppose deux implications :
-
Les entités doivent avoir un identifiant unique persistant. Il est déconseillé de se fier uniquement au nom d'un objet, car plusieurs objets peuvent porter le même nom.
-
Les entités doivent être enregistrées avec une valeur de hachage permettant la réimportation des données avec les performances les plus élevées possibles.
Lors de la création d'une entité Datasmith, un numéro unique est généré en fonction des données de l'objet. Par exemple, pour déterminer rapidement si deux maillages sont identiques, vous pouvez soit les comparer à l'aide d'un algorithme chronophage, soit calculer une valeur numérique en fonction du nombre de vertex, de faces et d'UV. La comparaison de ces deux valeurs permettrait alors de savoir plus rapidement si les maillages sont identiques ou non.
Consultez les exemples plus loin sur cette page.
Environnement et éclairage
Bien que vous soyez tenté de percevoir l'Unreal Engine comme un moteur de rendu capable d'exporter un modèle avec tous ses paramètres d'environnement (caméras, environnements, arrière-plans, etc.), nous constatons qu'en général, ces décisions artistiques sont mieux prises par les utilisateurs d'Unreal Engine ou de Twinmotion une fois les données importées dans le moteur.
L'aspect le plus important est d'importer les éléments du modèle (géométrie, matériaux, lumières, métadonnées). Une fois les données importées dans l'Unreal Engine ou Twinmotion, les utilisateurs peuvent modifier les matériaux, personnaliser l'éclairage et effectuer d'autres tâches artistiques.
Instructions UX pour les exportateurs Datasmith
Si vous êtes arrivé jusqu'ici, vous avez très probablement compilé Unreal et créé votre premier fichier Datasmith à l'aide d'une petite application. Félicitations !
Il est maintenant temps d'examiner les considérations UX liées à la structuration des données pour les utilisateurs finaux.
Interface utilisateur de l'exportateur
Comme nous l'avons décrit dans la section Principes de conception de Datasmith ci-dessus, nous souhaitons offrir le moins d'options possible lors de l'exportation vers Datasmith. Voici quelques exemples :
Exportateur Datasmith depuis Revit | Boîte de dialogue Options d'exportation dans l'Unreal Engine |
Instructions
-
Privilégiez les exportations WYSIWYG (What You See Is What You Get, c'est-à-dire tel écran, tel écrit) en vous appuyant sur les fonctionnalités de visualisation et de filtrage de l'application. Par exemple, Revit exporte uniquement les éléments visibles dans la vue active, et SketchUp uniquement les éléments visibles à l'écran. Il n'y a aucune raison d'inventer une toute nouvelle UX pour sélectionner et filtrer les entités à exporter.
-
Ne privilégiez aucune option lors de l'exportation.
-
Si vous devez exposer des options, gardez-les aussi simples que possible. Reportez-vous à l'exportateur 3ds Max ci-dessus à titre d'exemple.
À éviter
Options liées à la préparation et aux optimisations des données, telles que les détails de la géométrie, le filtrage des types d'objets, les canaux UV, etc. Ces décisions doivent être prises par l'utilisateur d'Unreal Engine, dans l'Unreal Engine.
Informations de progression et messages d'erreur
Les exportateurs Datasmith collectent toutes les entités pertinentes pour le transfert et la reconstruction de la scène dans l'Unreal Engine. Il est possible que certaines entités ne puissent pas être exportées. Vous devez dans ce cas informer les utilisateurs.
De plus, certains projets étant très volumineux, l'exportation peut prendre beaucoup de temps. Les utilisateurs doivent pouvoir afficher les informations de progression.
Voici quelques exemples. Cliquez sur n'importe quelle image ci-dessous pour l'afficher à sa taille réelle.
Informations de progression dans 3ds Max.
Avertissements de sortie dans l'exportateur Revit Datasmith.
Avertissements de sortie dans l'exportateur Datasmith 3ds Max.
Instructions
-
Les utilisateurs doivent pouvoir afficher les informations de progression lors de l'exportation.
-
Les utilisateurs doivent pouvoir annuler le processus d'exportation Datasmith.
-
Un journal des messages d'erreur doit s'afficher pour informer les utilisateurs des objets non pris en charge, des textures manquantes et d'autres problèmes.
Éléments utiles
Certains utilisateurs souhaitent d'ordinaire disposer de fonctionnalités de traitement par lots et de création de scripts. Par exemple, avec SketchUp, 3ds Max ou Revit, les utilisateurs peuvent effectuer des exportations par lots vers Datasmith à l'aide du langage de script de l'application native.
À éviter
Veillez à ne pas implémenter de boîtes de dialogue modales successives (fenêtres OK/Annuler) qui interrompent le processus d'exportation chaque fois qu'une erreur ou qu'un avertissement se produit.
Appels d'API utiles
Exemple de code
Pour obtenir un exemple d'implémentation, reportez-vous au fichier suivant dans le référentiel d'Unreal Engine :
/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpExporter.cpp
Structure des fichiers et dossiers exportés
Un « fichier » Datasmith se compose de deux parties :
-
Un fichier
.udatasmith
qui fait appel à une structure de données XML. -
Un dossier lié qui contient toutes les ressources associées au fichier
.udatasmith
.

Exemple de fichier d'exportation avec son dossier associé.
Conventions à respecter
-
Vous ne devez créer qu'un seul fichier
[nomdefichier].udatasmith
et qu'un un seul dossier [nomdefichier]_Assets associé. -
Toutes les ressources associées sont stockées dans le dossier [nomdefichier]_Assets.
-
Les ressources sont référencées dans la structure XML du fichier
.udatasmith
à l'aide de chemins relatifs.
À éviter
-
Ne référencez pas les ressources à l'aide de chemins absolus.
-
Ne créez pas de dossiers et de sous-dossiers supplémentaires contenant des ressources. Voici un exemple d'exportation incorrecte :
Notez que le dossier Textures se trouve en dehors des fichiers du projet Datasmith, ce qui est incorrect.
En-tête du fichier Datasmith
Nous (Epic Games) utilisons les informations d'en-tête pour comprendre d'où proviennent les données. Notre télémétrie collecte uniquement des statistiques sur les types de fichiers importés et sur la source de ces fichiers.
Voici un exemple d'en-tête de fichier Datasmith :
<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)"/>
Conventions à respecter
Les informations Datasmith doivent être correctement définies, comme dans l'exemple ci-dessus.
Appels d'API utiles
Exemple de code
Pour obtenir un exemple d'implémentation, reportez-vous au fichier suivant dans le référentiel d'Unreal Engine :
/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpExporter.cpp
Ressources de maillage statique
Les ressources de maillage statique (IDatasmithMeshElement) définissent la géométrie actuelle, mais ne figurent pas dans le hublot d'Unreal ou de Twinmotion tant qu'elles ne sont pas référencées par les acteurs (IDatasmithMeshActorElement). Plusieurs éléments IDatasmithMeshActorElement
dans une scène peuvent également pointer vers la même ressource de maillage statique.
Une ressource de maillage statique contient des données pour :
-
Les faces, vertex, normales et masques de lissage
-
Les UV
-
Les collisions
-
Les LOD
-
Les couleurs des vertex
-
Les ID et assignations de matériaux, etc.
Voici un exemple de structure de données pour un élément de maillage statique dans un fichier .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>
Conventions à respecter
-
Les noms de maillage statique doivent être uniques et ne doivent pas changer entre les exportations successives. Veillez à respecter cette exigence afin de pouvoir effectuer un suivi des entités au cours de réimportations ultérieures. Les applications 3D fournissent généralement des GUID adaptés à cet effet.
-
Les étiquettes de maillage statique doivent être assainies, lisibles par l'utilisateur et représentatives de ce que cet objet peut être.
Noms uniques pour les ressources de maillage | Étiquettes lisibles par l'utilisateur dans l'Unreal Engine |
-
Les ressources de maillage statique (
IDatasmithMeshElement
) doivent être réutilisées dans tous les acteurs, le cas échéant (elles doivent être instanciées). -
L'Unreal Engine utilise un système de coordonnées gaucher dont l'axe Z pointe vers le haut et mesure les dimensions en centimètres ; ainsi :
-
La conversion doit être effectuée du côté de l'exportateur.
-
Les coordonnées de texture UV doivent être inversées verticalement (sur l'axe Y) afin que nous n'utilisions pas d'échelle négative dans le quadrillage des matériaux pour contrecarrer les images inversées dans l'Unreal Engine.
-
La conversion d'échelle et la transformation des coordonnées doivent être intégrées au maillage statique plutôt qu'appliquées aux transformations de l'acteur.
L'échelle est intégrée à la géométrie, ce qui entraîne des transformations d'acteur définies sur une échelle de 1.0 (par opposition à 2.54 ou 0.333).
-
Les pivots de maillage doivent être calculés dans le maillage afin qu'ils ne soient finalement pas tous définis sur 0, 0, 0.
Gauche : pivot de maillage aligné sur l'objet (correct). Droit : pivot défini sur 0, 0, 0 (incorrect)
-
Les triangles doivent être soudés pour que les masques de lissage et l'ombrage fonctionnent correctement.
Le lissage, les normales, etc., sont correctement définis sur la géométrie.
-
Éléments utiles
-
Spécifiez des LOD supplémentaires.
-
Spécifiez les maillages de collision.
-
Spécifiez le canal UV de texture de lumière (déballage).
À éviter
-
N'utilisez pas de noms de maillage statiques qui ne sont pas uniques et réutilisables dans les exportations. N'utilisez pas de noms d'objet spécifiés par l'utilisateur.
-
Ne stockez pas les unités redimensionnées dans les transformations d'acteur.
-
Ne laissez pas les pivots définis sur 0, 0, 0.
-
N'exportez pas des milliers d'acteurs de maillage statique devant être soudés. Par exemple, une boîte est généralement un maillage unique avec 6 faces, et non 6 maillages individuels avec une seule face chacun.
Appels d'API utiles
Exemple de code
Pour obtenir un exemple d'implémentation, reportez-vous au fichier suivant dans le référentiel d'Unreal Engine :
/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpExporter.cpp
Acteurs de maillage statique
Les acteurs de maillage statique (IDatasmithMeshActorElements) ne définissent pas la géométrie réelle. Ils pointent vers les ressources de maillage statique (IDatasmithMeshElement). Notez que plusieurs éléments IDatasmithMeshActorElement
peuvent référencer le même maillage statique.
Voici un exemple de structure de données d'un acteur de maillage statique dans un fichier .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>

Deux acteurs de maillage statique référençant la même ressource de maillage statique (instanciation) importée à partir de 3ds Max.
Conventions à respecter
-
Les noms des acteurs de maillage doivent être uniques et ne doivent pas changer entre les exportations successives. Veillez à respecter cette exigence afin de pouvoir effectuer un suivi des entités au cours de réimportations ultérieures.
-
Les étiquettes de l'acteur de maillage doivent être assainies (c'est-à-dire qu'elles ne doivent pas contenir de caractères non valides) et lisibles par l'utilisateur.
-
Les ressources de maillage statique (
IDatasmithMeshElement
) doivent être réutilisées dans tous les acteurs, le cas échéant (elles doivent être instanciées). -
Les conversions d'échelle et de coordonnées, ainsi que les transformations de coordonnées, doivent être intégrées au maillage statique plutôt qu'appliquées aux transformations de l'acteur.
Éléments utiles
-
Spécification de la couche.
-
Prise en charge des balises et des métadonnées.
Appels d'API utiles
Exemple de code
Pour obtenir un exemple d'implémentation, reportez-vous au fichier suivant dans le référentiel d'Unreal Engine :
/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpComponent.cpp
Acteurs vides
Les acteurs vides sont des acteurs auxquels aucun composant ou maillage statique n'est rattaché. Ils sont utiles pour contenir des métadonnées ou représenter des parties d'une hiérarchie. Il n'existe aucune règle stricte sur la façon ou le moment où vous devez les utiliser. Les instructions ci-dessous sont communes à divers exemples d'utilisation courants.
Instructions
Utilisez des acteurs vides pour :
-
représenter des objets nuls (par exemple, des objets d'aide 3ds Max) ;
-
représenter des points d'origine personnalisés (par exemple, les emplacements de sites Revit) ;
-
représenter d'autres éléments qui rendent la hiérarchie plus lisible (par exemple, les couches de Rhino, les origines des blocs Rhino ou les niveaux de Revit) ;
-
représenter la tête d'un objet composé qui n'a pas de géométrie propre (par exemple, les murs-rideaux Revit).
Exemples

Objets d'aide 3ds Max traduits en acteurs vides.

Acteurs vides utilisés pour représenter les éléments invisibles de Revit.
Appels d'API utiles
Exemple de code
Pour obtenir un exemple d'implémentation, reportez-vous au fichier suivant dans le référentiel d'Unreal Engine :
/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpComponent.cpp
Hiérarchie d'acteurs
Comme de nombreuses autres applications 3D, l'Unreal Engine prend en charge les hiérarchies parents/enfants.
Voici un exemple de relation parent/enfant dans un fichier .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">
Instructions
-
Utilisez les hiérarchies d'acteurs pour refléter le modèle de données de votre application.
Hiérarchie 3ds Max traduite telle quelle dans l'Unreal Engine.
-
Insérez des acteurs vides supplémentaires si nécessaire pour stocker des informations pertinentes pour le modèle de données de votre application (par exemple, les niveaux Revit sont exportés en tant qu'acteur parent supplémentaire).
Les niveaux Revit ajoutés à la hiérarchie deviennent un moyen utile d'orienter les utilisateurs finaux.
À éviter
Pour que les utilisateurs finaux puissent parcourir facilement votre hiérarchie, utilisez des acteurs vides comme parents d'acteurs de maillage statique uniquement lorsque cela est nécessaire. Trop d'acteurs vides encombrent la hiérarchie et la rendent plus difficile à lire et à utiliser dans Twinmotion et l'Unreal Engine.
![]() |
![]() |
---|---|
Trop d'acteurs vides. | Acteurs vides utilisés uniquement lorsque cela est nécessaire. |
Appels d'API utiles
Exemple de code
Pour obtenir un exemple d'implémentation, reportez-vous au fichier suivant dans le référentiel d'Unreal Engine :
/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpComponent.cpp
Acteurs en tant que composants
Dans des applications telles que Revit ou Archicad, les objets comportant plusieurs sous-éléments sont courants. Par exemple, un mur-rideau est généralement construit avec des panneaux et des meneaux, et une balustrade est généralement constituée de rails et de balustres :

Dans Revit, les murs-rideaux et les balustrades sont des objets spéciaux qui contiennent des sous-éléments (panneaux, meneaux, balustres, garde-fous).
Bien que vous puissiez exporter chaque élément en tant qu'acteur de maillage statique individuel, vous finissez par exporter trop d'objets, ce qui encombre l'organiseur du monde dans l'Unreal Engine, comme illustré ci-dessous.
Mur-rideau exporté en tant qu'acteur de maillage statique par panneau et meneau = trop d'acteurs dans l'organiseur du monde ! Cliquez sur l'image pour l'afficher à sa taille réelle.
Le cas échéant, envisagez d'exporter des sous-éléments en tant que composants d'acteur. Par exemple, vous pouvez exporter un objet Mur-rideau à l'aide de la hiérarchie d'acteurs et de composants suivante :
-
Objet Mur-rideau → acteur vide.
-
Panneau → Composant d'acteur de maillage statique
-
Panneau → Composant d'acteur de maillage statique
-
Meneau → Composant d'acteur de maillage statique
-
Meneau → Composant d'acteur de maillage statique
-
Un mur-rideau exporté en tant qu'acteur vide avec chaque panneau et meneau en tant que composant d'acteur de maillage statique génère un encombrement beaucoup plus faible dans la hiérarchie de l'organiseur du monde. Cliquez sur l'image pour l'afficher à sa taille réelle.
Dans le fichier .udatasmith
, la hiérarchie ressemble à ceci :
<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>
Instructions
-
Utilisez des composants d'acteur de maillage statique pour représenter des objets enfants tels que des panneaux de murs-rideaux, des balustres ou des objets composés similaires.
-
Vous devez définir à la fois la hiérarchie (IDatasmithActorElement::AddChild) et l'indicateur de composant (IDatasmithActorElement::SetIsAComponent) pour que tout fonctionne correctement.
Appels d'API utiles
Exemple de code
Pour obtenir un exemple d'implémentation, reportez-vous au fichier suivant dans le référentiel d'Unreal Engine :
/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpComponent.cpp
Couches d'acteur
Comme de nombreuses autres applications 3D, l'Unreal Engine prend en charge le concept de couches. Une couche est une propriété d'acteur qui indique où l'acteur se situe dans la hiérarchie visuelle d'une scène.
L'exemple ci-dessous illustre une utilisation possible des couches dans un fichier .udatasmith
.
<ActorMesh name="2" label="Sphere001" layer="Layer002">
...
</ActorMesh>
<ActorMesh name="3" label="Box001" layer="Layer004">
...
</ActorMesh>
Instructions
-
Si votre application source utilise des couches, vous devez les traduire en couches dans l'Unreal Engine.
-
Si votre application source n'utilise pas de couches, déterminez s'il existe d'autres données que vous pouvez traduire en couches Unreal Engine. Par exemple, Revit n'utilise pas de couches, mais classe les entités en catégories.
Entités Revit importées sur des couches dérivées de catégories Revit.
Limites
-
Les noms de couche doivent être uniques.
-
L'Unreal Engine ne prend pas en charge les couches imbriquées.
![]() |
![]() |
---|---|
Couches imbriquées dans 3ds Max. | Les mêmes couches importées dans l'Unreal Engine. Observez la hiérarchie de couches plate. |
Appels d'API utiles
Exemple de code
Pour obtenir un exemple d'implémentation, reportez-vous au fichier suivant dans le référentiel d'Unreal Engine :
/Engine/Source/Programs/Enterprise/Datasmith/DatasmithMaxExporter/Private/DatasmithMaxSceneExporter.cpp
Balises d'acteur
L'Unreal Engine prend en charge les balises définies par l'utilisateur pour les acteurs. Datasmith utilise des balises d'acteur pour contenir des informations techniques qui décrivent la manière dont les données sont structurées dans l'application source. Les utilisateurs d'Unreal Engine peuvent ensuite utiliser ces balises d'acteur pour effectuer des opérations de script, par exemple avec Python, Blueprint Utilities ou Visual Dataprep.
Voici un exemple d'utilisation de balises sur des acteurs de maillage statique dans un fichier .udatasmith
exporté depuis 3ds Max :
<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>
Bien qu'il n'existe aucune règle stricte concernant le contenu des balises d'un acteur, nous avons choisi d'utiliser des balises contenant des informations propres à l'application source.
Par exemple, dans le cas de 3ds Max, nous avons décidé d'utiliser les balises pour contenir des informations sur le type d'objet (dans 3ds Max), pour indiquer si ce type d'objet fait ou non partie d'un groupe, etc.
Pour Revit, nous avons adopté une approche similaire où nous stockons des informations qui décrivent la structure interne des entités Revit.
![]() |
![]() |
---|---|
Balises d'acteur sur les composants d'acteur de Revit. | Les mêmes couches importées dans l'Unreal Engine. Observez la hiérarchie de couches plate. |
Instructions
-
Préfixez vos balises avec le nom de l'application à partir de laquelle vous importez (par exemple : Revit.TagName ou Max.TagName).
-
Utilisez des balises pour représenter des informations techniques sur le mode de structuration des données dans l'application source. Pour stocker d'autres données définies par l'utilisateur, utilisez plutôt des métadonnées.
Appels d'API utiles
Exemple de code
Pour obtenir un exemple d'implémentation, reportez-vous au fichier suivant dans le référentiel d'Unreal Engine :
/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpComponent.cpp
Métadonnées
Datasmith propose des paires clé/valeur qui peuvent servir à stocker des informations BIM (ou toute autre donnée personnalisée) sur des entités.

Métadonnées de 3ds Max (à gauche) traduites dans l'Unreal Engine (à droite).
Limites
-
Les paires clé/valeur ne peuvent contenir que des chaînes. Autrement dit, les floats, unités, etc., doivent être contenus (« précalculés ») dans la chaîne (par exemple, « 10 mm »).
-
Les propriétés hiérarchiques n'étant pas prises en charge, vous devez aplanir la hiérarchie à l'aide d'un séparateur de trait de soulignement ( _ ). Reportez-vous à l'exemple Revit ci-dessous où les propriétés Element et Type sont gérées en concaténant des chaînes de texte pour garder les éléments groupés.

Hiérarchie aplanie simulée utilisant des métadonnées de Revit.
Appels d'API utiles
Exemple de code
Pour obtenir un exemple d'implémentation, reportez-vous au fichier suivant dans le référentiel d'Unreal Engine :
/Engine/Source/Programs/Enterprise/Datasmith/DatasmithMaxExporter/Private/DatasmithMaxSceneExporter.cpp
Acteurs de caméra
Datasmith peut créer des caméras dans l'Unreal Engine, mais, selon votre cas d'utilisation, vous pouvez ou non souhaiter exporter des caméras à partir de l'application 3D. Dans certains cas, les utilisateurs définissent explicitement les caméras (par exemple, les caméras physiques 3ds Max). Dans d'autres cas, les caméras sont dérivées d'autres concepts d'application (par exemple, des vues de Revit ou des signets de SketchUp).
L'un des éléments clés à prendre en compte concernant les caméras de l'Unreal Engine est qu'elles ont des caractéristiques physiques que vous devrez définir au moment de l'exportation, telles que :
-
Largeur du capteur
-
Proportions
-
Valeur d'exposition
-
Point blanc
-
Profondeur de champ, etc.
Voici un exemple d'implémentation d'une caméra avec des balises et des caractéristiques dans un fichier .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>

Acteur caméra de cinéma d'Unreal Engine.
Instructions
La profondeur de champ, l'exposition et d'autres effets photographiques définis par les paramètres de post-traitement sont également facultatifs. Ces éléments nécessitent une relation étroite entre l'éclairage et les caméras dans l'application source, qui peut ne pas être définie dans le contexte de votre propre exportation Datasmith.
Limites
- Les caméras de l'Unreal Engine ne prennent pas en charge les caméras inclinées (perspective à 2 points). Par exemple, Revit peut avoir des vues « rognées » qui changent la perspective de la caméra ; or, Datasmith (et, par extension, l'Unreal Engine) ne prend pas en charge ce type de transformation de caméra.
Appels d'API utiles
Exemple de code
Pour obtenir un exemple d'implémentation, reportez-vous au fichier suivant dans le référentiel d'Unreal Engine :
-
/Engine/Source/Programs/Enterprise/Datasmith/DatasmithMaxExporter/Private/DatasmithMaxCameraExporter.cpp
-
/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpCamera.cpp
Ressources de texture
Dans l'Unreal Engine, les textures représentent plus que de simples informations de couleur. Pour échantillonner correctement les textures et veiller à ce qu'elles affectent correctement l'éclairage et l'ombrage, vous devez indiquer leur utilisation prévue (texturemode). Les utilisations possibles sont les suivantes :
-
Diffuse
-
Spéculaire
-
Normale
-
NormalGreenInv
-
Déplacement
-
Autre
-
Relief
-
Ies
Vous devez également spécifier son espace colorimétrique (généralement la correction gamma ou sRVB), qui a un impact direct sur la relation entre la lumière et les matériaux (courbe sRVB et RVB).
Voici un exemple d'implémentation d'une ressource de texture dans un fichier .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>
Instructions
-
Vous devez définir correctement votre espace colorimétrique (gamma/sRVB), en fonction de l'utilisation prévue de la texture :
-
L'espace colorimétrique sRVB est généralement utilisé pour les textures Albédo.
-
L'espace colorimétrique linéaire est généralement utilisé pour les textures de normale, de hauteur ou de relief.
-
-
Le nom de la texture (et non le nom du fichier) doit être assaini (c'est-à-dire qu'il ne doit inclure aucun caractère non valide).
-
Vous devez placer les textures dans le même dossier que les autres ressources.
Les textures doivent être exportées dans le même dossier que les autres ressources.
À éviter
-
N'utilisez pas de chemins absolus.
-
Ne placez pas les textures dans un dossier différent des autres ressources.
-
Lors de l'exportation, il est inutile de transformer les textures. L'importateur Datasmith se charge des transformations.
-
Il n'est pas nécessaire de convertir les textures en fichiers .uasset avec l'API DatasmithCore.
-
Il n'est pas nécessaire de reformater, de redimensionner ou de convertir les textures en différents formats.
-

Cette image illustre une utilisation incorrecte des fichiers .uasset pour représenter les textures.
Appels d'API utiles
Exemple de code
Pour obtenir un exemple d'implémentation, reportez-vous au fichier suivant dans le référentiel d'Unreal Engine :
/Engine/Source/Programs/Enterprise/Datasmith/DatasmithSketchUpRubyExporter/Private/DatasmithSketchUpMaterial.cpp
Matériaux
Exportation RPR simple
Dans l'exemple suivant, nous vous expliquons comment exporter les textures vers un fichier Datasmith pour créer un matériau RPR de base contenant une texture d'albédo et une texture de hauteur.
Matériau original dans Rhino
Dans cet exemple, nous utilisons le matériel suivant dans Rhino :

Les paramètres du matériau sont les suivants :
![]() |
![]() |
---|---|
Texture d'albédo | Texture de hauteur |
Fichier Datasmith généré
Le fichier Datasmith généré est similaire à celui-ci :
<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>
Notez que les deux textures ci-dessus ont des valeurs différentes pour texturemode
et srgb
:
texturemode="0"
etsrgb="1"
pour la première texturetexturemode="6"
etsrgb="0"
pour la deuxième texture
Importer dans l'Unreal Editor
Dans l'Unreal Engine, le graphique RPR de l'importateur de matériau est similaire à celui-ci :
Cliquez sur l'image pour l'afficher à taille réelle.
Notez que la texture d'albédo est définie sur SRGB=1
et que le type d'échantillonneur est défini sur Color
. Ces paramètres sont automatiquement configurés par l'importateur Datasmith et sont le résultat de la définition de la texture d'albédo exportée comme suit :
texturemode="0" srgb="1"
La texture de hauteur, qui était en niveaux de gris dans Rhino, a été convertie en texture de normales par l'importateur Datasmith, qui est le résultat de la définition de la texture comme suit :
texturemode="6" srgb="0"
Appels API utiles
- IDatasmithUEPbrMaterialElement
-
-
SetSRGB - EDatasmithColorSpace
-
SetTextureMode - EDatasmithTextureMode
-