3D2 format

CAD-3D THREE-DIMENSIONAL OBJECT FILE

CAD-3D 2.0 stores its 3D objects in a file which can hold up to 40 objects, and contains all the information about the objects, including the lighting and colour palette used by the objects.
The file is similar to the older file format, but no longer relies on the Motorola Fast Floating Point library (LIBF) for the storage of vertex coordinates. The new version stores each coordinate in a two-byte word instead of a four-byte floating-point value, saving a considerable amount of storage, as well as making the file usable more easily by programs written with different floating-point formats. The CAD-3D 2.0 3D object file uses an extension of .3D2, and is composed of two parts. The first section is a 256-byte header, which tells how many objects are included in the file, the light settings and the colour information. The second section of the file contains a repeating structure of data which defines the 3D objects in the file.

  WORD -- File ID -- $3D02
  WORD -- Count of objects in file (1-40)
  WORD -- Light source A on/off indicator (0=off, 1=on)
  WORD -- Light source B on/off indicator (0=off, 1=on)
  WORD -- Light source C on/off indicator (0=off, 1=on)
  WORD -- Light source A brightness (0-7)
  WORD -- Light source B brightness (0-7)
  WORD -- Light source C brightness (0-7)
  WORD -- Ambient light brightness (0-7)
  WORD -- Light source A Z position (-50 through +50)
  WORD -- Light source B Z position (-50 through +50)
  WORD -- Light source C Z position (-50 through +50)
  WORD -- Light source A Y position (-50 through +50)
  WORD -- Light source B Y position (-50 through +50)
  WORD -- Light source C Y position (-50 through +50)
  WORD -- Light source A X position (-50 through +50)
  WORD -- Light source B X position (-50 through +50)
  WORD -- Light source C X position (-50 through +50)
  16 WORDs -- Object color palette (BIOS format)
  16 WORDs -- Color group base array

In order for the palette to be useful, it must be accompanied by the colour group base array. This array indicates the index of the first colour in the group to which that colour belongs. In the following example palette, which contains a background colour of black, followed by five reds, five greens and five blues, you can see how the palette base array is used to group the colours together. The reds start at colour index 1, the greens at colour index 6, and the blues at colour index 11.

  INDEX    COLOR     BASE
  -----    -----     ----
     0      000        0
     1      100        1
     2      200        1
     3      300        1
     4      400        1
     5      500        1
     6      010        6
     7      020        6
     8      030        6
     9      040        6
    10      050        6
    11      001       11
    12      002       11
    13      003       11
    14      004       11
    15      005       11

The base value is used when performing shading operations, and if incorrectly set will result in odd-looking images.

  WORD -- Color palette type (0=Seven-shade, 1=Fourteen shade,2=Custom)
  WORD -- Wireframe line color (1-15)
  WORD -- Outline line color (0-15)
  150 BYTEs -- Filler for future expansion

The object data is a variable-sized section which depends on the complexity of the object. The section repeats for each object in the file, and is structured as follows:

  9 BYTEs -- Object name (8 characters max) with null terminator.
  WORD -- Number of vertices in object (15000 maximum)

The following structure defines the X, Y and Z coordinates for each vertex of the object. It is made up of three words and repeats the number of times specified by the vertex count word above.

  WORD -- X coordinate of vertex, stored in the standard CAD-3D
  fixed-point format.  For example, an X coordinate of 23.69 is
  stored as an integer value of 2369.  When reading this value,
  simply convert it to a floating-point variable and divide by
  100.
  WORD -- Y coordinate of vertex, also in fixed-point format.
  See above for description of format.
  WORD -- Z coordinate of vertex, also in fixed-point format.
  See above for description of the format.

After all the vertices' coordinates have been read in, the next part of the file describes the triangular faces which make up the object.

  WORD -- Number of triangular faces in the object (30000 maximum)

The following structure tells the face structure of the object. It is made up of four words and is repeated once for every face in the object, specified by the face count above. Each face is triangular, and defined by three vertices, or points, referred to as A, B and C. When looking at the face of the triangle facing outward, the A-B-C order of the vertices is counter-clockwise. This allows for quick calculation of whether or not a face is visible. Each face, in addition to having the three vertices of the triangle defined, has a colour and edge-flag word. This word tells the colour of the face and whether or not the line of one of the three edges (A-B, B-C, C-A) is to be drawn in edges-only mode.

  WORD -- Number of first vertex in the face, termed point A.
  This value can range from zero to the number of vertices in
  the object, and corresponds to the vertices read from the
  file earlier.
  WORD -- Number of second vertex in the face, termed point B.
  This value can range from zero to the number of vertices in
  the object, and corresponds to the vertices read from the
  file earlier.
  WORD -- Number of the third vertex in the face, termed point
  C.  This value can range from zero to the number of vertices
  in the object, and corresponds to the vertices read from the
  file earlier.
  WORD -- Color/edge flag indicator.  The low byte of this
  value is a number from 1 to 15 and tells the color used for
  that face when drawing.  This value is used by the object
  shading routine to determine the color group within the
  palette used by this face.  The upper byte is used to tell
  the program which edges are to be shown by a line segment
  when drawing in "edges only" mode.  The three low-order bits
  in this byte are used as flags for this purpose; a zero in
  the bit indicates that no line is to be drawn, a one in the
  bit indicates that the edge is to be drawn.  The bit
  assignments are:

      Bit 2: Line segment A-B
      Bit 1: Line segment B-C
      Bit 0: Line segment C-A

The face data repeats until all faces have been defined. This is the end of the file.

