RealityServer Features

glTF importer

The glTF importer imports the glTF 2.0 file format which has been standardised by the Khronos Group. The glTF file format has excellent functionality for representing physically based materials and is now widely used in many industries.

Scene Structure and Attributes

In general the importer will try to preserve as much of the structure of the scene graph defined in glTF as possible. Due to the requirements of the RealityServer database not all structures can be represented identically and additional elements may need to be created to ensure the resulting scene renders with the same appearance.

To allow post processing of imported glTF data with reference to information from the original file, in many cases the importer will create additional attributes on imported elements to preserve data contained in the glTF file. All such attributes are prefixed with gltf:: to allow them to be easily identified. The two most important attributes you will find on imported elements are gltf::name and gltf::extras which are obtained from the glTF name and extras properties. These properties are both optional. In the case of the extras these are stored directly as a JSON string and require decoding before use.

An exhaustive list of created attributes is not provided as this may change over time. However the easiest way to see which attributes are being created is to call the element_get_graph command on your scene with the include_attributes options set to true. This will give you a complete list of all attributes on all elements in the scene.

Supported Extensions

glTF has the concept of extensions. These are features which are not part of the core specification but add additional functionality to the format. There are both official Khronos extensions as well as vendor extensions. The glTF importer aims to support all appropriate official Khronos extensions as they become ratified and vendor extensions based on demand from our users. New glTF extensions are being considered and ratified on a regular basis and so extension support will continue to evolve. The following section provides details on the currently supported extensions.

  • KHR_draco_mesh_compression
  • KHR_lights_punctual
  • KHR_materials_clearcoat
  • KHR_materials_pbrSpecularGlossiness
  • KHR_materials_sheen
  • KHR_materials_transmission
  • KHR_materials_variants
  • KHR_mesh_quantization
  • KHR_texture_basisu
  • KHR_texture_transform
  • KHR_xmp
  • PTC_onshape_metadata

The following extensions have not been ratified at the time of this release however are already in active development and will be supported in a future release of RealityServer.

  • KHR_materials_ior
  • KHR_materials_thinfilm
  • KHR_materials_specular
  • KHR_materials_translucency
  • KHR_materials_volume

Unsupported Extensions and Features

Some extensions and glTF functionality does not make sense to support in RealityServer due to its physically correct nature. There are also certain types of geometry that currently are not able to be used. The following section provides details on which extensions are currently unsupported.

  • KHR_materials_unlit

The following are features of the glTF standard which are currently unsupported by RealityServer.

  • Non-triangular Primitives (e.g., POINTS and LINES)
  • Morph Targets
  • Skins

Name Templating

When importing a glTF document it can be useful to override the default naming scheme. The glTF importer supports name templating via the name_templates importer option.

