How to Write an IRIS Inventor File Translator

Release 1.0


Section 5 File Format Syntax

This section outlines details of the syntax for the Inventor ASCII file format. Inventor's file format ignores extra white space created by spaces, tabs, and new lines (except within quoted strings). Comments begin with a number sign (#) anywhere on a line and continue to the end of the line:

# this is a comment in the Inventor file format

See the IRIS Inventor Nodes Quick Reference for individual descriptions of the file format for each Inventor class.


5.1 File Header
Every Inventor data file must have a standard header to identify it. This header has the following form:

#Inventor V1.0 ascii

or

#Inventor V1.0 binary

To determine whether a file is an Inventor file or not, use the SoDB::isValidHeader() method and pass in the first line of the file in question. Although the header may change from version to version, it is guaranteed that it will begin with a # sign, will be no more than 80 characters, and will end at a newline. Therefore, the C fgets() routine can be used. The isValidHeader() method returns TRUE if the file contains an Inventor header.

An example of using fgets() to check the header is

FILE *fp = fopen ( filename, "r" );
char headerString [80];
fgets( headerString, 80, fp );

if( SoDB::isValidHeader( headerString ))
   printf( "File has valid Inventor header\n");
else
   printf( "Invalid Inventor header\n");
5.2 Writing a Node
A node is written as:

nodename {
      field1name   value
      field2name    value
      .
      .
      .
      [child nodes]
      [ . . . ]
}

For example:

DrawStyle {
	style		LINES
	lineWidth	3
	linePattern	0x00ff
}

5.3 Writing Values within a Field
Fields within a node are written as the name of the field, followed by the value or values contained in the field. If the field value has not been changed from its default value, that field is not written out. Fields within a node can be written in any order. An example of writing field values is

Transform {
	translation	0 -4 0.2
}

LightModel {
	model		BASE_COLOR
}

Use brackets to surround multiple-value elds, with commas separating the values, as shown below for the diffuseColor field. It's all right to have a comma after the last value as well:

[ value1, value2, value3, ]

For example:

Material {
	ambientColor	.3 .1 .1
	diffuseColor   [.8 .7 .2,
			 1 .2 .2,
			.2  1 .2,
			.2 .2  1]
	specularColor	.4 .3 .1
	emissiveColor	.1  0 .1
}

Single-value fields (SF) do not contain any brackets or commas. Multiple-value fields (MF) usually have brackets, but they are not necessary if only one value is present:

specularColor .4 .3 .1

or

specularColor [.4 .3 .1 ]

The value that is written depends on the type of the field, as follows:

Type of Field		Acceptable Formats

longs, shorts,		integers
unsigned shorts

floats			integer or floating point number. For example:
			13
			13.0
			13.123
			1.3e-2

