MI format (Mental Images)

Introduction

MI files primarily describe a scene to be rendered for the Mental Ray rendering engine and are most often generated from the SoftImage modelling package. For a full description of the MI format see "SOFTIMAGE|3D, Mental Ray Programmer's Guide".

The MI format uses a right handed coordinate system with x to the left, y upwards, and Z out of the page. The camera is fixed at the origin looking down the negative z axes, the objects in the scene are transformed so as to make this the correct view.

General

list of commands
frame number [time]
   list of lights, textures, and materials
   view description
   list of lights, textures, materials, and objects
end frame

An MI files can contain any number of these structures called frames, each frame describes one rendered image. The lights, textures, materials, and objects can appear in any order except that a view must precede the object definition.
Comments are indicated by a # and extend to the end of the line.

Commands

Lights

Mental Ray knows about point light sources and infinite light sources (parallel rays in a particular direction).

light "name of light"
   "shader (any_parameters)
   [area_light_primitive]
   [origin x y z]
   [direction x y z]
end light

Point light sources define an origin but no direction, the reverse applies to infinite light sources. An area_light_primitive is a way of applying a point source into an area light, it can be applied to either a rectangle, disc, or sphere.

Textures

MI supports two types of textures, images and procedural. The first is implemented with picture files, the second as a shading function. Textures can be used to specify scalars, colours, or vectors.

scalar texture "texture name" [width hight [depth]] bytes ...
[local] scalar texture "texture name" "filename"
scalar texture "texture name" "shader name" (parameters)

color texture "texture name" [width hight [depth]] bytes ...
[local] color texture "texture name" "filename"
color texture "texture name" "shader name" (parameters)

vector texture "texture name" [width hight [depth]] bytes ...
[local] vector texture "texture name" "filename"
vector texture "texture name" "shader name" (parameters)

Materials

Materials define the appearance of objects and is done entirely thought shaders.

material "material name" [nocontour] [opaque]
   "material shader name" (parameters)
   [displace "displacement shader name" (parameters)]
   [shadow "shadow shader name" (parameters)]
   [volume "volume shader name" (parameters)]
   [environment "environment shader name" (parameters)]
end material

View

A view specifies an output file type to result from a rendering. It can be a image file or a filter that operates on the rendered image.

view
   output_definitions
   view_definitions
end view

Objects

object "name of object"
   [visible]
   [shadow]
   [trace]
   [tag label_number]
   [transform 4x4_matrix]
   [basis list]
   group
      [merge eps]
      vector list
      vertex list
      geometry list
   end group
     :
     :
     further group definitions
     :
     :
end object

For some strange reason the default is for an object to be invisible, the visible flag usually needs to be set.

All group objects must contain a vector and vertex list. The vector list is simply a list of triples, points in 3D space. These points might represent vectors, normals, or texture coordinates. Vectors are usually stored as numbers represented as printable characters although MI does support a binary form of 12 bytes in IEEE 854, this is of course hardware (endian) dependent.

Vertices are defined by reference to the vector list which is numbered from 0 upwards and the numbering restarts from 0 for each group. A vertex list consists of a series of types with an associated index. The types may be 'v' for a point in space, 'n' for a normal, 'm' for a motion vector, and 't' for texture coordinate. A vertex starts with the type v and end at the occurrence of the next v.
For example, a square polygon with a gold texture might be defined as follows

object "plane"
   visible
   shadow
   group
      0 0 0
      0 1 0
      1 1 0
      1 0 0
      0 0 1
      v 0 n 4
      v 1 n 4
      v 2 n 4
      v 3 n 4
      p "goldmaterial" 0 1 2 3
   end group
end object

Two types of geometry can be defined, polygonal geometry as in the above example and free-form surfaces.

Polygonal geometry can be one of three types. 'c' for convex polygons (also cp for backward compatibility), 'p' for concave polygons optionally with holes specified by the 'hole' keyword. All polygons are defined in terms of vertex numbers, numbered from 0 upwards.

   c  "material name" list_of_vertex_numbers
   cp "material name" list_of_vertex_numbers
   p  "material name" list_of_vertex_numbers
   p  "material name" list_of_vertex_numbers hole list_of_vertex_numbers

Free-form surface geometry is beyond the scope of this document, please refer to the reference in the introduction. They can be polygonal patches up to a degree of 21, supported types are bezier, Taylor, B-Spline, cardinal, and general basis functional forms.

Example

This example might help you recognise MI files as well as illustrate the format with a concrete example (don't expect this to create a sensible scene!)