Every Inventor data file must have a standard header to identify it. This header is the first line of the file and has the following form:

#Inventor V2.0 ascii

#Inventor V2.0 binary

To determine whether a random file is an Inventor file, use the SoDB::isValidHeader() method and pass in the beginning of the file in question. Although the header may change from version to version (V2.0 is the current version), it is guaranteed to begin with a # sign, be no more than 80 characters, and end at a newline. Therefore, the C () routine can be used. The isValidHeader() method returns TRUE if the file contains an Inventor header. Inventor also reads older (V1.0) files and converts them.

A node is written with the following elements:

For example:

DrawStyle {
   style	        LINES
   lineWidth	    3
   linePattern	  255
}

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 as follows:

Transform {
	   translation	     0 -4 0.2
}

LightModel {
   model	           BASE_COLOR
}

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
}

Brackets surround multiple-value fields, with commas separating the values, as shown for the diffuseColor field in the preceding example. It's all right to have a comma after the last value as well:

[value1, value2, value3,]

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

specularColor    .4 .3 .1

specularColor   [.4 .3 .1]

255
0xff
0177

		13
	13.0
	13.123
	1.3e-2

label   " front left leg " 
label   car

MaterialBinding {
   value   PER_FACE
	}

	Cylinder {
	   parts   SIDES
	}

	Cylinder {
	   parts   (SIDES | TOP)
	}

PerspectiveCamera {
components of the	   position   0 0 9.5
vector)	}

	BaseColor {
	   rgb   0.3 0.2 0.6
	}

	Transform {
	   rotation   0 1 0 1.5708
	   # y axis ... pi\xb9 /2 radians
	}

Boolean	TRUE, FALSE or 0, 1:
	SoFile {
	   isWriteBack   FALSE
	}

The Ignore flag for a field (see Chapter 3, Nodes and Groups) 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.

	Tip: The Ignore flag applies only to properties. It is not used for cameras, lights, and shapes.

Connections are written as the object containing the field or output connected to the field, followed by a period (.) and then the name of the field or output. For example:

Separator {
	    DEF Trans Translation { translation  1 2 3 }
	    Cube {}
	}
	Separator {
	    Translation { translation 0 0 0 = USE Trans.translation }
	    Cone {}
	}

Translation { translation = USE Trans.translation }

translation 000 ~ = USE Trans.translation
#or
translation ~ = USE Trans.translation

A global field needs to have at least one connection in order for it to be written out. It is written out in this format:

GlobalField { type value }

The braces contain the type and value of the field. The name of the global field is stored as the name of the value field. For example, the Text3 node could be connected to a global field (here, currentFile) that stores the current file name an application is working on. The Text3 node would then always display that current file name. Here is the ASCII file format for that connection:

Text3 {
   string "" = GlobalField {
      type SFString
      currentFile "aircar.iv"
   } . currentFile
}

The syntax for an engine definition is the same as that of a nongroup node:

EngineType { input_fields }

Engines can't be written on their own; they must be connected to at least one part of the scene graph. A field-to-engine connection is specified as follows:

fieldname value = engine . outputname

Here is an example of changing a sphere's radius using an SoOneShot^{( C++ | Java | .NET )} engine:

Sphere {
   radius 0.5 = OneShot { duration 3.0 } . ramp
}

For a more complex example, see the section called “Defining and Using Shared Instances of Nodes”.

A path (see Chapter 3, Nodes and Groups) is written with the following elements:

When Inventor encounters separator groups within the subgraph, it ignores them if they do not affect the nodes in the path chain. Written indices for the children within a group are adjusted to account for the skipped separator groups. For example, in Figure 12.1, “ Adjusting Path Indices to Account for Separator Groups ”, node N is counted as child index 1 when written, since the two previous children are separator groups that do not affect this node at all. (The indices in the path itself remain unchanged.)

Figure 12.1.  Adjusting Path Indices to Account for Separator Groups

	Note: If a path contains connections to nodes that are not part of the path, these nodes are not written out. For example, if a path contains an engine connected to a node outside the path, the engine will be written, but the node will not be.

Example 12.1, “ Writing a Path ” illustrates the process of writing a path to a file. First, here is the file for the scene graph, which creates chartreuse, rust, and violet spheres.

