man/man1/robjutil.1

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