Directrices del SDK de exportación de Datasmith | Unreal Engine 5.5 Documentación

Público objetivo de esta guía

Esta guía está dirigida a desarrolladores de aplicaciones 3D que quieran exportar escenas de aplicaciones de diseño de terceros a Unreal Engine usando el marco de Datasmith.

Esta guía parte de los siguientes supuestos:

Tienes conocimientos y experiencia en programación C++.
Conoces bien el desarrollo de aplicaciones 3D.
Estás desarrollando funciones para exportar modelos desde una aplicación 3D de terceros a Unreal Engine o Twinmotion.
No conoces bien el funcionamiento de Unreal Engine, pero quieres conocerlo.

Qué vas a aprender

Esta página describe una serie de directrices y prácticas recomendadas para exportar modelos 3D desde otras aplicaciones de diseño a Unreal Engine usando el SDK de Datasmith. En términos generales, describe:

La filosofía de diseño de Datasmith.
Estructuras y modelos de datos en Unreal Engine.
Directrices de experiencia de usuario para exportadores de Datasmith con listas de control separadas para cada parte importante del proceso de exportación.
Llamadas a la API y ejemplos de código útiles para diferentes casos.

Descargas y requisitos previos

Esta sección contiene:

Una lista de las descargas necesarias y dónde encontrarlas.
Un resumen de los conocimientos necesarios de Datasmith y Unreal Engine que debes tener para empezar, además de enlaces a recursos para seguir aprendiendo.

Cómo descargar Unreal Engine y el SDK de Datasmith

Si descargas y compilas Unreal Engine desde el repositorio de Unreal Engine en GitHub, incluirá el SDK de Datasmith.

Para descargar el código fuente de Unreal Engine desde GitHub, primero debes seguir los pasos descritos en esta guía para solicitar acceso al repositorio. Si no se te concede acceso, recibirás un error 404.

Tras descargar el código fuente de Unreal Engine, encontrarás el SDK de Datasmith en:

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

La carpeta Documentation contiene un proyecto de ejemplo, así como instrucciones sobre cómo configurar tu entorno de desarrollo.

Si descargas e instalas Unreal Engine desde el iniciador de Epic Games, debes descargar el SDK de Datasmith por separado desde esta carpeta en el repositorio de Unreal Engine en GitHub.

Epic Games ha desarrollado complementos de exportación de Datasmith para algunas aplicaciones de diseño, como Revit, SketchUp y 3ds Max. Puedes consultar estos complementos como ejemplos para tu propio trabajo.

Puedes acceder al código fuente de estos complementos de exportación de Datasmith en el repositorio de Epic Games en GitHub, en:

\Engine\Source\Programs\Enterprise\Datasmith\

Qué es Datasmith

Datasmith es una colección de herramientas y complementos que trae escenas preconstruidas creadas en una variedad de aplicaciones de diseño a Unreal Engine. Se diseñó para superar las limitaciones de otros formatos de archivo genéricos, como FBX u OBJ.

Datasmith puede:

Manejar mallas grandes.
Almacenar datos que usa Unreal Engine, como:
- Niveles de detalle
- Colisiones
- Luces
- Jerarquías de objetos
- Metadatos
Reformatear los archivos de textura (potencia de 2, en formatos compatibles con Unreal).

Para obtener más información sobre las características y las funciones de Datasmith, consulta la página Descripción general de Datasmith.

La exportación de datos se realiza en dos pasos:

Se analizan la aplicación de diseño y se construye una escena DatasmithScene con la API DatasmithCore.
Se exporta la escena al disco usando la API DatasmithExporter.

Para obtener más información sobre cómo usar estas API, consulta la siguiente documentación:

Modelo de datos de Unreal Engine

Antes de empezar a escribir tu exportador de Datasmith, familiarízate con cómo Unreal Engine almacena y estructura la información.

Unreal Engine funciona con proyectos. Un proyecto de Unreal Engine contiene al menos un nivel, que a su vez contiene uno o varios actores. Los actores tienen una posición, una rotación y una escala. Pueden existir en distintas capas, mostrarse u ocultarse, tener animaciones, etc.

