man/man1/obj2mesh.1

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