Radiance obj2rad program

OBJ2RAD(1)                                                          OBJ2RAD(1)

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  mate-
       rial  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 conjunc-
       tion 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 sur-
       faces.  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  exam-
       ple,  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 tri-
                 angles 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 associ-
                 ations, 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 Radi-
                 ance 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  map-
                 ping 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 compo-
                 nents.  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  com-
       ment  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)