Cada actor tiene uno o más componentes, que pueden ser:

Recursos geométricos, como mallas estáticas.
Luces.
Cámaras, etc.

Referencia de mallas estáticas Materiales maestros o instancia de material. A su vez, los recursos de material hacen referencia a los recursos de textura.

Varios actores pueden hacer referencia a una misma malla estática. Es lo que se conoce como crear instancias de la geometría.

Este diagrama ilustra la relación entre actores, componentes y distintos tipos de recursos en Unreal Engine. Haz clic en la imagen para verla a de tamaño completo.

Principios de diseño de Datasmith

Como desarrollador de complementos, debes esforzarte por garantizar una experiencia de usuario coherente, independientemente del software desde el que se exporten los datos. Así, es importante comprender y cumplir los principios de diseño de Datasmith que se describen a continuación. Estos son los principios que seguimos (el equipo de desarrolladores de Datasmith) a la hora de desarrollar nuestros propios complementos.

Tipos de complementos de Datasmith

Todos los complementos de Datasmith usan uno de los dos siguientes esquemas:

Combinación de exportador/importador. Por ejemplo, en 3ds Max, Revit y Sketchup se usa lo siguiente:
- Un complemento de exportación de Datasmith por parte del software.
- El complemento Importador de archivos de Datasmith en Unreal Engine.
Importador directo. Por ejemplo, Unreal Engine puede importar algunos formatos de archivo nativos de Rhino, Solidworks y Cinema4D.

Este diagrama ilustra los distintos procesos de trabajo de importación disponibles en Datasmith. Haz clic en la imagen para verla a de tamaño completo.

La elección del proceso de trabajo depende de cada caso.

Lógica de exportación e importación

Uno de los retos a la hora de intercambiar datos entre distintas aplicaciones es saber dónde colocar parte de la lógica. Al trasladar datos de una aplicación a otra, es posible que nos preguntemos:

¿Deberíamos exportarlo todo o dar opciones para excluir algunas entidades?
¿Se deben excluir los objetos pequeños durante la exportación? ¿Cómo definimos «pequeño»?
¿Deberíamos reducir el número de polígonos durante la exportación? ¿Deberíamos reducir la resolución de las texturas?
¿Dónde cambiamos la escala de las entidades para que coincida con las unidades y la escala?, etc.

En términos generales, nuestro enfoque es exportarlo todo de forma granular (es decir, objeto a objeto) y encargarnos de la fusión de objetos, la reducción de polígonos y otras operaciones de preparación de datos cuando los datos se importen posteriormente a Unreal Engine o Twinmotion.

Aunque no existe una regla estricta, nuestro enfoque general es que lo mejor es tener la menor cantidad posible de opciones (o ninguna) expuestas en el exportador de Datasmith y dejar que sea el usuario de Unreal Engine quien tome la mayoría de las decisiones durante la importación.

Con este enfoque, depende del usuario de Unreal o Twinmotion decidir el nivel de detalle u optimización de los datos. Dataprep en Unreal Engine es una herramienta fantástica para tomar esas decisiones.

Ejemplo de división entre operaciones internas y seleccionadas por el usuario sobre el proceso de exportación/importación de Datasmith. Haz clic en la imagen para verla a de tamaño completo.

Reimportación de datos tras cambios en el origen

Datasmith lleva los datos de diseño de diversas aplicaciones de origen a Unreal Engine, normalmente con el fin de crear visualizaciones y experiencias en tiempo real en torno a esos datos. A menudo, mientras trabajas en la creación de esas visualizaciones y experiencias en Unreal Engine, los datos de diseño o la escena que incorpora tu trabajo tienen que cambiar para cumplir nuevos requisitos o incorporar los comentarios de las partes interesadas.

Para evitar repeticiones costosas y tediosas, debes ser capaz de incorporar esos cambios previos sin perder todo el trabajo que has hecho en Unreal Editor. Con este fin, Datasmith ofrece un proceso de trabajo de reimportación que conserva todos los cambios realizados en el proyecto de Unreal Engine.

