Imod ASCII File Format Version 2.0

The imod ASCII file format holds a subset of the binary data. Its main use is to simplify creating or transferring an IMOD model file. The format was upgraded in IMOD 3.10.11 to include most object, contour, and mesh properties, plus slicer angles and clipping planes, but few model-view related properties are stored. For the complete definition of any flags, check the description of the binary model file format.

Comment lines begin with a '#' character; blank lines are skipped. Data lines begin with a word directive followed by data. Some directives will assume data on new lines.

The first data line must begin with the word 'imod' followed by the number of objects in the model on the same line.

imod (Number of Objects)

Optional model directives.

The following directives are optional. They can be in any order anywhere in the file, except in the middle of contour or mesh data Each of these directives have three data values for x, y and z. The offsets and angles directives should be set to zero; they correspond to unused variables in the model that have been superceded by the image reference variables specified in the ref... directives below. The x and y scale values should be set to 1.0 and the z value should be set to compensate for the thickness of the image slices used to create the model. The max directive is set to the values of the image size used to make the model.

The ref... directives specify the relation between model and image coordinates for the last image file that the model was loaded with. The refcurscale and refcurrot values are based on the pixel spacing and rotation angles of the image file; refoldtrans values are based on the origin values in the image file, but with the original, internal IMOD sign convention (subareas have negative values); and refcurtrans values are based on the starting coordinate that was loaded in the image file. For example, if there is no rotation, then to get from an X coordinate in the model to the X pixel coordinate in the full image file, one would add ((refoldtrans x) - (refcurtrans x)) / (refcurscale x).

offsets (x) (y) (z) max (x) (y) (z) scale (x) (y) (z) angles (x) (y) (z) refcurscale (x) (y) (z) refcurtrans (x) (y) (z) refcurrot (x) (y) (z) refoldtrans (x) (y) (z)

Additional model directives are as follows. The units should be nm, um, or mm. The slicerAngle entry specifies X, Y, and Z angles then the X, Y, Z center position. drawmode (1 to draw model, -1 not to) b&w_level (black_slider,white_slider) resolution (pixel spacing for drawing model points) threshold (threshold for autocontouring) pixsize (pixel size) units (units) slicerAngle (time) (x) (y) (z) (x) (y) (z) (label) currentview (view number)

The view directive.

Initializes a new view and sets it as the current one. The index is ignored.


view (index)

Optional view directives

See the binary model specification of the VIEW chunk for the definition of bits in viewflags.




viewfovy  (perspective)


viewcnear  (near Z clipping plane value)


viewcfar  (far Z clipping plane value)


viewflags  (flags for lighting and transformation properties)


viewtrans  (x shift) (y shift) (z shift)


viewrot  (x rotation) (y rotation) (z rotation)


viewlight  (x position)  (y position)


depthcue  (starting distance)  (ending distance)


viewlabel  (text string with view name)


globalclips (# of planes) (flags) (trans) (current plane)

The globalclips line is followed by one line per clip plane, containing the X, Y, Z components of the normal vector and X, Y, Z coordinates of a point in the plane. Bits 0-6 of flags indicate which planes are on.

The object directive.

Initializes and selects the current object.


object (index) (number of contours in object) (number of meshes in object)

optional object directives


color (red) (green) (blue) (trans)


Fillcolor (red) (green) (blue)


name  (text string with object name)


linewidth   (2D line width)


surfsize    (maximum surface number in object)


pointsize   (3D sphere size)


axis        (unused)


drawmode    (unused)


width2D     (2D line width)


symbol      (symbol type)


symsize     (symbol size)


symflags    (flags for end symbols: bit 0 fill, bit 1 draw
beginning/end symbols)


ambient     (ambient light value)


diffuse     (diffuse light value)


specular    (specular setting)


shininess   (shininess setting)


obquality   (sphere drawing quality)


valblack   (black level for value display)


valwhite   (white level for value display)


matflags2   (flags for value drawing: bit 0 skip low, bit 1 skip
high, bit 2 constant color)


objclips (# of planes) (flags) (trans) (current plane)

The objclips line is followed by one line per clip plane, containing the X, Y, Z components of the normal vector and X, Y, Z coordinates of a point in the plane. Bits 0-6 of flags indicate which planes are on, and bit 7 indicates whether to ignore global clipping planes.

The following are object flags. open: Contours are open closed: Contours are not open scattered: Do not connect points fill: Draw model filled drawmesh: Draw mesh nolines: Do not draw lines with mesh nodraw: Turn off object bothsides: Light both sides insideout: Light the inside surface usefill: Use fill color to draw mesh pntusefill: Use fill color for 3D points pntonsec: Draw 3D points only on section antialias: Antialias line drawing hastimes: Contour data has times usevalue: Draw values in mesh display valcolor: Show values in false color

The contour directive.

The contour directive is used for each contour in current object. Three data variables are expected, the index to the contour that is being defined, a surface value, and the number of points in the contour. An optional fourth value can specify a general floating point value for the contour. Point data follows on the next line, one line for each point. Any point line can have one or two optional values: if there is one value, it is the point size; if there are two values, the first is a point size (which should be -1 if there is no size for the point) and the second is a general floating point value.





contour (index) (surface) 
(number of points in contour) [value]


(x) (y) (z)


(x) (y) (z) [point size] [value]

... for each point.
Following the contour data may be two optional directives: contflags (contour flags: bit 3 open, bit 4 wild, bit 17 scan contour) conttime (contour time)

The mesh directive.
An object can have more than one mesh. A mesh is organized into polygons, which are strips of triangles connecting two Z-levels of the object. The mesh data consist of a single list of unique vertices, with a normal at each vertex, plus a list of indices into the vertex/normal list describing how the polygons are drawn. Each mesh starts with a mesh directive followed by the data for that mesh. The vertex list in principle could consist of just vertices, but currently files contain just vertex/normal pairs as indicated below:
mesh (index) (# of vertices + # of normals) (index list size) (x) (y) (z) vertex (x) (y) (z) normal (x) (y) (z) vertex (x) (y) (z) normal ... for each vertex (index) (index) ... for each list index
negative index values give the following drawing instructions.
-1 end of list array -20 next item on list is normal vector. -21 begin concave polygon -22 end polygon -23 begin vertex,normal polygon pairs. -24 begin large convex polygon with normals. -25 begin vertex,normal polygon pairs with vertex indices
Currently, meshes in model files consist only of polygons with vertex, normal pairs, starting with -23 or -25 and ending with -22. In polygons starting with -23, each set of 6 indices describes a triangle as follows:
index to normal 1 index to vertex 1 index to normal 2 index to vertex 2 index to normal 3 index to vertex 3
In polygons starting with -25, each normal is assumed to follow its corresponding vertex, and each triangle is described by only 3 indices:
index to vertex 1 index to vertex 2 index to vertex 3
It is also legal to have polygons consisting only of vertices, without normals; these polygons start with -21 and each triangle is described by 3 indices as above for the polygons starting with -25.
Following all of the mesh data may be three optional directives: Meshflags (mesh flags; bit 16 normals have magnitudes; bits 20-23 resolution) Meshsurf (mesh surface number) Meshtime (mesh time)