################
Input-Output API
################


In addition to the RED file format (see :doc:`/book/subjects/bk_redfileformat`) HOOPS Luminate allows to load external data in other file formats:

    * .FBX (v7.3)
    * .OBJ and .MTL
    * .DXF (v13)
    * .DAE (v1.5)

The import-export operations can be done using the ``RED::IOTools`` functions:

    * ``RED::IOTools::Load`` and
    * ``RED::IOTools::Save``

This API needs an auxiliary module to work: **REDFbx.dll** provided with HOOPS Luminate. Be sure to have it in your application folder before using ``RED::IOTools``. The module is based on the Autodesk FBX SDK 2016.0.

.. note:: 
    
    The REDFbx library requires Microsoft Visual Studio 2010 redistributables.

*********************************
Loading and Saving External Files
*********************************

During a loading operation, all the content of the file is stored in the ``RED::IDataManager`` using contexts like with the .RED files (see :doc:`/book/subjects/bk_rff/bk_redfileformat_load`). A context corresponds to a whole file. So, when the loading is successful, the context array is returned with at least one new entry. Contexts are logical views of the content of a file. They let you access to parts of file even after it may have been merged with other into the ``RED::IDataManager``.

.. include:: /tasks/ta_ca/ta_ca_file/tk_loading_io_file.rst

.. include:: /tasks/ta_ca/ta_ca_file/tk_accessing_to_loaded_data.rst

With the ``RED::IOTools::Save`` function, HOOPS Luminate can export a list of complete scenegraphes and viewpoints to an external file format.

.. include:: /tasks/ta_ca/ta_ca_file/tk_saving_io_file.rst

******************
Importing FBX File
******************

From an external FBX file, the ``RED::IOTools`` function imports the following features:

    * Complete scenegraph node hierarchy and the transform matrices
    * Mesh and line shapes
    * Materials with textures
    * Cameras
    * Lights

The ``RED::IOTools::Load`` function lets the user defines which objects he want to import using the ``RED::IO_OBJECT_TYPE`` flags.

HOOPS Luminate converts the FBX scenes to right-handed Z-up coordinates. Units are converted to cm.

Scene Graph
-----------

The FBX node hierarchy and their transform matrices are imported as ``RED::ITransformShape``.

Mesh
----

FBX meshes data are imported into HOOPS Luminate as ``RED::IMeshShape`` following these rules:

    * Vertex position in the ``RED::MCL_VERTEX`` channel
    * Vertex color in the ``RED::MCL_COLOR`` channel
    * Normal in the ``RED::MCL_NORMAL`` channel
    * Texture coordinates in the ``RED::MCL_TEX0`` to ``RED::MCL_TEX7`` channels
    * Tangent and binormal are stored in the ``RED::MCL_USER0`` and ``RED::MCL_USER1`` channels

FBX skeleton and skinning data are also imported and stored in the ``RED::IMeshShape``.

If the FBX file contains a skinned mesh and a skeleton, the skinned mesh parent nodes will be ignored and the mesh object will be moved as child of the (animated) skeleton parent node.

.. figure:: API_FbxSkinnedMesh.png
    :align: center
    
    **Skinned mesh moved under its skeleton**

During the loading process, the meshes are triangulated and split to have one material per mesh. The vertices are duplicated to have one normal per vertex if needed.

.. note:: 
    
    To speed-up the loading function, one should ensure that his models are already in the correct RED format (triangles, one color / normal / texcoord per vertex).

FBX line data are imported as ``RED::ILineShape`` following the same rules as meshes. FBX line shapes don't handle materials. The HOOPS Luminate default material will be applied and used for display. ``RED::ILineShape`` objects will contain segment primitives.

.. note:: 
    
    The fbx file format doesn't support point primitives (``RED::IPointShape``).

Material
--------

According to a parameter, user can specify which type of RED material he wants to create during the FBX material import (``RED::IO_LOAD_MATERIAL_TYPE``):

    * Generic material (uses ``RED::IMaterial::SetupGenericMaterial``)
    * Realistic material (uses ``RED::IMaterial::SetupRealisticMaterial``)

All the FBX Lambert or Phong material properties are translated to the RED generic material. This includes:

    * Emissive color and texture
    * Ambient color and texture
    * Diffuse color and texture
    * Specular color and texture as well as shininess
    * Transparency color and texture
    * Bump texture