Desde la perspectiva del SDK de Datasmith, reimportar datos implica dos cosas:

Las entidades deben tener un identificador único persistente. Depender del nombre de un objeto no es una buena estrategia, ya que puede haber varios objetos con el mismo nombre.
Las entidades deben guardarse con un valor de hash que permita reimportar los datos con el mayor rendimiento posible.

Cuando se crea una entidad de Datasmith, se genera un número único en función de los datos del objeto. Por ejemplo, para determinar rápidamente si dos mallas son idénticas, puedes compararlas cara a cara usando un algoritmo costoso o puedes calcular un valor numérico basado en la cantidad de vértices, caras y UV. Comparar estos dos valores sería una forma mucho más rápida de saber si las mallas son idénticas o no.

Más adelante en esta página se describen algunos ejemplos.

Entorno e iluminación

Aunque es posible que sientas la tentación de percibir Unreal Engine como un motor de renderización y quieras exportar un modelo con todos sus ajustes de entorno (cámaras, entornos, fondos, etc.), hemos observado que, por lo general, es mejor que los usuarios de Twinmotion o Unreal Engine tomen esas decisiones artísticas después de que los datos se hayan importado al motor.

El aspecto más crucial es importar elementos del modelo (geometría, materiales, luces, metadatos). Una vez importados los datos a Unreal Engine o Twinmotion, los usuarios pueden cambiar los materiales, ajustar la iluminación y realizar otras tareas artísticas.

Directrices de experiencia de usuario para exportadores de Datasmith

Si has llegado hasta aquí, lo más probable es que hayas compilado Unreal y creado tu primer archivo de Datasmith con una pequeña aplicación. ¡Enhorabuena!

Ahora es el momento de ver las consideraciones de experiencia de usuario relacionadas con cómo deben estructurarse los datos para los usuarios finales.

Interfaz de usuario del exportador

Tal y como describimos en la sección anterior sobre los principios de diseño de Datasmith, queremos ofrecer la menor cantidad posible de opciones a la hora de exportar a Datasmith. Estos son algunos ejemplos:


Exportador de Datasmith de Revit	Diálogo de opciones de exportación en Unreal Engine

Directrices

Favorece las exportaciones WYSIWYG (lo que ves es lo que obtienes) basándote en las capacidades de visualización y filtrado de la aplicación. Por ejemplo, Revit solo exporta lo que es visible en la vista activa, mientras que SketchUp solo exporta lo que es visible en pantalla. No hay ninguna razón para inventar una experiencia de usuario completamente nueva para seleccionar y filtrar las entidades que se exportarán.
No des preferencia a ninguna opción al exportar.
Si tienes que exponer las opciones, haz que sean lo más simples posible. Toma como ejemplo el exportador de 3ds Max anterior.

Qué debes evitar

Opciones relacionadas con la preparación y las optimizaciones de los datos, como los detalles de la geometría, el filtrado por tipo de objeto, los canales UV, etc. Deben ser decisiones que tome el usuario de Unreal Engine en Unreal Engine.

Información sobre el progreso y mensajes de error

Los exportadores de Datasmith recopilan todas las entidades relevantes para transferir y reconstruir la escena en Unreal Engine. Es posible que algunas entidades no se puedan exportar. Debes informar a los usuarios si una o más entidades no se pueden exportar.

Además, algunos proyectos son muy grandes, lo que puede hacer que la exportación tarde mucho tiempo. Los usuarios deberían poder ver la información del progreso.

Estos son algunos ejemplos. Haz clic en cualquiera de las imágenes de abajo para verla a tamaño completo.

Información del progreso en 3ds Max.

Advertencias de salida en el exportador de Datasmith de Revit.

Advertencias de salida en el exportador de Datasmith de 3ds Max.

Directrices

La información del progreso debe presentarse al usuario durante la exportación.
Los usuarios deben poder cancelar el proceso de exportación de Datasmith.
Debería mostrarse un registro de mensajes de error para informar a los usuarios sobre objetos no compatibles, texturas que faltan y otros problemas.