The CAD-3D spin tool template file is a convenient way to store often-used templates for spun objects. It is an ideal way to send a simple spun object to another user of CAD-3D 2.0 (they cannot be used by CAD-3D 1.0), since the compact template file is smaller than the resulting 3D object, making transmission via telecommunications network an economical option.
The template file contains all information necessary to create a spun object except for the number of degrees or the percentage for a partial spin. The file contains the number of points in the template, the number of segments, a flag which tells whether or not the first point is connected to the last, and the actual coordinate data for the template.

  WORD -- Number of points in the template, a number from 1 to 99.
  WORD -- Number of segments in the spun object, a number from
  1 to 48.  Note that segment values less than 3 may not
  execute in partial or full spin operations.
  WORD -- Connect flag.  0 indicates that the first point and
  the last point are not connected, 1 indicates that they are
  connected.  When a template is loaded, the "Connect"
  selection in the drop-down menu will be set to the
  appropriate setting.

The following section of the file is a table of the X coordinates of all the points in the template. There are n WORDs in this table, where n is the number of points in the template, specified in the first word of the file. n WORDs -- The values of the X coordinates of the points in the spin template. These values range from 0 to 300. A value of zero indicates that the point lies on the spin tool's central axis at the center of the spin tool window; a value of 300 indicates that the point lies at the far right of the window.

The following section of the file is a table of the Y coordinates of all the points in the template. There are n WORDs in this table, where n is the number of points in the template, specified in the first word of the file.

  n WORDs -- The values of the Y coordinates of the points in
  the spin template.  These values range from -150 to 150.  A
  value of -150 indicates that the point lies at the top of the
  spin tool window; a value of 150 indicates that the point
  lies at the bottom of the window.

The CAD-3D extrude tool template file is almost exactly the same as the spin tool template file. The template file contains all information necessary to create an extruded object. It contains the number of points in the template, the number of segments, and the actual coordinate data for the template.

  WORD -- Number of points in the template, a number from 1 to 99.
  WORD -- Number of segments in the spun object, a number from 1 to 50.

The following section of the file is a table of the X coordinates of all the points in the template. There are n WORDs in this table, where n is the number of points in the template, specified in the first word of the file.

  n WORDs -- The values of the X coordinates of the points in
  the spin template.  These values range from -300 to 300.  A
  value of -300 indicates that the point lies at the far left
  of the extrude tool window; a value of 300 indicates that the
  point lies at the far right of the window.

The following section of the file is a table of the Y coordinates of all the points in the template. There are n WORDs in this table, where n is the number of points in the template, specified in the first word of the file.

  n WORDs -- The values of the Y coordinates of the points in
  the extrude template.  These values range from -150 to 150.
  A value of -150 indicates that the point lies at the top of
  the extrude tool window; a value of 150 indicates that the
  point lies at the bottom of the window.

Section 6: CAD-3D 2.0 Specifics

CAD-3D uses a non-standard coordinate system, and it is important to remember how this system is oriented when using the communication pipe.

Cad-3D's coordinate system is oriented as follows: The X axis, as viewed from the top of the universe (see the TOP view window) runs from left to right. The lowest X value an object can have is -45.00 (the left side of the window), and the highest value is 45.00 (the right side of the window).
The Y axis, as viewed from the top of the universe (see the TOP view window) runs from bottom to top. The lowest Y value an object can have is -45.00 (the bottom of the window), and the highest value is 45.00 (the top of the window). This is considered non-standard by most people, as this axis is usually considered the Z axis.
The Z axis, as viewed from the front of the universe (see the FRONT window) runs from bottom to top. The lowest Z value is -45.00 (the bottom of the window), and the highest value is 45.00 (the top of the window). This is also considered non-standard, as this is axis is usually labelled as the Y axis.
The reason the axis system is non-standard is due to the way I learned 3D graphics, which was charting in geometry. In most examples, the X and Y axes were always a sheet of graph paper on a desktop, and the Z values were "altitudes" above or below the sheet. The lack of formal education in this area led to the 3D axes being "mis-labelled" from the standpoint of most 3D users.
The non-standard orientation has been preserved in this version in order to remain compatible with the previous version of CAD-3D. If this causes problems for you, just exchange the Y and Z axes when working with them in CAD-3D.

Because CAD-3D allows you to refer to objects by name, it is very easy for most people to use. When naming your objects, please use meaningful names so that they can be easily recognized. Names such as WINGLET are much easier to identify than names like XXX. It's especially important to name objects well if you'll be exchanging your files with others.
Object names in CAD-3D can be up to eight characters in length, and are case-sensitive. This allows very flexible naming of objects. Be sure you are using the proper name when using the communication pipe -- "ABC" is not the same as "abc" or "ABc". If you use the communication pipe for manipulation of objects, you must be careful to use the proper name or CAD-3D will not find the object.

CAD-3D 2.0's communication pipe and file formats use an integer format to store floating-point values. This is done to save disk space and make the program compatible with other compilers which may use a different floating-point format. The fixed-point format used is simply the integer equivalent of the floating-point value multiplied by 100. This results in values with two digits to the right of the decimal (i.e. 1.567 becomes 1.56). This precision is used because two decimal places is the precision used in the boolean shape operations in the JOIN function. The Motorola Fast Floating Point library is used in CAD-3D, and the 3D object vertex coordinates had to be truncated to two decimal places in order to avoid serious problems with the math results. For this reason, you should keep your objects as large as possible when executing JOIN operations -- it will prevent extreme truncation.