The Realistic material only handles these parameters:

    * Diffuse color and texture
    * Transparency color and texture
    * Bump texture

Material textures are loaded from the FBX specified filename. If not found, HOOPS Luminate searches images next to the FBX file. For transparency textures, HOOPS Luminate lets the user choose the transparency channel (``RED::IO_LOAD_TEXTURE_TRANSPARENCY``). Sometimes transparency data can be in the alpha channel of the diffuse texture, sometimes it can be in the RGB channels. Material textures are automatically bound to the correct mesh texture coordinate channels.

Light
-----

HOOPS Luminate imports the following FBX light types and their parameters as well as their attenuation data:

    * Ambient Light
    * Directional Light
    * Spot Light
    * Point Light
    * Rectangular Area Light

The rectangular area lights are built with the ``RED::ILightShape::SetRectangularAreaLight`` function. The number of sample is set to 4 by default. If you want to change it, just get the light and call ``RED::ILightShape::SetSamplesCount``. The size of the area is set to 1 unit since FBX sdk only supports unit areas. The size is controlled by the parent node scale transform.

Camera
------

FBX target and free cameras are loaded as ``RED::IViewpoint``. They can be perspective or orthographic.

.. note:: 
    
    HOOPS Luminate viewpoints are always at the root of the scenegraph. All the node hierarchy upper to the FBX camera will be ignored during the loading of the file.

Animation
---------

FBX node transform animations are imported as ``RED::IAnimationClipController``. They are not linked to any transform shape as they can be used to animate anything. User must use it manually to move its target object (see the tutorial: :doc:`/tutorials/workflows/wf_realtime/wf_playing_an_animation_clip`).

FBX skeletal animations are imported as ``RED::ISkeletalAnimationController``. This type of animation is linked to a skinned ``RED::IMeshShape`` object if the associated skinned mesh is included in the FBX. If not, it must be associated by the user later (``RED::ISkeletalAnimationController::AddSkinnedMesh``).

******************
Exporting FBX File
******************

The ``RED::IOTools`` function exports the following HOOPS Luminate features into FBX:

    * Complete scenegraph node hierarchy and the transform matrices
    * Mesh and line shapes
    * Generic and realistic materials with textures
    * Viewpoints
    * Lights

The ``RED::IOTools::Save`` function lets the user defines which objects he want to export using the ``RED::IO_OBJECT_TYPE`` flags.

Scene Graph
-----------

The RED Direct Acyclic scene Graph is completely saved in FBX as node containing transform matrices.

Mesh
----

``RED::IMeshShape`` are exported as FBX meshes. The exported meshes contain only triangles. Their data are:

    * Vertex position (``RED::MCL_VERTEX``)
    * Vertex color (``RED::MCL_COLOR``)
    * Normal (``RED::MCL_NORMAL``)
    * Texture coordinates (``RED::MCL_TEX0`` to ``RED::MCL_TEX7``)
    * ``RED::MCL_USER0`` and ``RED::MCL_USER1`` are saved as tangent and binormal data

Skeletons are exported as a hierarchy of FBX nodes. Skinning data are exported as FBX mesh data.

``RED::ILineShape`` are exported as FBX lines. Arbitrary line strips are built during export for ``RED::ILineShape`` objects containing segment primitives.

.. note:: 
    
    The fbx file format doesn't support point primitives (``RED::IPointShape``).

Material
--------

The HOOPS Luminate material export is based on the associated ``RED::IMaterialController`` and its ``RED::IMaterialControllerProperty`` list. Only materials with valid property names are exported to FBX.

Properties currently exported are:

* Emissive (``RED_MATCTRL_EMISSIVE_COLOR``, ``RED_MATCTRL_EMISSIVE_TEXTURE``, ``RED_MATCTRL_EMISSIVE_CHANNEL``, ``RED_MATCTRL_EMISSIVE_MATRIX``)
* Ambient (``RED_MATCTRL_AMBIENT_COLOR``, ``RED_MATCTRL_AMBIENT_TEXTURE``, ``RED_MATCTRL_AMBIENT_CHANNEL``, ``RED_MATCTRL_AMBIENT_MATRIX``)
* Diffuse (``RED_MATCTRL_DIFFUSE_COLOR``, ``RED_MATCTRL_DIFFUSE_TEXTURE``, ``RED_MATCTRL_DIFFUSE_CHANNEL``, ``RED_MATCTRL_DIFFUSE_MATRIX``)
* Specular (``RED_MATCTRL_SPECULAR_COLOR``, ``RED_MATCTRL_SPECULAR_TEXTURE``, ``RED_MATCTRL_SPECULAR_CHANNEL``, ``RED_MATCTRL_SPECULAR_MATRIX``, ``RED_MATCTRL_SPECULAR_EXPONENT``)
* Opacity (``RED_MATCTRL_OPACITY_COLOR``, ``RED_MATCTRL_OPACITY_TEXTURE``, ``RED_MATCTRL_OPACITY_CHANNEL``, ``RED_MATCTRL_OPACITY_MATRIX``)
* Bump (``RED_MATCTRL_BUMP_TEXTURE``, ``RED_MATCTRL_BUMP_CHANNEL``, ``RED_MATCTRL_BUMP_MATRIX``)

Generic and realistic materials can be exported to FBX as they have a controller handling these valid property names.

The ``RED::IOTools::Save`` function saves all the material textures on disk next to the output file. They are then embedded into the FBX file and thus can be deleted from the output folder. Textures are saved as PNG files. Material textures are automatically bound to the correct mesh texture coordinate channels.

Light
-----

``RED::ILightShape`` objects are exported to FBX files. Light type can be:

    * Ambient
    * Directional
    * Spot
    * Point
    * Rectangular Area

The size of the rectangular area light is set to 1 unit at export since FBX sdk only supports unit areas. The size set in HOOPS Luminate is converted to scaling and applied to the parent node.

Camera
------

``RED::IViewpoint`` objects are exported as FBX cameras. The first viewpoint of the provided list is defined as the default FBX camera. Orthographic and perspective cameras are exported.

Animation
---------

``RED::IAnimationClipController`` objects are exported as FBX animated nodes.

In HOOPS Luminate, the ``RED::IAnimationClipController`` objects are not linked with any scenegraph object. The basic animations are saved as animated nodes located under a node named **"Animations"** directly under the FBX root. When opening the .FBX file with another 3D graphics software, the user have to reassign the animations to their proper objects.

Skeletal animations (``RED::ISkeletalAnimationController``) are exported as animation curves for the skeleton nodes already exported.

**********************************************
Importing and Exporting OBJ, DAE and DXF Files
**********************************************

HOOPS Luminate uses the FBX SDK to deal with OBJ, DAE and DXF files. Therefore, the majority of the FBX options described previously also applied for these formats.

Several limitations may occurs when using these formats. They may come from the format itself or from the FBX sdk.

OBJ Format
----------

OBJ files contains only geometry data:

    * Vertex
    * Color
    * Normal
    * Texture Coordinates

Unlike .FBX, .OBJ does not contain:

    * Node Matrix Hierarchy
    * Lights
    * Camera
    * Animation

A separate .MTL file can be associated to the .OBJ to specify material informations:

    * Ambient Color and Texture
    * Diffuse Color and Texture
    * Specular Color and Texture
    * Transparency Value and Texture

Due to the FBX sdk, only diffuse textures are correctly exported to the .MTL file (no ambient texture, specular texture or transparency texture). The OBJ file format does not handle bump data. The texture coordinates translations, scales and rotations are not saved.

The OBJ format handles only one texture coordinates channel. The FBX sdk does not export the materials of objects with more than one texture coordinates channel.

DAE Format
----------

The DAE format allows to store:

    * Vertex Data (Vertex, Normal, Color, Texture Coordinates)
    * Node Matrix Hierarchy
    * Lights
    * Camera
    * Materials

The DAE format does not handle bump data. UV transforms are not exported in the DAE file.

The FBX sdk prevents the transparency textures to be saved. However they can be loaded correctly.

DXF Format
----------

The DXF file format is the most restrictive. It can only store the vertex positions, but not the normals nor the texture coordinates.

Also, only material diffuse color is correctly exported and imported.

No lights, camera or scene hierarchy is handled by the DXF format.