Te resultará útil

Ciertos usuarios exigen a menudo secuencias de comandos y procesamiento por lotes. Por ejemplo, con SketchUp, 3ds Max o Revit, los usuarios pueden exportar por lotes a Datasmith usando el lenguaje nativo de programación de aplicaciones.

Qué debes evitar

No implementes diálogos modales sucesivos (ventanas con opciones de Aceptar/Cancelar) que interrumpan el proceso de exportación cada vez que se produzca un error o una advertencia.

Llamadas útiles a la API

Código de ejemplo

Para ver un ejemplo de implementación, consulta el siguiente archivo del repositorio de Unreal Engine:

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

Estructura de los archivos y carpetas exportados

Un «archivo» de Datasmith consta de dos partes:

Un archivo .udatasmith que usa una estructura de datos XML.
Una «carpeta asociada» que contiene todos los recursos asociados al archivo .udatasmith.

Carpeta asociada de ejemplo para un archivo .udatasmith

Ejemplo de archivo de exportación con su carpeta asociada.

Requisitos

Un solo archivo [nombredearchivo].udatasmith y una carpeta asociada [nombredearchivo]_Assets.
Todos los recursos relacionados se almacenan en la carpeta [nombredearchivo]_Assets.
Se hace referencia a los recursos en la estructura XML del archivo .udatasmith mediante rutas relativas.

Qué debes evitar

No hagas referencia a los recursos mediante rutas absolutas.
No crees carpetas y subcarpetas adicionales que contengan recursos. Aquí tienes un ejemplo de una exportación incorrecta:

Ten en cuenta que la carpeta Textures está fuera de los archivos del proyecto de Datasmith. No es correcto.

Encabezados de archivo de Datasmith

En Epic Games usamos la información de los encabezados para saber de dónde proceden los datos. Nuestra telemetría solo recopila estadísticas sobre qué tipos de archivos se importan y de qué origen.

A continuación se muestra el encabezado de ejemplo de un archivo de 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)"/>

Requisitos

La información de Datasmith debe configurarse correctamente, como en el ejemplo anterior.

Llamadas útiles a la API

Código de ejemplo

Para ver un ejemplo de implementación, consulta el siguiente archivo del repositorio de Unreal Engine:

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

Recursos de malla estática

Los recursos de malla estática (IDatasmithMeshElement) definen la geometría real, pero no aparecerán en el visor de Unreal o Twinmotion hasta que sean referenciados por actores (IDatasmithMeshActorElement). Varios IDatasmithMeshActorElement en una escena también pueden apuntar al mismo recurso de malla estática.

Un recurso de malla estática almacena datos para:

Caras, vértices, normales y máscaras de suavizado
UV
Colisiones
Niveles de detalle
Colores de los vértices
Identificadores y asignaciones de material, etc.

A continuación se muestra un ejemplo de estructura de datos para un recurso de malla estática en un archivo .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>

Requisitos

Los nombres de malla estática deben ser únicos y no deben cambiar entre exportaciones sucesivas. Esto es necesario para realizar un pista de las entidades en futuras reimportaciones. Las aplicaciones 3D suelen proporcionar GUID muy adecuados para este fin.
Las etiquetas de malla estática deben estar depuradas, deben ser legibles por los usuarios y representativas de lo que puede ser ese objeto.


Nombres únicos para los recursos de malla	Etiquetas legibles por el usuario en Unreal Engine

Los recursos de malla estática (IDatasmithMeshElement) deben reutilizarse en todos los actores donde corresponda (deben instanciarse).
Unreal Engine usa coordenadas a la izquierda en eje Z ascendente y mide las dimensiones en centímetros, por lo tanto:
- La conversión debe realizarse en el exportador.
- Las coordenadas de las texturas UV deben invertirse verticalmente (en el eje Y) para que no se use una escala negativa en el teselado de materiales que contrarreste las imágenes que se invierten en Unreal Engine.
- La conversión de escala y la transformación de coordenadas deben incluirse en la malla estática en lugar de aplicarse a las transformaciones del actor.
  
  La escala se ha integrado en la geometría, lo que da como resultado que las transformaciones del actor se establezcan en una escala de 1.0 (en lugar de 2.54 o 0.333).
