Diretrizes do SDK de exportação do Datasmith | Unreal Engine 5.5 Documentação

Público-alvo deste guia

Este guia é destinado a desenvolvedores de aplicativos 3D que desejam exportar cenas de aplicativos de design de terceiros para a Unreal Engine usando o framework Datasmith.

Este guia parte das seguintes suposições:

Você é um programador experiente em C++.
Você tem familiaridade com o desenvolvimento de aplicativos 3D.
Você está desenvolvendo a funcionalidade para exportar modelos de um aplicativo 3D de terceiros para a Unreal Engine ou o Twinmotion.
Você não tem familiaridade com o funcionamento da Unreal Engine, mas tem interesse em aprender.

Aprendizados

Esta página descreve uma série de diretrizes e práticas recomendadas para exportar modelos 3D de outros aplicativos de design para a Unreal Engine usando o Datasmith SDK. De modo geral, explica:

A filosofia de design do Datasmith.
Modelos e estruturas de dados na Unreal Engine.
Diretrizes do Datasmith, com listas de verificação separadas para cada parte principal do processo de exportação.
Chamadas de API e exemplos de código úteis para diferentes cenários.

Downloads e pré-requisitos

Esta seção contém:

Uma lista de downloads necessários e onde encontrá-los.
Uma visão geral do conhecimento necessário em Datasmith e Unreal Engine para começar, além de links para recursos para aprender mais.

Como baixar a Unreal Engine e o SDK do Datasmith

Se você baixar e compilar a Unreal Engine a partir do repositório GitHub da Unreal Engine , o SDK do Datasmith estará incluído.

Para baixar o código-fonte da Unreal Engine pelo GitHub, primeiro siga as etapas descritas neste guia para solicitar acesso ao repositório. Se você não tiver acesso, receberá um erro 404.

Após baixar o código-fonte da Unreal Engine, você encontrará o SDK do Datasmith em:

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

A pasta "Documentation" contém um projeto de amostra e instruções sobre como configurar o ambiente de desenvolvimento.

Se você baixar e instalar a Unreal Engine pelo inicializador da Epic Games , baixe o SDK do Datasmith separadamente nesta pasta no repositório GitHub da Unreal Engine.

A Epic Games desenvolveu plugins de exportação via Datasmith para alguns aplicativos de design, como Revit, SketchUp e 3ds Max. Você pode consultar esses plugins como exemplos para o seu trabalho.

Você pode acessar o código-fonte desses plugins de exportação do Datasmith no repositório GitHub da Epic Games, em:

\Engine\Source\Programs\Enterprise\Datasmith\

Entendendo o Datasmith

O Datasmith é uma coleção de ferramentas e plugins que trazem para a Unreal Engine cenas pré-compiladas criadas em diversos aplicativos de design. Foi projetado para superar as limitações de outros formatos de arquivo genéricos, como FBX ou OBJ.

O Datasmith é capaz de:

Lidar com malhas grandes.
Armazenar dados usados pela Unreal Engine, como:
- LODs
- Colisão
- Luzes
- Hierarquia de objeto
- Metadados
Arquivos de textura reformatados (elevado à potência de 2, para formatos suportados pela Unreal).

Para saber mais sobre os recursos e a funcionalidade do Datasmith, confira a página Visão geral do Datasmith.

A exportação de dados ocorre em duas etapas:

Analisar o aplicativo de design e compilar um DatasmithScene com a API DatasmithCore.
Exportar a cena para o disco usando a API DatasmithExporter.

Para aprender a usar essas APIs, confira a seguinte documentação:

Modelo de dados da Unreal Engine

Antes de começar a gravar o Datasmith Exporter, familiarize-se com o armazenamento e a estrutura das informações na Unreal Engine.

A Unreal Engine trabalha com projetos. Um projeto da Unreal contém pelo menos um Nível, que contém um ou mais atores. Os atores têm uma posição, uma rotação e um redimensionamento. Eles podem existir em diferentes camadas, ser exibidos ou ocultos, ter animações e assim por diante.

