man/man1/robjutil.1

.\" RCSid "$Id: robjutil.1,v 1.2 2020/04/02 20:44:15 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.
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.
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).
.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 AUTHOR
Greg Ward
.SH "SEE ALSO"
obj2mesh(1), obj2rad(1) oconv(1), xform(1)
Revision:	1.3
Committed:	Thu Apr 2 20:50:59 2020 UTC (5 years, 1 month ago) by greg
Branch:	MAIN
Changes since 1.2:	+6 -4 lines
Log Message:	Minor wording changes
#	User	Rev	Content
1	greg	1.3	.\" RCSid "$Id: robjutil.1,v 1.2 2020/04/02 20:44:15 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			The
46			.I +v
47			option turns on verbose progress reports.
48			.PP
49			The
50			.I \-t
51			option tells
52			.I robjutil
53			to remove texture coordinates from the input.
54			The
55			.I \-n
56			option will cause all surface normals to be removed.
57			.PP
58			The
59			.I "\-m mname"
60			option tells
61			.I robjutil
62			to remove all faces that use the material
63			.I mname.
64			Multiple
65			.I \-m
66			options may be given, each with a single (unique) material name.
67			Alternatively, the
68			.I "+m mname"
69			option may be used to specify a material one wishes to keep, discarding the rest.
70			Multiple
71			.I +m
72			options will keep all the named materials.
73			The
74			.I \-m
75			and
76			.I \+m
77			options are mutually exclusive.
78			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			.PP
89	greg	1.3	The
90	greg	1.1	.I "\-c epsilon"
91	greg	1.3	option tells
92			.I robjutil
93			to coalesce vertices that are within the given epsilon.
94	greg	1.1	This is useful to improve the connectivity of models that were produced
95			in a sloppy conversion process from independent polygons.
96			When producing a Radiance file via the
97			.I +r
98			option, there will be no savings in the output size, but there can be
99			a benefit in reducing the number of "cracks" in the resulting geometry,
100			at least for triangle mesh input.
101			.I Robjutil
102			does not attempt to break up non-planar polygons into triangles,
103			which is usually not a problem for .OBJ output, but may be for Radiance
104			scene descriptions (+r).
105	greg	1.2	.PP
106			The
107			.I \-x
108			option may be used to specify a final transform to apply to all
109			coordinates in the file before output.
110			This specification must be contained in a single quoted word and
111			match the standard arguments used by
112			.I xform(1),
113			except that the
114			.I \-a
115			option is not supported for creating arrays of objects.
116	greg	1.3	Also, any scaling factors do not affect the epsilon value given for
117	greg	1.2	coalescing vertices, as this operation is applied prior to the transform,
118			even if
119			.I \-c
120			appears later in the command line.
121	greg	1.1	.SH EXAMPLES
122			To remove degenerate and duplicate faces from "orig.obj" and write to "final.rad":
123			.IP "" .2i
124			robjutil +r orig.obj > final.rad
125			.PP
126			To convert the same file, preserving surface normal interpolation:
127			.IP "" .2i
128			robjutil orig.obj \| obj2rad > withnormals.rad
129			.PP
130			To extract only the groups "cat" and "bell" from the file "kitty.obj" and
131			write to a Radiance triangle mesh using materials from "kitty.mat":
132			.IP "" .2i
133			robjutil +g cat +g bell kitty.obj \| obj2mesh -a kitty.mat > kitty.rtm
134	greg	1.2	.PP
135			To rotate the scene 90 degrees about the Y-axis and scale by 10:
136			.IP "" .2i
137			robjutil -x "-ry 90 -s 10" orig.obj > transformed.obj
138	greg	1.1	.SH AUTHOR
139			Greg Ward
140			.SH "SEE ALSO"
141			obj2mesh(1), obj2rad(1) oconv(1), xform(1)