UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes

Import System

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.

Warning
Runtime import feature is available only for Engineering and Sim SDK editions.

Imported Scene is a set of metadata on objects to be brought to UNIGINE, which can contain the following components:

  • Lights
  • Cameras
  • Meshes
  • Mesh animations
  • Textures
  • Materials
  • Nodes

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

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.

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.

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:

  • Pre-processor — performs additional operations on scene metadata (ImportScene) and prepares it for the object generation stage.
  • 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.
  • 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.

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

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

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.

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

Customization#

The Import System is utilized by both the Engine and the Editor. Out-of-the-box it currently offers:

  • Importer for FBX scenes implemented as FbxImporter plugin, which in addition to .fbx format also supports .obj, .dae, and .3ds.
  • Importer for CAD models implemented as CadImporter plugin, which supports .iges, .step, and .stl CAD formats.

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

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:

Shell commands
-extern_plugin FbxImport

In general, the workflow via the C++ API may be represented as follows:

Source code (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());

You can also load a model with default settings simply like this:

Source code (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());

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.

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.

need_reset_mesh
Deletes the mesh from the FBX SDK after it has been converted.
  • 0 — disabled (by default)
  • 1 — to enable
create_unique_material_names
Creates unique names for materials with identical names.
  • 0 — disable
  • 1 — enabled (by default)
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)
  • 1 — to enable
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).
  • 1 — Specular workflow that uses the old standard of textures that was used in mesh_base material (diffuse, specular, gloss).
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)
  • 1 — to enable
import_tangent_space
Imports built-in tangent space data instead of recalculating it.
  • 0 — disabled (by default)
  • 1 — to enable
Notice
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.
import_morph_targets
Imports morph targets from the file.
  • 0 — disabled (by default)
  • 1 — to enable
create_transform_bones_for_joints
Imports the hierarchy of the joints (bones) for animated assets as a list of World Transform Bones.
  • 0 — disabled (by default)
  • 1 — to enable
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.
  • 0 — disabled (by default)
  • 1 — to enable
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.
  • 0 — disabled (by default)
  • 1 — to enable
up_axis
Defines which axis is the up vector of the World Coordinate System.
  • -1 — none (by default)
  • 0 — X
  • 1 — negative X
  • 2 — Y
  • 3 — negative Y
  • 4 — Z
  • 5 — negative Z
Notice
The up_axis value should be different from the front_axis value.
front_axis
Defines which axis is the forward vector of the World Coordinate System.
  • -1 — none (by default)
  • 0 — X
  • 1 — negative X
  • 2 — Y
  • 3 — negative Y
  • 4 — Z
  • 5 — negative Z
Notice
The front_axis value should be different from the up_axis value.
need_triangulate
Enables correct triangulation of meshes, NURBS and patches.
  • 0 — disabled (by default)
  • 1 — to enable
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.
  • 0 — disabled (by default)
  • 1 — to enable
merge_similar_materials
Merges materials with the same settings, but different names.
  • 0 — disabled (by default)
  • 1 — to enable
uv_channel
Sets the UV channel to store the lightmap.
  • 0 — Channel 0
  • 1 — Channel 1
Requires adding CreateUV post-processor.
uv_padding
Sets the padding value from 0 to 8, in pixels. The default value is 0. Requires adding CreateUV post-processor.
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.
uv_high_quality
Defines the efficiency of UV islands layout on the texture.
  • 0 — Low quality (by default)
  • 1 — High quality
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.

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.


The following table lists the names for the parameters available out of the box that can be set via the setParameterString("name", value) method.

lods_postfixes
Lists the postfixes to be used to differeciate between LODs, in the following format:
Source code
importer->setParameterString("lods_postfixes", "_lod_0,_lod_1,_lod_2");
Requires adding CombineByPostfixes pre-processor.
Notice
The amount of postfixes should be the same as the amount of listed lods_distances.
lods_distances
Lists the minimum distances for LODs, in the following format:
Source code
importer->setParameterString("lods_distances", "-1e+09,3,9");
Requires adding CombineByPostfixes pre-processor.
Notice
The amount of distances should be the same as the amount of listed 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.

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.
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.
CombineByPostfixes
Enables automatic creation of the Levels of Detail (LODs) based on the values of the lods_postfixes and lods_distances parameters.

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.

CreateUV
Creates UV based on the values of uv_channel, uv_padding, uv_resolution, and uv_high_quality parameters.

See Also#

  • FbxImporter plugin as an a example for your custom import plugin: source/plugins/Import/FbxImporter.
  • CadImporter plugin as an a example for your custom import plugin: 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:

  • File Import Functionality classes for more details on managing the Import System, importers and processors via code (C++, UnigineScript).

    Notice
    Import System API is not available for the Community SDK edition.
Last update: 2020-08-25