    This file describes how the entities defined in an AutoCAD 10.0 DXF file are
    treated by the converter, how to install and run this converter. Please
    refer "AutoCAD 10.0 Reference Manual" for related information about the
    format of an AutoCAD 10.0 DXF, especially Appendix C "Drawing Interchange
    and File Format" (pp.395-413).


I. TREATMENT OF ENTITY GEOMETRY

    In this section, the treatment of geometric information of each entity is
    described.

 1. LINE
    If a LINE has no thickness, no face will be defined. If it has, then a
    parallel tetragon will be defined along the extrusion direction. This
    3DFACE will not be tesselated by the converter.

 2. POINT
    A POINT is used as a reference point for checking the orientation of all
    faces defined by entities in a layer. If a layer has no reference point and
    the layer name has an "_I" suffix, the orientation of faces of all *closed*
    objects which may be defined by entities like CIRCLE, TRACE, SOLID and
    POLYLINE will be reversed. If a layer has a reference point, and the layer
    name has no "_I" suffix, then the normal vectors of all faces defined by
    entities in this layer have to point toward that point; and if the layer
    name has an "_I" suffix, then the normal vectors have to be reversed against
    the point. See section III for related information about layer name
    treatment.

 3. CIRCLE
    A CIRCLE may define a circle disk, if it has no thickness. Otherwise it
    defines a *closed* circle cylinder along the extrusion direction. The
    tesselation of a circle disk or a *closed* circle cylinder will be described
    in section II.

 4. ARC
    If an ARC has no thickness, no face will be defined. If it has, then a set
    of rectangle will be defined along the extrusion direction. Those rectangle
    will be tesselated by the converter. See section II for more information.

 5. TRACE
    A TRACE must have 4 points lying on one plane, but the third and the forth
    points are the same for a triangle. If a TRACE has no thickness, only one
    tetragon or triangle will be defined. Otherwise, a *closed* 2-1/2D polygon
    cylinder will be defined by sweeping the TRACE along its extrusion
    direction. The side faces of the cylinder are rectangles, which will not
    be tesselated by the converter.

 6. SOLID
    A SOLID will be treated as the same as a TRACE.

 7. TEXT
    A TEXT will not be handled by the converter.

 8. SHAPE
    A SHAPE will not be handled by the converter.

 9. BLOCK
    A BLOCK may include many entities, including other BLOCKs. But a BLOCK 
    cannot be defined recursively. Unlike other kind of entities, a BLOCK is
    defined only in the BLOCKS section of a DXF file and is instanced by INSERT
    entities. The definition of a BLOCK ends with an "ENDBLK" entity and may
    includes a series of ATTRIB entities. See section III about treatment of
    block names.

10. ENDBLK
    An ENDBLK indicates the end of a BLOCK definition. See BLOCK for more
    information.

11. INSERT
    A INSERT have transformation parameters for entities defined in the BLOCK
    to be instanced. Its layer name will not handled by the converter.

12. ATTDEF
    An ATTDEF will not be handled by the converter.

13. ATTRIB
    An ATTRIB will not be handled by the converter.