Cada ator tem um ou mais componentes, que podem ser:

Ativos geométricos, como [malhas estáticas]understanding-the-basics/actors/actors-reference/static-mesh-actors).
Luzes.
Câmeras e assim por diante.

Referência de malhas estáticas materiais-base ou instâncias de material . Por sua vez, os ativos de material referência a ativos de textura.

Uma única malha estática pode ser referenciada por vários atores. Isso se chama instanciação de geometria.

Este diagrama ilustra a relação entre atores, componentes e vários tipos de ativos na Unreal Engine. Clique na imagem para ver em tamanho grande.

Princípios de design do Datasmith

Como desenvolvedor de plugin, você deve se esforçar para garantir uma experiência do usuário consistente, independentemente do software do qual os dados estão sendo exportados. Por isso, é importante entender e seguir os princípios de design do Datasmith descritos a seguir. Estes são os princípios que nós (a equipe de desenvolvedor do Datasmith) usamos ao desenvolver nossos próprios plugins.

Tipos de plugin do Datasmith

Todos os plugins Datasmith usam um dos dois esquemas a seguir:

Combinação de exportador/importador. Por exemplo, 3ds Max, Revit e Sketchup usam:
- Um plugin do Datasmith Exporter para software.
- Plugin de importador de arquivo do Datasmith para a Unreal Engine.
Importador direto. Por exemplo, a Unreal Engine pode importar alguns formatos de arquivo nativos para Rhino, Solidworks e Cinema4D.

Este diagrama ilustra os vários fluxos de trabalho de importação do Datasmith disponíveis. Clique na imagem para ver em tamanho grande.

A escolha do fluxo de trabalho de trabalho a ser usado varia de acordo com o caso.

Lógica de exportação e importação

Um dos desafios da troca de dados entre diferentes aplicativos é entender onde colocar um pouco da lógica. Quando transladar dados de um aplicativo para outro, podemos nos perguntar:

Devemos exportar tudo ou fornecer opções para excluir algumas entidades?
Devemos excluir objetos pequenos ao exportar? Como definimos "pequeno"?
Devemos reduzir o número de polígonos ao exportar? Devemos reduzir as resoluções das texturas?
Onde redimensionamos entidades para corresponder a unidades e escala? E assim por diante.

De modo geral, nossa abordagem é exportar tudo de forma granular (ou seja, objeto por objeto) e lidar com a mesclagem de objetos, redução de polígonos e outras operações de preparação de dados quando os dados forem importados posteriormente para a Unreal Engine ou o Twinmotion.

Embora não haja uma regra rígida, nossa abordagem geral é que é melhor ter o mínimo de opções (ou nenhuma) expostas no Datasmith Exporter e deixar que o usuário da Unreal Engine tome a maior parte das decisões durante a importação.

Com essa abordagem, cabe ao usuário da Unreal ou do Twinmotion decidir até que ponto seus dados serão detalhados ou otimizados. O Dataprep da Unreal Engine é uma ótima ferramenta para tomar essas decisões.

Exemplo de divisão entre operações internas e operações selecionadas pelo usuário durante o processo de exportação/importação do Datasmith. Clique na imagem para ver em tamanho grande.

Como reimportar dados após alterações na fonte

O Datasmith traz dados de design de vários aplicativos de origem para a Unreal Engine, geralmente com a finalidade de criar visualizações e experiências em tempo real com base nesses dados. Muitas vezes, enquanto você trabalha na criação dessas visualizações e experiências na Unreal Engine, os dados de cena ou design que seu trabalho incorpora precisam mudar para atender a novos requisitos ou incorporar o feedback das partes interessadas.

