--- ray/doc/man/man1/obj2mesh.1	2003/03/11 22:48:20	1.1
+++ ray/doc/man/man1/obj2mesh.1	2020/03/30 18:28:35	1.14
@@ -1,15 +1,21 @@
-.\" RCSid "$Id"
+.\" RCSid "$Id: obj2mesh.1,v 1.14 2020/03/30 18:28:35 greg Exp $"
 .TH OBJ2MESH 1 03/11/03 RADIANCE
 .SH NAME
 obj2mesh - create a compiled RADIANCE mesh file from Wavefront .OBJ input
 .SH SYNOPSIS
 .B obj2mesh
 [
+.B "\-a matfile"
+][
+.B "\-l matlib"
+][
 .B "\-n objlim"
 ][
 .B "\-r maxres"
 ][
 .B \-w
+][
+.B \-v
 ]
 [
 .B "input.obj"
@@ -25,6 +31,13 @@ reads a Wavefront .OBJ file from
 which is sent to
 .I output.rtm
 (or standard output).
+Any RADIANCE material descriptions included via one or more
+.I \-a
+options will be compiled and stored in the mesh as well.
+If the
+.I \-l
+option is used to specify a material file, the RADIANCE library
+locations are searched.
 This mesh may be included in a RADIANCE scene description via the
 .I mesh
 primitive, thus:
@@ -37,23 +50,25 @@ mod mesh id
 .br
 0
 .PP
-The syntax and semantics are nearly identical to the RADIANCE
+The syntax and semantics are identical to the RADIANCE
 .I instance
-primitive, except that the mesh modifier may not be "void", since
-materials are not included in a compiled mesh file.
+primitive.
+If
+.I mod
+is "void", then the stored mesh materials will be applied during rendering.
+Otherwise, the given material will be substituted on
+all the mesh surfaces.
 .PP
 The
 .I \-n
 option specifies the maximum surface set size for
 each voxel.
-Larger numbers result in quicker mesh generation needing
-less memory, but potentially slower rendering.
-Smaller values may produce faster renderings,
-since the default number (15) is on the high side to reduce
-the compiled mesh octree size.
-Values below 6 are not recommended, since the median
-valence (number of adjacent faces) for a mesh vertex is 6,
-and smaller limits will result in pointless octree subdivision.
+Larger numbers result in quicker mesh generation,
+but potentially slower rendering.
+Values below 6 are not recommended, since this is the median
+valence for a mesh vertex (the number of adjacent faces),
+and smaller values will result in pointless octree subdivision.
+The default setting is 9.
 .PP
 The
 .I \-r
@@ -65,11 +80,78 @@ The default is 16384.
 The
 .I \-w
 option suppresses warnings.
+The
+.I \-v
+option prints out final mesh statistics.
 .PP
 Although the mesh file format is binary, it is meant to be portable
 between machines.
 The only limitation is that machines with radically different integer
 sizes will not work together.
+.SH DETAILS
+The following Wavefront statements are understood and compiled by
+.I obj2mesh.
+.TP 10n
+.BI v " x y z"
+A vertex location, given by its Cartesian coordinates.
+The final mesh position may of course be modified by
+the transform arguments given to the
+.I mesh
+primitive in the Radiance scene description.
+.TP
+.BI vn " dx dy dz"
+A vertex normal vector, given by its three
+direction components, which will be normalized by
+.I obj2mesh.
+Normals will be interpolated over the mesh
+during rendering to produce a smooth surface.
+If no vertex normals are present, the mesh will appear tesselated.
+A zero length normal (i.e., 0 0 0) will generate a syntax error.
+.TP
+.BI vt " u v"
+A local vertex texture coordinate.
+These coordinates will be interpolated and passed
+to the "Lu" and "Lv" variables during rendering.
+Local coordinates can extend over any desired range of values.
+.TP
+.BI usemtl " mname"
+A material name.
+The following faces will use the named material, which is
+taken from the material definitions in the
+.I \-a
+input file(s).
+.TP
+.BI g " gname"
+Group association.
+The following faces are associated with the named group.
+If no "usemtl" statement has been
+encountered, the current group is used for the surface material
+identifier.
+.TP
+.BI f " v1/t1/n1 v2/t2/n2 v3/t3/n3" " .."
+A polygonal face.
+Polygon vertices are specified as three indices separated
+by slashes ('/').
+The first index is the vertex location, the
+second index is the local (u,v) texture coordinate, and the
+third index is the vertex surface normal.
+Positive indices count from the beginning of the input,
+where the first vertex position (
+.I v
+statement) is numbered 1, and likewise
+for the first texture coordinate and the first surface normal.
+Negative indices count backward from the current position in
+the input, where \-1 is the last vertex encountered, \-2
+is the one before that, etc.
+An index of 0 may be used for the vertex texture or normal to
+indicate none, or these may be left off entirely.
+All faces will be broken into triangles in the final mesh.
+.PP
+All other statement types will be ignored on the input.
+Statements understood by
+.I obj2rad(1)
+will be ignored silently; other statements will generate
+a warning message after translation to indicate how much was missed.
 .SH DIAGNOSTICS
 There are four basic error types reported by obj2mesh:
 .IP
@@ -88,7 +170,7 @@ However, the following internal errors should be menti
 .IP "Set overflow in addobject (id)"
 This error occurs when too many surfaces are close together in a
 scene.
-Sometimes a dense mesh can be accomodated by increasing
+Sometimes a dense mesh can be accommodated by increasing
 the maximum resolution (by powers of two) using the
 .I \-r
 option, but usually this error indicates something is wrong.
@@ -100,12 +182,34 @@ those causing the problem.
 .IP "Hash table overflow in fullnode"
 This error is caused by too many surfaces, and there is
 little hope of compiling this mesh.
-.SH EXAMPLE
-To create a compiled triangle mesh from the scene file mesh.obj:
+.SH EXAMPLES
+To create a compiled triangle mesh from the scene file mesh.obj
+using materials from the file mesh.mat:
 .IP "" .2i
-oconv mesh.obj mesh.rtm
+obj2mesh \-a mesh.mat mesh.obj mesh.rtm
+.PP
+To use local coordinates to place a square tiled image on a mesh object:
+.sp
+.nf
+void colorpict tiled_pat
+7 red green blue mytile.hdr . frac(Lu) frac(Lv)
+0
+0
+
+tiled_pat plastic tiled_mat
+0
+0
+5 .9 .9 .9 0 0
+
+tiled_mat mesh tiled_mesh
+1 mymesh.rtm
+0
+0
+.fi
+.SH ENVIRONMENT
+RAYPATH		the directories to search for material files.
 .SH AUTHOR
 Greg Ward
 .SH "SEE ALSO"
-gensurf(1), getinfo(1), make(1),
-oconv(1), rpict(1), rview(1), rtrace(1), xform(1)
+gensurf(1), getinfo(1), make(1), obj2rad(1), objutil(1)
+oconv(1), rpict(1), rvu(1), rtrace(1), xform(1)