The name template syntax is inspired by javascript template strings and the JSON Pointer syntax. A variable in a template string can be referenced by using the syntax ${expression}. Where expression is one of the following JSON Pointer formatted strings:

  • /* Look up a field in the glTF JSON root document using the JSON pointer following the / specifier.
  • ./* Look up a field in the glTF document relative to the current parser element using the JSON pointer following the ./ specifier. For instance when naming a material, the JSON Pointer lookup will be relative to the glTF material being imported.
  • ext/* Look up the JSON data provided to the importer via the name_templates_context option using JSON pointer syntax following the ext/ specifier.
  • var/* Look up an importer variable after the var/ specifier by name. The variables available will vary across importer element types.
  • url/* Encode everything following the url/ specifier as a URL.
  • jsonptr/* Encode everything following the jsonptr/ specifier for use in a JSON Pointer.
  • ?:/*/*/*Test whether the first parameter in the path is empty, if it is not empty the second parmater is used, if it is empty the third parameter is used. This can be used to provide a fallback to a variable in case it doesn't exist, for instance referencing an attribute of the glTF document.

For more information on JSON Pointer formatting including escape characters, see JavaScript Object Notation (JSON) Pointer [RFC 6901]

Templates may be nested and are evaluated from in inner-most to outer-most in left to right order. For instance it's possible to specify ${jsonptr/${./name}} which would first look up the name attribute from the currently parsed element and proceed to ecode it as a JSON Pointer. In addition, characters in a string template may be escaped by using the backslash \ character.

Importer elements that may be assigned name templates have the following type ids:

  • root
  • options
  • node_instance
  • node_group
  • node_camera
  • camera
  • default_camera
  • default_camera_instance
  • node_light
  • light
  • light_material
  • mesh
  • mesh_primitive
  • image
  • material
  • default_material
  • material_base_color
  • material_cutout_opacity
  • texture_call
  • transmission_color_r
  • data_lookup_color
  • data_lookup_float
  • scale_color
  • scale_float
  • coord_src
  • coord_src_call
  • file_texture_call
  • rotation_translation_scale
  • transform_call
  • default_environment_image
  • default_environment_texture
  • default_environment_function_call

Importer variables that may be referenced by the var/* directive include:

  • uuid Generates a v4 UUID unique to the element.
  • type The importer element type.
  • index The gltf index of the element.
  • material_name The material name used when naming material properties.
  • call_name The name of the parent material/function argument, for instance cutout_opacity, sheen_color, etc. Available when naming material properties.
  • onshape_id An Onshape id created by concatenating all parent Onshape ids using a '>' delimitter.
  • mesh_index The index of the parent mesh, available when naming mesh primitives.
  • prefix Used when generating names for mdl functions, includes results of parent name templating.

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 glTF importer. This is in addition to the standard options provided by all importers.

glTF Importer Options
Property Key Default Description
default_environment true If false, no default lighting environment will be created. By default a simple HDRI image based lighting environment and tone-mapping is used.
scene 0 glTF allows multiple scenes to be specified. By default the scene specified by the scene property in the glTF file will be used if this property exists. Otherwise the first scene will be used. If a numeric scene index is provided by this option then the numbered scene will be used instead.
material_variant None The KHR_material_variants extension if present allows multiple material configurations to be specified within a single glTF file. By default the materials specified on glTF meshes will be used. If a numeric value is given for this property then the material variant from the glTF file with that index will be used instead. If a string is given for this property then the list of variants will be searched for a variant with a name property matching the string given and then that variant will be used instead.
import_material_variants true The KHR_material_variants extension if present allows multiple material configurations to be specified within a single glTF file. If this property is set to true (the default) and the KHR_material_variants extension is used by the glTF file then all materials which are used by any variant will also be imported in addition to the base material assigned to the glTF meshes. If this property is false then only either the base material on the mesh, or if the material_variant property is provided, the specified material variant will be imported. The material variant list is stored as a JSON encoded string in the gltf::material_variants attribute on the rootgroup Group element of the imported scene. This holds the list of all available material variants. On each element which is assigned a material that uses variants a gltf::material_variant_mappings attribute will be stored as a JSON encoded string. This stores an array of mappings from each material to the variants which use it. The material index used in the glTF file will be replaced with the element name of the Material_instance element of the appropriate material. To switch between variants the gltf_material_variant command is provided which takes the name of the root group cointaining the variant data and the index or name of the variant to switch to.
base_uri None The glTF importer is able to load resources such as binary data and textures from remote servers if a remote URI is specified in the file. This will happen automatically when the URI provides a protocol (http or https) however it is also possible to force all resources to be loaded from a remote URI by providing an alternative base URI using this option. This base_uri string will be added to the start of the resource URI before RealityServer attempts to load it. This is useful for example when a glTF file is downloaded from a server but the resources referenced in the file relative to that file (on the same server).
node_collapse_index 0 Instance elements created from glTF scene nodes will have the mig::collapse attribute set to true at the node depth level specified by this attribute. Negative indices will be referenced from the leaf scene nodes. For instance -2 will apply the collapse attribute to the parent nodes of the scene graph leaf nodes. Whereas an index of 1 would apply the collapse attribute to nodes directly to the scene root nodes. A value of 0 disables the attribute.
collapse_elements None Scene graph elements may have a mig::collapse attribute set to 1 if the element type is included in the collapse_elements importer options string array. For instance a value of ["node_instance"] would apply the collapse attribute to all scene node instances created by the importer. Currently the only supported element tyoe is node_instance.
srgb_encoded_colors false Colors in the glTF document will be gamma corrected from sRGB color space to linear, using a gamma value of 2.2. This affects both material color values as well as vertex colors.
diffuse_scaling 1 Diffuse colors in the glTF document can be optionally uniformally scaled by the diffuse_scaling number.
name_templates None A map of importer element types mapped to name template strings. An element type is looked up in the map and its resulting template string is resolved to create the element name. The name template may refer to internal importer state or the optional name_templates_context JSON data. See section Name Templating for more information.
name_templates_context None A JSON encoded string that may be queried in element name templates. The encoded data may be any valid JSON data type.

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

{
    "method": "import_scene",
    "params": {
        "scene_name": "my_scene",
        "filename": "my_file.gltf",
        "import_options": {
            "default_environment": false,
            "scene": 3,
            "base_uri": "https://example.com/resources/"
        }
    }
}