--- ray/doc/man/man1/rtpict.1	2018/03/20 18:03:52	1.2
+++ ray/doc/man/man1/rtpict.1	2025/06/04 20:32:24	1.16
@@ -1,11 +1,18 @@
-.\" RCSid "$Id: rtpict.1,v 1.2 2018/03/20 18:03:52 greg Exp $"
+.\" RCSid "$Id: rtpict.1,v 1.16 2025/06/04 20:32:24 greg Exp $"
 .TH RTPICT 1 3/19/2018 RADIANCE
 .SH NAME
-rtpict - generate a RADIANCE picture using rtrace
+rtpict - generate a RADIANCE picture, hyperspectral image, or layers using rtrace
 .SH SYNOPSIS
 .B rtpict
 .B "-n nproc"
 [
+.B -co
+][
+.B "-o[vrxlLRXnNsmM] out_dir"
+][
+.B "-d ref_depth/unit"
+]
+[
 .B "rpict options"
 ]
 [
@@ -14,18 +21,22 @@ rtpict - generate a RADIANCE picture using rtrace
 .B octree
 .SH DESCRIPTION
 .I Rtpict
-is a script that generates a picture from the RADIANCE scene given in
+is a script that generates a picture or hyperspectral image
+from the RADIANCE scene given in
 .I octree
 and sends it to the standard output, or to a file specified with the
 .I \-o
 option.
 Most options and defaults are the same as
 .I rpict(1),
-although a few switches are silently ignored.
-Options incompatible with multi-processing can generate an error.
+although a few options are silently ignored, and the
+.I rtrace(1)
+.I \-co
+boolean switch is supported.
+Options incompatible with multi-processing may generate an error.
 .PP
 The
-.I rtrace(1)
+.I rtrace
 tool is called with
 .I vwrays(1)
 to perform the actual work.
@@ -43,13 +54,87 @@ Also, it is very important to set the
 .I \-af
 option if an irradiance cache is being generated;
 otherwise, your speed-up will be far from linear.
-.SH EXAMPLE
+.PP
+If the
+.I \-o
+option has additional characters corresponding to output types from
+.I rtrace,
+it must be followed by the name of a directory that either exists or
+will be created to contain image layers, one per output type.
+The supported types are listed below, and do not include types that
+are useless or have no convenient representation.
+The table below shows the correspondence between output type and file name
+in the specified directory:
+.sp
+.nf
+v	radiance.hdr
+r	r_refl.hdr
+x	r_unrefl.hdr
+l	d_effective.dpt
+L	d_firstsurf.dpt
+R	d_refl.dpt
+X	d_unrefl.dpt
+n	perturbed.nrm
+N	unperturbed.nrm
+s	surface.idx
+m	modifier.idx
+M	material.idx
+.fi
+.sp
+Different encodings are associated with different data types.
+Color data (from the 'v', 'r', and 'x' types) will be converted to
+a flat RGBE picture by
+.I pvalue(1),
+unless the
+.I \-co+
+option is specified and
+.I \-cs
+is greater than 3.
+In this case, a hyperspectral image will be generated for each
+of the value types, converted by
+.I rcomb(1)
+and with its suffix set to ".hsr" rather than ".hdr".
+Distances (from the 'l', 'L', 'R', and 'X' types) will be
+converted to a 16-bit representation by
+.I rcode_depth(1),
+and the
+.I \-d
+option should be used to assign the reference (median) depth and world
+units, which applies to the overall scene.
+Surface normals (from the 'n' and 'N' types) will be converted
+to a 32-bit representation by
+.I rcode_norm(1).
+Finally, identifiers (from the 's', 'm', and 'M' types) will be
+converted to a 16-bit index format by
+.I rcode_ident(1).
+.PP
+If the
+.I \-i
+option is used to turn on irradiane output, then the picture associated
+with the 'v' type will be renamed
+.I "irradiance.hdr"
+or
+.I "irradiance.hsr"
+and some other output types become irrelevant
+(i.e., 'r', 'x', 'R', and 'X').
+If one or more of the associated output files already exists in the
+destination directory, an error will be printed and the command will abort.
+.SH EXAMPLES
 To render a scene with four processes:
 .IP "" .2i
 rtpict -n 4 -vf mypers.vf -ab 1 -af scene.amb scene.oct > scene_pers.hdr
+.PP
+To render radiance, first surface distance, and normals in a layered image:
+.IP "" .2i
+rtpict -n 8 -vf fish.vf @render.opt -ovLn fisholay scene.oct
+.PP
+To render a hyperspectral irradiance image with 18 spectral samples:
+.IP "" .2i
+rtpict -vf inside.vf -i+ -cs 18 -co+ scene.oct > scene_inside.hsr
 .SH AUTHOR
 Greg Ward
 .SH "SEE ALSO"
-getinfo(1), lookamb(1), mkpmap(1), oconv(1), pdfblur(1), pfilt(1), 
-pinterp(1), pmblur(1), printf(3), ra_rgbe(1), rad(1), rpiece(1),
-rpict(1), rtrace(1), rvu(1) vwrays(1),
+getinfo(1), mkpmap(1), oconv(1), pfilt(1), 
+pvalue(1), rad(1), rcode_depth(1), rcode_norm(1), rcode_ident(1),
+rcomb(1), rcrop(1), rmtxop(1),
+rpiece(1), rpict(1), rsplit(1), rtrace(1), rvu(1), rxpiece(1), vwrays(1)