--- ray/doc/man/man1/rpict.1	2005/01/18 01:13:23	1.5
+++ ray/doc/man/man1/rpict.1	2008/11/10 19:08:17	1.13
@@ -1,4 +1,4 @@
-.\" RCSid "$Id: rpict.1,v 1.5 2005/01/18 01:13:23 greg Exp $"
+.\" RCSid "$Id: rpict.1,v 1.13 2008/11/10 19:08:17 greg Exp $"
 .TH RPICT 1 2/26/99 RADIANCE
 .SH NAME
 rpict - generate a RADIANCE picture
@@ -70,13 +70,21 @@ A cylindrical panorma may be selected by setting
 to the letter 'c'.
 This view is like a standard perspective vertically, but projected
 on a cylinder horizontally (like a soupcan's-eye view).
-Two fisheye views are provided as well; 'h' yields a hemispherical fisheye
-view and 'a' results in angular fisheye distortion.
+Three fisheye views are provided as well; 'h' yields a hemispherical fisheye
+view, 'a' results in angular fisheye distortion, and 's'
+results in a planisphere (stereographic) projection.
 A hemispherical fisheye is a projection of the hemisphere onto a circle.
 The maximum view angle for this type is 180 degrees.
 An angular fisheye view is defined such that distance from the center of
 the image is proportional to the angle from the central view direction.
 An angular fisheye can display a full 360 degrees.
+A planisphere fisheye view maintains angular relationships between lines,
+and is commonly used for sun path analysis.
+This is more commonly known as a
+"stereographic projection," but we avoid the term here so as not to
+confuse it with a stereoscopic pair.
+A planisphere fisheye can display up to (but not including) 360 degrees,
+although distortion becomes extreme as this limit is approached.
 Note that there is no space between the view type
 option and its single letter argument.
 .TP
@@ -152,7 +160,7 @@ This is option is useful for generating skewed perspec
 rendering an image a piece at a time.
 A value of 1 means that the rendered image starts just to the right of
 the normal view.
-A value of -1 would be to the left.
+A value of \-1 would be to the left.
 Larger or fractional values are permitted as well.
 .TP
 .BI -vl \ val
@@ -263,7 +271,7 @@ A warning about aiming failure will issued if
 .I frac
 is too large.
 It is usually wise to turn off image sampling when using
-direct jitter by setting -ps to 1.
+direct jitter by setting \-ps to 1.
 .TP
 .BI -ds \ frac
 Set the direct sampling ratio to
@@ -472,23 +480,23 @@ header of the ambient file.
 .I Getinfo(1)
 may be used to print out this information.
 .TP
-.BI -ae \ mat
+.BI -ae \ mod
 Append
-.I mat
+.I mod
 to the ambient exclude list,
 so that it will not be considered during the indirect calculation.
 This is a hack for speeding the indirect computation by
 ignoring certain objects.
 Any object having
-.I mat
+.I mod
 as its modifier will get the default ambient
 level rather than a calculated value.
-Any number of excluded materials may be given, but each
+Any number of excluded modifiers may be given, but each
 must appear in a separate option.
 .TP
-.BI -ai \ mat
+.BI -ai \ mod
 Add
-.I mat
+.I mod
 to the ambient include list,
 so that it will be considered during the indirect calculation.
 The program can use either an include list or an exclude
@@ -497,16 +505,16 @@ list, but not both.
 .BI -aE \ file
 Same as
 .I \-ae,
-except read materials to be excluded from
+except read modifiers to be excluded from
 .I file.
 The RAYPATH environment variable determines which directories are
 searched for this file.
-The material names are separated by white space in the file.
+The modifier names are separated by white space in the file.
 .TP
 .BI -aI \ file
 Same as
 .I \-ai,
-except read materials to be included from
+except read modifiers to be included from
 .I file.
 .TP
 .BI -me " rext gext bext"
@@ -555,16 +563,38 @@ though the
 .I \-dv
 option (above) may be used to override this.
 .TP
+.BR \-u
+Boolean switch to control uncorrelated random sampling.
+When "off", a low-discrepancy sequence is used, which reduces
+variance but can result in a brushed appearance in specular highlights.
+When "on", pure Monte Carlo sampling is used in all calculations.
+.TP
 .BI -lr \ N
 Limit reflections to a maximum of
 .I N.
+If
+.I N
+is zero, then Russian roulette is used for ray
+termination, and the
+.I -lw
+setting (below) must be positive.
+If N is a negative integer, then this sets the upper limit
+of reflections past which Russian roulette will not be used.
+In scenes with dielectrics and total internal reflection,
+a setting of 0 (no limit) may cause a stack overflow.
 .TP
 .BI -lw \ frac
 Limit the weight of each ray to a minimum of
 .I frac.
-During ray-tracing, a record is kept of the final contribution
-a ray would have to the image.
-If it is less then the specified minimum, the ray is not traced.
+During ray-tracing, a record is kept of the estimated contribution
+(weight) a ray would have in the image.
+If this weight is less than the specified minimum and the
+.I -lr
+setting (above) is positive, the ray is not traced.
+Otherwise, Russian roulette is used to
+continue rays with a probability equal to the ray weight
+divided by the given
+.I frac.
 .TP
 .BI -S \ seqstart
 Instead of generating a single picture based only on the view
@@ -752,7 +782,7 @@ Set the time between progress reports to
 A progress report writes the number of rays traced, the percentage
 completed, and the CPU usage to the standard error.
 Reports are given either automatically after the specified interval,
-or when the process receives a continue (-CONT) signal (see
+or when the process receives a continue (\-CONT) signal (see
 .I kill(1)).
 A value of zero turns automatic reporting off.
 .TP
@@ -766,13 +796,13 @@ Boolean switch for warning messages.
 The default is to print warnings, so the first appearance of
 this option turns them off.
 .SH EXAMPLE
-rpict -vp 10 5 3 -vd 1 -.5 0 scene.oct > scene.pic
+rpict \-vp 10 5 3 \-vd 1 \-.5 0 scene.oct > scene.hdr
 .PP
-rpict -S 1 -o frame%02d.pic scene.oct < keyframes.vf
+rpict \-S 1 \-o frame%02d.hdr scene.oct < keyframes.vf
 .SH ENVIRONMENT
 RAYPATH		the directories to check for auxiliary files.
 .SH FILES
-/usr/tmp/rtXXXXXX		common header information for picture sequence
+/tmp/rtXXXXXX		common header information for picture sequence
 .br
 rfXXXXXX		temporary name for recover file
 .SH DIAGNOSTICS