| 1 |
.\" RCSid "$Id: obj2rad.1,v 1.3 2003/12/09 15:59:06 greg Exp $" |
| 2 |
.TH OBJ2RAD 1 6/14/94 RADIANCE |
| 3 |
.SH NAME |
| 4 |
obj2rad - convert Wavefront .obj file to RADIANCE description |
| 5 |
.SH SYNOPSIS |
| 6 |
.B obj2rad |
| 7 |
[ |
| 8 |
.B \-n |
| 9 |
][ |
| 10 |
.B \-f |
| 11 |
][ |
| 12 |
.B "\-m mapfile" |
| 13 |
][ |
| 14 |
.B "\-o objname" |
| 15 |
] |
| 16 |
[ |
| 17 |
.B input |
| 18 |
] |
| 19 |
.SH DESCRIPTION |
| 20 |
.I Obj2rad |
| 21 |
converts a Wavefront .obj file to a RADIANCE scene description. |
| 22 |
The material names for the surfaces will assigned based on the |
| 23 |
mapping rules file given in the |
| 24 |
.I \-m |
| 25 |
option. |
| 26 |
If no mapping file is given, the identifiers given by the "usemtl" |
| 27 |
statements will be used as the material names. |
| 28 |
If no "usemtl" statements are found, the group names (given by |
| 29 |
the "g" statement) will be used instead. |
| 30 |
Failing this, the default material "white" will be used. |
| 31 |
.PP |
| 32 |
A mapping file contains a list of materials followed by the conditions |
| 33 |
a surface must satisfy in order to have that material. |
| 34 |
For example, if we wanted all faces in the Group "thingy" with |
| 35 |
texture Map "pine" to use the material "wood", |
| 36 |
and all other surfaces to use the |
| 37 |
material "default", we would create the following mapping file: |
| 38 |
.nf |
| 39 |
|
| 40 |
default ; |
| 41 |
wood (Group "thingy") (Map "pine") ; |
| 42 |
|
| 43 |
.fi |
| 44 |
All faces would satisfy the first set of conditions (which is empty), |
| 45 |
but only the faces in the Group "thingy" |
| 46 |
with texture Map "pine" would satisfy the |
| 47 |
second set of conditions. |
| 48 |
.PP |
| 49 |
Each rule can have up to one condition per qualifier, and different |
| 50 |
translators use different qualifiers. |
| 51 |
In |
| 52 |
.I obj2rad, |
| 53 |
the valid qualifiers are |
| 54 |
.I "Material, Map, Group, Object" |
| 55 |
and |
| 56 |
.I Face. |
| 57 |
A condition is either a single value for a |
| 58 |
specific attribute, or an integer range of values. |
| 59 |
(Integer ranges are |
| 60 |
specified in brackets and separated by a colon, eg. [\-15:27], and are |
| 61 |
always inclusive.) A semicolon is used to indicate the end of a rule, |
| 62 |
which can extend over several lines if necessary. |
| 63 |
.PP |
| 64 |
The semantics of the rule are such that "and" is the implied conjunction |
| 65 |
between conditions. |
| 66 |
Thus, it makes no sense to have more than one |
| 67 |
condition in a rule for a given qualifier. |
| 68 |
If the user wants the same |
| 69 |
material to be used for surfaces that satisfy different conditions, |
| 70 |
they simply add more rules. |
| 71 |
For example, if the user also wanted faces between 50 and 175 in the |
| 72 |
Group "yohey" to use "wood", |
| 73 |
they would add the following rule to the end of the example above: |
| 74 |
.nf |
| 75 |
|
| 76 |
wood (Face [50:175]) (Group "yohey") ; |
| 77 |
|
| 78 |
.fi |
| 79 |
Note that the order of conditions in a rule is irrelevant. |
| 80 |
However, |
| 81 |
the order of rules is very important, since the last rule satisfied |
| 82 |
determines which material a surface is assigned. |
| 83 |
.PP |
| 84 |
By convention, the identifier "void" is used to delete unwanted |
| 85 |
surfaces. |
| 86 |
A surface is also deleted if it fails to match any rule. |
| 87 |
Void is used in a rule as any other material, but it has the |
| 88 |
effect of excluding all matching surfaces from the translator output. |
| 89 |
For example, the following mapping would delete all surfaces in the |
| 90 |
Object "junk" except those with the Group name "beige", to which it |
| 91 |
would assign the material "beige_cloth", and all other surfaces |
| 92 |
would be "tacky": |
| 93 |
.nf |
| 94 |
|
| 95 |
tacky ; |
| 96 |
void (Object "junk") ; |
| 97 |
beige_cloth (Object "junk") (Group "beige") ; |
| 98 |
|
| 99 |
.fi |
| 100 |
.PP |
| 101 |
The |
| 102 |
.I \-n |
| 103 |
option may be used to produce a list of qualifiers from which to construct |
| 104 |
a mapping for the given .obj file. |
| 105 |
This is also useful for determining which materials must be defined |
| 106 |
when no mapping is used. |
| 107 |
.PP |
| 108 |
The |
| 109 |
.I \-f |
| 110 |
option is used to flatten all faces, effectively ignoring vertex |
| 111 |
normal information. |
| 112 |
This is sometimes desirable when a smaller model or more robust |
| 113 |
rendering is desired, since interpolating vertex normals takes time |
| 114 |
and is not always reliable. |
| 115 |
.PP |
| 116 |
The |
| 117 |
.I \-o |
| 118 |
option may be used to specify the name of this object, though it |
| 119 |
will be overriden by any "o" statements in the input file. |
| 120 |
If this option is absent, and there are no "o" statements, |
| 121 |
.I obj2rad |
| 122 |
will attempt to name surfaces based on their group associations. |
| 123 |
.PP |
| 124 |
If no input files are given, the standard input is read. |
| 125 |
.SH DETAILS |
| 126 |
The following Wavefront statements are understood and translated by |
| 127 |
.I obj2rad. |
| 128 |
.TP 10n |
| 129 |
.BR # |
| 130 |
A comment. |
| 131 |
This statement is passed to the output verbatim. |
| 132 |
It has no effect. |
| 133 |
.TP |
| 134 |
.BR f |
| 135 |
A polygonal face. |
| 136 |
If the vertices have associated surface normals, the face |
| 137 |
will be broken into quadrilaterals and triangles with the |
| 138 |
appropriate Radiance textures to interpolate them. |
| 139 |
Likewise, if the face is non-planar, it will be broken |
| 140 |
into triangles. |
| 141 |
Each face in the input file is assigned a number, starting with 1, |
| 142 |
and this number may be used in the material mapping rules. |
| 143 |
.TP |
| 144 |
.BR g |
| 145 |
Group association. |
| 146 |
The following faces are associated with the named group(s). |
| 147 |
These may be used in the mapping rules, where a rule is matched |
| 148 |
if there is an association with the named Group. |
| 149 |
(I.e. since there may be multiple group associations, any match |
| 150 |
is considered valid.) |
| 151 |
If a mapping file is not used and no "usemtl" statement has been |
| 152 |
encountered, the main group is used for the surface material |
| 153 |
identifier. |
| 154 |
.TP |
| 155 |
.BR o |
| 156 |
Object name. |
| 157 |
This is used to name the following faces, and may be used |
| 158 |
in the mapping rules. |
| 159 |
.TP |
| 160 |
.BR usemap |
| 161 |
A texture map (i.e. Radiance pattern) name. |
| 162 |
The name may be used in the material mapping rules, but |
| 163 |
the indexing of Radiance patterns is not yet supported. |
| 164 |
.TP |
| 165 |
.BR usemtl |
| 166 |
A material name. |
| 167 |
The name may be used in mapping rules, or will be used |
| 168 |
as the Radiance material identifier if no mapping is given. |
| 169 |
.TP |
| 170 |
.BR v |
| 171 |
A vertex, given by its x, y and z coordinates. |
| 172 |
.TP |
| 173 |
.BR vn |
| 174 |
A vertex normal, given by its x, y and z direction components. |
| 175 |
This vector will be normalized by |
| 176 |
.I obj2rad, |
| 177 |
and an error will result if it has length zero. |
| 178 |
.TP |
| 179 |
.BR vt |
| 180 |
A vertex texture coordinate. |
| 181 |
Not currently used, but will be if we ever get around to |
| 182 |
supporting Wavefront textures. |
| 183 |
.PP |
| 184 |
All other statement types will be ignored on the input. |
| 185 |
A final comment at the end of the Radiance output file will give some |
| 186 |
indication of how successful the translation was, since |
| 187 |
it will mention the number of statements |
| 188 |
.I obj2rad |
| 189 |
did not recognize. |
| 190 |
.SH EXAMPLE |
| 191 |
To create a qualifier list for triceratops.obj: |
| 192 |
.IP "" .2i |
| 193 |
obj2rad \-n triceratops.obj > triceratops.qual |
| 194 |
.PP |
| 195 |
To translate triceratops.obj into a RADIANCE file using the mapping |
| 196 |
triceratops.map: |
| 197 |
.IP "" .2i |
| 198 |
obj2rad \-m triceratops.map triceratops.obj > triceratops.rad |
| 199 |
.SH NOTES |
| 200 |
Many good and useful Wavefront object files are available by |
| 201 |
anonymous ftp from "avalon.chinalake.navy.mil" in the |
| 202 |
/pub/objects/obj directory. |
| 203 |
.SH FILES |
| 204 |
tmesh.cal - used for triangle normal interpolation |
| 205 |
.br |
| 206 |
surf.cal - used for quadrilateral normal interpolation |
| 207 |
.SH AUTHOR |
| 208 |
Greg Ward |
| 209 |
.SH "SEE ALSO" |
| 210 |
arch2rad(1), ies2rad(1), obj2mesh(1), oconv(1), thf2rad(1), xform(1) |