Separator {
   PerspectiveCamera {
      position 0 0 9.53374
      aspectRatio 1.09446
      nearDistance 0.0953375
      farDistance 19.0675
      focalDistance 9.53374
   }

   DirectionalLight {
   }

   Transform {
      rotation -0.189479 0.981839 -0.00950093 0.102051
      center 0 0 0 
   }

   DrawStyle {
   }

   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 12.2, “ Scene Graph for a Scene with Three Spheres ” shows the scene graph for this file.

Figure 12.2.  Scene Graph for a Scene with Three Spheres

If you pick the third sphere (the violet one), the pick path could be written to a file as shown in Example 12.1, “ Writing a Path ”. First, the subgraph under the root node is written. This description is followed by the number of indices in the path (3), and the indices themselves (4, 1, 2), as shown in Figure 12.3, “ Pick Path for Violet Sphere ”.

Path {
   Separator {
      PerspectiveCamera {
         position 0 0 9.53374
         aspectRatio 1.09446
         nearDistance 0.0953375
         farDistance 19.0675
         focalDistance 9.53374
      }
      DirectionalLight {
      }
      Transform {
         rotation -0.189479 0.981839 -0.00950093 0.102051
      }
      DrawStyle {
      }
      Separator {
         LightModel {
            model BASE_COLOR
         }
         Separator {
            Transform {
               translation 2.2 0 0
            }
            BaseColor {
               rgb 0.3 0.2 0.6
            }
            Sphere {
            }
         }
      }
   }
   3
   4
   1
   2
}

Figure 12.3.  Pick Path for Violet Sphere

In the file format, the keyword DEF introduces a named instance of a node, path, or engine. It can be referenced later with the USE keyword. For example:

// This example shows keeping a cone between two cubes using an
// InterpolateVec3f engine.

Separator {
   DEF A Translation { translation -4 0 0 }
   Cube { }
}
Separator {
   DEF B Translation { translation 4 5 6 }
   Cube { }
}
Separator {
   Translation { translation 0 0 0 =
                 InterpolateVec3f {
                    input0 0 0 0 = USE A.translation
                    input1 0 0 0 = USE B.translation
                    alpha 0.5
                 } . output
               }
   Cone { }
}

The name can be any valid SbName^{( C++ )}. In certain cases, Inventor adds some extra characters to the name when the file is written out. For example, consider the somewhat unusual scene graph shown in Figure 12.4, “ Shared Instances of Nodes ”. To indicate which instance of the beachball node is used by node B, the scene graph is written out as follows:

Separator{
   Separator{
      DEF beachball+0
      DEF beachball+1
   }
   Separator{
      USE beachball+0
      USE beachball+1
   }
}

When the scene graph is read back in, the original names are preserved, but the +n notations are discarded.

Figure 12.4.  Shared Instances of Nodes

When a node kit is written, it includes one field for each part. For example:

AppearanceKit {
   lightModel			    LightModel { model PHONG }
   drawStyle			     DrawStyle  { style LINES }
   material			      Material   { diffuseColor .5 .5 .5 }
   complexity	    Complexity { value .5 }
}

In this format, the name of the field (lightModel) is followed by the name of the node (LightModel), and then the node's fields and values (each part is contained in an SoSFNode^{( C++ | Java | .NET )} field). If the part has not been created, or if it is NULL, it is not written out. However, if a part is created by default (such as the shape part in the SoShapeKit^{( C++ | Java | .NET )}), and if the part is explicitly set to NULL, it is written out.

This example shows nesting node kits. Here, the appearance kit is the value for the appearance field. The appearance kit, in turn, has a material field.

SeparatorKit {
   appearance			    AppearanceKit {
      material   				Material { diffuseColor	   1 1 1 }
   }
}

When Inventor writes out a node kit, it writes out the intermediate parts. When you enter the information yourself, you can use a shorthand method and omit the intermediate parts. For example, if you omit the AppearanceKit, the SeparatorKit knows to add an AppearanceKit and put the Material node inside. So, you could simply enter this:

SeparatorKit {
   material   				Material { diffuseColor	   1 1 1 }
}

The file format for list parts within node kits is a bit more specialized. Each list part has three standard fields:

For example, here is the childList part of an instance of SoSeparatorKit^{( C++ | Java | .NET )}:

SeparatorKit {
   childList			    NodeKitListPart {
      containerTypeName	   "Separator"
      childTypeNames	      "SeparatorKit"
      containerNode	        			Separator {
         SeparatorKit {
            transform	      Transform { translation 	1 0 0 }
         }
         SeparatorKit {
            transform	      Transform { translation 	0 1 0 }
         }
         SeparatorKit {
            transform	      Transform { translation 	0 0 1 }
         }
      }
   }
}

By default, Inventor does not write out the internal parts, such as separators and groups, or fields with default values. But if the node kit is in a path, everything is written out, as the following example shows. Generally, it writes out the parts in the reverse order they are defined in the catalog, with the leaf nodes first:

#Inventor V2.0 ascii

SeparatorKit {
   appearance	    DEF +0 AppearanceKit {
      material   		DEF +1 Material {
         diffuseColor	   1 0 1
      }
   }
   childList	    DEF +2 NodeKitListPart {
      containerTypeName   "Separator"
      childTypeNames	       "SeparatorKit"
      containerNode	   	     DEF +3 Separator {
         ShapeKit {
            appearance	   		  DEF +4 AppearanceKit {
               material			    DEF +5 Material {}
		            }
            transform			   DEF +6 Transform {}
            shape			   DEF +7 Cube {}
		            topSeparator			  Separator {
               USE +4
               USE +6
               DEF +8 Separator {
                  USE +7
               }
            }

            shapeSeparator  			USE +8
        }
   }
}
topSeparator	    Separator {
   USE +0
   USE +2
   }
}

To include a file within another file, use an SoFile^{( C++ | Java | .NET )} node. This node is useful when you are building scene graphs that include many objects. The objects can reside in their own files, and SoFile^{( C++ | Java | .NET )} nodes can be used to refer to them without copying them directly into the new file. The SoFile^{( C++ | Java | .NET )} node is written as

File {
   name "myFile.iv"
}

where the name field is the name of the file to be included. On read, the contents of the file myFile.iv are added as hidden children of SoFile^{( C++ | Java | .NET )}. On write, Inventor just writes the filename (but not the children).

The objects within an SoFile^{( C++ | Java | .NET )} node are not editable. You can copy the contents of an SoFile^{( C++ | Java | .NET )} node using the method

SoFile::copyChildren()

or you can modify the name field of the SoFile^{( C++ | Java | .NET )} node. Whenever the value of the name field changes, the new file is read in. If the name is not an absolute path name, the list of directories set on SoInput^{( C++ | Java | .NET )} is used to search for the file (see the section called “Reading a File into the Database”). automatically adds the directory of the file being read to 's list of directories to search.

For example, suppose you have myFile.iv, which contains windmill.iv.

Contents of /usr/tmp/myFile.iv:

#Inventor V2.0 ascii
File { name "myObjects/windmill.iv" }

Contents of /usr/tmp/myObjects/windmill.iv:

#Inventor V2.0 ascii
//format to make the windmill

When /usr/tmp/myFile.iv is read in, /usr/tmp is added to the directory search list. When the SoFile^{( C++ | Java | .NET )} node in myFile.iv calls SoDB::read, SoInput^{( C++ | Java | .NET )} will find /usr/tmp/myObjects/windmill.iv, and it will be read (the directory /usr/tmp/myObjects will also be added to the list of search directories). When reading finishes, /usr/tmp/myObjects and /usr/tmp will be removed from the search directories list.

The SoOutput^{( C++ | Java | .NET )} object in an SoWriteAction^{( C++ | Java | .NET )} has a setBinary() method, which sets whether the output should be in ASCII (default) or binary format (see Chapter 8, Applying Actions). The getOutput() method returns a pointer to the SoOutput^{( C++ | Java | .NET )}. 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 (see the section called “File Header”).

If Inventor is unable to locate the code for the new node or engine, it creates an instance of the class SoUnknownNode or SoUnknownEngine. The first keyword in the file format for all new nodes is named fields, and it is followed by the field type and name of all fields defined within the node. For example:

WeirdNode {
   fields [ SFFloat length, SFLong data ]
   length 5.3
   Material {}
   Cube {}
}

This unknown node has two fields, length and data. Because the data field uses its default value, it is not written out. The node also has two children, an SoMaterial^{( C++ | Java | .NET )} and an SoCube^{( C++ | Java | .NET )}, which are listed after the fields of WeirdNode. These nodes are treated as hidden children and are not used for rendering, picking, or searching. They are only used by the write action.

The file format for new engines contains descriptions of both the inputs and outputs for the engine, as follows:

WeirdEngine {
   inputs [ SFFloat factor, SFFloat seed ]
   factor 100
   seed 0.5
   outputs [ SFFloat result ]
}

The author of a new node class may also provide an alternate representation for the node, to be used in cases where the node is treated as an unknown node. This representation is specified in the alternateRep field for the node, which contains the complete scene graph for the alternate representation. This scene graph will be used in place of the actual node for picking, rendering, and bounding-box actions.

The following node kit provides an alternate representation:

Airplane {
   fields [ SFNode wing, SFNode fuselage, SFNode alternateRep ]
   wing Separator { ... the wing scene graph ... }
   fuselage Separator { ... the fuselage scene graph ... }
   alternateRep Separator {
      Cube {}
      Transform { translation 10 0 0 }
      Cone {}
   }
}