3D Models

3D models of various standard formats can be used in Maria 3D. Models can be used in various parts of the system, but the most common is to add a 3D model to a point object, such as a track or a point symbol.

In order to use a model it needs to be registered in the INative3DRenderingManager. Models are referenced by a string ID which can be set explicitly with AddModel, or it will be defined in the model config file.

When using the AddModelDirectory method all models with a corresponding model config file will be added.

Model instances

The same model can be added to a scene multiple times with different transforms, i.e the same 3D model can be displayed multiple times in different positions and orientations. This is controlled through the IMap3DInterfacer interface. Use the AddModelInstance method to add an instance of a model with a specific ID, and give it a unique Instance ID. Use this Instance ID to make changes to the model instance later through the various SetModelInstanceTransform methods

Model config files

A 3D model can have an associated model config file. The model config file will define the ID and transform for a model, as well as optionally materials and multiple variants of the same model. There are two formats for this file which will be found as model.cfg or model.json. The JSON format is preferred and new models should only use this.

Example:

{
    "id": "pawn",
    "file": "pawn.fbx",

    "rotate": [ -90.0, 0.0, 0.0 ],
    "translate": [ 0.0, 0.0, 0.0 ],
    "scale": 1.0,

    "variants":
    [
         {
            "id": "pawn_blue",
            "material": "blue.mtl"
        },
        {
            "id": "pawn_red",
            "material": "red.mtl"
        },
        {
            "id": "pawn_green",
            "material": "green.mtl"
        },
        {
            "id": "pawn_yellow",
            "material": "yellow.mtl"
        }
    ]
}

This model has three variants. These will be registered with separate ID's so that if you use a model with id "pawn_green" in Maria 3D, you will get the Pawn model with the green materials applied.

Material files

Material files can be used to modify the materials of a 3D model, such as texture, color and shader. These files are in an internal format tightly bound the "Silent Toolkit" scene graph and material system. This format has a quite rich set of options to modify a 3D mesh or parts of it with various settings, but we will only describe the basics here:

Example:

material {
   name = green
   shader {
      name = DefaultTextureShading
   }

   texture {
	  file = pawn_ao.png
	  min_filter = GL_LINEAR
	  mag_filter = GL_LINEAR
   }
   
   ambient = [ 0.4, 0.6, 0.4 ]
   diffuse = [ 0.6, 1.0, 0.6 ]
   specular = [ 0.0 0.0 0.0 ]
}

binding {
   material = green
}

Material bindings

Each defined material can be bound to specific nodes in the mesh. If no node is specified in the binding, the material is applied to all nodes in the model. Here is an example with multiple materials and node specific bindings:

material {
   name = main_texture
   shader {
      name = DefaultTextureShading
   }

   texture {
	  file = TextureAtlas.png
	  min_filter = GL_LINEAR_MIPMAP_LINEAR
	  mag_filter = GL_LINEAR
   }
}

material {
    name = rotor
    cast_shadows = false   
    transparent = true
    shader {
      name = DefaultShading
    }
}


binding {
   node = fuselage
   material = main_texture

   ambient = [ 0.3, 0.3, 0.3 ]
   diffuse = [ 0.44, 0.47, 0.44 ]
   specular = [ 0.0, 0.0, 0.0 ]
   shininess = 64.0
}

binding {
   node = battery
   material = main_texture

   ambient = [ 0.2, 0.2, 0.2 ]
   diffuse = [ 0.34, 0.37, 0.34 ]
   specular = [ 0.0, 0.0, 0.0 ]
   shininess = 64.0
}

binding {
   node = tail_rotor_hub
   material = main_texture

   ambient = [ 0.1, 0.1, 0.1 ]
   diffuse = [ 0.34, 0.37, 0.34 ]
   specular = [ 0.0, 0.0, 0.0 ]
   shininess = 64.0
}

binding {
   node = main_rotor
   material = rotor

   ambient = [ 0.1, 0.1, 0.1, 0.6 ]
   diffuse = [ 0.2, 0.2, 0.2, 0.6 ]
   specular = [ 0.0, 0.0, 0.0, 0.0 ]
   shininess = 64.0
}

binding {
   node = tail_rotor
   material = rotor

   ambient = [ 0.1, 0.1, 0.1, 0.6 ]
   diffuse = [ 0.2, 0.2, 0.2, 0.6 ]
   specular = [ 0.0, 0.0, 0.0 ]
   shininess = 64.0
}

Note that colors can be specified per node, independently of the rest of the material properties. I.e you can have the same material on multiple nodes, but different color properties.

Version 4.6.0.43 and newer: You only need to include the properties you want to change in the material file, so if all you want is to change the color, the material file should look like this:

material {
   name = green
   ambient = [ 0.4, 0.6, 0.4 ]
   diffuse = [ 0.6, 1.0, 0.6 ]
   specular = [ 0.0 0.0 0.0 ]
}

binding {
   material = green
}

Supported formats

In theory we support all formats that are supported by the assimp asset loading library, but in practice there are only a few formats that are generally well behaved. We have had most success with the following formats:

• Autodesk FBX (.fbx)
• Collada (.dae)
• Wavefront OBJ (.obj)
• Lightwave (.lwo)