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 color 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 color information.  The
  second section of the file contains a repeating structure of
  data which defines the 3D objects in the file.

  The header is structured as follows:

  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)
  32 WORDs -- Object color palette (BIOS format)
  32 WORDs -- Color group base array

  In order for the palette to be useful, it must be accompanied
  by the color group base array.  This array indicates the
  index of the first color in the group to which that color
  belongs.  In the following example palette, which contains a
  background color of black, followed by five reds, five greens
  and five blues, you can see how the palette base array is
  used to group the colors together.  The reds start at color
  index 1, the greens at color index 6, and the blues at color
  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 counterclockwise.  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 color and edge-flag word.  This word tells the
  color 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.

  SPIN TEMPLATE FILE FORMAT

  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.

  The format of the file is as follows:

  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.

  EXTRUDE TEMPLATE FILE FORMAT

  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.

  The format of the file is as follows:

  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

  NON-STANDARD AXIS LABELING

  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 condsidered
  non-standard, as this is axis is usually labeled 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-labeled" 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.

  OBJECT NAME CONVENTIONS

  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.

  "FIXED-POINT" MATH FORMAT

  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.