MI format (Mental Images)

Written by Paul Bourke


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

The overall structure of an MI file is a structure as follows
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

$include "filename"
version "string"
verbose on | off
echo "message to echo"
system "shell command to execute"
memory amount_in_MB
code "filename"
link "filename"
declare "name of shader" (any_parameters)

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
The available view definitions are
focal nnn | infinity
aperture nnn
aspect nnn
resolution www yyy
window xmin ymin xamx ymax
transform 4x4_matrix
min samples nnn
max samples nnn
recursive on | off
samples nnn
adaptive on | off
contrast r g b [a]
time contrast r g b [a]
filter box | triangle | gauss width [height]
jitter nnn
shutter nnn
trace depth nnn
shadow_sort on | off
acceleration spatial subdivision
acceleration ray classification
max size nnn
max depth nnn
subdivision memory nnn
face front | back | both
clip hither yon
volume "shader name" (parameters)
environment "environment name" (parameters)
lens "lens name" (parameter)
shadow on | off
trace on | off
scanline on | off
desaturate on | off
dither on | off
gamma nnn
field even | odd | both
contour on | off
paper size "format"
paper cale nnn
discontinuity angle
contour line width nnn
contour depth nnn
paper transform nnn nnn

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!)