names, strings		double quotation marks (" ") around the name if it is more than
			one word, or just the name (with no white space) if it is a single
			word. For example:

			label	" front left leg "
			label	car

			You can have any character in the string, including newlines and
			backslashes, except for double quotation marks. To include a double
			quotation mark in the string, precede it with a backslash (\").

enums			either the mnemonic form of the enum or the integer equivalent.
			(The mnemonic form is recommended, both for portability and
			readability of les.) For example:

			MaterialBinding {
				value	PER_FACE
			}

bit mask		one or more mnemonic ags, separated by a vertical bar (|) if there
			are multiple ags. When more than one ag is used, parentheses are
			required.

			Cylinder {
				parts	SIDES
			}

			Cylinder {
				parts	(SIDES | TOP)
			}

vectors			n floats separated by white space:
(SbVecnf, where n is
the number of		PerspectiveCamera {
components of the		position	0 0 9.5
vector)			}

colors			3 floats (RGB) separated by white space:

			BaseColor {
				rgb	0.3 0.2 0.6
			}

rotation		a 3-vector of oats for the axis, followed by a oat for the angle (in
			radians), separated by white space:

			Transform {
				rotation	0 1 0       1.5708
          					# y axis ... PI/2 radians
				}

matrix			16 floats, separated by white space (row major order)

path			An SoSFPath has one value, a pointer to a path. To write this
			value, write the path (see Section 12.3.5 of the Inventor
			Programming Guide, Volume I). An SoMFPath has multiple
			values, which are all pointers to paths. To write this value, enclose
			the path list in brackets, and use commas to separate each path:

			[ first_path, second_path, ... nth_path ]

node			An SoSFNode has one value, a pointer to a node. To write this
			value, write the node using the standard format for all nodes. An
			SoMFNode has multiple values, which are all pointers to nodes. To
			write this value, enclose the node list in brackets, and use commas to
			separate each node:

			[ node1, node2, ... noden ]

5.4 Ignore Flag
The ignore flag for a node (see Chapter 3 of the Inventor Programming Guide, Volume I) is written as a tilde ( ~ ), either after or in place of the field value or values. For example:

transparency [ .9, .1 ] ~

or

transparency ~

The first case preserves the values even though the field is ignored. The second case uses the default value but ignores the field.

5.5 Sample Scene Graph and Inventor File
Here is the file for a sample scene graph, which creates chartreuse, rust, and violet wireframe spheres. Figure 13 shows the scene graph for this file.

Separator {
	PerspectiveCamera {
		position 0 0 9.53374
		aspectRatio 1.09446
		nearDistance 0.0953375
		farDistance 19.0675
		focalDistance 9.53374
	}
	DirectionalLight { }     # note:  default fields for this light
	Transform {
		rotation -0.189479 0.981839 -0.00950093 0.102051
		center 0 0 0
	}
	DrawStyle {
		style  LINES
	}
	Separator {
		LightModel {
			model BASE_COLOR
		}
		Separator {
			Transform {
				translation -2.2 0 0
			}
			BaseColor {
				rgb .2 .6 .3	# chartreuse
			}
			Sphere { }
		}
		Separator {
			BaseColor {
				rgb .6 .3 .2	# rust
			}
			Sphere { }
		}
		Separator {
			Transform {
				translation 2.2 0 0
			}
			BaseColor {
				rgb .3 .2 .6	# violet
			}
			Sphere { }
		}
	}
}
Figure 13 Scene graph for a scene with three spheres

5.6 Instancing
When a scene graph contains shared instances of a node, Inventor defines a temporary name for the node and uses that name when writing subsequent occurrences of that node in the scene graph. It inserts the letters DEF (for define), followed by the name for the first use of the node. Thereafter, Inventor simply writes USE plus the name defined for that node.

For example, the scene graph shown in Figure 14 would be written as follows (without the comments):

Group {				# group A
	Group {			# group B
		DEF d Cube { }	# define D and use it
	}
	Group {			# group C
		USE  d		# use D again
	}
}

Figure 14 Defining a node for multiple uses

Inventor uses this DEF/USE technique for paths as well as for nodes. For les to be read into Inventor, the name for a node or path can be any valid identier. This name is thrown away after the file is read. (Identiers start with an underscore or a letter and must consist entirely of letters, numbers, and underscores.) Names used within a file must be unique. A name can, however, be used in multiple les, since each file maintains its own list of names.

5.7 Including Other Files
To include a file within another le, use an SoFile node. This node is written as

File {
	name "myFile.iv"
}

where the name field is the name of the file to be included. The contents of the file myFile.iv are added as children of SoFile.

The SoFile node has an associated WriteBack flag. If this flag is TRUE (the default), then the children of SoFile are written back to their original file if anything below the SoFile node changed. If this flag is FALSE, then the original file remains untouched, even if changes occurred to the subgraph below the node. Use the setWriteBack() and getWriteBack() methods to change the value of this ag and to obtain its current value. If the file cannot be written, Inventor prints a warning.

5.8 ASCII and Binary Versions
The SoOutput object in an SoWriteAction has a setBinary() method, which sets whether the output should be in ASCII (default) or binary format. The getOutput() method returns a pointer to the SoOutput. When a file is written, Inventor inserts a header line that indicates whether the file is in ASCII or binary format, as well as the Inventor version number.

For example, to write in ASCII to a file:

SoWriteAction w;

w.getOutput()->setBinary( FALSE );
if ( w.getOutput()->openFile( "myFile.iv" )) {
	w.apply( root );
	w.getOutput()->closeFile();
}