man/man1/obj2rad.1

.\" RCSid "$Id: obj2rad.1,v 1.4 2007/09/04 17:36:40 greg Exp $"
.TH OBJ2RAD 1 6/14/94 RADIANCE
.SH NAME
obj2rad - convert Wavefront .OBJ file to RADIANCE description
.SH SYNOPSIS
.B obj2rad
[
.B \-n
][
.B \-f
][
.B "\-m mapfile"
][
.B "\-o objname"
]
[
.B input
]
.SH DESCRIPTION
.I 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
.I \-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.
.PP
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:
.nf

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

.fi
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.
.PP
Each rule can have up to one condition per qualifier, and different
translators use different qualifiers.
In
.I obj2rad,
the valid qualifiers are
.I "Material, Map, Group, Object"
and
.I 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.
.PP
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:
.nf

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

.fi
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.
.PP
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":
.nf

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

.fi
.PP
The
.I \-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.
.PP
The
.I \-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.
.PP
The
.I \-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,
.I obj2rad
will attempt to name surfaces based on their group associations.
.PP
If no input files are given, the standard input is read.
.SH DETAILS
The following Wavefront statements are understood and translated by
.I obj2rad.
.TP 10n
.BR #
A comment.
This statement is passed to the output verbatim.
It has no effect.
.TP
.BR 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.
.TP
.BR 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.
.TP
.BR o
Object name.
This is used to name the following faces, and may be used
in the mapping rules.
.TP
.BR 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.
.TP
.BR 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.
.TP
.BR v
A vertex, given by its x, y and z coordinates.
.TP
.BR vn
A vertex normal, given by its x, y and z direction components.
This vector will be normalized by
.I obj2rad,
and an error will result if it has length zero.
.TP
.BR vt
A vertex texture coordinate.
Not currently used, but will be if we ever get around to
supporting Wavefront textures.
.PP
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
.I obj2rad
did not recognize.
.SH EXAMPLES
To create a qualifier list for triceratops.obj:
.IP "" .2i
obj2rad \-n triceratops.obj > triceratops.qual
.PP
To translate triceratops.obj into a RADIANCE file using the mapping
triceratops.map:
.IP "" .2i
obj2rad \-m triceratops.map triceratops.obj > triceratops.rad
.SH FILES
tmesh.cal               - used for triangle normal interpolation
.br
surf.cal                - used for quadrilateral normal interpolation
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
arch2rad(1), ies2rad(1), obj2mesh(1), objutil(1) oconv(1), thf2rad(1), xform(1)
Revision:	1.5
Committed:	Mon Mar 30 18:28:35 2020 UTC (5 years, 1 month ago) by greg
Branch:	MAIN
CVS Tags:	rad5R4, rad5R3, HEAD
Changes since 1.4:	+6 -10 lines
Log Message:	Created robjutil tool to manipulate Wavefront .OBJ files
#	User	Rev	Content
1	greg	1.5	.\" RCSid "$Id: obj2rad.1,v 1.4 2007/09/04 17:36:40 greg Exp $"
2	greg	1.1	.TH OBJ2RAD 1 6/14/94 RADIANCE
3			.SH NAME
4	greg	1.5	obj2rad - convert Wavefront .OBJ file to RADIANCE description
5	greg	1.1	.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	greg	1.5	converts a Wavefront .OBJ file to a RADIANCE scene description.
22	greg	1.1	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	greg	1.5	a mapping for the given .OBJ file.
105	greg	1.1	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	greg	1.5	.SH EXAMPLES
191	greg	1.1	To create a qualifier list for triceratops.obj:
192			.IP "" .2i
193	greg	1.4	obj2rad \-n triceratops.obj > triceratops.qual
194	greg	1.1	.PP
195			To translate triceratops.obj into a RADIANCE file using the mapping
196			triceratops.map:
197			.IP "" .2i
198	greg	1.4	obj2rad \-m triceratops.map triceratops.obj > triceratops.rad
199	greg	1.1	.SH FILES
200			tmesh.cal - used for triangle normal interpolation
201			.br
202			surf.cal - used for quadrilateral normal interpolation
203			.SH AUTHOR
204			Greg Ward
205			.SH "SEE ALSO"
206	greg	1.5	arch2rad(1), ies2rad(1), obj2mesh(1), objutil(1) oconv(1), thf2rad(1), xform(1)