Para evitar retrabalhos penosos e caros, você precisa ser capaz de incorporar essas alterações sem perder todo o trabalho que fez no Unreal Editor. Para isso, o Datasmith oferece um fluxo de trabalho de trabalho de reimportação que preserva todas as alterações feitas no projeto da Unreal.

Da perspectiva do SDK do Datasmith, reimportar dados implica em duas coisas:

As entidades devem ter um identificador único persistente. Basear-se no nome de um objeto não é uma boa estratégia, pois vários objetos podem ter o mesmo nome.
As entidades devem ser salvas com um valor de hash que permita a reimportação de dados com o melhor desempenho possível.

Quando uma entidade do Datasmith é criada, um número exclusivo é gerado com base nos dados do objeto. Por exemplo, para determinar rapidamente se duas malhas são idênticas, você pode compará-las diretamente usando um algoritmo longo ou pode calcular um valor numérico com base no número de vértices, faces e UV. Comparar esses dois valores seria uma maneira muito mais rápida de dizer se as malhas são idênticas ou não.

Os exemplos são descritos mais adiante nesta página.

Ambiente e iluminação

Embora você possa ficar tentado a ver a Unreal como uma engine de renderização e esperar exportar um modelo com todas as configurações de ambiente (câmeras, ambientes, planos de fundo etc.), descobrimos que, em geral, essas decisões artísticas são melhores feitas pela Unreal Engine ou os usuários do Twinmotion após a importação dos dados na engine.

O aspecto mais importante é importar os elementos do modelo (geometria, materiais, luzes, metadados). Depois que os dados forem importados para a Unreal Engine ou o Twinmotion, os usuários podem alterar materiais, ajustar a iluminação e realizar outras tarefas artísticas.

Diretrizes de UX para exportadores do Datasmith

Se você chegou até aqui, é provável que tenha compilado a Unreal e criado seu primeiro arquivo Datasmith com um pequeno aplicativo. Parabéns!

Agora é hora de ver as considerações de UX relacionadas a como os dados devem ser estruturados para usuários finais.

Interface de usuário do exportador

Como descrevemos na seção "Princípios de design do Datasmith" acima, queremos oferecer o mínimo de opções ao exportar para o Datasmith. Veja alguns exemplos:


Datasmith Exporter do Revit	Caixa de diálogo de opções de exportação na Unreal Engine

Diretrizes

Favoreça exportações WYSIWYG (What You See Is What You Get) contando com as capacidades de visualização e filtragem do aplicativo. Por exemplo, o Revit exporta apenas o que está visível na visualização ativa, e o SketchUp exporta apenas o que está visível na tela. Não há motivo para inventar uma UX totalmente nova para selecionar e filtrar entidades a serem exportadas.
Não favoreça nenhuma opção ao exportar.
Se precisar expor opções, use-as o mais simples possível. Consulte o exemplo do exportador do 3ds Max acima.

Evitar

Opções relacionadas à preparação de dados e otimizações, como detalhes de geometria, filtragem de tipo de objeto, canais UV etc. Essas devem ser decisões feitas pelo usuário da Unreal Engine na Unreal Engine.

Informações de progresso e mensagens de erro

Os exportadores do Datasmith coletam todas as entidades relevantes para transferir e reconstruir a cena na Unreal Engine. É possível que algumas entidades não possam ser exportadas. Você deve informar aos usuários se uma ou mais entidades não podem ser exportadas.

Além disso, alguns projetos são muito grandes, o que pode tornar a exportação muito demorada. Os usuários devem poder ver as informações de progresso.

Veja alguns exemplos. Clique em qualquer imagem abaixo para ver em tamanho grande.

Informações de progresso no 3ds Max.

Avisos de saída no Datasmith Exporter do Revit.

Avisos de saída no Datasmith 3ds Max Exporter.

Diretrizes

As informações do progresso precisam ser apresentadas ao usuário durante a exportação.
Os usuários precisam poder cancelar o processo de exportação do Datasmith .
Um log de mensagem de erro deve ser exibido para informar os usuários sobre objetos não compatíveis, texturas ausentes e outros problemas.

