Arcs require the following parameters, typically formatted as follows:
Radius<spc>StartAngle<spc>EndAngle<nl>
where Radius is a double defining the radius of the arc, StartAngle is a double containing the angle, in degrees, between the local X-axis and the start of the arc, EndAngle is a double containing the angle, in degrees, between the local X-axis and the end of the arc, <spc> is the space character and <nl> is the newline sequence.
Arcs are drawn, counter-clockwise from the start angle to the end angle, on the local X-Y plane. In wireframe mode, an arc is drawn as a fragment of a circular circumference; in solid mode, an arc is drawn as a wedge (acute angles) or like a cheese round with a wedge cut out (obtuse angles). In both cases, the arc's local origin is at centre of the circle of which it is a fragment.
Arcs exist as either coarse arcs or fine arcs; the former are drawn with fewer triangles (or arc-sections, if drawn as a wireframe) than the latter. With the introduction of VR Graphics (using the OpenInventor scene graph rendering engine), ACE creates all new arcs as fine arcs and converts coarse arcs to fine arcs during the read process.
There is one special case: an arc that has a start angle of 0 and an end angle of 360 is a Circle.
With the introduction of the OpenInventor scene graph rendering engine into AutoMod/ACE, the default compiled picture format was changed to be an embedded Inventor file. This format is also used to embed other "foreign" format graphics files, such as VRML, into a cell file.
The format for the type-specific parameters is as follows:
[FileLine<nl> [...]] #Inventor END<nl>
where FileLine is a line of source from a supported, embedded, 3D image file and <nl> is the newline sequence. Multiple lines may be read until the #Inventor END tag is read. Note that this tag is used even if the file is not an Inventor format file.
Care must be taken to ensure that the #Inventor END tag is not contained within the body of the embedded file.
Cones require the following parameters, typically formatted as follows:
Radius<spc>Height<spc>XOffset<spc>YOffset<nl>
where Radius is a double defining the radius of the base of the cone, Height is a double defining the distance, measured along the local Z-axis, between the base and the tip of the cone, XOffset is a double containing an offset from the X-axis local origin for the tip of the cone, YOffset is a double containing an offset from the Y-axis local origin for the tip of the cone, <spc> is the space character and <nl> is the newline sequence.
Cones are drawn with their base on the local X-Y plane, with the cell origin used as the center of the base, and the cone extending up along the local Z-axis.
Cylinders require the following parameters, typically formatted as follows:
Radius<spc>Height<spc>XOffset<spc>YOffset<nl>
where Radius is a double defining the radius of the cylinder, Height is a double defining the distance, measured along the local Z-axis, between the base and the top of the cylinder, XOffset is a double containing an offset from the X-axis local origin for the top of the cylinder, YOffset is a double containing an offset from the Y-axis local origin for the top of the cylinder, <spc> is the space character and <nl> is the newline sequence.
Cylinders are drawn with their base on the local X-Y plane, with the cell origin used as the center of the base, and the cylinder extending up along the local Z-axis.
A file reference identifies the location of a supported, 3D graphics file on a local or networked storage device; the file is read in and processed when the cell file is loaded. The following type-specific parameters are required, typically formatted as follows:
FilePath<nl>
where FilePath is the name, including an absolute or relative path, to the file referenced and <nl> is the newline sequence. If a relative path is used, then the search starts from the current directory.
The POSIX path separator character "/" can be used in place of the Windows path separator "\"; since it is more portable, the POSIX separator is preferred.
Note that the file path cannot contain any whitespace characters; such characters will cause the filename to be parsed as more than one token; the first token only will be used as the file path with the second token being taken as the cell type of the next cell entity.
The file's contents will be positioned such that the file's X, Y and Z axes align with the file reference's local axes and the file's origin will be placed at the file reference's origin.
Note that if the referenced file is in a format that follows the left-hand-rule for geometry, then an appropriate geometry adjustment must be made for the image to be loaded correctly; the simplest is for the file reference to define a 90 degree rotation about the X-axis.
A referenced file is only included in the image when it is referenced by an instance element. The file reference cell element itself is included within the first instance cell element that references it; file references cannot be included within a set and are not included in the member count of the set that contains the first instance.
It is recommended that file references be assigned a unique name, to avoid unexpected behavior during dereferencing.
Instances are used to include the contents of a definition (either a block definition or a file reference). The following type-specific parameters are required, typically formatted as follows:
DefinitionName<nl> [DefinitionCellDefinition]
where DefinitionName is the name of the definition to be included, DefinitionCellDefinition is the definition cell being referenced (if not previously defined, see later) and <nl> is the newline sequence.
The contents of the referenced definition are included using the instance's geometry, with the definition's origin being placed at the instance's origin, etc. Any inherited colors within the definition are satisfied from the instance also.
If the definition has yet to be read from the cell file, that is, if there is no definition currently defined which is named DefinitionName, then the definition must follow immediately after the first instance's type-specific parameters. Note that the definition is not included in the member count of the parent set.
Conic frustums require the following parameters, typically formatted as follows:
BaseRadius<spc>TopRadius<spc>Height<spc>XOffset<spc>YOffset<nl>
where BaseRadius is a double defining the radius of the base of the frustum, TopRadius is a double defining the radius of the top of the frustum, Height is a double defining the distance, measured along the local Z-axis, between the base and the top of the frustum, XOffset is a double containing an offset from the X-axis local origin for the top of the frustum, YOffset is a double containing an offset from the Y-axis local origin for the top of the frustum, <spc> is the space character and <nl> is the newline sequence.
Frustums are drawn with their base on the local X-Y plane, with the cell origin used as the center of the base, and the frustum extending up along the local Z-axis.
Hemispheres require the following parameters, typically formatted as follows:
Radius<nl>
where Radius is a double defining the radius of the hemisphere and <nl> is the newline sequence.
Hemispheres are drawn with their base on the local X-Y plane, with the cell origin used as the center of the base, and the hemisphere extending up along the local Z-axis.
Polyhedra require the following parameters, typically formatted as follows:
NumVertices<nl> [VertexX<spc>VertexY<spc>VertexZ<nl> [...]] NumFaces<nl> [VerticesInFace[<spc>VertexIndex[<spc>...]]<nl> [...]]
where NumVertices is an integer defining the number of vertices making up the polyhedron, VertexX is a double defining a local X co-ordinate for a vertex, VertexY is a double defining a local Y co-ordinate for a vertex, VertexZ is a double defining a local Z co-ordinate for a vertex, NumFaces is an integer defining the number of faces making up the polyhedron, VertexIndex is an integer identifying the index of a previously defined point, <spc> is the space character and <nl> is the newline sequence.
Each polyhedron is constructed from a number of faces. Each face is visible from a single side only, depending upon the face's normal vector, and is made up of three or more vertices. The constituent vertices must all lie in the same plane, although ACE does not object if they are not. Furthermore, the vertices must be listed in anti-clockwise order when viewing the intended visible side of the face.
Each vertex is defined as a point made up of an X, Y and Z co-ordinate. These are defined first and are numbered from 0 through to NumVertices - 1. The number of vertex definitions must match the NumVertices parameter. When defining each face, the number of vertices in that face is defined followed by that many vertex indices.
For example, the following defines the parameters for a square polyhedron that is visible from above and below (it requires two faces to do this):
4 0.0 0.0 0.0 1.0 0.0 0.0 1.0 1.0 0.0 0.0 1.0 0.0 2 4 0 1 2 3 4 0 3 2 1
All vertex co-ordinates are relative to the polyhedron's local axes.
Rectangles require the following parameters, typically formatted as follows:
Width<spc>Length<spc>XOffset<spc>YOffset<nl>
where Width is a double defining the width (local Y-axis dimension) of the rectangle, Length is a double defining the length (local X-axis dimension) of the rectangle, XOffset is a double that is required but ignored, YOffset is a double that is required but ignored, <spc> is the space character and <nl> is the newline sequence.
Note that ACE, for reasons unknown, generally mixes up the terms width and length, so that a cell's width is called its length and vice versa, confusing many users. In this document, at the risk of further confusion to ACE users, the terms width and height are used with their more natural definitions.
Rectangles are drawn on the local X-Y plane, with the cell origin used as the center of the rectangle. The rectangle has an upper and lower face and is visible from both sides.
Sets, and block definitions, require the following parameters, typically formatted as follows:
NumChildren<nl> [ChildCellDefinition [...]]
where NumChildren is an integer containing the number of child cells belonging to the set, ChildCellDefinition is a complete cell definition for a child cell and <nl> is the newline sequence.
The number of child cell definitions must match the NumChildren parameter.
Note that NumChildren excludes block definitions, file references and any children belonging to child sets.
Since sets contain the definitions of their child sets, and since child sets can themselves have child sets, it can be seen that the inclusion of sets gives cell files a hierarchical structure.
For a discussion of Root Sets and Main Sets, refer to the notes with the section on general file structure.
Tetrahedra require the following parameters, typically formatted as follows:
BaseLength<spc>TopLength<spc>Height<spc>XOffset<spc>YOffset<nl>
where BaseLength is a double defining the side length of the base equilateral triangle, TopLength is a double defining the side length of the top equilateral triangle, Height is a double defining the distance, measured along the local Z-axis, between the base and the top of the tetrahedron, XOffset is a double containing an offset from the X-axis local origin for the top of the tetrahedron, YOffset is a double containing an offset from the Y-axis local origin for the top of the tetrahedron, <spc> is the space character and <nl> is the newline sequence.
Tetrahedra are drawn with their base on the local X-Y plane, with the cell origin used as the center of the base, and each tetrahedron extending up along the local Z-axis.
Text cells require the following parameters, which have to be formatted as follows:
Text<nl>
where Text is a text string containing the text to be displayed and <nl> is the newline sequence.
Text, which is delimited by the previous line's newline sequence and the newline sequence at the end of this text line (i.e. each text field must be on a line by itself), can contain spaces, but no other whitespace or control characters. Furthermore only 7-bit ASCII characters are processed; 8-bit characters have their 8th bit stripped during a read operation.
Note that the VR Graphics versions of ACE do not appear to support empty text fields.
There are a number of different types of text, as follows:
| Type | Meaning |
|---|---|
| World | Text is drawn on the local X-Y plane using a 3D font; the cell's origin defines the bottom-left-hand-corner of the first character cell with the text itself displayed to the right of this point, along the local X-axis. By default, each line of text is 1 model distance unit in height. Character width varies according to the specific character and the selected font, making it difficult to exert control over the exact appearance of such text. Text height and width can be adjusted by the scaling parameters. |
| Screen Fast | Text is drawn relative to the dimensions of the window in which the image is displayed, using a screen font. The screen is mapped to absolute co-ordinates of -100 to 100 in both the X and Y dimensions, such that the absolute co-ordinate (-50, 50) identifies a point in the middle of the top-left-hand quadrant of the screen. The absolute X-Y co-ordinates of the cell therefore map to a point on the screen marking the bottom-left-hand-corner of the first character cell with the text itself displayed to the right of this point, along the screen's X-axis. The height and width of the the text is fixed and is not expressed as a percentage of the screen's physical height and width; text height and width is also unaffected by the scaling parameters. Because of the better control over formatting, Screen Normal text should be used in preference to Screen Fast. |
| Screen Normal | This is essentially the same as Screen Fast text, except that the text is displayed using a 3D font, providing better control over text appearance. Unit text height is approximately 1.25% of the screen height, with unit text width scaled according to the specific character, the selected font and the screen width. Text height and width can be adjusted by the scaling parameters. |
| Unrotate Fast | Text is drawn on the screen's X-Y plane using a screen font. The absolute X-Y co-ordinates of the cell defines the bottom-left-hand-corner of the first character cell with the text itself to the right of this point, along the screen's X-axis; consequently, the text appears not to rotate when the image is rotated and always faces the user. The height and width of the the text is fixed and is not expressed as a percentage of the screen's physical height and width; text height and width is also unaffected by the scaling parameters. Because of better overall appearance, Unrotate Fast text should be used in preference to Unrotate Normal. |
| Unrotate Normal | This is essentially the same as Unrotate Fast text, except that the text is displayed using a 3D font. By default, each line of text is 1 model distance unit in height. Character width varies according to the specific character and the selected font, making it difficult to exert control over the exact appearance of such text. Text height and width can be adjusted by the scaling parameters. |
Note that Text Lists are not supported in VR Graphics versions of ACE; attempting to read a cell file containing a Text List primitive into such a version will result in errors. However, Text Lists are still supported by the Standard Graphics versions.
Since this feature now seems to be deprecated, and since it causes problems for newer versions, it is recommended that you avoid the use of Text Lists; use the Text primitive instead.
Text List cells require the following parameters, which have to be formatted as follows:
NumItems<nl> [XTranslate<spc>YTranslate<spc>ZTranslate<nl> Text<nl> [...]]
where NumItems is an integer containing the number of items in the text list, XTranslate, YTranslate and ZTranslate are the X, Y and Z translations, for each item, applied after the cell's standard geometry, Text is a text string containing the text belonging to each item, <spc> and <nl> is the newline sequence.
Text, which is delimited by the newline sequence following each item's translation parameters and the newline sequence at the end of the text line (i.e. each text field must be on a line by itself), can contain spaces, but no other whitespace or control characters. Furthermore only 7-bit ASCII characters are processed; 8-bit characters have their 8th bit stripped during a read operation. It is not possible to have an empty text string!
There are a number of different types of text (see Text for more information), but all items in a text list are displayed in the same way.
Trapezoids require the following parameters, typically formatted as follows:
BaseWidth<spc>BaseLength<spc>TopWidth<spc>TopLength<spc>Height<spc>XOffset<spc>YOffset<nl>
where BaseWidth is a double defining the width (local Y-axis dimension) of the base of the trapezoid, BaseLength is a double defining the length (local X-axis dimension) of the base of the trapezoid, TopWidth is a double defining the width of the top of the trapezoid, TopLength is a double defining the length of the of top of the trapezoid, Height is a double defining the distance, measured along the local Z-axis, between the base and the top of the trapezoid, XOffset is a double containing an offset from the X-axis local origin for the top of the trapezoid, YOffset is a double containing an offset from the Y-axis local origin for the top of the trapezoid, <spc> is the space character and <nl> is the newline sequence.
Note that ACE, for reasons unknown, generally mixes up the terms width and length, so that a cell's width is called its length and vice versa, confusing many users. In this document, at the risk of further confusion to ACE users, the terms width and height are used with their more natural definitions.
Trapezoids are drawn with their base on the local X-Y plane, with the cell origin used as the center of the base, and each trapezoid extending up along the local Z-axis.
There is one special case: a trapezoid whose base and top lengths are equal, and whose base and top widths are equal, is a Box.
A triad, which merely displays the orientation of the local axes and the position of the local origin, has a single integer parameter whose purpose is unknown. This typically has the value 1 and is formatted as follows:
Unknown<nl>
where Unknown is an integer and <nl> is the newline sequence.
Current speculation on the purpose of Unknown is that it is a visibility flag: if the value is 0, then the triad is not displayed; any other value and it is displayed, with no noticeable change in appearance. Furthermore, any non-zero value is converted to 1 when ACE next writes the file.
Vector lists require the following parameters, typically formatted as follows:
NumVertices<nl> [VertexX<spc>VertexY<spc>VertexZ<spc>MoveDrawFlag<nl> [...]]
where NumVertices is an integer defining the number of vertices making up the vector list, VertexX is a double defining a local X co-ordinate for a vertex, VertexY is a double defining a local Y co-ordinate for a vertex, VertexZ is a double defining a local Z co-ordinate for a vertex, MoveDrawFlag is an integer indicating whether a straight line should be drawn from the previous vertex to the current vertex (1) or not (0), <spc> is the space character and <nl> is the newline sequence.
Each vector list, analogous to a Polyline in AutoCAD, is made up of a number of vertices linked by straight lines.
Each vertex is defined as a point made up of an X, Y and Z co-ordinate and a move-draw flag. The MoveDrawFlag of the first vertex must be 0 (move). The number of vertices defined must match the value of the NumVerticesparameter.
For example, the following defines the parameters for a vector list that appears as a square:
5 0.0 0.0 0.0 0 1.0 0.0 0.0 1 1.0 1.0 0.0 1 0.0 1.0 0.0 1 0.0 0.0 0.0 1
All vertex co-ordinates are relative to the vector list's local axes.