14. POLYLINE
    POLYLINE entities are the most complex ones in a DXF file.

    A POLYLINE will define a set of tetragons, which will be tesselated if they
    are not meshes.

    A POLYLINE may have starting width and ending width. Right now the two width
    numbers should be the same as I think it is very difficult to implement a
    good way to handle various widths, even AutoCAD 10.0 do not have one.
  
    A POLYLINE may be a curve or spline, which cannot be handled by the
    converter as I do not know exactly what fomula are used in AutoCAD 10.0 to
    tesselate (or regenerate) them. So for a curve or spline, they have to be
    converted into polylines first in AutoCAD before outputting them into DXF
    files.

    A POLYLINE may be a mesh. Only the polygon meshes can be handled by the
    converter. Other mesh types for smooth surfaces, i.e. quadratic B-spline
    surfaces, cubic B-spline surfaces, Bezier surfaces and Coons surfaces,
    cannot be handled, since I do not know how to regenerate them as the same
    way as AutoCAD 10.0 does. So for smooth surfaces, they have to be converted
    into polygon meshes first in AutoCAD before outputing them into DXF files.

    A segment of a POLYLINE may be an arc or a line. This information is stored
    in the VERTEX data structure. The tesselation of an arc will be described in
    section II.

    A VERTEX is always and only following a POLYLINE entity with a "SEQEND"
    entity indicating the end of the VERTEX sequence. It may have starting and
    ending widths. Right now they are not used as it is very difficult to
    implement various width. Only the default widths of the POLYLINE are
    used, but they should be the same as said before. As there is no smooth
    surface can be handled by the converter, there are only 3D polyline vertices
    or 3D polygon mesh vertices in VERTEX sequences following POLYLINE entities.
    A VERTEX may have curve fit tangent, but I cannot handle it as I cannot
    handle curves and curve surfaces.
  
    The bulge value of a VERTEX is the tangent of 1/4 the included angle for
    an ARC segment, made negative if the arc goes clockwise from the start
    point to the end point; for example, a bulge of 0 indicates a straight
    segment, and a bulge of 1 is a semi-circle.
  
    The surfaces, i.e. tetragons, defined by a POLYLINE entity are treated as
    follows:
  
    1. If it is just a simple polygon
       1. If it has nonzero width only, then the surfaces are a set of tetragons
          lying on the extrusion plane
       2. If it has thickness only, then the surfaces are a set of parallel
          tetragons orthogonal to the extrusion plane, i.e. parallel to its
          extrusion direction. If the polyline is *closed*, and its layer name
          has an "_I" suffix, but the reference point is not defined, the
          orientation of the faces defined by the polyline have to be reversed.
       3. If it has both width and thickness, then the surfaces will defined
          a *closed* object with its bottom lying in the extrusion plane and
          its cup parallel to the extrusion plane, and a set of side faces,
          rectangles, parallel to the extrusion direction. If the layer name of
          the polygon has an "_I" suffix, but the reference points is not
          defined, the orientation of the faces defined by the polyline have to
          be reversed. 

       The tesselation of the surfaces defined as above will be handled as
       follows:
       1. If there are arcs as segments of the polyline, the minimum tesselation
          length for surfaces, i.e. tetragons, lying on the extrusion plane, or
          parallel to the extrusion is the minimum tesselation length of all
          those arcs.
       2. If there is no arc segment, the minimum tesselation is the width of
          the polyline when there is nonzero width.
       3. If the polyline is closed and has thickness, but no width, the minimum
          tesselation is the minimum length of all line segments. But if the
          thickness is smaller than the minimum length, no treatment for the
          side faces, i.e. parallel tetragons, parallel to the extrusion
          direction.
  
    2. If it is a 3D polyline, i.e. its vertices do not lie in the same plane,
       then it will be treated as sub-case 2 of case 1, only if it has
       thickness. A 3D polyline cannot have arcs as its segments.
  
    3. If it is a 3D mesh, it cannot be extruded, nor have width, the surfaces
       are just a set of tetragons, although the four points of a tetragon may
       not always lie on one plane. No tesselation will be performed for
       surfaces defined by a 3D mesh. As there is a special primitive called
       'ppatch' (Phong Patch) in NFF format, a mesh is mapped into patch
       with additional normal information for smoothness.
  
    Note if the object defined by a POLYLINE with or without width is
    intersected with itself, unexpected results will occur.

15. VERTEX
    See POLYLINE for more information.

16. SEQEND
    See POLYLINE for more information

17. 3DLINE
    A 3DLINE is treated as the same as a LINE.

18. 3DFACE
    A 3DFACE defines only a tetragon, although the third and the forth points
    are the same for a triangle. The four points of a tetragon defined by
    3Dface may not lie on one plane and the tetragon will not be tesselated by
    the converter.

19. DIMENSION
    A DIMENSION will not be handled by the converter.