Dicas úteis

Alguns usuários geralmente exigem processamento em lote e scripts. Por exemplo, com SketchUp, 3ds Max ou Revit, os usuários podem exportar em lote para o Datasmith usando a linguagem de programação nativa do aplicativo.

Evitar

Não implemente caixas de diálogo modais sucessivas (janelas OK/Cancelar) que interrompem o processo de exportação sempre que ocorrer um erro ou aviso.

Chamadas de API úteis

Exemplo de código

Para obter um exemplo de implementação, consulte o seguinte arquivo no repositório da Unreal Engine:

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

Estrutura de pastas e arquivos exportados

Um "arquivo" do Datasmith é formado por duas partes:

Um arquivo ".udatasmith" que usa uma estrutura de dados XML.
Uma "pasta secundária" (pasta associada) que contém todos os ativos associados ao arquivo ".udatasmith".

Exemplo de pasta secundária para um arquivo .udatasmith

Arquivo de exportação de exemplo com a pasta associada.

Indispensável

Um único arquivo "[filename].udatasmith" e uma pasta [filename]_Assets associada.
Todos os ativos relacionados são armazenados na pasta [filename]_Assets.
Os ativos são referenciados na estrutura XML do arquivo ".udatasmith" usando caminhos relativos.

Evitar

Não faça referência aos ativos por caminhos absolutos.
Não crie pastas e subpastas adicionais que contenham ativos. Este é um exemplo de uma exportação incorreta:

Observe que a pasta "Textures" está fora dos arquivos do projeto Datasmith . Isso está incorreto.

Cabeçalho do arquivo do Datasmith

Nós (Epic Games) usamos as informações do cabeçalho para entender de onde os dados vêm. A telemetria só coleta estatísticas sobre os tipos de arquivo importados e de qual fonte vieram.

Este é um exemplo de cabeçalho de um arquivo 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)"/>

Indispensável

As informações do Datasmith devem estar definidas corretamente, como no exemplo acima.

Chamadas de API úteis

Exemplo de código

Para obter um exemplo de implementação, consulte o seguinte arquivo no repositório da Unreal Engine:

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

Ativos de malha estática

Ativos de Malha Estática (IDatasmithMeshElement) definem a geometria real, mas não aparecerão na janela de visualização da Unreal ou do Twinmotion até que sejam referenciados por atores (IDatasmithMeshActorElement). Vários "IDatasmithMeshActorElement" em uma cena também podem apontar para o mesmo ativo de malha estática.

Um ativo de malha estática contém dados para:

Faces, vértices, normais e máscaras de suavização
UV
Colisões
LODs
Cores do vértice
IDs e atribuições de material etc.

Este é um exemplo de estrutura de dados para um ativo de malha estática em um arquivo ".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>

Indispensável

Os nomes das malhas estáticas devem ser únicos e não podem ser alterados entre exportações sucessivas. Necessário para rastrear entidades para reimportações subsequentes. Os aplicativos 3D geralmente fornecem GUIDs adequados para essa finalidade.
Os rótulos de malha estática devem ser limpos, legíveis pelo usuário e representativos do que o objeto pode ser.


Nomes exclusivos para ativos de malha	Etiquetas legíveis pelo usuário na Unreal Engine

Os ativos de malha estática ("IDatasmithMeshElement") devem ser reutilizados entre atores quando aplicável (eles devem ser instanciados).
A Unreal Engine usa coordenadas z para cima para canhotos e mede as dimensões em centímetros, por isso:
- A conversão deve ser feita no lado do exportador.
- As coordenadas de textura UV devem ser invertidas verticalmente (no eixo Y) para não usarmos uma escala negativa no ladrilhamento do material de modo a neutralizar a inversão de imagens na Unreal Engine.
- A conversão de escala e a transformação de coordenadas devem ser incorporadas à malha estática em vez de aplicadas às transformações de ator.
  
  A escala é incorporada na geometria, resultando em transformações de ator definidas para uma escala de 1.0 (em vez de 2.54 ou 0.333)
