虚幻引擎5文档已被迁移至 Epic开发者社区

自定义Datasmith导入流程

介绍如何使用蓝图或Python导入Datasmith和CAD文件，以及如何更改场景变换为虚幻资源和Actor的方式。

Choose your operating system:

Windows

macOS

Linux

Datasmith导入流程旨在将内容创建工具中设置的一组3D对象顺利导入虚幻编辑器。为此，在尽可能尊重设计意图的前提下，它会自动将对象（如网格体、光源、摄像机和表面材质）转换为虚幻引擎中对应的对象，并自动使用这些资源的实例来填充关卡。详情请参阅 Datasmith概述 。

但您有时需要深入了解导入流程，更改原始场景转换为虚幻引擎资源的方式，或更改处理这些资源的方式。例如，如果虚幻引擎项目中不需要原始场景的某些部分，可以在创建资源之前将其过滤掉。这会减少需要在虚幻编辑器中处理的不同内容的数量，加快大型场景的导入。

本页介绍如何使用蓝图或Python脚本控制Datasmith导入流程。

了解导入流程

使用虚幻编辑器工具栏中其中一个Datasmith导入器导入场景时（详见将Datasmith内容导入虚幻引擎4），导入器在内部执行一个两步式流程，将从 .udatasmith 、CAD或磁盘上的其他源文件中抓取数据，并将其转换为虚幻编辑器中的资源和Actor：

  1. 导入器将文件内容读入名为Datasmith场景的内存中数据结构。这包括3D对象在场景中的展示、它们的关系，以及Datasmith可从原始场景中提取的对象的所有属性。

  2. Datasmith场景在内存中准备就绪后，导入流程的第二阶段在内容浏览器中将场景元素最终转化为虚幻引擎资源。Datasmith场景资源准备就绪后，导入流程会在当前关卡中将其生成。该场景资源转而生成其所有子项：Actor、静态网格体Actor、光源、摄像机等。

Datasmith两步导入流程

导入流程自定义选项

如果使用蓝图或Python脚本启动Datasmith导入流程，可解构上述流程，分别执行这两个阶段。此时可插入自己的处理，但必须在内存中构建Datasmith场景之后、且在将该场景最终转化为资源和Actor之前。

蓝图和Python的整体流程相同：

  1. 从 .udatasmith 、CAD或磁盘上的其他支持文件类型的位置构造新的内存中Datasmith场景展示。

  2. 酌情对场景进行其他修改，改变场景转换为虚幻资源的方式。

    利用场景中对象的相关元数据，可轻松识别需要更改的对象。欲详细了解如何在Datasmith场景中访问元数据，请参阅 使用Datasmith元数据 。

  3. 设置导入流程选项。这些选项基本上等同于使用 导入Datasmith（Import Datasmith） 按键开始导入时在虚幻编辑器UI中设置的选项。例如，设置导入器将导入资源放置在项目中的路径，从Datasmith场景创建的对象类型，参数化CAD格式的曲面细分设置等。

  4. 完成导入流程，将Datasmith场景最终转化为虚幻资源。

  5. 若不再需要之前构建的Datasmith场景，应将其销毁，清除其占用的内存资源。

  6. 现在导入流程已完成，内容浏览器中已有新资源，当前关卡中有新的Actor（如果在导入选项中要求添加）。若要对生成的虚幻资源进行额外的 后期 处理（例如自动创建碰撞数据或LOD），可在此时进行。另可参阅 编辑器脚本编写和自动化 。

自定义导入流程很可能会对 关于Datasmith重新导入工作流 中所述的重新导入流程产生影响。例如，若在完成导入流程之前使用脚本从Datasmith场景中删除网格体或光源等元素，然后重新导入Datasmith场景资源，则在重新导入期间会绕过预处理脚本。这会导致最初从场景中过滤掉的对象被检测为新添加的对象，并添加到项目或关卡中。