- Los puntos de traslación de la malla deben calcularse en la malla para que no acaben todos en 0, 0, 0.
  
  Izquierda: punto de traslación de la malla alineado con el objeto (correcto). Derecha: punto de traslación en 0, 0, 0 (incorrecto).
- Los triángulos deben soldarse para que las máscaras de suavizado y el sombreado funcionen correctamente.
  
  El suavizado, las normales, etc. están correctamente definidos en la geometría.

Te resultará útil

Especificar niveles de detalle adicionales.
Especificar mallas de colisión.
Especificar el canal UV del mapa de iluminación (desenvolver).

Qué debes evitar

Nombres de malla estática que no garanticen que sean únicos y repetibles en las exportaciones. No utilices nombres de objeto especificados por el usuario.
No guardes las unidades de reescalado dentro de las transformaciones del actor.
No dejes los puntos de traslación en 0, 0, 0.
No exportes miles de actores de malla estática que deberían soldarse entre sí. Por ejemplo, una caja suele ser una sola malla con 6 caras, no 6 mallas individuales con una sola cara cada una.

Llamadas útiles a la API

Código de ejemplo

Para ver un ejemplo de implementación, consulta el siguiente archivo del repositorio de Unreal Engine:

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

Actores de malla estática

Los actores de malla estática (IDatasmithMeshActorElements) no definen la geometría real. Apuntan a recursos de malla estática (IDatasmithMeshElement). Ten en cuenta que varios IDatasmithMeshActorElement pueden hacer referencia a la misma malla estática.

A continuación se muestra un ejemplo de estructura de datos de un actor de malla estática en un archivo .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>

Dos actores de malla estática que hacen referencia al mismo recurso de malla estática (instanciación) importado de 3ds Max.

Requisitos

Los nombres de los actores de malla deben ser únicos y no deben cambiar entre exportaciones sucesivas. Esto es necesario para realizar un pista de las entidades en futuras reimportaciones.
Las etiquetas de los actores de malla deben estar depuradas (es decir, no deben contener caracteres no válidos) y deben ser legibles por los usuarios.
Los recursos de malla estática (IDatasmithMeshElement) deben reutilizarse en todos los actores donde corresponda (deben instanciarse).
Las conversiones de escala y coordenadas, así como las transformaciones de coordenadas, deben incluirse en la malla estática en lugar de aplicarse a las transformaciones del actor.

Te resultará útil

Especificación de capas.
Soporte para etiquetas y metadatos.

Llamadas útiles a la API

Código de ejemplo

Para ver un ejemplo de implementación, consulta el siguiente archivo del repositorio de Unreal Engine:

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

Actores vacíos

Los actores vacíos son actores que no tienen componentes ni mallas estáticas asociadas a ellos. Sirven para almacenar metadatos o para representar partes de una jerarquía. No hay reglas estrictas sobre cómo o cuándo usarlos. Las siguientes directrices cubren algunos ejemplos de uso común.

Directrices

Usa actores vacíos para:

Representar objetos nulos (por ejemplo, objetos auxiliares de 3ds Max).
Representar puntos de origen personalizados (por ejemplo, ubicaciones de sitios de Revit).
Representar otros elementos que hacen que la jerarquía sea más legible (por ejemplo, las capas de Rhino, los orígenes de bloques de Rhino o los niveles de Revit).
Representar la cabeza de un objeto compuesto que no tenga geometría propia (por ejemplo, los muros cortina de Revit).

Ejemplos

Objetos de ayuda de 3ds Max trasladados como actores vacíos.

Actores vacíos utilizados para representar elementos invisibles de Revit

Actores vacíos usados para representar elementos invisibles de Revit.

Llamadas útiles a la API

Código de ejemplo

Para ver un ejemplo de implementación, consulta el siguiente archivo del repositorio de Unreal Engine:

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

Jerarquía de actor

