--- ray/doc/man/man1/pmapdump.1	2019/01/10 18:29:34	1.4
+++ ray/doc/man/man1/pmapdump.1	2019/01/22 18:29:08	1.5
@@ -1,30 +1,37 @@
-.\" RCSid "$Id: pmapdump.1,v 1.4 2019/01/10 18:29:34 rschregle Exp $"
-.TH PMAPDUMP 1 "$Date: 2019/01/10 18:29:34 $ $Revision: 1.4 $" RADIANCE
+.\" RCSid "$Id: pmapdump.1,v 1.5 2019/01/22 18:29:08 rschregle Exp $"
+.TH PMAPDUMP 1 "$Date: 2019/01/22 18:29:08 $ $Revision: 1.5 $" RADIANCE
 
 .SH NAME
-pmapdump - generate RADIANCE scene description of photon map distribution
+pmapdump - generate RADIANCE scene description or point list representing
+photon positions and (optionally) flux
 
 .SH SYNOPSIS
-pmapdump [\fB-n\fR \fInspheres1\fR] [\fB-r\fR \fIradscale1\fR] 
-         [\fB-f\fR | \fB-c\fR \fIrcol1\fR \fIgcol1\fR \fIbcol1\fR] \fIpmap1\fR 
-         [\fB-n\fR \fInspheres2\fR] [\fB-r\fR \fIradscale2\fR] 
-         [\fB-f\fR | \fB-c\fR \fIrcol2\fR \fIgcol2\fR \fIbcol2\fR] \fIpmap2\fR 
-         ...
+pmapdump [\fB-a\fR] [\fB-n\fR \fInum1\fR] [\fB-r\fR \fIradscale1\fR] 
+[\fB-f\fR | \fB-c\fR \fIrcol1\fR \fIgcol1\fR \fIbcol1\fR] 
+         \fIpmap1\fR 
+         [\fB-a\fR] [\fB-n\fR \fInum2\fR] [\fB-r\fR \fIradscale2\fR] 
+[\fB-f\fR | \fB-c\fR \fIrcol2\fR \fIgcol2\fR \fIbcol2\fR] 
+         \fIpmap2\fR ...
 
 .SH DESCRIPTION
 \fIpmapdump\fR takes one or more photon map files generated with
-\fImkpmap(1)\fR as input and sends a RADIANCE scene description of their
-photon distributions to the standard output. Photons are represented as
-spheres of material type \fIglow\fR. These can be visualised with
-e.g. \fIobjview(1)\fR, \fIrpict(1)\fR, or \fIrvu(1)\fR to assess the
-location and local density of photons in relation to the scene geometry. No
-additional light sources are necessary, as the spheres representing the
-photons are self-luminous.
+\fImkpmap(1)\fR as input and, by default, sends a RADIANCE scene description
+of their photon distributions to the standard output. Photons are 
+represented as spheres of material type \fIglow\fR. These can be 
+visualised with e.g. \fIobjview(1)\fR, \fIrpict(1)\fR, or \fIrvu(1)\fR to 
+assess the location and local density of photons in relation to the scene 
+geometry. No additional light sources are necessary, as the spheres 
+representing the photons are self-luminous.
 .PP
+Alternatively, photons can also be output as an ASCII point list, where
+each line contains a photon's position and colour.
+This point list can be imported in a 3D point cloud processor/viewer 
+to interactively explore the photon map.
+.PP
 An arbitrary number of photon maps can be specified on the command line and
-the respective photon type is determined automagically.  Per default, the
-different photon types are visualised as colour coded spheres according to
-the following default schema:
+the respective photon type is determined automagically.Per default, the
+different photon types are visualised as colour coded spheres/points 
+according to the following default schema:
 .IP
 \fIBlue\fR: global photons 
 .br
@@ -39,50 +46,60 @@ the following default schema:
 \fIYellow\fR: contribution photons
 .PP
 These colours can be overridden for individual photon maps with the \fB-c\fR
-option (see below).  Alternatively, photons can be individually coloured
+option (see below). Alternatively, photons can be individually coloured
 according to their actual RGB flux with the \fB-f\fR option (see below);
 while this makes it difficult to discern photon types, it can be used to
-quantitatively analyse colour bleeding effects.
+quantitatively analyse colour bleeding effects, for example.
 
 .SH OPTIONS
 Options are effective for the photon map file immediately following on the
 command line, and are reset to their defaults after completion of each dump. 
 As such they may be set individually for each photon map.
 
-.IP "\fB-n \fInspheres\fR"
-Specifies the number of spheres to dump for the next photon map.  The dump
-is performed by random sampling with \fInspheres\fR as target count, hence
-the number actually output will be approximate.  \fINspheres\fR may be
-followed by a multiplier suffix for convenience, where \fIk\fR = 10^3 and
-\fIm\fR = 10^6, although the latter may lead to problems when processing the
-output geometry with \fIoconv(1)\fR.  The default number of spheres is 10k.
+.IP "\fB-a\fR"
+Boolean switch to output photons as a point list in ASCII (text) format
+instead of a RADIANCE scene.
+Each output line consists of 6 tab-separated floating point values: the
+X, Y, Z coordinates of the photon's position, and the R, G, B colour 
+channels of its flux. These values. notably the flux, may be expressed
+in scientific notation to accommodate their high dynamic range.
 