II. TESSELATION OF SURFACES
    The tesselation is performed on surfaces defined by entities with circle
    or arcs, i.e. CIRCLE, ARC and POLYLINE. The tesselation is based on the
    circle tesselation. The minimum tesselation number for a circle is defined
    in the defs.h file as a constant. You cannot modify this number without
    recompiling the whole source code. However, if you want to increase the
    the minimum tesselation number of a circle, you could achieve the same goal
    by providing an option in the command line for a minimum radius number,
    which is 10 as default, of circle tesselation. See section V for more
    information about how to specify this parameter. The tesselation number
    of an ARC is determined by the delta angle it has, comparing to 360 degree
    a circle has. The circle disk, or the bottom and cup of a circle cylinder
    are tesselated into triangles for DEF and DXF files, but not for NFF file
    as the Raytracing package supports a general circle cylinder primitive.
    Those symmetric triangles for tesselating a circle disk in a DEF files have
    to be further tesselated into a short triangle and a set of more-squared
    planer tetragons. The tesselation number of a triangle is determined by
    the ratio of the circle radius and the length of bottom edge of the
    triangle. For the side faces of objects defined by circles or arcs, i.e.
    rectangles, the tesselation number is determined by the ratio of the
    thickness of the circle and the length of the bottom edge of the triangle
    the rectangle connected.

    For a polygon with width, but no arcs as its segment, the width is used
    as tesselation number. If it has arcs, then the smaller one between the
    minimum value tesselation value and the width is chosen as the tesselation
    value for the bottom and cup tetragons, if there are any. But for the
    sides faces, i.e. rectangles, if any, the tesselation value is determined
    by the ratio of the thickness and the minimum tesselation number of arcs
    on the polyline.


III. TREATMENT OF BLOCK NAMES AND LAYER NAMES
    The layer name of an entity is used as an index to describe the properties
    of the surfaces (for NFF files) and surface subdivision (for DEF files),
    or layer name of a exploded (3DFACE only) DXF files. If the entity is
    insided a BLOCK, then the block name appended with "-" and the layer name
    will be used. See section IV for related information.

IV. OUTPUT FILES
    As said in section II, there are three types of outputs the converter
    generated.

    1. DEF files: The DEF files are used by my Radiosity package. There are
       two files, one with the ".def" suffix, which defines all the surfaces in
       the scene; another with the ".obj" suffix, which defines all object names
       occurring in the ".def" file, and it will be used as an index file for
       surface property and subdivision definitions. See the README file, the
       DEF-RULE file and the scene.y file in the Radiosity package for more
       information about the DEF file format. Note the profile surface of an
       object are not supported right now either by the converter and the
       Radiosity package. It will be included in the later release.

    2. NFF files: The NFF files are used by the Raytracing package. There
       are two files, one with the ".nff" suffix, which defines all the surfaces
       in the scene; another with the ".surf" suffix (or ."sur" on MSDOS),
       which defines all surface names occurring in the ".nff" file, and it will
       be used as an index file for surface property definitions. See the
       NFF-RULE file and the nff.y file in the Raytracing package for more
       information about the NFF file format.

    3. DXF files: The DXF files are used by AutoCAD for verifying the converting
       and tesselating of the converter. All BLOCKs are exploded and the only
       entity type occurs is 3DFACE. There are two files, one with the ".ent"
       suffix, which defines all the 3DFACEs in the scene; another with the
       ".lay" suffix, which defines all the layer names occurring in the ".ent"
       file. Note the layer name of an entity in a BLOCK will be the block name
       appended with "-" and the entity layer name. See Appendix C of "AutoCAD
       10.0 Reference Manual" for more information about the DXF file format.

    4. RAD files: The RAD files are used by Greg Ward's RADIANCE package. There
       are two files, one with the ".mod" suffix, which contains a list of
       all modifiers occurring in the scene; another with ".rad" suffix which
       defines all primitives. See RADIANCE manual for more information about
       the file format.