目前建议在导入 后 使用 编辑器脚本编写和自动化 中介绍的工具和技巧执行大部分修改。除非完成导入后无法通过修改资源或Actor满足特定需求（例如阻止创建某些资源），否则切勿在导入期间修改Datasmith场景。

开始之前

  • 确保项目已经启用了 Datasmith导入器 插件。

  • 有关如何在编辑器中使用蓝图和Python脚本的背景信息，请参阅 编辑器脚本编写和自动化 下的页面。

示例

以下示例展示使用蓝图和Python自定义将 .udatasmith 文件和CAD文件导入虚幻编辑器的过程。

选择实现方法：

Blueprints

Python

若要使用蓝图自定义导入流程，主要会用到 编辑器脚本（Editor Scripting）> Datasmith 、 Datasmith >场景（Scene） 和 Datasmith >元素（Element） 类别下的节点。

要访问所需节点，需使用编辑器工具控件和编辑器工具蓝图，或使蓝图类派生自纯编辑器基类（如 EditorUtilityActor ）。下例显示由编辑器工具控件中的按钮触发的蓝图图表。

目标文件夹必须以 /Game/ 开头。

导入.udatasmith文件

本例中， Get Options 节点请求 DatasmithImportOptions 类，该类的 Base Options 变量中包含基本导入设置。

Copy Node Graph

customized-DS-import.png

单击图像的右上角复制节点图表。

导入CAD文件

本例中，第一个 Get Options 调用请求的是与上一例相同的 DatasmithImportOptions 类。第二个调用请求的是 DatasmithCommonTessellationOptions 类，该类的 Options 变量中包含曲面细分设置。第三个调用请求的是 DatasmithCADImportOptions 类，该类包含其他CAD的特有设置（通常用于特殊情况）。

Copy Node Graph

customized-CAD-import.png

单击图像的右上角复制节点图表。

若要利用Python自定义导入流程，主要的着手点是 unreal.DatasmithSceneElement 类。该类提供从文件构造场景、处理场景中元素（利用在 unreal.DatasmithSceneElementBase 基类中定义的函数），以及完成导入所需的所有函数。

导入.udatasmith文件 

import unreal

ds_file_on_disk = "C:\\scenes\\building.udatasmith"
ds_scene_in_memory = unreal.DatasmithSceneElement.construct_datasmith_scene_from_file(ds_file_on_disk)

if ds_scene_in_memory is None:
    print "Scene loading failed."
    quit()

# 修改场景中的数据来过滤掉或合并元素...

# 删除名称含特定关键字的网格体。
remove_keyword = "exterior"      # 删除名称含此字符串的Actor。
meshes_to_skip = set([])         # 将使用此设置临时存储不需要的网格体。

# 从场景中删除名称与上述设定字符串匹配的网格体Actor。
for mesh_actor in ds_scene_in_memory.get_all_mesh_actors():
    actor_label = mesh_actor.get_label()
    if remove_keyword in actor_label:
        print("removing actor named:" + actor_label)
        # 将该Actor的网格体资源添加到要忽略的网格体列表
        mesh = mesh_actor.get_mesh_element()
        meshes_to_skip.add(mesh)
        ds_scene_in_memory.remove_mesh_actor(mesh_actor)

# 删除所有无需导入的网格体。
for mesh in meshes_to_skip:
    mesh_name = mesh.get_element_name()
    print("removing mesh named " + mesh_name)
    ds_scene_in_memory.remove_mesh(mesh)

# 设置导入选项。
import_options = ds_scene_in_memory.get_options(unreal.DatasmithImportOptions)
import_options.base_options.scene_handling = unreal.DatasmithImportScene.NEW_LEVEL

# 创建资源和Actor，完成流程。

# 目标文件夹必须以/Game/开头
result = ds_scene_in_memory.import_scene("/Game/MyStudioScene")

if not result.import_succeed:
    print "Importing failed."
    quit()

