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) |