man/man1/robjutil.1

.\" RCSid "$Id: robjutil.1,v 1.4 2020/04/03 02:32:58 greg Exp $"
.TH ROBJUTIL 1 3/31/20 RADIANCE
.SH NAME
robjutil - operate on Wavefront .OBJ file
.SH SYNOPSIS
.B robjutil
[
.B +/-r
][
.B +/-v
][
.B +/-t
][
.B +/-n
][
.B "+/-m mname"
][
.B "+/-g gname"
][
.B "-c epsilon"
][
.B "-x 'xf spec'"
]
[
.B input.obj ..
]
.SH DESCRIPTION
.I Robjutil
reads and manipulates a Wavefront .OBJ file, removing degenerate and
duplicate faces.
If the
.I +r
option is specified, a Radiance scene description
will be produced on the standard output.
If
.I -r
is given, a modified .OBJ file will be sent to the standard output.
This is the default, and is
typically more useful, since surface normals are better handled by the
.I obj2rad(1)
and
.I obj2mesh(1)
converters.
The latter also preserves local texture coordinates for mapping materials.
.PP
The
.I +v
option turns on verbose progress reports.
.PP
The
.I \-t
option tells
.I robjutil
to remove texture coordinates from the input.
The
.I \-n
option will cause all surface normals to be removed.
.PP
The
.I "\-m mname"
option tells
.I robjutil
to remove all faces that use the material
.I mname.
Multiple
.I \-m
options may be given, each with a single (unique) material name.
Alternatively, the
.I "+m mname"
option may be used to specify a material one wishes to keep, discarding the rest.
Multiple
.I +m
options will keep all the named materials.
The
.I \-m
and
.I \+m
options are mutually exclusive.
.PP
Similarly, the
.I "\-g gname"
option says to remove all faces belonging to the group
.I gname,
and multiple
.I \-g
options may be given.
There is also a
.I +g
option to save just the named group(s).
Object statements are treated the same as group statements in the input, so
.I +/-g
option can also be applied to object names.
Note that an object name will be overridden by a group name that follows
it in the input, and vice versa.
.PP
The
.I "\-c epsilon"
option tells
.I robjutil
to coalesce vertices that are within the given epsilon.
This is useful to improve the connectivity of models that were produced
in a sloppy conversion process from independent polygons.
When producing a Radiance file via the
.I +r
option, there will be no savings in the output size, but there can be
a benefit in reducing the number of "cracks" in the resulting geometry,
at least for triangle mesh input.
.I Robjutil
does not attempt to break up non-planar polygons into triangles,
which is usually not a problem for .OBJ output, but may be for Radiance
scene descriptions (+r).
.PP
The
.I \-x
option may be used to specify a final transform to apply to all
coordinates in the file before output.
This specification must be contained in a single quoted word and
match the standard arguments used by
.I xform(1),
except that the
.I \-a
option is not supported for creating arrays of objects.
Also, any scaling factors do not affect the epsilon value given for
coalescing vertices, as this operation is applied prior to the transform,
even if
.I \-c
appears later in the command line.
.SH EXAMPLES
To remove degenerate and duplicate faces from "orig.obj" and write to "final.rad":
.IP "" .2i
robjutil +r orig.obj > final.rad
.PP
To convert the same file, preserving surface normal interpolation:
.IP "" .2i
robjutil orig.obj | obj2rad > withnormals.rad
.PP
To extract only the groups "cat" and "bell" from the file "kitty.obj" and
write to a Radiance triangle mesh using materials from "kitty.mat":
.IP "" .2i
robjutil +g cat +g bell kitty.obj | obj2mesh -a kitty.mat > kitty.rtm
.PP
To rotate the scene 90 degrees about the Y-axis and scale by 10:
.IP "" .2i
robjutil -x "-ry 90 -s 10" orig.obj > transformed.obj
.SH NOTES
The .OBJ output of
.I robjutil
uses relative indices, so files it produces may be concatenated
on the input of other tools such as
.I obj2rad
and
.I obj2mesh
by piping from
.I cat(1)
or similar.
This offers a convenient way to separate geometry from a single .OBJ
input, manipulate it in some way, then recombine during conversion.
.PP
Unlike
.I obj2rad
and
.I obj2mesh,
.I robjutil
with the
.I +r
option will not substitute the group name for a material id if no
.I usemtl
statements are found on the input.
Instead, it will assign each surface the material
.I DEFAULT_MATERIAL.
Since it is possible to use the
.I +/-g
option to select groups to include or exclude on output, it is
still possible to assign materials by group manually.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
cat(1), obj2mesh(1), obj2rad(1) oconv(1), xform(1)
Revision:	1.5
Committed:	Fri Apr 3 02:45:13 2020 UTC (5 years, 1 month ago) by greg
Branch:	MAIN
CVS Tags:	rad5R3
Changes since 1.4:	+8 -1 lines
Log Message:	Added some notes about object and group statements being treated the same
#	User	Rev	Content
1	greg	1.5	.\" RCSid "$Id: robjutil.1,v 1.4 2020/04/03 02:32:58 greg Exp $"
2	greg	1.1	.TH ROBJUTIL 1 3/31/20 RADIANCE
3			.SH NAME
4			robjutil - operate on Wavefront .OBJ file
5			.SH SYNOPSIS
6			.B robjutil
7			[
8			.B +/-r
9			][
10			.B +/-v
11			][
12			.B +/-t
13			][
14			.B +/-n
15			][
16			.B "+/-m mname"
17			][
18			.B "+/-g gname"
19			][
20			.B "-c epsilon"
21	greg	1.2	][
22			.B "-x 'xf spec'"
23	greg	1.1	]
24			[
25			.B input.obj ..
26			]
27			.SH DESCRIPTION
28			.I Robjutil
29			reads and manipulates a Wavefront .OBJ file, removing degenerate and
30			duplicate faces.
31			If the
32			.I +r
33			option is specified, a Radiance scene description
34			will be produced on the standard output.
35			If
36			.I -r
37			is given, a modified .OBJ file will be sent to the standard output.
38			This is the default, and is
39			typically more useful, since surface normals are better handled by the
40			.I obj2rad(1)
41			and
42			.I obj2mesh(1)
43			converters.
44			The latter also preserves local texture coordinates for mapping materials.
45	greg	1.5	.PP
46	greg	1.1	The
47			.I +v
48			option turns on verbose progress reports.
49			.PP
50			The
51			.I \-t
52			option tells
53			.I robjutil
54			to remove texture coordinates from the input.
55			The
56			.I \-n
57			option will cause all surface normals to be removed.
58			.PP
59			The
60			.I "\-m mname"
61			option tells
62			.I robjutil
63			to remove all faces that use the material
64			.I mname.
65			Multiple
66			.I \-m
67			options may be given, each with a single (unique) material name.
68			Alternatively, the
69			.I "+m mname"
70			option may be used to specify a material one wishes to keep, discarding the rest.
71			Multiple
72			.I +m
73			options will keep all the named materials.
74			The
75			.I \-m
76			and
77			.I \+m
78			options are mutually exclusive.
79	greg	1.5	.PP
80	greg	1.1	Similarly, the
81			.I "\-g gname"
82			option says to remove all faces belonging to the group
83			.I gname,
84			and multiple
85			.I \-g
86			options may be given.
87			There is also a
88			.I +g
89			option to save just the named group(s).
90	greg	1.5	Object statements are treated the same as group statements in the input, so
91			.I +/-g
92			option can also be applied to object names.
93			Note that an object name will be overridden by a group name that follows
94			it in the input, and vice versa.
95	greg	1.1	.PP
96	greg	1.3	The
97	greg	1.1	.I "\-c epsilon"
98	greg	1.3	option tells
99			.I robjutil
100			to coalesce vertices that are within the given epsilon.
101	greg	1.1	This is useful to improve the connectivity of models that were produced
102			in a sloppy conversion process from independent polygons.
103			When producing a Radiance file via the
104			.I +r
105			option, there will be no savings in the output size, but there can be
106			a benefit in reducing the number of "cracks" in the resulting geometry,
107			at least for triangle mesh input.
108			.I Robjutil
109			does not attempt to break up non-planar polygons into triangles,
110			which is usually not a problem for .OBJ output, but may be for Radiance
111			scene descriptions (+r).
112	greg	1.2	.PP
113			The
114			.I \-x
115			option may be used to specify a final transform to apply to all
116			coordinates in the file before output.
117			This specification must be contained in a single quoted word and
118			match the standard arguments used by
119			.I xform(1),
120			except that the
121			.I \-a
122			option is not supported for creating arrays of objects.
123	greg	1.3	Also, any scaling factors do not affect the epsilon value given for
124	greg	1.2	coalescing vertices, as this operation is applied prior to the transform,
125			even if
126			.I \-c
127			appears later in the command line.
128	greg	1.1	.SH EXAMPLES
129			To remove degenerate and duplicate faces from "orig.obj" and write to "final.rad":
130			.IP "" .2i
131			robjutil +r orig.obj > final.rad
132			.PP
133			To convert the same file, preserving surface normal interpolation:
134			.IP "" .2i
135			robjutil orig.obj \| obj2rad > withnormals.rad
136			.PP
137			To extract only the groups "cat" and "bell" from the file "kitty.obj" and
138			write to a Radiance triangle mesh using materials from "kitty.mat":
139			.IP "" .2i
140			robjutil +g cat +g bell kitty.obj \| obj2mesh -a kitty.mat > kitty.rtm
141	greg	1.2	.PP
142			To rotate the scene 90 degrees about the Y-axis and scale by 10:
143			.IP "" .2i
144			robjutil -x "-ry 90 -s 10" orig.obj > transformed.obj
145	greg	1.4	.SH NOTES
146			The .OBJ output of
147			.I robjutil
148			uses relative indices, so files it produces may be concatenated
149			on the input of other tools such as
150			.I obj2rad
151			and
152			.I obj2mesh
153			by piping from
154			.I cat(1)
155			or similar.
156			This offers a convenient way to separate geometry from a single .OBJ
157			input, manipulate it in some way, then recombine during conversion.
158			.PP
159			Unlike
160			.I obj2rad
161			and
162			.I obj2mesh,
163			.I robjutil
164			with the
165			.I +r
166			option will not substitute the group name for a material id if no
167			.I usemtl
168			statements are found on the input.
169			Instead, it will assign each surface the material
170			.I DEFAULT_MATERIAL.
171			Since it is possible to use the
172			.I +/-g
173			option to select groups to include or exclude on output, it is
174			still possible to assign materials by group manually.
175	greg	1.1	.SH AUTHOR
176			Greg Ward
177			.SH "SEE ALSO"
178	greg	1.4	cat(1), obj2mesh(1), obj2rad(1) oconv(1), xform(1)