Al igual que muchas otras aplicaciones 3D, Unreal Engine es compatible con las jerarquías de elementos padre e hijo.

A continuación se muestra un ejemplo de relación entre elementos padre e hijo en un archivo .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">

Directrices

Usa jerarquías de actor para reflejar el modelo de datos de tu aplicaciones.

Jerarquía de 3ds Max trasladada a Unreal Engine en su estado actual
Inserta actores vacíos adicionales si es necesario para almacenar información relevante para el modelo de datos de tu aplicación (por ejemplo, los niveles de Revit se exportan como un actor padre adicional).

Los niveles de Revit añadidos a la jerarquía se convierten en una forma útil de orientar a los usuarios finales.

Qué debes evitar

Para que los usuarios finales puedan recorrer fácilmente tu jerarquía, usa actores vacíos como raíz de actores de malla estática solo cuando sea necesario. Demasiados actores vacíos desordenan la jerarquía y la hacen más difícil de leer y utilizar tanto en Twinmotion como en Unreal Engine.


Demasiados actores vacíos.	Los actores vacíos solo se usan cuando es necesario.

Llamadas útiles a la API

IDatasmithActorElement::AddChild

Código de ejemplo

Para ver un ejemplo de implementación, consulta el siguiente archivo del repositorio de Unreal Engine:

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

Actores como componentes

En aplicaciones como Revit o Archicad, es habitual tener objetos con varios subelementos. Por ejemplo, un muro cortina se suele construir con paneles y montantes, mientras que una barandilla se suele construir con barandillas y balaustres:

En Revit, los muros cortina y las barandillas son objetos especiales que contienen subelementos (paneles, montantes, balaustres, pasamanos).

Aunque es posible exportar cada elemento como un actor de malla estática individual, esto acaba exportando demasiados objetos y el esquematizador del esquematizador del mundo de Unreal Engine se sobrecarga, tal y como se muestra en la imagen.

Muro cortina exportado como un actor de malla estática por panel y montante = montones de actores en el esquematizador del mundo. Haz clic en la imagen para verla a de tamaño completo.

Si procede, plantéate exportar subelementos como componentes del actor. Por ejemplo, un objeto de muro cortina puede exportarse usando la siguiente jerarquía de actor y componente:

Objeto de muro cortina → actor vacío.
- Panel → componente de actor de malla estática
- Panel → componente de actor de malla estática
- Montante → Componente de actor de malla estática
- Montante → Componente de actor de malla estática

Un muro cortina exportado como actor vacío con cada panel y montante como componente de actor de malla estática reduce considerablemente el desorden en la jerarquía de la vista del mundo. Haz clic en la imagen para verla a de tamaño completo.

En el archivo .udatasmith, la jerarquía es la siguiente:


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

Directrices

Usa componentes de actor de malla estática para representar objetos hijo, como paneles de muro cortina, balaustres u objetos compuestos similares.
Debes establecer tanto la jerarquía (IDatasmithActorElement::AddChild) como el indicador del componente (IDatasmithActorElement::SetIsAComponent) para que esto funcione correctamente.

Llamadas útiles a la API

Código de ejemplo

Para ver un ejemplo de implementación, consulta el siguiente archivo del repositorio de Unreal Engine:

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

Capas de actor

Como muchas otras aplicaciones 3D, Unreal Engine es compatible con el concepto de capas. Una capa es una propiedad del actor que indica su posición en la jerarquía visual de una escena.

El siguiente ejemplo muestra un posible uso de las capas en un archivo .udatasmith.


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

Directrices

Si tu aplicación de origen usa capas, deberías trasladarlas a la sección de capas en Unreal Engine.
Si tu aplicación de origen no usa capas, analiza si hay otros datos que puedas trasladar a la sección de capas de Unreal Engine. Por ejemplo, Revit no usa capas, sino que clasifica las entidades en categorías.

Entidades de Revit importadas en capas derivadas de categorías de Revit.

Limitaciones

Los nombres de las capas deben ser únicos.
Unreal Engine no es compatible con capas anidadas.


