导入系统

警告

本文介绍的功能在 Community SDK 版本中不可用。
您应该升级到 Engineering / Sim SDK版本才能使用它。

章节:

UNIGINE offers a flexible and extendable Import System, enabling you to import whole scenes as well as selected scene components from any external format and use them in your projects.UNIGINE 提供了一个灵活且可扩展的导入系统，使您能够从任何外部格式导入整个场景以及选定的场景组件，并在您的项目中使用它们。

Imported Scene is a set of metadata on objects to be brought to UNIGINE, which can contain the following components:Imported Scene是一组关于要带到 UNIGINE 的对象的元数据，它可以包含以下组件：

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

The structure of Import System is shown below. It includes Import Manager and a dynamic set of importers and processors for various external file formats.导入系统的结构如下图所示。它包括导入管理器和一组动态的进口商和处理器适用于各种外部文件格式。

Import System

导入系统结构

Import Manager is used to create and manage importers and processors, as well as to directly import files in non-native formats, if an importer for such files was previously registered.Import Manager 用于创建和管理导入器和处理器，以及直接导入非本地格式的文件（如果此类文件的导入器先前已注册）。

Importers and Processors进口商和加工商#

Importer is a module used by Import System to bring the data stored in various non-native formats to UNIGINE. It generates UNIGINE objects on the basis of metadata extracted from the imported file. A single importer can be used to import multiple external file formats (extensions), but there shouldn't be two or more importers registered for a single file format. Importer 是 Import System 使用的一个模块，用于将存储在各种非本地格式的数据带到 UNIGINE。它根据从导入文件中提取的元数据生成 UNIGINE 对象。单个导入器可用于导入多种外部文件格式（扩展名），但不应为单个文件格式注册两个或多个导入器。

Each importer has a set of parameters that control the whole import process (e.g., scale multiplier, use of various processors such as static mesh merger or vertex cache optimizer, etc.). It also has a set of flags that define which scene components are to be extracted and imported. So, the importer should be initialized before use.每个导入器都有一组控制整个导入过程的参数（例如，缩放倍数、使用各种处理器，例如 static mesh merger 或 vertex cache optimizer 等）。它还具有一组标志，用于定义要提取和导入哪些场景组件。因此，导入器在使用前应进行初始化。

Importers use a set of processors to perform all necessary auxiliary operations. A processor is a module that performs auxiliary operations during the import process (data preparation, file saving, file management, etc.). The list of processor types that can be used includes the following:Importers 使用一组处理器来执行所有必要的辅助操作。处理器是在导入过程中执行辅助操作（数据准备、文件保存、文件管理等）的模块。可以使用的处理器类型列表包括：

Pre-processor — performs additional operations on scene metadata (ImportScene) and prepares it for the object generation stage.预处理器——执行附加操作场景元数据(ImportScene) 并为对象生成阶段做好准备。
Import processor — saves UNIGINE objects generated by an importer on the basis of metadata to a file in UNIGINE's native format. You can use a set of different processors for each scene component or a single processor for all of them.导入处理器——将导入器基于元数据生成的 UNIGINE 对象保存到 UNIGINE 原生格式的文件中。您可以为每个场景组件使用一组不同的处理器，也可以为所有场景组件使用一个处理器。
Post-processor — performs additional operations with generated files (copying files to other folders, adding files to packages, etc.).后处理器- 对生成的文件执行附加操作（将文件复制到其他文件夹、将文件添加到包等）。

Importer allows you to add any number of pre- and post-processors. However, you can set only one processor for each scene component.Importer 允许您添加任意数量的前处理器和后处理器。但是，您只能为每个场景组件设置一个处理器。

Import System offers you the DefaultProcessor — it is, as its name says, a default processor used to save objects that were generated by an importer to corresponding UNIGINE file formats (.mesh, .dds, .node, etc.).Import System 为您提供 DefaultProcessor — 正如其名称所说，它是一个默认处理器，用于将导入器生成的对象保存为相应的 UNIGINE 文件格式（.mesh, .dds, .node 等）。

If your application does not require any specific file saving operations, you can use DefaultProcessor, otherwise, you can implement your own custom processor with any additional functionality (e.g., import models directly to memory).如果您的应用程序不需要任何特定的文件保存操作，您可以使用 DefaultProcessor，否则，您可以实现自己的定制处理器具有任何附加功能（例如，将模型直接导入内存）。

Basic Workflow基本工作流程#

In order to be used, importers and processors must be registered in the system via Import Manager. You can manage the list of available modules dynamically by adding them to or removing from the registry. When you import a file in any external format, Import System automatically tries to find and use an appropriate importer registered for the specified file extension.为了使用，进口商和加工商必须通过 Import Manager 在系统中注册。您可以通过将可用模块添加到注册表或从注册表中删除来动态管理可用模块的列表。当您以任何外部格式导入文件时，导入系统会自动尝试查找并使用为指定文件扩展名注册的适当导入器。

