man/man1/obj2mesh.1

.\" RCSid "$Id: obj2mesh.1,v 1.9 2007/07/12 14:58:52 greg Exp $"
.TH OBJ2MESH 1 03/11/03 RADIANCE
.SH NAME
obj2mesh - create a compiled RADIANCE mesh file from Wavefront .OBJ input
.SH SYNOPSIS
.B obj2mesh
[
.B "\-a matfile"
][
.B "\-l matlib"
][
.B "\-n objlim"
][
.B "\-r maxres"
][
.B \-w
]
[
.B "input.obj"
[
.B "output.rtm"
]
]
.SH DESCRIPTION
.I Obj2mesh
reads a Wavefront .OBJ file from
.I input.obj
(or the standard input) and compiles it into a RADIANCE triangle mesh,
which is sent to
.I output.rtm
(or standard output).
Any RADIANCE material descriptions included via one or more
.I \-a
options will be compiled and stored in the mesh as well.
If the
.I \-l
option is used to specify a material file, the RADIANCE library
locations are searched.
This mesh may be included in a RADIANCE scene description via the
.I mesh
primitive, thus:
.IP "" .2i
mod mesh id
.br
1+ output.rtm [xform args]
.br
0
.br
0
.PP
The syntax and semantics are identical to the RADIANCE
.I instance
primitive.
If
.I mod
is "void", then the stored mesh materials will be applied during rendering.
Otherwise, the given material will be substituted on
all the mesh surfaces.
.PP
The
.I \-n
option specifies the maximum surface set size for
each voxel.
Larger numbers result in quicker mesh generation,
but potentially slower rendering.
Values below 6 are not recommended, since this is the median
valence for a mesh vertex (the number of adjacent faces),
and smaller values will result in pointless octree subdivision.
The default setting is 9.
.PP
The
.I \-r
option specifies the maximum octree resolution.
This should be greater than or equal to the ratio of the mesh bounding
box to the smallest triangle.
The default is 16384.
.PP
The
.I \-w
option suppresses warnings.
.PP
Although the mesh file format is binary, it is meant to be portable
between machines.
The only limitation is that machines with radically different integer
sizes will not work together.
.SH DETAILS
The following Wavefront statements are understood and compiled by
.I obj2mesh.
.TP 10n
.BI v " x y z"
A vertex location, given by its Cartesian coordinates.
The final mesh position may of course be modified by
the transform arguments given to the
.I mesh
primitive in the Radiance scene description.
.TP
.BI vn " dx dy dz"
A vertex normal vector, given by its three
direction components, which will be normalized by
.I obj2mesh.
Normals will be interpolated over the mesh
during rendering to produce a smooth surface.
If no vertex normals are present, the mesh will appear tesselated.
A zero length normal (i.e., 0 0 0) will generate a syntax error.
.TP
.BI vt " u v"
A local vertex texture coordinate.
These coordinates will be interpolated and passed
to the "Lu" and "Lv" variables during rendering.
Local coordinates can extend over any desired range of values.
.TP
.BI usemtl " mname"
A material name.
The following faces will use the named material, which is
taken from the material definitions in the
.I \-a
input file(s).
.TP
.BI g " gname"
Group association.
The following faces are associated with the named group.
If no "usemtl" statement has been
encountered, the current group is used for the surface material
identifier.
.TP
.BI f " v1/t1/n1 v2/t2/n2 v3/t3/n3" " .."
A polygonal face.
Polygon vertices are specified as three indices separated
by slashes ('/').
The first index is the vertex location, the
second index is the local (u,v) texture coordinate, and the
third index is the vertex surface normal.
Positive indices count from the beginning of the input,
where the first vertex position (
.I v
statement) is numbered 1, and likewise
for the first texture coordinate and the first surface normal.
Negative indices count backward from the current position in
the input, where \-1 is the last vertex encountered, \-2
is the one before that, etc.
An index of 0 may be used for the vertex texture or normal to
indicate none, or these may be left off entirely.
All faces will be broken into triangles in the final mesh.
.I Obj2mesh
currently makes an unsafe assumption that faces are convex,
which may result in odd results if they are not.
.PP
All other statement types will be ignored on the input.
Statements understood by
.I obj2rad(1)
will be ignored silently; other statements will generate
a warning message after translation to indicate how much was missed.
.SH DIAGNOSTICS
There are four basic error types reported by obj2mesh:
.IP
warning - a non-fatal input-related error
.IP
fatal - an unrecoverable input-related error
.IP
system - a system-related error
.IP
internal - a fatal error related to program limitations
.IP
consistency - a program-caused error
.PP
Most errors are self-explanatory.
However, the following internal errors should be mentioned:
.IP "Set overflow in addobject (id)"
This error occurs when too many surfaces are close together in a
scene.
Sometimes a dense mesh can be accommodated by increasing
the maximum resolution (by powers of two) using the
.I \-r
option, but usually this error indicates something is wrong.
Either too many surfaces are lying right on top of each other,
or the bounding cube is inflated from disparate geometry
in the input.
Chances are, the face number "id" is near
those causing the problem.
.IP "Hash table overflow in fullnode"
This error is caused by too many surfaces, and there is
little hope of compiling this mesh.
.SH EXAMPLES
To create a compiled triangle mesh from the scene file mesh.obj
using materials from the file mesh.mat:
.IP "" .2i
obj2mesh \-a mesh.mat mesh.obj mesh.rtm
.PP
To use local coordinates to place a square tiled image on a mesh object:
.sp
.nf
void colorpict tiled_pat
7 red green blue mytile.pic . frac(Lu) frac(Lv)
0
0