- Os pivôs da malha devem ser calculados na malha para que não terminem todos em 0, 0, 0.
  
  Esquerda: pivô da malha alinhado ao objeto (corrigido). Direita: pivô em 0, 0, 0 (incorreto)
- Os triângulos devem ser soldados para que as máscaras de suavização e o sombreamento funcionem corretamente.
  
  Suavizações, normais etc. estão definidas corretamente na geometria.

Dicas úteis

Especifique LODs adicionais.
Especifique malhas de colisão.
Especifique o canal UV do mapa de iluminação de iluminação (descompactar).

Evitar

Nomes de malha estática que não têm garantia de serem exclusivos e repetíveis nas exportações. Não use nomes de objetos especificados pelo usuário.
Não armazene unidades redimensionadas em transformações de ator.
Não deixe os pivôs em 0, 0, 0.
Não exporte milhares de atores de malha estática que devem ser soldados. Por exemplo, um Box costuma ser uma única malha com seis faces, e não seis malhas individuais com uma única face cada.

Chamadas de API úteis

Exemplo de código

Para obter um exemplo de implementação, consulte o seguinte arquivo no repositório da Unreal Engine:

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

Atores de malha estática

Atores de malha estática (IDatasmithMeshActorElements) não definem a geometria real. Eles apontam para ativos de malha estática (IDatasmithMeshElement). Observe que vários "IDatasmithMeshActorElements" podem referência à mesma malha estática.

Este é um exemplo de estrutura de dados de um ator de malha estática em um arquivo ".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>

Dois atores de malha estática referenciando o mesmo recurso de malha estática (instanciamento) importado do 3ds Max.

Dois atores de malha estática que fazem referência ao mesmo ativo de malha estática (instanciamento) importado do 3ds Max.

Indispensável

Os nomes** dos atores de malha devem ser únicos e não podem ser alterados entre exportações sucessivas. Necessário para rastrear entidades para reimportações subsequentes.
Os rótulos de ator de malha devem ser limpos (ou seja, não podem conter caracteres inválidos) e legíveis pelo usuário.
Os ativos de malha estática ("IDatasmithMeshElement") devem ser reutilizados entre atores quando aplicável (eles devem ser instanciados).
As conversões de escala e coordenadas, bem como as transformações de coordenadas, devem ser incorporadas à malha estática em vez de aplicadas às transformações de ator.

Dicas úteis

Especificação de camada.
Suporte para tags e metadados.

Chamadas de API úteis

Exemplo de código

Para obter um exemplo de implementação, consulte o seguinte arquivo no repositório da Unreal Engine:

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

Atores vazios

Atores vazios são atores que não têm componentes ou malhas estáticas anexados a eles. São úteis para armazenar metadados ou representar partes de uma hierarquia. Não há regras rígidas sobre como ou quando você deve usá-los. As diretrizes a seguir abordam alguns exemplos de uso comuns.

Diretrizes

Use atores vazios para:

Representar objetos nulos (por exemplo, objetos auxiliares do 3ds Max).
Representar pontos de origem personalizados [por exemplo, posições de local no Revit).
Representar outros elementos que tornam a hierarquia mais legível (por exemplo, camadas do Rhino, origens de blocos do Rhino ou níveis do Revit).
Representar a cabeça de um objeto composto sem geometria própria (por exemplo, paredes com cortinas do Revit ).

Exemplos

Objetos auxiliares do 3ds Max transladados como atores vazios.

Atores vazios usados para representar elementos invisíveis do Revit.

Chamadas de API úteis

Exemplo de código

Para obter um exemplo de implementação, consulte o seguinte arquivo no repositório da Unreal Engine:

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

Hierarquia de ator