The basic file import workflow is as follows:基本文件导入工作流程如下：

Check the extension of the specified input file and find the appropriate importer among the registered ones.检查指定输入文件的扩展名，并在已注册的文件中找到合适的导入程序。
Extract scene metadata from the input file, put the data to the corresponding import structures (ImportMesh, ImportMaterial, etc.), and build the import scene.从输入文件中提取场景元数据，将数据放入相应的导入结构（ImportMesh, ImportMaterial等），并构建导入场景.
Use pre-processor(s) to prepare scene metadata when necessary (merge all static meshes into a single one, optimize vertex cache, etc.).必要时使用预处理器准备场景元数据（将所有静态网格合并为一个，优化顶点缓存等）。
Use the appropriate importer to generate UNIGINE objects (nodes, lights, cameras, materials, etc.) on the basis of scene metadata.使用合适的导入器在场景元数据的基础上生成 UNIGINE 对象（节点、灯光、相机、材质等）。
Use the appropriate import processor to save generated objects to the corresponding files in the specified output directory.使用适当的导入处理器将生成的对象保存到指定输出目录中的相应文件中。
Use post-processor(s) to perform necessary operations with generated files.使用后处理器对生成的文件执行必要的操作。

Customization定制#

The Import System is utilized by both the Engine and the UnigineEditor. Out-of-the-box it currently offers:引擎和 UnigineEditor 都使用导入系统。它目前提供的开箱即用：

Importer for FBX scenes implemented as UnigineFbxImporter plugin, which in addition to .fbx format also supports .obj, .dae, and .3ds.FBX 场景导入器实现为 UnigineFbxImporter 插件，除了 .fbx 格式还支持 .obj、.dae, 和 .3ds。
Importer for CAD models implemented as UnigineCadImporter plugin, which supports .iges, .step, and .stl CAD formats.CAD 模型导入器作为UnigineCadImporter插件实现，支持 .iges、.step, 和 .stl CAD 格式。

Custom importing modules (importers and processors) for any file format containing 3D scene data are also to be implemented as plugins. So, you can consider the UnigineFbxImporter and UnigineCadImporter plugins as examples to build your own custom importing modules. You can also modify and rebuild these plugins to use your own custom importer in the Editor (add functionality to process used-defined attributes of CAD models, some additional scene processing functionality, etc.).包含 3D 场景数据的任何文件格式的自定义导入模块（导入器和处理器）也将作为插件实现。因此，您可以将 UnigineFbxImporter 和 UnigineCadImporter 插件作为示例来构建您自己的自定义导入模块。您还可以修改和重建这些插件可以在编辑器中使用您自己的自定义导入器（添加功能以处理 CAD 模型的使用定义属性、一些额外的场景处理功能等）。

To use the UnigineFbxImporter plugin, just load it via the plugin_load console command or the following command line option on the application start-up:

命令行

-extern_plugin UnigineFbxImporter

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

命令行

-extern_plugin UnigineFbxImporter

In general, the workflow via the API may be represented as follows:一般来说，通过 API 的工作流可以表示如下：

源代码 (C++)

// create an importer for the imported file ("1.fbx" in our case)
ImporterPtr importer = Import::createImporterByFileName("../data/1.fbx");

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

	// add a pre-processor to merge static meshes
	importer->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());
}

You can also load a model with default settings simply like this:您还可以像这样加载具有默认设置的模型：

