--- ray/doc/man/man1/robjutil.1	2020/04/02 20:50:59	1.3
+++ ray/doc/man/man1/robjutil.1	2023/01/31 16:29:19	1.8
@@ -1,4 +1,4 @@
-.\" RCSid "$Id: robjutil.1,v 1.3 2020/04/02 20:50:59 greg Exp $"
+.\" RCSid "$Id: robjutil.1,v 1.8 2023/01/31 16:29:19 greg Exp $"
 .TH ROBJUTIL 1 3/31/20 RADIANCE
 .SH NAME
 robjutil - operate on Wavefront .OBJ file
@@ -19,6 +19,8 @@ robjutil - operate on Wavefront .OBJ file
 ][
 .B "-c epsilon"
 ][
+.B +T
+][
 .B "-x 'xf spec'"
 ]
 [
@@ -35,13 +37,10 @@ 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.
+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.
@@ -75,6 +74,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
@@ -85,6 +85,11 @@ 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"
@@ -102,6 +107,9 @@ 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).
+To break all surfaces into triangles, include the
+.I +T
+option.
 .PP
 The
 .I \-x
@@ -123,10 +131,6 @@ To remove degenerate and duplicate faces from "orig.ob
 .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
@@ -135,7 +139,37 @@ robjutil +g cat +g bell kitty.obj | obj2mesh -a kitty.
 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), genbox(1), gensurf(1), obj2mesh(1), obj2rad(1) oconv(1), xform(1)