# 清除Datasmith场景。
ds_scene_in_memory.destroy_scene()
print "Custom import process complete!"

导入CAD文件 

import unreal

# 从磁盘上的文件构建Datasmith CAD场景。
# 目标文件夹必须以/Game/开头
ds_file_on_disk = "C:\\designs\\Clutch assembly.SLDASM"
ds_scene_in_memory = unreal.DatasmithSceneElement.construct_datasmith_scene_from_file(ds_file_on_disk)

if ds_scene_in_memory is None:
    print "Scene loading failed."
    quit()

# 修改场景中数据以过滤掉或合并元素。
remove_keyword = "_BODY"         # 删除名称含此字符串的Actor。
meshes_to_skip = set([])         # 将使用此集临时存储不需要的网格体。

# 从场景中删除名称与上述字符串集匹配的网格体Actor。
for mesh_actor in ds_scene_in_memory.get_all_mesh_actors():
    actor_label = mesh_actor.get_label()
    if remove_keyword in actor_label:
        print("removing actor named:" + actor_label)
        # 将该Actor的网格体资源添加到要忽略的网格体列表
        mesh = mesh_actor.get_mesh_element()
        meshes_to_skip.add(mesh)
        ds_scene_in_memory.remove_mesh_actor(mesh_actor)

# 删除所有无需导入的网格体。
for mesh in meshes_to_skip:
    mesh_name = mesh.get_element_name()
    print("removing mesh named " + mesh_name)
    ds_scene_in_memory.remove_mesh(mesh)

# 设置导入选项。

# 主导入选项：
import_options = ds_scene_in_memory.get_options(unreal.DatasmithImportOptions)
import_options.base_options.scene_handling = unreal.DatasmithImportScene.NEW_LEVEL

# 纯CAD表面曲面细分选项：
tessellation_options = ds_scene_in_memory.get_options(unreal.DatasmithCommonTessellationOptions)
tessellation_options.options.chord_tolerance = 0.1
tessellation_options.options.max_edge_length = 0
tessellation_options.options.normal_tolerance = 30
tessellation_options.options.stitching_technique = unreal.DatasmithCADStitchingTechnique.STITCHING_SEW

# 其他纯CAD选项：
cad_import_options = ds_scene_in_memory.get_options(unreal.DatasmithCADImportOptions)
cad_import_options.uv_generation = unreal.CADUVGeneration.KEEP
cad_import_options.num_threads = 8

# 创建资源和Actor，完成流程。
ds_scene_in_memory.import_scene("/Game/MyCADScene")

# 清除Datasmith场景。
ds_scene_in_memory.destroy_scene()
print "Custom import process complete!"

访问导入选项

处理不同类型的Datasmith源文件时，API中唯一不同点在于，不同类型的文件会提供不同的方法来控制导入。

  • 对于 .udatasmith 文件，上述第一个示例展示如何访问 DatasmithImportOptions 对象，该对象提供对目标资源和路径名、要导入的数据类型、光照贴图分辨率设置等的访问。这适用于可使用Datasmith导入的所有文件类型。

  • 对于CAD文件，第二个示例展示如何访问第一例中的对象以及 DatasmithCommonTessellationOptions 对象（该对象控制曲面细分流程中所用的设置）和 DatasmithCADImportOptions 对象（该对象可访问其他实用内部调试设置）。

  • Datasmith支持的其他文件类型将导入设置封装在其他类中，比如Cinema 4D的 DatasmithC4DImportOptions 。

除了访问这些导入选项，用于处理Datasmith场景及其内部元素的其余脚本是完全相同的。

如需更详细地了解这些导入选项类及提供的设置，请参阅 Python API说明 或 蓝图API说明 中的相关条目。

在Python中调用 DatasmithSceneElement.get_options() 、或在蓝图中使用 Get Options 节点时，如果指定了未应用于已构造的源文件类型的Datasmith选项的类，将返回null。在Python中，可测试 None 返回。在蓝图中，可将返回值传递到 Utilities > IsValid 节点，检查是否是所请求类的有效实例。