Capas anidadas en 3ds Max.	Las mismas capas importadas en Unreal Engine. Fíjate en la jerarquía plana de las capas.

Llamadas útiles a la API

IDatasmithActorElement::SetLayer

Código de ejemplo

Para ver un ejemplo de implementación, consulta el siguiente archivo del repositorio de Unreal Engine:

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

Etiquetas de actor

Unreal Engine admite etiquetas definidas por el usuario para los actores. Datasmith usa etiquetas de actor para almacenar información técnica que describe cómo se estructuran los datos en la aplicación de origen. Después, los usuarios de Unreal Engine pueden usar estas etiquetas de actor para realizar operaciones de secuenciación, por ejemplo con Python, Blueprint Utilities o Visual Dataprep.

A continuación se muestra un ejemplo del uso de etiquetas en actores de malla estática en un archivo .udatasmith exportado desde 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>

Aunque no hay reglas estrictas sobre qué poner en las etiquetas de un actor, adoptamos la metodología de usar etiquetas para almacenar información que es específica de la aplicación de origen.

Por ejemplo, en el caso de 3ds Max, decidimos usar las etiquetas para almacenar información sobre el tipo de objeto (en 3ds Max), si forma parte de un grupo o no, etc.

Para Revit, hemos adoptado un enfoque similar en el que almacenamos información que describe la estructura interna de las entidades de Revit.


Etiquetas de actor en componentes de actor de Revit.	Las mismas capas importadas en Unreal Engine. Fíjate en la jerarquía plana de las capas.

Directrices

Prefija tus etiquetas con el nombre de la aplicación desde la que estás importando (por ejemplo: Revit.TagName o Max.TagName).
Usa etiquetas para representar información técnica sobre cómo se estructuran los datos en la aplicación de origen. Para almacenar otros datos definidos por el usuario, utiliza metadatos.

Llamadas útiles a la API

Código de ejemplo

Para ver un ejemplo de implementación, consulta el siguiente archivo del repositorio de Unreal Engine:

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

Metadatos

Datasmith contiene pares clave/valor que pueden usarse para almacenar información BIM (o cualquier otro dato personalizado ) en entidades.

Metadatos de 3ds Max (izquierda) trasladados a Unreal Engine (derecha).

Limitaciones

Los pares clave/valor solo pueden contener cadenas. Esto significa que los valores flotantes, las unidades, etc. tendrán que estar contenidos («baked») en la cadena (por ejemplo, «10 mm»).
Las propiedades jerárquicas no son compatibles, por lo que tendrás que aplanar la jerarquía con un guion bajo ( _ ) como separador. Fíjate en el siguiente ejemplo de Revit, donde las propiedades Elemento y Tipo se controlan concatenando cadenas de texto para mantener los elementos agrupados.

Una jerarquía aplanada simulada utilizando metadatos de Revit.

Llamadas útiles a la API

Código de ejemplo

Para ver un ejemplo de implementación, consulta el siguiente archivo del repositorio de Unreal Engine:

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

Actores de cámara

Datasmith puede crear cámaras en Unreal Engine, pero, dependiendo de tu caso, puede que quieras o no exportar cámaras desde la aplicación 3D. En ocasiones, los usuarios configuran las cámaras de forma explícita (por ejemplo, en el caso de las cámaras físicas de 3ds Max). Otras veces, las cámaras se derivan de otros conceptos de la aplicación (por ejemplo, las vistas de Revit o los marcadores de SketchUp).

Un elemento clave a tener en cuenta con respecto a las cámaras de Unreal Engine es que tienen características físicas que tendrás que configurar en el momento de exportar, tales como:

Ancho del sensor
Relación de aspecto
Valor de exposición
Punto blanco
Profundidad de campo, etc.

A continuación se muestra un ejemplo de implementación de una cámara con etiquetas y características en un archivo .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>

CineCameraActor de Unreal Engine.

Directrices

La profundidad de campo, la exposición y otros efectos fotográficos definidos por los ajustes de posprocesamiento también son opcionales. Esto requiere una estrecha relación entre la iluminación y las cámaras en la aplicación de origen, que puede no estar definida en el contexto de tu propia exportación de Datasmith.