Como muitos outros aplicativos 3D, a Unreal Engine é compatível com hierarquias pai/filho.

Este é um exemplo de relação pai/filho em um arquivo ".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">

Diretrizes

Use hierarquias de ator para refletir o modelo de dados do seu aplicativo.

Hierarquia do 3ds Max transladada como está na Unreal Engine.
Se necessário, insira outros atores vazios para armazenar informações relevantes ao modelo de dados do aplicativo (por exemplo, níveis do Revit são exportados como um ator-pai adicional).

Níveis do Revit adicionados à hierarquia se tornam uma maneira útil de orientar os usuários finais.

Evitar

Para facilitar a navegação na hierarquia para os usuários finais, use atores vazios como pais de atores de malha estática apenas quando necessário. Muitos atores vazios sobrecarregam a hierarquia, a leitura e o uso tanto no Twinmotion quanto na Unreal Engine.

!Excesso de atores](too-many-empty-actors.png)
Muitos atores vazios.	Atores vazios usados somente quando necessário.

Chamadas de API úteis

IDatasmithActorElement::AddChild

Exemplo de código

Para obter um exemplo de implementação, consulte o seguinte arquivo no repositório da Unreal Engine:

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

Atores como componentes

Em aplicativos como Revit ou Archicad, é comum ter objetos que possuem vários subelementos. Por exemplo, uma parede com cortina é construída com painéis e fasquias, e um parapeito é construído com corrimãos e balaústres:

Paredes com cortina e parapeitos no Revit

No Revit, paredes com cortinas e parapeitos são objetos especiais que contêm subelementos (painéis, fasquias, balaústres, corrimãos).

Embora seja possível exportar cada elemento como um ator de malha estática individual, isso acaba exportando muitos objetos, e o organizador de mundo da Unreal Engine fica muito cheio, como mostrado a seguir.

Parede com cortina exportada como um ator de StaticMesh através de painel e fasquia = muitos atores no organizador de mundo! Clique na imagem para ver em tamanho grande.

Se aplicável, considere exportar subelementos como componentes de ator. Por exemplo, um objeto de parede com cortina pode ser exportado usando a seguinte hierarquia de ator e componente :

Objeto de parede com cortina → Ator vazio.
- Painel → Componente de ator de malha estática
- Painel → Componente de ator de malha estática
- Mullion → Componente de ator de malha estática
- Mullion → Componente de ator de malha estática

A exportação de paredes com cortinas como um ator vazio com cada painel e fasquia vertical como um componente de ator de malha estática resulta em um acúmulo consideravelmente menor na hierarquia da visualização do mundo. Clique na imagem para ver em tamanho grande.

No arquivo ".udatasmith", a hierarquia se parece com isso:


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

Diretrizes

Use componentes de ator de malha estática para representar objetos-filho, como painéis de parede com cortina, balaústres ou objetos compostos semelhantes.
Você deve definir a hierarquia (IDatasmithActorElement::AddChild) e o sinalizador de componente (IDatasmithActorElement::SetIsAComponent) para que isso funcione corretamente.

Chamadas de API úteis

Exemplo de código

Para obter um exemplo de implementação, consulte o seguinte arquivo no repositório da Unreal Engine:

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

Camadas de ator

Como muitos outros aplicativos 3D, a Unreal Engine é compatível com o conceito de camadas. Uma camada é uma propriedade de ator que indica onde o ator se encaixa na hierarquia visual de uma cena.

O exemplo a seguir mostra um possível uso de camadas em um arquivo ".udatasmith".


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

Diretrizes

Se o aplicativo de origem usar camadas, você deve transladá-las para camadas na Unreal Engine.
Se o aplicativo de origem não usar camadas, verifique se há outros dados que você pode transladar em camadas da Unreal Engine . Por exemplo, o Revit não usa camadas, mas classifica as entidades em categorias.