-.IP "\fB-r \fIradscale\fR"
-Specifies a relative scale factor \fIradscale\fR for the sphere radius. The
-sphere radius is determined automatically from an estimated average distance
-between spheres so as to reduce clustering, assuming a uniform distribution. 
-In cases where the distribution is substantially nonuniform (e.g.  highly
-localised caustics) the radius can be manually corrected with this option. 
-The default value is 1.0.
+.IP "\fB-f\fR"
+Boolean switch to colour each sphere/point according to the corresponding 
+photon's RGB flux instead of a constant colour. Note that no exposure is 
+applied, and as such the resulting colours can span several orders of 
+magnitude and may require tone mapping with \fIpcond(1)\fR for 
+visualisation. This option is mutually exclusive with \fB-c\fR.
 
 .IP "\fB-c\fR \fIrcol\fR \fIgcol\fR \fIbcol\fR"
-Specifies a custom sphere colour for the next photon map. The colour is
-specified as an RGB triplet, with each component in the range (0..1].
+Specifies a custom sphere/point colour for the next photon map. The colour
+is specified as an RGB triplet, with each component in the range (0..1].
 Without this option, the default colour for the corresponding photon type 
 is used. This option is mutually exclusive with \fB-f\fR.
 
-.IP "\fB-f\fR"
-Boolean switch to colour each sphere according to the corresponding photon's
-RGB flux instead of a constant colour. Note that the resulting colours can
-span several orders of magnitude and may require tone mapping with
-\fIpcond(1)\fR for visualisation.  This option is mutually exclusive with
-\fB-c\fR.
+.IP "\fB-n \fInum\fR"
+Specifies the number of spheres or points to dump for the next photon map.  
+The dump is performed by random sampling with \fInum\fR as target count, 
+hence the number actually output will be approximate. \fINum\fR may be
+suffixed by a case-insensitive multiplier for convenience, where
+\fIk\fR = 10^3 and \fIm\fR = 10^6, although the latter may lead to problems
+when processing the output geometry with \fIoconv(1)\fR. The default number
+is 10k.
 
+.IP "\fB-r \fIradscale\fR"
+Specifies a relative scale factor \fIradscale\fR for the sphere radius. The
+sphere radius is determined automatically from an estimated average distance
+between spheres so as to reduce clustering, assuming a uniform distribution. 
+In cases where the distribution is substantially nonuniform (e.g. highly
+localised caustics) the radius can be manually corrected with this option. 
+The default value is 1.0. This option is ignored for point list output 
+in conjuction with \fB-a\fR.
+
 .SH NOTES
-The output may contain many overlapping spheres in areas with high photon
-density, particularly in caustics.  This results in inefficient and slow
-octree generation with \fIoconv(1)\fR.  Generally this can be improved by
-reducing \fInspheres\fR and/or \fIradscale\fR.
+The RADIANCE scene output may contain many overlapping spheres in areas with
+high photon density, particularly in caustics. This results in inefficient 
+and slow octree generation with \fIoconv(1)\fR. Generally this can be 
+improved by reducing \fInum\fR and/or \fIradscale\fR.
 
 .SH EXAMPLES
 Visualise the distribution of global and caustic photons superimposed
@@ -90,18 +107,27 @@ on the scene geometry with 5000 pale red and 10000 pal
 respectively:
 .IP
 pmapdump -n 5k -c 1 0.4 0.4 global.pm -n 10k -c 0.4 0.4 1 caustic.pm | 
-oconv - scene.rad > scene_pmdump.oct
+oconv - scene.rad > scene_pm.oct
 .PP
 Visualise the caustic photon distribution superimposed on the scene geometry
 with 10000 spheres coloured according to the photons' respective RGB flux:
 .IP
-pmapdump -n 10k -f caustic.pm | oconv - scene.rad > scene_pmdump.oct
+pmapdump -n 10k -f caustic.pm | oconv - scene.rad > scene_pm.oct
 .PP
-Dumps may also be viewed on their own by piping the output of \fIpmapdump\fR
-directly into \fIobjview(1)\fR (using the default number of spheres in this
-example):
+RADIANCE scene dumps may also be viewed on their own by simply piping the
+output of \fIpmapdump\fR directly into \fIobjview(1)\fR (using the default
+number of spheres in this example):
 .IP
 pmapdump zombo.pm | objview
+.PP
+Dump photons as a (really long) point list to an ASCII file for import in
+a 3D point cloud viewer:
+.IP
+pmapdump -a -f -n 1m lotsa.pm > lotsa-pointz.txt
+.PP
+Capt. B. wants 'em bigger:
+.IP
+pmapdump -r 4.0 bonzo.pm > bigbonzo-pm.rad
 
 .SH AUTHOR
 Roland Schregle (roland.schregle@{hslu.ch,gmail.com})
@@ -117,5 +143,7 @@ German Research Foundation (DFG) and the Swiss Nationa
 
 .SH "SEE ALSO"
 mkpmap(1), objview(1), oconv(1), rpict(1), rvu(1), 
-\fIThe RADIANCE Photon Map Manual\fR
+\fIThe RADIANCE Photon Map Manual\fR,
+\fIBonzo Daylighting Tool [TM]\fR
+