NAME

       obj2rad - convert Wavefront .obj file to RADIANCE description

SYNOPSIS

       obj2rad [ -n ][ -f ][ -m mapfile ][ -o objname ] [ input ]

DESCRIPTION

       Obj2rad  converts  a  Wavefront  .obj  file  to a RADIANCE scene description.  The material names for the
       surfaces will assigned based on the mapping rules file given in the -m option.  If  no  mapping  file  is
       given,  the  identifiers  given  by  the  "usemtl"  statements will be used as the material names.  If no
       "usemtl" statements are found, the group names (given  by  the  "g"  statement)  will  be  used  instead.
       Failing this, the default material "white" will be used.

       A mapping file contains a list of materials followed by the conditions a surface must satisfy in order to
       have that material.  For example, if we wanted all faces in the Group "thingy" with texture Map "pine" to
       use  the  material  "wood",  and  all  other  surfaces to use the material "default", we would create the
       following mapping file:

            default ;
            wood (Group "thingy") (Map "pine") ;

       All faces would satisfy the first set of conditions (which is empty), but only the  faces  in  the  Group
       "thingy" with texture Map "pine" would satisfy the second set of conditions.

       Each rule can have up to one condition per qualifier, and different translators use different qualifiers.
       In  obj2rad,  the  valid  qualifiers  are Material, Map, Group, Object and Face.  A condition is either a
       single value for a specific attribute, or an integer range of values.  (Integer ranges are  specified  in
       brackets  and  separated  by  a  colon,  eg. [-15:27], and are always inclusive.)  A semicolon is used to
       indicate the end of a rule, which can extend over several lines if necessary.

       The semantics of the rule are such that "and" is the implied conjunction between  conditions.   Thus,  it
       makes  no  sense  to have more than one condition in a rule for a given qualifier.  If the user wants the
       same material to be used for surfaces that satisfy different conditions, they simply add more rules.  For
       example, if the user also wanted faces between 50 and 175 in the Group "yohey" to use "wood", they  would
       add the following rule to the end of the example above:

            wood (Face [50:175]) (Group "yohey") ;

       Note  that  the  order  of  conditions  in  a  rule  is  irrelevant.  However, the order of rules is very
       important, since the last rule satisfied determines which material a surface is assigned.

       By convention, the identifier "void" is used to delete unwanted surfaces.  A surface is also  deleted  if
       it  fails  to  match  any  rule.   Void is used in a rule as any other material, but it has the effect of
       excluding all matching surfaces from the translator output.  For example,  the  following  mapping  would
       delete  all  surfaces  in  the  Object "junk" except those with the Group name "beige", to which it would
       assign the material "beige_cloth", and all other surfaces would be "tacky":

            tacky ;
            void (Object "junk") ;
            beige_cloth (Object "junk") (Group "beige") ;

       The -n option may be used to produce a list of qualifiers from which to construct a mapping for the given
       .obj file.  This is also useful for determining which materials must be defined when no mapping is used.

       The -f option is used to flatten all faces, effectively ignoring  vertex  normal  information.   This  is
       sometimes  desirable when a smaller model or more robust rendering is desired, since interpolating vertex
       normals takes time and is not always reliable.

       The -o option may be used to specify the name of this object, though it will  be  overriden  by  any  "o"
       statements  in  the  input file.  If this option is absent, and there are no "o" statements, obj2rad will
       attempt to name surfaces based on their group associations.

       If no input files are given, the standard input is read.

DETAILS

       The following Wavefront statements are understood and translated by obj2rad.

       #         A comment.  This statement is passed to the output verbatim.  It has no effect.

       f         A polygonal face.  If the vertices have associated surface normals, the  face  will  be  broken
                 into  quadrilaterals  and triangles with the appropriate Radiance textures to interpolate them.
                 Likewise, if the face is non-planar, it will be broken into triangles.  Each face in the  input
                 file is assigned a number, starting with 1, and this number may be used in the material mapping
                 rules.

       g         Group  association.   The following faces are associated with the named group(s).  These may be
                 used in the mapping rules, where a rule is matched if there is an association  with  the  named
                 Group.   (I.e.  since there may be multiple group associations, any match is considered valid.)
                 If a mapping file is not used and no "usemtl" statement has been encountered, the main group is
                 used for the surface material identifier.

       o         Object name.  This is used to name the following faces, and may be used in the mapping rules.

       usemap    A texture map (i.e. Radiance pattern) name.  The name may  be  used  in  the  material  mapping
                 rules, but the indexing of Radiance patterns is not yet supported.

       usemtl    A  material  name.   The  name  may  be  used in mapping rules, or will be used as the Radiance
                 material identifier if no mapping is given.

       v         A vertex, given by its x, y and z coordinates.

       vn        A vertex normal, given by its x, y and z direction components.  This vector will be  normalized
                 by obj2rad, and an error will result if it has length zero.

       vt        A  vertex  texture  coordinate.   Not  currently  used,  but  will  be if we ever get around to
                 supporting Wavefront textures.

       All other statement types will be ignored on the input.  A final comment  at  the  end  of  the  Radiance
       output  file  will  give some indication of how successful the translation was, since it will mention the
       number of statements obj2rad did not recognize.

EXAMPLE

       To create a qualifier list for triceratops.obj:

         obj2rad -n triceratops.obj > triceratops.qual

       To translate triceratops.obj into a RADIANCE file using the mapping triceratops.map:

         obj2rad -m triceratops.map triceratops.obj > triceratops.rad

NOTES

       Many   good   and   useful   Wavefront   object   files   are   available   by   anonymous    ftp    from
       "avalon.chinalake.navy.mil" in the /pub/objects/obj directory.

FILES

       tmesh.cal      - used for triangle normal interpolation
       surf.cal       - used for quadrilateral normal interpolation

AUTHOR

       Greg Ward

SEE ALSO

       arch2rad(1), ies2rad(1), obj2mesh(1), oconv(1), thf2rad(1), xform(1)

RADIANCE                                             6/14/94                                          OBJ2RAD(1)