Система импорта

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 StructureСтруктура Системы импорта

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 используется для создания и управления импортерами и обработчиками, а также для прямого импорта файлов в неродных форматах, если ранее был зарегистрирован импортер для таких файлов.

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 — это модуль, используемый системой импорта для переноса данных, хранящихся в различных неродных форматах, в 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, в противном случае вы можете реализовать свои собственные пользовательские процессоры со всеми дополнительными функциями (например, импортировать модели прямо в память ).

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:Основной рабочий процесс импорта файлов выглядит следующим образом:

1. Check the extension of the specified input file and find the appropriate importer among the registered ones.Проверьте расширение указанного входного файла и найдите подходящий импортер среди зарегистрированных.
2. 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 и т.д.) и создайте сцена импорта .
3. Use pre-processor(s) to prepare scene metadata when necessary (merge all static meshes into a single one, optimize vertex cache, etc.).При необходимости используйте препроцессоры для подготовки метаданных сцены (объединение всех статических мешей в один, оптимизация кеша вершин и т. д.).
4. Use the appropriate importer to generate UNIGINE objects (nodes, lights, cameras, materials, etc.) on the basis of scene metadata.Используйте соответствующий импортер для создания объектов UNIGINE (узлов, источников света, камер, материалов и т.д.) на основе метаданных сцены.
5. Use the appropriate import processor to save generated objects to the corresponding files in the specified output directory.Используйте соответствующий процессор импорта для сохранения сгенерированных объектов в соответствующие файлы в указанном выходном каталоге.
6. Use post-processor(s) to perform necessary operations with generated files.Используйте постпроцессор(ы) для выполнения необходимых операций с сгенерированными файлами.

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 FbxImporter plugin, which in addition to .fbx format also supports .obj, .dae, and .3ds.Импортер для сцен FBX реализован в виде плагина FbxImporter, который помимо формата .fbx также поддерживает форматы .obj, .dae, и .3ds.
• Importer for CAD models implemented as CadImporter plugin, which supports .iges, .step, and .stl CAD formats.Импортер для CAD-моделей , реализованный в виде плагина CadImporter , который поддерживает форматы САПР .iges, .step, и .stl.

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 FbxImporter and CadImporter 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-сцены, также должны быть реализованы в виде плагинов. Таким образом, вы можете рассмотреть плагины FbxImporter и CadImporter в качестве примеров для создания собственных пользовательских модулей импорта. Вы также можете изменить и восстановить эти плагины для использования собственного пользовательского импортера в редакторе (добавляют функциональность для обработки используемых определенных атрибутов моделей САПР, некоторые дополнительные функциональные возможности обработки сцен и т.д.).

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

-extern_plugin FbxImporter

-extern_plugin FbxImporter

In general, the workflow via the C++ API may be represented as follows:В общем виде рабочий процесс через C++ API можно представить следующим образом:

// 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());

You can also load a model with default settings simply like this:Вы также можете загрузить модель с настройками по умолчанию следующим образом:

// 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());

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, а такжеCAD Importer) имеют ряд параметров импорта которые также можно использовать в пользовательских импортерах.

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 в сцену, все сетки в мировой иерархии будут ссылаться на одну сетку, хранящуюся внутри импортированного контейнера 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 — Х 1 — negative X1 — отрицательный X 2 — Y2 — И 3 — negative Y3 — отрицательное И 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 — Х 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, в следующем формате: Исходный код 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 в следующем формате: Исходный код 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. Включает автоматическое создание уровней детализации (LOD) на основе значений параметров lods_postfixes и lods_distances.

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 на основе значений параметров uv_channel, uv_padding, uv_resolution и uv_high_quality.

• FbxImporter plugin as an a example for your custom import plugin: source/plugins/Import/FbxImporter.FbxImporter в качестве примера для вашего пользовательского плагина импорта: source/plugins/Import/FbxImporter.
• CadImporter plugin as an a example for your custom import plugin: source/plugins/Import/CadImporter.CadImporter в качестве примера для вашего пользовательского плагина импорта: source/plugins/Import/CadImporter.
• Custom Import Plugin usage example to learn the basics of writing your own custom import plugin.Пользовательский плагин импорта пример использования, чтобы изучить основы написания собственного пользовательского плагина импорта.
• Importing Models Directly to Memory usage example to learn the basics of writing your own custom import processor.Импорт моделей непосредственно в память пример использования, чтобы изучить основы написания собственного обработчика импорта.

File Import System API:API системы импорта файлов:

• File Import Functionality classes for more details on managing the Import System, importers and processors via code (C++, UnigineScript).
  Примечание

  Import System API is not available for the Community SDK edition.Import System API is not available for the Community SDK edition.
  Import System API is not available for the Community SDK edition.Классы функциональности импорта файлов для получения более подробной информации об управлении системой импорта, модулями импорта и процессорами с помощью кода (C++, UnigineScript).
  Примечание

  Import System API is not available for the Community SDK edition.Системный API импорта недоступен для версии Community SDK.