导入系统

UNIGINE 提供了一个灵活且可扩展的导入系统，使您能够从任何外部格式导入整个场景以及选定的场景组件，并在您的项目中使用它们。

Imported Scene是一组关于要带到 UNIGINE 的对象的元数据，它可以包含以下组件：

灯光
相机
网格
网格动画
纹理
材料
节点

导入系统的结构如下图所示。它包括导入管理器和一组动态的进口商和处理器适用于各种外部文件格式。

Import System

导入系统结构

Import Manager 用于创建和管理导入器和处理器，以及直接导入非本地格式的文件（如果此类文件的导入器先前已注册）。

Importer 是 Import System 使用的一个模块，用于将存储在各种非本地格式的数据带到 UNIGINE。它根据从导入文件中提取的元数据生成 UNIGINE 对象。单个导入器可用于导入多种外部文件格式（扩展名），但不应为单个文件格式注册两个或多个导入器。

每个导入器都有一组控制整个导入过程的参数（例如，缩放倍数、使用各种处理器，例如 static mesh merger 或 vertex cache optimizer 等）。它还具有一组标志，用于定义要提取和导入哪些场景组件。因此，导入器在使用前应进行初始化。

Importers 使用一组处理器来执行所有必要的辅助操作。处理器是在导入过程中执行辅助操作（数据准备、文件保存、文件管理等）的模块。可以使用的处理器类型列表包括：

预处理器——执行附加操作场景元数据(ImportScene) 并为对象生成阶段做好准备。
导入处理器——将导入器基于元数据生成的 UNIGINE 对象保存到 UNIGINE 原生格式的文件中。您可以为每个场景组件使用一组不同的处理器，也可以为所有场景组件使用一个处理器。
后处理器- 对生成的文件执行附加操作（将文件复制到其他文件夹、将文件添加到包等）。

Importer 允许您添加任意数量的前处理器和后处理器。但是，您只能为每个场景组件设置一个处理器。

Import System 为您提供 DefaultProcessor — 正如其名称所说，它是一个默认处理器，用于将导入器生成的对象保存为相应的 UNIGINE 文件格式（.mesh, .dds, .node 等）。

如果您的应用程序不需要任何特定的文件保存操作，您可以使用 DefaultProcessor，否则，您可以实现自己的定制处理器具有任何附加功能（例如，将模型直接导入内存）。

为了使用，进口商和加工商必须通过 Import Manager 在系统中注册。您可以通过将可用模块添加到注册表或从注册表中删除来动态管理可用模块的列表。当您以任何外部格式导入文件时，导入系统会自动尝试查找并使用为指定文件扩展名注册的适当导入器。

基本文件导入工作流程如下：

检查指定输入文件的扩展名，并在已注册的文件中找到合适的导入程序。
从输入文件中提取场景元数据，将数据放入相应的导入结构（ImportMesh, ImportMaterial等），并构建导入场景.
必要时使用预处理器准备场景元数据（将所有静态网格合并为一个，优化顶点缓存等）。
使用合适的导入器在场景元数据的基础上生成 UNIGINE 对象（节点、灯光、相机、材质等）。
使用适当的导入处理器将生成的对象保存到指定输出目录中的相应文件中。
使用后处理器对生成的文件执行必要的操作。

引擎和 UnigineEditor 都使用导入系统。它目前提供的开箱即用：

FBX 场景导入器实现为 FbxImporter 插件，除了 .fbx 格式还支持 .obj、.dae, 和 .3ds。
CAD 模型导入器作为CadImporter插件实现，支持 .iges、.step, 和 .stl CAD 格式。

包含 3D 场景数据的任何文件格式的自定义导入模块（导入器和处理器）也将作为插件实现。因此，您可以将 FbxImporter 和 CadImporter 插件作为示例来构建您自己的自定义导入模块。您还可以修改和重建这些插件可以在编辑器中使用您自己的自定义导入器（添加功能以处理 CAD 模型的使用定义属性、一些额外的场景处理功能等）。

