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.
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