除了在Python中使用 DatasmithSceneElement.get_options() 或在蓝图中使用 Datasmith >场景（Scene）> 获取选项（Get Options） ，还可以使用 DatasmithSceneElement.get_all_options() 或 Datasmith >场景（Scene）> 获取所有选项（Get All Options） 获取已在单个地图中构建的Datasmith场景的 所有 选项类。地图中各个条目的键值是利用文件构造的Datasmith场景元素所拥有选项的类，条目的值是Datasmith场景元素所拥有的类的实例。若不知道脚本将处理的文件类型，也不知道 DatasmithSceneElement 应包含什么类型的选项类，则可使用此法获取并迭代。

关于Datasmith场景

要探究预导入阶段中可对Datasmith场景执行的操作，可先了解一下场景的构造方式。

场景内容

Datasmith场景主要作为各种不同类型的 元素 的容器。这些元素将代表在导入后将在内容浏览器中创建的 资源 ，或代表将在关卡中生成、具有自身特有3D空间变换的 Actor 。

主要资源元素类型包括：

  • 网格体：每个网格体元素代表一个3D几何体。完成导入时，每个网格体元素最终会成为Geometry文件夹中一个单独的静态网格体对象。每个网格体元素都有许多材质槽，每个槽都通过名称与材质元素关联。

  • 材质：每个材质元素都代表几何体所需的一种独特的表面。完成导入时，每个材质元素最终会成为Materials文件夹中一个单独的材质对象。

  • 纹理：每个纹理元素代表被至少一个材质所使用的单个2D图像。完成导入时，每个纹理元素最终会成为Textures文件夹中一个单独的纹理对象。

主要的Actor元素类型包括：

  • 网格体Actor：每个网格体Actor元素都代表关卡中网格体几何体的一个实例。完成导入时，每个网格体Actor元素最终会成为世界大纲视图中的一个静态网格体Actor。

  • 光源Actor：每个光源Actor元素都代表场景中的一个光线发射器。完成导入时，每个光源Actor元素最终会成为关卡中基本虚幻光源类型（如点光源或聚光源）的某个实例，或成为一个模拟区域光源的自定义Datasmith Actor。可在这些光源上获取和设置许多属性，例如光源强度、颜色、IES描述纹理文件等等。

  • 摄像机Actor：每台摄像机都代表源场景中设置的一个视点。完成导入时，每个摄像机Actor元素最终会成为关卡中的一个CineCameraActor。可在这些摄像机Actor上获取和设置一些基本属性，例如高宽比。

Datasmith场景在内存中包含的数据与打开 .udatasmith 文件时看到的内容非常相似。使用3ds Max或Sketchup可打开任意导出的 .udatasmith 文件，了解Datasmith场景对象的构造方式：

Datasmith文件XML内容

使用Datasmith场景

主要与Datasmith场景交互，获取上述元素列表。要在Python中做到这一点，需要使用 DatasmithSceneElementBase 类（ DatasmithSceneElement 派生自此类）中定义的函数。在蓝图中，使用 Datasmith > Scene 节点，如上例所示。

拥有元素列表后，可在列表中迭代，获取特定元素。然后使用该元素（如 DatasmithMeshActorElement ）的Python API或蓝图中的 Datasmith > Element 节点，获取和设置该特定元素的相关信息。若元素是Actor类型，还可获取子Actor元素，向下浏览场景层级。

若要从场景中删除现有元素（如上例中所示）或添加新元素，也可通过在相同位置公开函数来实现。例如，可使用Python中 DatasmithSceneElement 类公开的函数，或蓝图中 Datasmith > Scene 类别中的节点，删除Actor并在不同的父项下重新添加，以此调整Actor的层级。

欢迎帮助改进虚幻引擎文档！请告诉我们该如何更好地为您服务。
填写问卷调查
取消