要使用 FbxImporter 插件，只需通过plugin_load控制台命令或以下命令行选项在应用程序启动时：

命令行

-extern_plugin FbxImporter

一般来说，通过 C++ API 的工作流可以表示如下：

源代码 (C++)

// create an importer for the imported file ("1.fbx" in our case)
Importer *importer = Import::get()->createImporterByFileName("1.fbx"); 

// set up import parameter "scale" to 0.5
importer->setParameterFloat("scale", 0.5f); 

// add a pre-processor to merge static meshes
impoter->addPreProcessor("MergeStaticMeshes");

// initialize importer with all available import flags
importer->init("1.fbx", ~0);

// import our model to the specified directory
importer->import("../data/1/"); 

// create a node reference using the .node file generated for our model
NodeReferencePtr noderef = NodeReference::create(importer->getOutputFilepath());

您还可以像这样加载具有默认设置的模型：

源代码 (C++)

// string to store the path to the .node file for your model
String filepath_node;

// import an fbx file to the specified location and get the path to the generated .node file
Unigine::Import::get()->import("../my_data/1.fbx", "../data/1/", filepath_node);

// create a node reference using the .node file generated
NodeReferencePtr noderef = NodeReference::create(filepath_node.get());

内置导入选项#

引擎的内置导入器（例如FBX和加元进口商）有一些导入选项这也可用于自定义进口商。

参数名称#

下表列出了可通过 setParameterInt("name", value) 方法设置的现成可用参数的名称。

need_reset_mesh
转换后从 FBX SDK 中删除网格。 0 — 禁用（默认） 1 — 启用
create_unique_material_names
为具有相同名称的材料创建唯一名称。 0 — 禁用 1 — 启用（默认）
vertex_cache
优化顶点缓存。此选项重新排序索引三角形列表以提高运行时的顶点缓存利用率。可以关闭以加快保存过程；但是，如果保存最终版本，则应始终将其打开。 0 — 禁用（默认） 1 — 启用
workflow
定义工作流程对于进口的基于物理的材料（如果有）。 0 — Metalness 工作流程，使用新的纹理标准（反照率、金属度、粗糙度）（默认情况下）。 1 — Specular 工作流程，使用在 mesh_base 材质（漫反射、镜面反射、光泽）中使用的旧纹理标准。
import_bones_without_skin
导入未附加到骨架且不影响动画皮肤的骨骼，例如，角色手中的武器。如果禁用，则不会导入此类骨骼，并且与之连接的骨骼（如果有）将成为孤立骨骼。 0 — 禁用（默认） 1 — 启用
import_tangent_space
导入内置的切线空间数据而不是重新计算它。 0 — 禁用（默认） 1 — 启用注意如果启用该选项，但 FBX 资源没有切线空间，则将使用右手坐标系的方向进行计算。
import_morph_targets
从文件中导入变形目标。 0 — 禁用（默认） 1 — 启用
create_transform_bones_for_joints
将动画资产的关节（骨骼）层次导入为 World Transform Bones 列表。 0 — 禁用（默认） 1 — 启用
joints_reorientation
定义动画和动画几何体的骨骼方向。启用后，所有骨骼都将具有与几何体相同的正向轴。这通过代码为程序员简化了动画工作，减少了过多的轴操作：如果网格有 +Y 作为前向轴，那么骨骼也将有 +Y。 0 — 禁用（默认） 1 — 启用
use_instances
使用网格实例导入 FBX。启用后，将导入单个网格而不是几个相同的网格。如果将此类 FBX 添加到场景中，则 World Hierarchy 中的所有网格都将引用存储在导入的 FBX 容器中的单个网格。 0 — 禁用（默认） 1 — 启用
up_axis
定义哪个轴是世界坐标系的向上向量。 -1 — 无（默认） 0 - X 1 — 负 X 2 — 与 3 — 负 Y 4 - Z 5 — 负 Z 注意 up_axis 值应该不同于 front_axis 值。
front_axis
定义哪个轴是世界坐标系的前向矢量。 -1 — 无（默认） 0 - X 1 — 负 X 2 — 与 3 — 负与 4 - Z 5 — 负 Z 注意 front_axis 值应该不同于 up_axis 值。
need_triangulate
启用网格、NURBS 和面片的正确三角剖分。 0 — 禁用（默认） 1 — 启用
skip_empty_nodes
跳过空节点。复杂的 CAD 模型可能包含大量空节点，从而导致世界层次结构过载。您可以启用此选项以通过忽略不包含任何有用信息的节点来简化生成的层次结构。 0 — 禁用（默认） 1 — 启用
merge_similar_materials
合并具有相同设置但名称不同的材质。 0 — 禁用（默认） 1 — 启用
uv_channel
设置 UV 通道以存储光照贴图。 0 — 通道 0 1 — 通道 1 需要添加 CreateUV 后处理器。
uv_padding
将填充值从 0 设置为 8，以像素为单位。默认值为 0。需要添加 CreateUV 后处理器。
uv_resolution
设置生成的光照贴图的分辨率。可用值：32, 64, 128, 256, 512, 1024, 2048, 4096。默认值为 0。需要添加 CreateUV 后处理器。
uv_high_quality
定义纹理上 UV 岛布局的效率。 0 - 低质量（默认） 1 - 高质量 Requires adding CreateUV post-processor.

