man/man1/obj2mesh.1

.\" RCSid "$Id"
.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 "\-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).
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, except that the mesh modifier may not be "void", since
materials are not included in a compiled mesh file.
.PP
The
.I \-n
option specifies the maximum surface set size for
each voxel.
Larger numbers result in quicker mesh generation needing
less memory, but potentially slower rendering.
Smaller values may produce faster renderings,
since the default number (15) is on the high side to reduce
the compiled mesh octree size.
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.
.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 mess 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 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 EXAMPLE
To create a compiled triangle mesh from the scene file mesh.obj:
.IP "" .2i
oconv mesh.obj mesh.rtm
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
gensurf(1), getinfo(1), make(1), obj2rad(1),
oconv(1), rpict(1), rview(1), rtrace(1), xform(1)
Revision:	1.2
Committed:	Wed Mar 12 17:26:58 2003 UTC (22 years, 2 months ago) by greg
Branch:	MAIN
Changes since 1.1:	+59 -6 lines
Log Message:	Returned old behavior with flat surfaces and improved documentation
#	User	Rev	Content
1	greg	1.1	.\" RCSid "$Id"
2			.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			.B "\-n objlim"
9			][
10			.B "\-r maxres"
11			][
12			.B \-w
13			]
14			[
15			.B "input.obj"
16			[
17			.B "output.rtm"
18			]
19			]
20			.SH DESCRIPTION
21			.I Obj2mesh
22			reads a Wavefront .OBJ file from
23			.I input.obj
24			(or the standard input) and compiles it into a RADIANCE triangle mesh,
25			which is sent to
26			.I output.rtm
27			(or standard output).
28			This mesh may be included in a RADIANCE scene description via the
29			.I mesh
30			primitive, thus:
31			.IP "" .2i
32			mod mesh id
33			.br
34			1+ output.rtm [xform args]
35			.br
36			0
37			.br
38			0
39			.PP
40	greg	1.2	The syntax and semantics are identical to the RADIANCE
41	greg	1.1	.I instance
42			primitive, except that the mesh modifier may not be "void", since
43			materials are not included in a compiled mesh file.
44			.PP
45			The
46			.I \-n
47			option specifies the maximum surface set size for
48			each voxel.
49			Larger numbers result in quicker mesh generation needing
50			less memory, but potentially slower rendering.
51			Smaller values may produce faster renderings,
52			since the default number (15) is on the high side to reduce
53			the compiled mesh octree size.
54	greg	1.2	Values below 6 are not recommended, since this is the median
55			valence for a mesh vertex (the number of adjacent faces),
56			and smaller values will result in pointless octree subdivision.
57	greg	1.1	.PP
58			The
59			.I \-r
60			option specifies the maximum octree resolution.
61			This should be greater than or equal to the ratio of the mesh bounding
62			box to the smallest triangle.
63			The default is 16384.
64			.PP
65			The
66			.I \-w
67			option suppresses warnings.
68			.PP
69			Although the mesh file format is binary, it is meant to be portable
70			between machines.
71			The only limitation is that machines with radically different integer
72			sizes will not work together.
73	greg	1.2	.SH DETAILS
74			The following Wavefront statements are understood and compiled by
75			.I obj2mesh.
76			.TP 10n
77			.BI v " x y z"
78			A vertex location, given by its Cartesian coordinates.
79			The final mesh position may of course be modified by
80			the transform arguments given to the
81			.I mesh
82			primitive in the Radiance scene description.
83			.TP
84			.BI vn " dx dy dz"
85			A vertex normal vector, given by its three
86			direction components, which will be normalized by
87			.I obj2mesh.
88			Normals will be interpolated over the mesh
89			during rendering to produce a smooth surface.
90			If no vertex normals are present, the mess will appear tesselated.
91			A zero length normal (i.e., 0 0 0) will generate a syntax error.
92			.TP
93			.BI vt " u v"
94			A local vertex texture coordinate.
95			These coordinates will be interpolated and passed
96			to the "Lu" and "Lv" variables during rendering.
97			Local coordinates can extend over any desired range of values.
98			.TP
99			.BI f " v1/t1/n1 v2/t2/n2 v3/t3/n3" " .."
100			A polygonal face.
101			Polygon vertices are specified as three indices separated
102			by slashes ('/').
103			The first index is the vertex location, the
104			second index is the local (u,v) texture coordinate, and the
105			third index is the vertex surface normal.
106			Positive indices count from the beginning of the input,
107			where the first vertex position (
108			.I v
109			statement) is numbered 1, and likewise
110			for the first texture coordinate and the first surface normal.
111			Negative indices count backward from the current position in
112			the input, where -1 is the last vertex encountered, -2
113			is the one before that, etc.
114			An index of 0 may be used for the vertex texture or normal to
115			indicate none, or these may be left off entirely.
116			All faces will be broken into triangles in the final mesh.
117			.I Obj2mesh
118			currently makes an unsafe assumption that faces are convex,
119			which may result in odd results if they are not.
120			.PP
121			All other statement types will be ignored on the input.
122			Statements understood by
123			.I obj2rad(1)
124			will be ignored silently; other statements will generate
125			a warning message after translation to indicate how much was missed.
126	greg	1.1	.SH DIAGNOSTICS
127			There are four basic error types reported by obj2mesh:
128			.IP
129			warning - a non-fatal input-related error
130			.IP
131			fatal - an unrecoverable input-related error
132			.IP
133			system - a system-related error
134			.IP
135			internal - a fatal error related to program limitations
136			.IP
137			consistency - a program-caused error
138			.PP
139			Most errors are self-explanatory.
140			However, the following internal errors should be mentioned:
141			.IP "Set overflow in addobject (id)"
142			This error occurs when too many surfaces are close together in a
143			scene.
144	greg	1.2	Sometimes a dense mesh can be accommodated by increasing
145	greg	1.1	the maximum resolution (by powers of two) using the
146			.I \-r
147			option, but usually this error indicates something is wrong.
148			Either too many surfaces are lying right on top of each other,
149			or the bounding cube is inflated from disparate geometry
150			in the input.
151			Chances are, the face number "id" is near
152			those causing the problem.
153			.IP "Hash table overflow in fullnode"
154			This error is caused by too many surfaces, and there is
155			little hope of compiling this mesh.
156			.SH EXAMPLE
157			To create a compiled triangle mesh from the scene file mesh.obj:
158			.IP "" .2i
159			oconv mesh.obj mesh.rtm
160			.SH AUTHOR
161			Greg Ward
162			.SH "SEE ALSO"
163	greg	1.2	gensurf(1), getinfo(1), make(1), obj2rad(1),
164	greg	1.1	oconv(1), rpict(1), rview(1), rtrace(1), xform(1)