man/man1/obj2mesh.1

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