tiled_pat plastic tiled_mat
0
0
5 .9 .9 .9 0 0

tiled_mat mesh tiled_mesh
1 mymesh.rtm
0
0
.fi
.SH ENVIRONMENT
RAYPATH         the directories to search for material files.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
gensurf(1), getinfo(1), make(1), obj2rad(1),
oconv(1), rpict(1), rvu(1), rtrace(1), xform(1)
Revision:	1.10
Committed:	Tue Sep 4 17:36:40 2007 UTC (16 years, 8 months ago) by greg
Branch:	MAIN
CVS Tags:	rad3R9
Changes since 1.9:	+3 -3 lines
Log Message:	Added backslashes in front of hyphens (thanks to Bernd Zeimetz for his effort)
#	User	Rev	Content
1	greg	1.10	.\" RCSid "$Id: obj2mesh.1,v 1.9 2007/07/12 14:58:52 greg Exp $"
2	greg	1.1	.TH OBJ2MESH 1 03/11/03 RADIANCE
3			.SH NAME
4			obj2mesh - create a compiled RADIANCE mesh file from Wavefront .OBJ input
5			.SH SYNOPSIS
6			.B obj2mesh
7			[
8	greg	1.8	.B "\-a matfile"
9			][
10			.B "\-l matlib"
11	greg	1.3	][
12	greg	1.1	.B "\-n objlim"
13			][
14			.B "\-r maxres"
15			][
16			.B \-w
17			]
18			[
19			.B "input.obj"
20			[
21			.B "output.rtm"
22			]
23			]
24			.SH DESCRIPTION
25			.I Obj2mesh
26			reads a Wavefront .OBJ file from
27			.I input.obj
28			(or the standard input) and compiles it into a RADIANCE triangle mesh,
29			which is sent to
30			.I output.rtm
31			(or standard output).
32	greg	1.3	Any RADIANCE material descriptions included via one or more
33			.I \-a
34			options will be compiled and stored in the mesh as well.
35	greg	1.8	If the
36			.I \-l
37			option is used to specify a material file, the RADIANCE library
38			locations are searched.
39	greg	1.1	This mesh may be included in a RADIANCE scene description via the
40			.I mesh
41			primitive, thus:
42			.IP "" .2i
43			mod mesh id
44			.br
45			1+ output.rtm [xform args]
46			.br
47			0
48			.br
49			0
50			.PP
51	greg	1.2	The syntax and semantics are identical to the RADIANCE
52	greg	1.1	.I instance
53	greg	1.3	primitive.
54			If
55			.I mod
56			is "void", then the stored mesh materials will be applied during rendering.
57			Otherwise, the given material will be substituted on
58			all the mesh surfaces.
59	greg	1.1	.PP
60			The
61			.I \-n
62			option specifies the maximum surface set size for
63			each voxel.
64	greg	1.9	Larger numbers result in quicker mesh generation,
65			but potentially slower rendering.
66	greg	1.2	Values below 6 are not recommended, since this is the median
67			valence for a mesh vertex (the number of adjacent faces),
68			and smaller values will result in pointless octree subdivision.
69	greg	1.9	The default setting is 9.
70	greg	1.1	.PP
71			The
72			.I \-r
73			option specifies the maximum octree resolution.
74			This should be greater than or equal to the ratio of the mesh bounding
75			box to the smallest triangle.
76			The default is 16384.
77			.PP
78			The
79			.I \-w
80			option suppresses warnings.
81			.PP
82			Although the mesh file format is binary, it is meant to be portable
83			between machines.
84			The only limitation is that machines with radically different integer
85			sizes will not work together.
86	greg	1.2	.SH DETAILS
87			The following Wavefront statements are understood and compiled by
88			.I obj2mesh.
89			.TP 10n
90			.BI v " x y z"
91			A vertex location, given by its Cartesian coordinates.
92			The final mesh position may of course be modified by
93			the transform arguments given to the
94			.I mesh
95			primitive in the Radiance scene description.
96			.TP
97			.BI vn " dx dy dz"
98			A vertex normal vector, given by its three
99			direction components, which will be normalized by
100			.I obj2mesh.
101			Normals will be interpolated over the mesh
102			during rendering to produce a smooth surface.
103	greg	1.7	If no vertex normals are present, the mesh will appear tesselated.
104	greg	1.2	A zero length normal (i.e., 0 0 0) will generate a syntax error.
105			.TP
106			.BI vt " u v"
107			A local vertex texture coordinate.
108			These coordinates will be interpolated and passed
109			to the "Lu" and "Lv" variables during rendering.
110			Local coordinates can extend over any desired range of values.
111	greg	1.3	.TP
112			.BI usemtl " mname"
113			A material name.
114			The following faces will use the named material, which is
115			taken from the material definitions in the
116			.I \-a
117			input file(s).
118			.TP
119			.BI g " gname"
120			Group association.
121			The following faces are associated with the named group.
122			If no "usemtl" statement has been
123			encountered, the current group is used for the surface material
124			identifier.
125	greg	1.2	.TP
126			.BI f " v1/t1/n1 v2/t2/n2 v3/t3/n3" " .."
127			A polygonal face.
128			Polygon vertices are specified as three indices separated
129			by slashes ('/').
130			The first index is the vertex location, the
131			second index is the local (u,v) texture coordinate, and the
132			third index is the vertex surface normal.
133			Positive indices count from the beginning of the input,
134			where the first vertex position (
135			.I v
136			statement) is numbered 1, and likewise
137			for the first texture coordinate and the first surface normal.
138			Negative indices count backward from the current position in
139	greg	1.10	the input, where \-1 is the last vertex encountered, \-2
140	greg	1.2	is the one before that, etc.
141			An index of 0 may be used for the vertex texture or normal to
142			indicate none, or these may be left off entirely.
143			All faces will be broken into triangles in the final mesh.
144			.I Obj2mesh
145			currently makes an unsafe assumption that faces are convex,
146			which may result in odd results if they are not.
147			.PP
148			All other statement types will be ignored on the input.
149			Statements understood by
150			.I obj2rad(1)
151			will be ignored silently; other statements will generate
152			a warning message after translation to indicate how much was missed.
153	greg	1.1	.SH DIAGNOSTICS
154			There are four basic error types reported by obj2mesh:
155			.IP
156			warning - a non-fatal input-related error
157			.IP
158			fatal - an unrecoverable input-related error
159			.IP
160			system - a system-related error
161			.IP
162			internal - a fatal error related to program limitations
163			.IP
164			consistency - a program-caused error
165			.PP
166			Most errors are self-explanatory.
167			However, the following internal errors should be mentioned:
168			.IP "Set overflow in addobject (id)"
169			This error occurs when too many surfaces are close together in a
170			scene.
171	greg	1.2	Sometimes a dense mesh can be accommodated by increasing
172	greg	1.1	the maximum resolution (by powers of two) using the
173			.I \-r
174			option, but usually this error indicates something is wrong.
175			Either too many surfaces are lying right on top of each other,
176			or the bounding cube is inflated from disparate geometry
177			in the input.
178			Chances are, the face number "id" is near
179			those causing the problem.
180			.IP "Hash table overflow in fullnode"
181			This error is caused by too many surfaces, and there is
182			little hope of compiling this mesh.
183	greg	1.7	.SH EXAMPLES
184	greg	1.5	To create a compiled triangle mesh from the scene file mesh.obj
185			using materials from the file mesh.mat:
186	greg	1.1	.IP "" .2i
187	greg	1.10	obj2mesh \-a mesh.mat mesh.obj mesh.rtm
188	greg	1.7	.PP
189			To use local coordinates to place a square tiled image on a mesh object:
190			.sp
191			.nf
192			void colorpict tiled_pat
193			7 red green blue mytile.pic . frac(Lu) frac(Lv)
194			0
195			0
196
197			tiled_pat plastic tiled_mat
198			0
199			0
200			5 .9 .9 .9 0 0
201
202			tiled_mat mesh tiled_mesh
203			1 mymesh.rtm
204			0
205			0
206			.fi
207	greg	1.8	.SH ENVIRONMENT
208			RAYPATH the directories to search for material files.
209	greg	1.1	.SH AUTHOR
210			Greg Ward
211			.SH "SEE ALSO"
212	greg	1.2	gensurf(1), getinfo(1), make(1), obj2rad(1),
213	greg	1.6	oconv(1), rpict(1), rvu(1), rtrace(1), xform(1)