Limitaciones

Las cámaras de Unreal Engine no son compatibles con cámaras oblicuas (perspectiva de 2 puntos). Por ejemplo, Revit puede tener vistas recortadas que cambiarán la perspectiva de la cámara, pero Datasmith (y, por extensión, Unreal Engine) no es compatible con este tipo de transformación de cámara.

Llamadas útiles a la API

Código de ejemplo

Para ver un ejemplo de implementación, consulta los siguientes archivos del repositorio de Unreal Engine:

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

Recursos de textura

En Unreal Engine, las texturas representan más que información sobre el color. Para poder muestrearlas e iluminar y sombrear correctamente, debes indicar el uso previsto para la textura (modo de textura). Los posibles usos son:

Difusa
Especular
Normal
Normal verde invertida
Desplazada
Otra
Rebote
Ies

También tenemos que especificar su espacio de color (normalmente, la corrección de gamma o sRGB), ya que tiene afecta directamente al funcionamiento de luz con los materiales (curva sRGB y RGB).

A continuación se muestra un ejemplo de implementación de un recurso de textura en un archivo .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>

Directrices

Debes configurar el espacio de color (gamma/sRGB) correctamente en función del uso previsto de la textura:
- El espacio de espacio de color sRGB se usa normalmente para las texturas de albedo.
- El espacio de color lineal se usa normalmente para mapas de normales, de altura o de relieve.
El nombre de la textura (no el nombre del archivo) debe estar depurado (es decir, no debe incluir ningún carácter no válido).
Debes colocar las texturas en la misma carpeta que el resto de recursos.

Las texturas deben exportarse en la misma carpeta que el resto de recursos.

Qué debes evitar

No utilices rutas absolutas.
No coloques las texturas en una carpeta diferente a la del resto de recursos.
Durante la exportación, no es necesario transformar las texturas. El importador de Datasmith se encargará de las transformaciones.
- No es necesario convertir las texturas a archivos .uasset con la API de DatasmithCore.
- No es necesario reformatear, cambiar el tamaño ni convertir texturas a diferentes formatos.

Colocación incorrecta de los archivos de textura

Esta imagen muestra un uso incorrecto de los archivos .uasset para representar texturas.

Llamadas útiles a la API

Código de ejemplo

Para ver un ejemplo de implementación, consulta el siguiente archivo del repositorio de Unreal Engine:

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

Materiales

Exportación PBR simple

El siguiente ejemplo demuestra cómo se pueden exportar texturas a un archivo de Datasmith para crear un material de PBR básico que contenga un mapa de albedo y un mapa de alturas.

Material original en Rhino

Este ejemplo utiliza los siguientes materiales en Rhino:

Los ajustes del material son los siguientes:


Mapa de albedo	Mapa de alturas

Archivo resultante de Datasmith

El archivo resultante de Datasmith tendrá este aspecto:


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

Observa que las dos texturas anteriores tienen valores distintos para texturemode y srgb:

texturemode="0" y srgb="1" para la primera textura
texturemode="6" y srgb="0" para la segunda textura

Importación en Unreal Editor

En Unreal Engine, el grafo PBR del material del importador tendrá el siguiente aspecto:

Haz clic en la imagen para verla a de tamaño completo.

Ten en cuenta que el mapa de albedo está configurado como SRGB=1 y el tipo de muestreador está configurado como Color. Esto lo configura automáticamente el importador de Datasmith y es el resultado de ajusta el mapa de albedo exportado como:

texturemode="0" srgb="1"

El mapa de alturas, que estaba en escala de grises en Rhino, ha sido convertido a un mapa normal por el importador de Datasmith, que es el resultado de ajustar la textura como:

texturemode="6" srgb="0"

Llamadas útiles a la API

IDatasmithUEPbrMaterialElement
IDatasmithTextureElement:
- SetSRGB - EDatasmithColorSpace
- SetTextureMode - EDatasmithTextureMode