man/man1/robjutil.1

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