--- ray/doc/man/man1/robjutil.1	2020/03/30 18:28:35	1.1
+++ ray/doc/man/man1/robjutil.1	2020/04/03 02:45:13	1.5
@@ -1,4 +1,4 @@
-.\" RCSid "$Id: robjutil.1,v 1.1 2020/03/30 18:28:35 greg Exp $"
+.\" 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
@@ -18,6 +18,8 @@ robjutil - operate on Wavefront .OBJ file
 .B "+/-g gname"
 ][
 .B "-c epsilon"
+][
+.B "-x 'xf spec'"
 ]
 [
 .B input.obj ..
@@ -40,6 +42,7 @@ 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.
@@ -73,6 +76,7 @@ The
 and
 .I \+m
 options are mutually exclusive.
+.PP
 Similarly, the
 .I "\-g gname"
 option says to remove all faces belonging to the group
@@ -83,10 +87,17 @@ 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
-Finally, a
+The
 .I "\-c epsilon"
-parameter may be given to coalesce vertices that are within the given 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
@@ -98,6 +109,22 @@ at least for triangle mesh input.
 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
@@ -111,7 +138,41 @@ To extract only the groups "cat" and "bell" from the f
 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"
-obj2mesh(1), obj2rad(1) oconv(1), xform(1)
+cat(1), obj2mesh(1), obj2rad(1) oconv(1), xform(1)