RealityServer Features

OBJ importer

The OBJ importer imports the common Wavefront OBJ 3D file format as well as the associated .mtl format allowing OBJ files to reference basic materials. The OBJ file format is a relatively loose standard and there exist many variants which diverge from the established specifications. For this reason the importer offers several options to vary the interpretation of OBJ file and material parameters. Options are also provided for selectively enabling and disabling the automatic creation of elements not represented in OBJ such as cameras and lights.

Importer Options

When using the importer through the import_scene, import_scene_elements or import_scene_elements_from_string commands in RealityServer it is possible to provide additional options through the use of the import_options parameter. This parameter accepts a Map where the property key corresponds to the option name and the value to the value you want to set for the option. The table below describes the options available for the OBJ importer. This is in addition to the standard options provided by all importers.

OBJ Importer Options
Property Key Default Description
no_lights false If true, no default lights will be created. By default four directional lights are created to illuminate the imported content.
no_camera false If true, no default camera will be created. By default a camera fitting the scene in the view is created. Note: take care when using this with import_scene since the resulting scene will not contain a camera and not render until you associate one with it.
no_options false If true, no options will be created. By default an options element for the scene is created with basic settings. Note: take care when using this with import_scene since the resulting scene will not contain an options element not render until you associate one with it.
no_daylight false If true, no daylighting environment will be created. By default a daylighting environment is created to help illuminate the scene.
invert_transparency false Setting this to true will cause every materials transparency value (d or tr) to be inverted. This option is provided for cases were the .mtl file incorrectly specifies zero as opaque. We have found this error to be common enough in OBJ files to require this option to be available.
collapse_groups false By default the OBJ importer will maintain the groups in the .obj file. Where possible the geometry instances generated from these groups will have the same name as the .obj group. If two or more groups have the same name then the OBJ importer will append a unique identifier to the group name. If the .obj group structure is not desired then groups can be condensed into one geometry instance by setting this option to true.
clockwise_winding false By default the OBJ importer will use counter clockwise winding to generate normals if none are present in the file. To use clockwise winding set this option to true. This has no effect if the .obj file supplies its own normals.
emission_intensity 7.0 Intensity by which to multiply the emission color if used on materials in the .mtl file. Can be useful since OBJ materials typically do not specify colors outside the 0-1 range and so will not emit much light.
ignore_obj_tags null A Map where the property keys represent OBJ tag names and the value is a boolean instructing the importer whether it should ignore the given tag or not. Useful for omitting parts of the .obj file that might produce undesirable results.
ignore_mtl_tags null A Map where the property keys represent .mtl file tag names and the value is a boolean instructing the importer whether it should ignore the given tag or not. Useful for omitting parts of the .mtl file that might produce undesirable or disabling features of OBJ materials. For example one can easily remove all diffuse textures by ignoring the map_Kd tag.

Example: Imports an OBJ file as a scene and sets various options. 

{
    "method": "import_scene",
    "params": {
        "scene_name": "my_scene",
        "filename": "my_file.obj",
        "import_options": {
            "no_lights": true,
            "no_daylight": false,
            "no_camera": false,
            "no_options": false,
            "invert_transparency": true,
            "collapse_groups": false,
            "clockwise_winding": false,
            "emission_intensity": 100.0,
            "ignore_obj_tags": {},
            "ignore_mtl_tags": {
                "map_Ka": true,
                "Ka": true
            }
        }
    }
}