Mexximp Mappings

RenderToolbox allows you to specify mappings that modify the imported 3D scene, before converting to any renderer-native format. These mappings must use the destination mexximp.

These mappings will apply to the struct representation of the scene provided by the mexximp tool that RenderToolbox uses internally.

You can explore this scene representation yourself. For example:

>> [scene, elements] = mexximpCleanImport(which('Dragon.blend'))

scene = 

             cameras: [1x1 struct]
              lights: []
           materials: [1x4 struct]
              meshes: [1x7 struct]
    embeddedTextures: []
            rootNode: [1x1 struct]


elements = 

1x21 struct array with fields:

    name
    type
    path

This will give you a scene struct which represents the scene in a hierarchical, intuitive way. It will also give you a struct array elements, which is a flattened view of the same scene struct.

Mexximp Scene Elements

Here are several examples of mexximp scene elements that you can specify in the mappings file, with destination mexximp.

Each element is presented as a JSON object which you could copy into your mappings file. You could change the property names to other field names within the scene struct. You could change the property values to anything sensible.

You should also change the mapping name field to the name of an element in your own 3D scene.

cameras

The cameras field of the scene struct can contain zero or more cameras. Usually there's only one. Here's an example:

>> scene.cameras

ans = 

               name: 'Camera'
           position: [3x1 double]
    lookAtDirection: [3x1 double]
        upDirection: [3x1 double]
        aspectRatio: 0
      horizontalFov: 0.4288
       clipPlaneFar: 100
      clipPlaneNear: 0.1000

You can use mappings to specify a value for any camera field, for example the horizontalFov, which is in radians:

{
  "name": "Camera",
  "broadType": "cameras",
  "destination": "mexximp",
  "operation": "update",
  "properties": {
    "name": "horizontalFov",
    "value": 1.0472
  }
}

lights

The lights field of the scene struct can contain zero or more light sources. Each light may have type directional, point, or spot. Here's an example:

>> scene.lights

ans = 

                    name: 'Point'
                position: [3x1 double]
                    type: 'point'
         lookAtDirection: [3x1 double]
          innerConeAngle: 1
          outerConeAngle: 1
     constantAttenuation: 0
       linearAttenuation: 0
    quadraticAttenuation: 0
            ambientColor: [3x1 double]
            diffuseColor: [3x1 double]
           specularColor: [3x1 double]

You can use mappings to specify a value for any light field. Use the name or index field to select one light in particular.

{
  "name": "Point",
  "index": 1, 
  "broadType": "lights",
  "destination": "mexximp",
  "operation": "update",
  "properties": {
    "name": "diffuseColor",
    "value": [1 1 0]
  }
}

meshes

The meshes field of the scene struct can contain zero or more mesh objects. These are holders for geometry data like vertices, normals, faces, etc.

>> scene.meshes(2)

ans = 

                   name: 'Plane'
          materialIndex: 1
         primitiveTypes: [1x1 struct]
               vertices: [3x4 double]
                  faces: [1x2 struct]
                colors0: [4x0 double]
                colors1: [4x0 double]
                colors2: [4x0 double]
                colors3: [4x0 double]
                colors4: [4x0 double]
                colors5: [4x0 double]
                colors6: [4x0 double]
                colors7: [4x0 double]
                normals: [3x4 double]
               tangents: [3x0 double]
             bitangents: [3x0 double]
    textureCoordinates0: [3x0 double]
    textureCoordinates1: [3x0 double]
    textureCoordinates2: [3x0 double]
    textureCoordinates3: [3x0 double]
    textureCoordinates4: [3x0 double]
    textureCoordinates5: [3x0 double]
    textureCoordinates6: [3x0 double]
    textureCoordinates7: [3x0 double]

You can use mappings to specify a value for any mesh field, for example the vertices, which is a 3xn matrix of xyz points. This example uses a custom operation to shrink the mesh.

{
  "name": "Plane",
  "broadType": "meshes",
  "destination": "mexximp",
  "operation": "update",
  "properties": {
    "name": "vertices",
    "operation": "mexximpApplyTransform(oldValue, mexximpScale([0.5 0.5 0.5]))"
  }
}

nodes

The rootNode field of the scene struct contains a hierarchy of nodes. Each node has a spatial transformation and points to one or more of the scene meshes. Thus, nodes are the way objects get placed into the 3D scene.

>> scene.rootNode

ans = 

              name: '<BlenderRoot>'
       meshIndices: []
    transformation: [4x4 double]
          children: [1x8 struct]

>> scene.rootNode.children(7)

ans = 

              name: 'Dragon'
       meshIndices: 6
    transformation: [4x4 double]
          children: []

You can use mappings to specify a value for any node field, for example the transformation, which is a 4x4 matrix. This example uses a custom operation to specify a new position for a mesh object:

{
  "name": "Dragon",
  "broadType": "nodes",
  "destination": "mexximp",
  "operation": "update",
  "properties": {
    "name": "transformation",
    "operation": "mexximpTranslate([10 20 -30])"
  }
}

This example uses a custom operation to adjust the current camera position by rotating it pi/6 radians about the x-axis:

{
  "name": "Camera",
  "broadType": "nodes",
  "destination": "mexximp",
  "operation": "update",
  "properties": {
    "name": "transformation",
    "operation": "mexximpTranslate([1 0 0], pi()/6) * oldValue"
  }
}

embeddedTextures

Embedded textures are a way for mexximp scenes to incorporate image textures directly, as binary data. This is an alternative to referring to an external image file by name.

We have not yet encountered a scene that requires embedded textures. Moreover, image data embedded in the scene itself would not be accessible to renderers further on in the workflow.

You should use other kinds of mappings like Generic, PBRT, and Mitsuba to specify textures that refer to external image files.

materials

The materials field of the scene struct can contain zero or more surface reflectance materials. Here's what mexximp materials look like:

>> scene.materials

ans = 

1x2 struct array with fields:

    properties

>> scene.materials(1).properties

ans = 

1x40 struct array with fields:

    key
    dataType
    data
    textureSemantic
    textureIndex
>> scene.materials(1).properties(2)

ans = 

                key: 'specular'
           dataType: 'float'
               data: [1 1 1]
    textureSemantic: 'none'
       textureIndex: 0

As you can see, the representation of materials in mexximp is deeply nested and rather cumbersome. It's also restricted to RGB color values.

You could try to specify materials using mexximp mappings, but it would be awkward. Instead, you should use other kinds of mappings like Generic, PBRT, and Mitsuba.