.\" 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 or point list representing
photon positions and (optionally) flux

.SH SYNOPSIS
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, 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/points 
according to the following default schema:
.IP
\fIBlue\fR: global photons 
.br
\fICyan\fR: precomputed global photons
.br
\fIRed\fR: caustic photons
.br
\fIGreen\fR: volume photons
.br
\fIMagenta\fR: direct photons
.br
\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
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, 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-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-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/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-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 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
on the scene geometry with 5000 pale red and 10000 pale blue spheres, 
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_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_pm.oct
.PP
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})

.SH COPYRIGHT
(c) Fraunhofer Institute for Solar Energy Systems, Lucerne University of 
Applied Sciences and Arts.

.SH ACKNOWLEDGEMENT
Development of the RADIANCE photon mapping extension was sponsored by the 
German Research Foundation (DFG) and the Swiss National Science Foundation 
(SNF). 

.SH "SEE ALSO"
mkpmap(1), objview(1), oconv(1), rpict(1), rvu(1), 
\fIThe RADIANCE Photon Map Manual\fR,
\fIBonzo Daylighting Tool [TM]\fR