V. HOW TO INSTALL AND RUN THE CONVERTER

    To compile and install the converter is very simple. First you have to
    create a directory and then copy all source codes into that directory you
    just created. Make sure your current working directory is current. Then
    you have to define some basic constants in the config.h file for indication
    what kind of system you have and what kind of data type your machine
    supports. Afterwards, you can use the make command for compiling the
    converter. If your machine is a IBM-PC or compatible running MS-DOS, and
    MSC-4.0 or later is on your PC, you can compile the converter by issuing
    the command:

                    make Makefile.MSC

    If you have MetaWare C 1.6 or later with Phar Lap DOS|Extender 2.2d or
    later on your PC, you should type the command:

                    make Makefile.HC

    Note the Makefile.HC file is for the make command of MSC-4.0, as the Make
    utility from MetaWare is not available during the development. On UNIX
    platforms, and your machine is not running HP-UX, you have to use the
    commands as follows:

                make depend
                make

    If your machine is running HP-UX, use the follow command instead

                make -f Makefile.HP-UX

    After compiling and linking, a file called "dxfcvt" on UNIX machines,
    or "dxfcvt.exe" on MS-DOS machines, will be generated. You could install
    the by copying it to the command directory as you desire.

    To know how to run this program, just simply type a command like

                dxfcvt

    you will get a on-line menu on your terminal screen. It looks like this

	usage: dxfcvt [-o[def|nff|dxf|rad] outfile] [-l libdxffile...]
		      [-i indxffile...] [-m radius] [-s joinstr] [-p prefix]
		      [-l layer]
       
       -odef outfile: convert a DXF file into DEF format
                      the output files are outfile.obj and outfile.def
       -onff outfile: convert a DXF file into NFF format
                      the output files are outfile.sur and outfile.nff
       -odxf outfile: convert a DXF file into a DXF file which has no
                      only 3DFACE entities
                      the output file are outfile.lay and outfile.ent
       -orad outfile: convert a DXF file into RADIANCE input format
                      the output files are outfile.mod and outfile.rad
       -l libdxffile: specify a set of library DXF files defining BLOCKs
                      their ENTITIES sections are also included
       -i inputfile : specify a set of input DXF files defining objects
                      both BLOCKS and ENTITIES sections of them are used
       -m minradius : specify a minimum value of circle radius for
                      tesselate CIRCLEs and ARCs. its default value is 10
       -s string    : string linking block name and layer name. default is '_'
       -p string    : string as a prefix for a name starting with non-alpha
                      char. default is '_'
       -n layer     : change default 'block name + layer' name mode into
                      'layer name' only mode
       
       note: if none of the -odef, -onff, -odxf and -orad options is specified,
             only the syntax of the library DXF files and/or the input DXF
             files are checked, and there is no file created
             at least, either the -l option or the -i option should be
             supplied

    I think the on-line information is enough for running the converter. You
    may see section IV for details about the meaning of the output files.


VI. REPORTING BUGS

    This converter was developed for using AutoCAD 10.0 as the modeling system
    to build scenes for my Radiosity and Raytracing packages. This converter was
    developed on IBM-PC/DOS platform with MSC 4.0 or MetaWare C 1.6. It's very
    trivial to port it onto other architectures running UNIX, such as SUN-3,
    SUN-4, HP-9000/3xx, HP-9000/8xx, Multiflow TRACE, and so on. While I have
    tested this program on the architectures mentioned above and it probably
    will work on others, no guarantees...

    Of course, there are a lot of bugs inside the code. Should you significantly
    extend the program, through bug fixes or additional features, please send
    the changes back to me for inclusion in later versions of the program. And
    any suggestions about improving this program are welcome. Thanks!


    Ning Zhang

    Permanent Address:
    c/o: Prof. Zhijun He
    Artificial Intelligence Institute
    Zhejiang University
    Hangzhou, Zhejiang
    310013 P.R.China
    Fax:       +86 (571) 571197
    Telephone: +86 (571) 570057

    Current Address:
    Laboratory for Image Science and Engineering
    School of Electric Engineering
    The University of Sydney
    NSW 2006, Australia
    Email: nzhang@ee.su.oz.au
    Telephone: +61 (2) 692 2962