Entidades do Revit importadas em camadas derivadas de categorias do Revit.

Limitações

Os nomes das camadas devem ser exclusivos.
A Unreal Engine não é compatível com camadas aninhadas.


Camadas aninhadas no 3ds Max.	As mesmas camadas importadas na Unreal Engine. Observe a hierarquia de camada plana.

Chamadas de API úteis

IDatasmithActorElement::SetLayer

Exemplo de código

Para obter um exemplo de implementação, consulte o seguinte arquivo no repositório da Unreal Engine:

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

Tags de ator

A Unreal Engine é compatível com tags definidas pelo usuário para atores. O Datasmith usa tags de ator para armazenar informações técnicas que descrevem como os dados são estruturados no aplicativo de origem. Os usuários da Unreal Engine podem usar essas tags de ator para realizar operações de script, por exemplo, com Python, funções de Blueprint ou Dataprep visual.

O exemplo a seguir mostra o uso de tags em atores de malha estática em um arquivo ".udatasmith" exportado do 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>

Embora não haja regras rígidas sobre o que colocar nas tags de um ator, adotamos a metodologia de usar tags para conter informações específicas ao aplicativo de origem.

Por exemplo, no caso do 3ds Max, decidimos usar as tags para conter informações sobre o tipo de objeto (no 3ds Max), se faz parte ou não de um grupo e assim por diante.

Para o Revit, adotamos uma abordagem semelhante, armazenando informações que descrevem a estrutura interna das entidades do Revit.


Tags de ator em componentes de ator do Revit.	As mesmas camadas importadas na Unreal Engine. Observe a hierarquia de camada plana.

Diretrizes

Use como prefixo nas tags o nome do aplicativo do qual está importando (por exemplo: Revit.TagName or Max.TagName).
Use tags para representar informações técnicas sobre como os dados são estruturados no aplicativo de origem. Para armazenar outros dados definidos pelo usuário, use metadados.

Chamadas de API úteis

Exemplo de código

Para obter um exemplo de implementação, consulte o seguinte arquivo no repositório da Unreal Engine:

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

Metadados

O Datasmith carrega pares de chave/valor que podem ser usados para armazenar informações BIM (ou outros dados personalizados) em entidades.

Metadados do 3ds Max (esquerda) transladados na Unreal Engine (direita).

Limitações

Pares de chave/valor só podem conter strings. Isso significa que floats, unidades etc. precisarão estar contidos ("incorporados") na string (por exemplo, "10 mm").
Não há suporte para propriedades hierárquicas . Você precisará nivelar a hierarquia usando um separador sublinhado ( _ ). Consulte o exemplo do Revit abaixo em que as propriedades Element e Type são gerenciadas concatenando strings de texto para manter as coisas agrupadas.

Uma hierarquia plana simulada usando metadados do Revit.

Chamadas de API úteis

Exemplo de código

Para obter um exemplo de implementação, consulte o seguinte arquivo no repositório da Unreal Engine:

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

Atores de câmera

O Datasmith pode criar câmeras na Unreal Engine, mas, dependendo do caso de uso, talvez você queira exportar câmeras do aplicativo 3D. Às vezes, os usuários definem as câmeras de forma explícita (por exemplo, câmeras físicas do 3ds Max). Outras vezes, as câmeras são derivadas de conceitos de outros aplicativos (por exemplo, Visualizações no Revit, ou Favoritos no SketchUp).

Um elemento-chave a considerar com relação às câmeras da Unreal Engine é que elas têm características físicas que você precisará definir no momento da exportação, como:

Largura do sensor
Proporção
Valor de exposição
Ponto branco
Profundidade de campo e assim por diante.

Veja abaixo um exemplo de implementação de uma câmera com tags e características em um arquivo ".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 da Unreal Engine.

Diretrizes

