                         -= Vector Object Utils =-


  Here are a few utils and a binary file format I have come up with to make
my life a little easier when doing 3d vector objects. The main utils convert
the popular ASC and DXF files to a binary format (a 3DS converter is in the 
works). The other utils complement the converters by re-organizing the data
to a format best suited for realtime purposes. A more indepth explination
is provided later. Here is a list of the inlcuded files:


ASC2VO.EXE         - ASC -> VO conversion program
DXF2VO.EXE         - DXF -> VO conversion program
TRI.EXE            - Triangle polygon reduction program
CCWS.EXE           - Counter Clockwise Normal sorting program
VN.EXE             - Vertex normal calculation program 
VOFORMAT.TXT       - VO file format specifications
DUCK.ASC           - Sample ASC file 
SKULL.DXF          - Sample DXF file
STAR.DXF           - Sample DXF file
SHOWVO.EXE         - Sample program to display VO files
README.TXT         - This file


Here is a brief description of the utils:


ASC2VO:
  Converts a .ASC file to the VO binary format. The lines in the ASC file
  must be terminated by a carrige returns (while testing the converter, I
  recieved a couple ASC files via email that didn't have carrige returns
  so be careful), if you are in doubt, load the ASC file in your favorite
  editor and save it (without modifying it) and things should be fine.
  ASC2VO accepts 2 parameters. The first one is the ASC file to convert, and
  the optional second parameter is a name to call the binary output VO file.
  The default is the same name as the ASC file but with a VO extention.
  ASC2VO has several limitations that you should be aware of. It can only
  handle about 5000 polygons. Not a real problem, but still a limitation.
  If the ASC has more than 5000 or so polygons, you will either crash the
  program or get undesired results in the finished VO file. Run ASC2VO from
  the command line for more parameter information.


DXF2VO:
  Converts a .DXF file to the VO binary format. The DXF converter only accepts
  text DXF files (there are binary DXFs), and will only convert the files with
  the "3DFACE" sections (the other is "POLYLINE"). This shouldn't pose a
  serious problem as most program use "3DFACE". DXF files can also have polygons
  with more than 3 sides (non-tirangles), but this can be reduced to triangles
  (using the TRI program) for easier use (the other utilities only supprt
  triangles you will learn to like the TRI.EXE program). Although I haven't
  maxed out the DXF2VO converter, it has a maximum limit of 4000 or so polygons.
  If the DXF has more than 4000 or so polygons, you will either crash the
  program or get undesired results in the finished VO file. Run DXF2VO from
  the command line for more parameter information.


TRI:
  Takes a VO file as input and creates a new VO file as the output. This program
  Convertes all non triangle polygons into triangles and removes all duplicate
  polygons from the file (duplicate polys may exist due to rounding errors in
  the conversion). TRI accepts 2 parameters. The first one is the input VO file
  the optional second parameter is a name to call the new output VO file.
  The default is the same name as the input file (overwriting the old VO file).
  This program should be run on ALL converted VO files (from the ASC2VO and
  DXF2VO conversion program) before any of the other utilities are used. Run
  TRI from the command line for more parameter information.


CCWS:
  CCWS trys and sorts you polygons so they all share the same coordiante
  system (either right handed or left handed). This ensures that your polygon
  normals are pointing the proper direction for backface removal. This program
  doesn't work on all object. Any object that has "disconnected" parts (where
  polygons are not adjacent to others) will not be sorted properly. Convert
  the STAR.DXF file (using DXF2VO) and run TRI on it the show it using SHOWVO
  and you will see what incorrect normals will do. Then run CCWS on the STAR.VO
  file and re-run SHOWVO and you will see what it does. By default, CCWS sorts
  all polygons so the verticies are oriented in a counter clockwise manor. If
  you are using a system where you need a clockwise orientation, run CCWS to
  sort the normals, then run it again with the -S parameter to swap the
  orientation of the polygons. Run CCWS from the command line for more
  parameter information.

VN:
  Calculates the vertex normals and stores them in the VO file. This is for
  use with gouraud/phong/env mapping type routines that use vertex normals.
  This program handles a maximum of about 5000 polygons. This program is
  fairly self explanitory for those people who know how to use vertex normals.
  Run VN from the command line for more parameter information.


A brief description of the other files:

VOFORMAT.TXT
  A complete description of the VO binary file format.

DUCK.ASC
  A sample ASC file to show the conversion process from an ASC file

SKULL.DXF
  A sample DXF file to show the conversion process from a DXF file

STAR.DXF
  A sample DXF file to show the conversion process from a DXF file. It
  also demonstrates the use of the CCWS program.

SHOWVO.EXE
  A sample program to show the converted VO file. It is a rather shabby
  demonstration program that uses a phong approximation (to demonstrate
  the use of the vertex normals). Its clumsy, but it works.


The conversion process:

  To correctly convert a file follow these steps:

   1. Convert the file using ASC2VO or DXF2VO
   2. Run TRI to get rid of any extra polygons and non-triangle polys
   3. Run CCWS to sort the normals
   4. Run VN to calculate the vertex normals (this is optional, as the program
      SHOWVO calculates the vertex normals if they do not exist in the data file).

  If after all this is done, and the object looks like it is displaying
  "backwards", re-run CCWS with the -S option, and re-run VN to re-calcuate
  te new vertex normals.

  NOTE: These programs are not very smart. If you have any data in the file
  after the polygon definition (like vertex normals or textures), it will be
  lost when running TRI and CCWS. Just make sure you keep a backup of the extra
  data (I'll probably write a VO "assembler" util for the next repelase that will
  help with this). Sorry for the inconvience this causes.



Final notes:

  Well, thats about it. I can't really think of anything more to say about
  the format. I didn't include any sample loader code because the format
  is simple enough for anyone to follow, and I didn't feel like documenting
  any of my code. If you have any questions/comments/suggestions about the
  VO format or any utility suggestions, just ask, all comments will be
  considered.

  Phred/OTM
  achalfin@uceng.uc.edu

  Greets:
    OTM, TAP, #coders