下表列出了可通过 setParameterFloat("name", value) 方法设置的现成可用参数的名称。

scale
几何比例乘数。
fps
导入动画的每秒帧数。
bound_size
用于分割导入网格的网格单元的大小，以单位为单位。需要添加 SplitByBound 预处理器。

下表列出了可通过 setParameterString("name", value) 方法设置的现成可用参数的名称。

lods_postfixes
列出用于区分 LOD 的后缀，格式如下：源代码 `importer->setParameterString("lods_postfixes", "_lod_0,_lod_1,_lod_2");` Requires adding CombineByPostfixes pre-processor. 注意后缀的数量应与列出的 lods_distances 的数量相同。
lods_distances
以下列格式列出 LOD 的最小距离：源代码 `importer->setParameterString("lods_distances", "-1e+09,3,9");` Requires adding CombineByPostfixes pre-processor. 注意距离的数量应与列出的 lods_postfixes 的数量相同。

预处理器类型名称#

下表列出了可通过 addPreProcessor("type_name") 方法添加的开箱即用的预处理器的类型名称。

MergeStaticMeshes
将所有子静态网格合并为一个（以父网格命名）。所有网格表面的所有表面都将被复制并显示在 Surfaces 层次结构中。
MergeSurfacesByMaterials
启用合并具有相同材质的曲面。
Repivot
将生成的网格的枢轴放置到其中心。可用于几何形状离其枢轴太远的网格，因为这可能会导致与定位错误相关的各种伪影（抖动等）。
SplitByBound
根据 bound_size 参数定义的网格大小分割导入的网格。
CombineByPostfixes
根据 lods_postfixes 和 lods_distances 参数的值自动创建细节层次 (LOD)。

后处理器类型名称#

下表列出了可通过 addPostProcessor("type_name") 方法添加的开箱即用后处理器的类型名称。

CreateUV
根据 uv_channel, uv_padding, uv_resolution 和 uv_high_quality 参数的值创建 UV。

FbxImporter 插件作为自定义导入插件的示例：source/plugins/Import/FbxImporter。
CadImporter 插件作为自定义导入插件的示例：source/plugins/Import/CadImporter。
自定义导入插件使用示例来学习编写自己的自定义导入插件的基础知识。
将模型直接导入内存使用示例来学习编写自己的自定义导入处理器的基础知识。

文件导入系统 API：

文件导入功能类有关通过代码（C++、UnigineScript）管理导入系统、导入器和处理器的更多详细信息。
注意
导入系统 API 不适用于 Community SDK 版本。

章节:

进口商和加工商#

基本工作流程#