Profundidade de campo, exposição e outros efeitos fotográficos definidos pelas configurações de pós-processamento também são opcionais. Isso exige uma relação estreita entre iluminação e câmeras no aplicativo de origem, que pode não ser definida no contexto de sua própria exportação do Datasmith.

Limitações

As câmeras da Unreal Engine não são compatíveis com câmeras distorcidas (perspectiva de 2 pontos). Por exemplo, o Revit pode ter vistas "cortadas" que mudarão a perspectiva da câmera, mas o Datasmith (e, por extensão, a Unreal Engine) não é compatível com esse tipo de transformação de câmera.

Chamadas de API úteis

Exemplo de código

Para obter um exemplo de implementação, consulte os seguintes arquivos no repositório da Unreal Engine:

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

Ativos de textura

Na Unreal Engine, as texturas representam mais que apenas informações de cores. Para realizar amostragem e afetar a iluminação e o sombreamento corretamente, você deve indicar o uso pretendido da textura (texturemode). Os usos possíveis incluem:

Diffuse
Specular
Normal
NormalGreenInv
Displace
Other
Bump
Ies

Também precisamos especificar o espaço de cores (geralmente correção gama ou sRGB), pois tem um impacto direto em como a luz funcionará com os materiais (curva sRGB e RGB).

Veja abaixo um exemplo de implementação de um ativo de textura em um arquivo ".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>

Diretrizes

Você deve definir o espaço de cores (Gamma/sRGB) corretamente, com base no uso pretendido da textura:
- O espaço de cores sRGB costuma ser usado para texturas de albedo.
- O espaço de cores linear geralmente é usado para mapas de normais, de altura ou de colisão.
O nome da textura (não o nome do arquivo) deve ser sanitizado (ou seja, não deve incluir nenhum caractere inválido).
Você deve colocar as texturas na mesma pasta que o restante dos ativos.

As texturas devem ser exportadas na mesma pasta que os outros ativos.

Evitar

Não use caminhos absolutos.
Não coloque as texturas em uma pasta diferente do resto dos ativos.
Durante a exportação, não é necessário transformar as texturas. O importador do Datasmith processará as transformações.
- Não é necessário converter texturas para .uasset com a API DatasmithCore.
- Não é necessário reformatar, redimensionar ou converter texturas em formatos diferentes.

Esta imagem mostra o uso incorreto de arquivos ".uasset" para representar texturas.

Chamadas de API úteis

Exemplo de código

Para obter um exemplo de implementação, consulte o seguinte arquivo no repositório da Unreal Engine:

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

Materiais

Exportação PBR simples

O exemplo a seguir demonstra como as texturas podem ser exportadas para um arquivo Datasmith para criar um material PBR básico contendo um mapa de albedo e um mapa de altura.

Material original no Rhino

Este exemplo usa o seguinte material no Rhino:

As configurações do material são as seguintes:


Mapa de albedo	mapa de altura

Arquivo resultante do Datasmith

O arquivo resultante do Datasmith ficará assim:


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

Observe que as duas texturas acima têm valores diferentes para "texturemode" e "srgb":

"texturemode="0" e "srgb="1" para a primeira textura
"Texturemode="6" e "srgb="0" para a segunda textura

Importado no Unreal Editor

Na Unreal Engine, o gráfico PBR do material importador será assim:

Clique na imagem para ver no tamanho original.

Observe que o mapa de albedo está definido como "SRGB=1" e o tipo de amostra está definido como "Color". Isso é configurado automaticamente pelo importador do Datasmith e resulta da configuração do mapa de albedo exportado como:

"texturemode="0" srgb="1""

O mapa de altura, que estava em escala de cinza no Rhino, foi convertido em um mapa de normais pelo importador do Datasmith, que é resultado da configuração da textura como:

"texturemode="6" srgb="0""

Chamadas de API úteis

IDatasmithUEPbrMaterialElement
IDatasmithTextureElement:
- SetSRGB - EDatasmithColorSpace
- SetTextureMode - EDatasmithTextureMode