源代码 (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
filepath_node = Import::doImport("../data/1.fbx", "../data/1/");

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

Built-in Import Options内置导入选项#

The engine's built-in importers (such as FBX and CAD Importer) have a number of import options that also can be used in custom importers.引擎的内置导入器（例如FBX和加元进口商）有一些导入选项这也可用于自定义进口商。

Parameter Names参数名称#

The following table lists the names for the parameters available out of the box that can be set via the setParameterInt("name", value) method. 下表列出了可通过 setParameterInt("name", value) 方法设置的现成可用参数的名称。

need_reset_mesh
Deletes the mesh from the FBX SDK after it has been converted.转换后从 FBX SDK 中删除网格。 0 — disabled (by default)0 — 禁用（默认） 1 — to enable1 — 启用
create_unique_material_names
Creates unique names for materials with identical names.为具有相同名称的材质创建唯一名称。 0 — disable0 — 禁用 1 — enabled (by default)1 — 启用（默认）
vertex_cache
Optimizes vertex cache. This option reorders an indexed triangle list to improve vertex cache utilization at runtime. It can be turned off to accelerate saving process; however, it should always be turned on if saving the final version.优化顶点缓存。此选项重新排序索引三角形列表以提高运行时的顶点缓存利用率。可以关闭以加快保存过程；但是，如果保存最终版本，则应始终将其打开。 0 — disabled (by default)0 — 禁用（默认） 1 — to enable1 — 启用
workflow
Defines the workflow for the imported physically based materials (if any).定义工作流程对于进口的基于物理的材质（如果有）。 0 — Metalness workflow that uses the new standard of textures (albedo, metalness, roughness) (by default).0 — Metalness 工作流程，使用新的纹理标准（反照率、金属度、粗糙度）（默认情况下）。 1 — Specular workflow that uses the old standard of textures that was used in mesh_base material (diffuse, specular, gloss).1 — Specular 工作流程，使用在 mesh_base 材质（漫反射、镜面反射、光泽）中使用的旧纹理标准。
import_bones_without_skin
Imports bones that are not attached to the skeleton and do not affect the animation's skin, for example, a weapon held in the character's hands. If disabled, such bone is not imported and bones connected to it, if any, become orphans.导入未附加到骨架且不影响动画皮肤的骨骼，例如，角色手中的武器。如果禁用，则不会导入此类骨骼，并且与之连接的骨骼（如果有）将成为孤立骨骼。 0 — disabled (by default)0 — 禁用（默认） 1 — to enable1 — 启用
import_tangent_space
Imports built-in tangent space data instead of recalculating it.导入内置的切线空间数据而不是重新计算它。 0 — disabled (by default)0 — 禁用（默认） 1 — to enable1 — 启用注意 If the option is enabled, but an FBX asset has no tangent space, it will be calculated with orientation for the right-handed coordinate system.如果启用该选项，但 FBX 资源没有切线空间，则将使用右手坐标系的方向进行计算。
import_morph_targets
Imports morph targets from the file.从文件中导入变形目标。 0 — disabled (by default)0 — 禁用（默认） 1 — to enable1 — 启用
create_transform_bones_for_joints
Imports the hierarchy of the joints (bones) for animated assets as a list of World Transform Bones.将动画资源的关节（骨骼）层次导入为 World Transform Bones 列表。 0 — disabled (by default)0 — 禁用（默认） 1 — to enable1 — 启用
joints_reorientation
Defines orientation of bones for animations and animated geometry. When enabled, all bones will have the same forward axis as the geometry. This simplifies work with animations via code for programmers reducing excessive axis manipulations: if a mesh has +Y as a forward axis, the bones will have +Y as well.定义动画和动画几何体的骨骼方向。启用后，所有骨骼都将具有与几何体相同的正向轴。这通过代码为程序员简化了动画工作，减少了过多的轴操作：如果网格有 +Y 作为前向轴，那么骨骼也将有 +Y。 0 — disabled (by default)0 — 禁用（默认） 1 — to enable1 — 启用
use_instances
Imports FBX with mesh instances. When enabled, a single mesh is imported instead of several identical ones. If you add such FBX to the scene, all meshes in the World Hierarchy will refer to the single mesh stored inside the imported FBX container.使用网格实例导入 FBX。启用后，将导入单个网格而不是几个相同的网格。如果将此类 FBX 添加到场景中，则 World Hierarchy 中的所有网格都将引用存储在导入的 FBX 容器中的单个网格。 0 — disabled (by default)0 — 禁用（默认） 1 — to enable1 — 启用
up_axis
Defines which axis is the up vector of the World Coordinate System.定义哪个轴是世界坐标系的向上向量。 -1 — none (by default)-1 — 无（默认） 0 — X0 - X 1 — negative X1 — 负 X 2 — Y2 — 与 3 — negative Y3 — 负 Y 4 — Z4 - Z 5 — negative Z5 — 负 Z 注意 The up_axis value should be different from the front_axis value.up_axis 值应该不同于 front_axis 值。
front_axis
Defines which axis is the forward vector of the World Coordinate System.定义哪个轴是世界坐标系的前向矢量。 -1 — none (by default)-1 — 无（默认） 0 — X0 - X 1 — negative X1 — 负 X 2 — Y2 — 与 3 — negative Y3 — 负与 4 — Z4 - Z 5 — negative Z5 — 负 Z 注意 The front_axis value should be different from the up_axis value.front_axis 值应该不同于 up_axis 值。
need_triangulate
Enables correct triangulation of meshes, NURBS and patches.启用网格、NURBS 和面片的正确三角剖分。 0 — disabled (by default)0 — 禁用（默认） 1 — to enable1 — 启用
skip_empty_nodes
Skips empty nodes. Complex CAD models may contain a lot of empty nodes, resulting in an overloaded world hierarchy. You can enable this option to simplify generated hierarchy by ignoring nodes, that do not contain any useful information.跳过空节点。复杂的 CAD 模型可能包含大量空节点，从而导致世界层次结构过载。您可以启用此选项以通过忽略不包含任何有用信息的节点来简化生成的层次结构。 0 — disabled (by default)0 — 禁用（默认） 1 — to enable1 — 启用
merge_similar_materials
Merges materials with the same settings, but different names.合并具有相同设置但名称不同的材质。 0 — disabled (by default)0 — 禁用（默认） 1 — to enable1 — 启用
uv_channel
Sets the UV channel to store the lightmap.设置 UV 通道以存储光照贴图。 0 — Channel 00 — 通道 0 1 — Channel 11 — 通道 1 Requires adding CreateUV post-processor.需要添加 CreateUV 后处理器。
uv_padding
Sets the padding value from 0 to 8, in pixels. The default value is 0. Requires adding CreateUV post-processor.将填充值从 0 设置为 8，以像素为单位。默认值为 0。需要添加 CreateUV 后处理器。
uv_resolution
Sets the resolution of the resulting lightmap. Available values: 32, 64, 128, 256, 512, 1024, 2048, 4096. The default value is 0. Requires adding CreateUV post-processor.设置生成的光照贴图的分辨率。可用值：32, 64, 128, 256, 512, 1024, 2048, 4096。默认值为 0。需要添加 CreateUV 后处理器。
uv_high_quality
Defines the efficiency of UV islands layout on the texture.定义纹理上 UV 岛布局的效率。 0 — Low quality (by default)0 - 低质量（默认） 1 — High quality1 - 高质量 Requires adding CreateUV post-processor.

The following table lists the names for the parameters available out of the box that can be set via the setParameterFloat("name", value) method.
下表列出了可通过 setParameterFloat("name", value) 方法设置的现成可用参数的名称。

scale
Geometry scale multiplier.几何比例乘数。
fps
Number of frames per second of imported animation.导入动画的每秒帧数。
bound_size
Size of the grid cell to split imported meshes, in units. Requires adding SplitByBound pre-processor.用于分割导入网格的网格单元的大小，以单位为单位。需要添加 SplitByBound 预处理器。

The following table lists the names for the parameters available out of the box that can be set via the setParameterString("name", value) method.
下表列出了可通过 setParameterString("name", value) 方法设置的现成可用参数的名称。

lods_postfixes
Lists the postfixes to be used to differeciate between LODs, in the following format:列出用于区分 LOD 的后缀，格式如下：源代码 (C++) `importer->setParameterString("lods_postfixes", "_lod_0,_lod_1,_lod_2");` Requires adding CombineByPostfixes pre-processor. 注意 The amount of postfixes should be the same as the amount of listed lods_distances.后缀的数量应与列出的 lods_distances 的数量相同。
lods_distances
Lists the minimum distances for LODs, in the following format:以下列格式列出 LOD 的最小距离：源代码 (C++) `importer->setParameterString("lods_distances", "-1e+09,3,9");` Requires adding CombineByPostfixes pre-processor. 注意 The amount of distances should be the same as the amount of listed lods_postfixes.距离的数量应与列出的 lods_postfixes 的数量相同。

Pre-processor Type Names预处理器类型名称#

The following table lists the type names for the pre-processors available out of the box that can be added via the addPreProcessor("type_name") method.下表列出了可通过 addPreProcessor("type_name") 方法添加的开箱即用的预处理器的类型名称。

MergeStaticMeshes
Merges all of the children static meshes into a single one (named after the parent mesh). All surfaces of all meshes surfaces will be copied and shown in the Surfaces hierarchy.将所有子静态网格合并为一个（以父网格命名）。所有网格表面的所有表面都将被复制并显示在 Surfaces 层次结构中。
MergeSurfacesByMaterials
Enables merging surfaces that have the same materials.启用合并具有相同材质的曲面。
Repivot
Places a pivot of generated mesh to its center. Can be used for meshes having their geometry located too far from their pivot, as this may lead to various artefacts (jitter, etc.) associated with positioning errors.将生成的网格的枢轴放置到其中心。可用于几何形状离其枢轴太远的网格，因为这可能会导致与定位错误相关的各种伪影（抖动等）。
SplitByBound
Splits imported meshes according to the grid size defined by bound_size parameter.根据 bound_size 参数定义的网格大小分割导入的网格。
CombineByPostfixes
Enables automatic creation of the Levels of Detail (LODs) based on the values of the lods_postfixes and lods_distances parameters. 根据 lods_postfixes 和 lods_distances 参数的值自动创建细节层次 (LOD)。

Post-processor Type Names后处理器类型名称#

The following table lists the type names for the post-processors available out of the box that can be added via the addPostProcessor("type_name") method.下表列出了可通过 addPostProcessor("type_name") 方法添加的开箱即用后处理器的类型名称。

CreateUV
Creates UV based on the values of uv_channel, uv_padding, uv_resolution, and uv_high_quality parameters.根据 uv_channel, uv_padding, uv_resolution 和 uv_high_quality 参数的值创建 UV。