man/man1/pmapdump.1

.\" RCSid "$Id: pmapdump.1,v 1.8 2019/08/14 18:03:23 rschregle Exp $"
.TH PMAPDUMP 1 "$Date: 2019/08/14 18:03:23 $ $Revision: 1.8 $" 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 must 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, are expressed in
scientific notation if necessary to accommodate their high dynamic range. 

.IP
As \fIpmapdump\fR groups its options per photon map, this option must be
specified per photon map for consistent output. This prevents erroneously
dumping RADIANCE scene descriptions along with point lists, which will
fail to load in the 3D point cloud processor/viewer.

.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-f\fR"
Boolean switch to colour each sphere/point according to the corresponding
photon's RGB flux instead of a constant colour.  The flux is adjusted for
the fraction of dumped photons to maintain the total flux contained in the
dumped photon map.  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-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
But Capt. B wants 'em bigger:
.IP
pmapdump -r 4.0 bonzo.pm > bonzo_bigballz.rad
.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
Instead of a RADIANCE scene, dump photons as a (really long) point list to
an ASCII file for import into a 3D point cloud processor/viewer:
.IP
pmapdump -a -f -n 1m lotsa.pm > lotsa_pointz.txt

.SH AUTHOR
Roland Schregle (roland.schregle@{hslu.ch,gmail.com})

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

.SH ACKNOWLEDGEMENTS
Development of the RADIANCE photon mapping extension was supported by:

.RS
\fIFraunhofer Institute for Solar Energy Systems\fR 
funded by
the German Research Foundation (\fIDFG LU204/10-2\fR, "Fassadenintegrierte 
Regelsysteme (FARESYS)"), 

\fILucerne University of Applied Sciences and Arts\fR 
funded by
the Swiss National Science Foundation (\fISNSF 147053\fR, "Daylight redirecting components"),

\fITokyo University of Science\fR 
funded by the JSPS Grants-in-Aid for Scientific 
Research Programme (\fIKAKENHI JP19KK0115\fR, "Three-dimensional light flow"). 
.RE

Many thanks also to the many individuals who tested the code and provided
valuable feedback. Special greetz to Don Gregorio, PAB and Capt.\~B!

.SH "SEE ALSO"
mkpmap(1), objview(1), oconv(1), rpict(1), rvu(1), 
.br
\fIThe RADIANCE Photon Map Manual\fR,
.br
\fIDevelopment and Integration of the RADIANCE Photon Map Extension: 
Technical Report\fR,
.br
\fIThe RADIANCE Out-of-Core Photon Map: Technical Report\fR,
.br
\fIBonzo Daylighting Tool a.k.a. EvilDRC [TM]\fR

Revision:	1.9
Committed:	Fri Aug 7 01:26:20 2020 UTC (4 years, 9 months ago) by rschregle
Branch:	MAIN
CVS Tags:	rad5R4, rad5R3, HEAD
Changes since 1.8:	+37 -12 lines
Log Message:	docs(pmapdump): Updated acknowlegements and copyright.
#	User	Rev	Content
1	rschregle	1.9	.\" RCSid "$Id: pmapdump.1,v 1.8 2019/08/14 18:03:23 rschregle Exp $"
2			.TH PMAPDUMP 1 "$Date: 2019/08/14 18:03:23 $ $Revision: 1.8 $" RADIANCE
3	greg	1.1
4			.SH NAME
5	rschregle	1.5	pmapdump - generate RADIANCE scene description or point list representing
6			photon positions and (optionally) flux
7	greg	1.1
8			.SH SYNOPSIS
9	rschregle	1.5	pmapdump [\fB-a\fR] [\fB-n\fR \fInum1\fR] [\fB-r\fR \fIradscale1\fR]
10			[\fB-f\fR \| \fB-c\fR \fIrcol1\fR \fIgcol1\fR \fIbcol1\fR]
11			\fIpmap1\fR
12			[\fB-a\fR] [\fB-n\fR \fInum2\fR] [\fB-r\fR \fIradscale2\fR]
13			[\fB-f\fR \| \fB-c\fR \fIrcol2\fR \fIgcol2\fR \fIbcol2\fR]
14			\fIpmap2\fR ...
15	greg	1.1
16			.SH DESCRIPTION
17			\fIpmapdump\fR takes one or more photon map files generated with
18	rschregle	1.5	\fImkpmap(1)\fR as input and, by default, sends a RADIANCE scene description
19			of their photon distributions to the standard output. Photons are
20			represented as spheres of material type \fIglow\fR. These can be
21			visualised with e.g. \fIobjview(1)\fR, \fIrpict(1)\fR, or \fIrvu(1)\fR to
22			assess the location and local density of photons in relation to the scene
23			geometry. No additional light sources are necessary, as the spheres
24			representing the photons are self-luminous.
25			.PP
26			Alternatively, photons can also be output as an ASCII point list, where
27			each line contains a photon's position and colour.
28			This point list can be imported in a 3D point cloud processor/viewer
29			to interactively explore the photon map.
30	greg	1.1	.PP
31			An arbitrary number of photon maps can be specified on the command line and
32	rschregle	1.7	the respective photon type is determined automagically. Per default, the
33	rschregle	1.5	different photon types are visualised as colour coded spheres/points
34			according to the following default schema:
35	greg	1.1	.IP
36			\fIBlue\fR: global photons
37			.br
38			\fICyan\fR: precomputed global photons
39			.br
40			\fIRed\fR: caustic photons
41			.br
42			\fIGreen\fR: volume photons
43			.br
44			\fIMagenta\fR: direct photons
45			.br
46			\fIYellow\fR: contribution photons
47	rschregle	1.2	.PP
48			These colours can be overridden for individual photon maps with the \fB-c\fR
49	rschregle	1.5	option (see below). Alternatively, photons can be individually coloured
50	rschregle	1.4	according to their actual RGB flux with the \fB-f\fR option (see below);
51			while this makes it difficult to discern photon types, it can be used to
52	rschregle	1.5	quantitatively analyse colour bleeding effects, for example.
53	greg	1.1
54			.SH OPTIONS
55			Options are effective for the photon map file immediately following on the
56			command line, and are reset to their defaults after completion of each dump.
57	rschregle	1.7	As such they must be set individually for each photon map.
58	greg	1.1
59	rschregle	1.5	.IP "\fB-a\fR"
60			Boolean switch to output photons as a point list in ASCII (text) format
61			instead of a RADIANCE scene.
62			Each output line consists of 6 tab-separated floating point values: the
63			X, Y, Z coordinates of the photon's position, and the R, G, B colour
64	rschregle	1.7	channels of its flux. These values. notably the flux, are expressed in
65			scientific notation if necessary to accommodate their high dynamic range.
66
67			.IP
68			As \fIpmapdump\fR groups its options per photon map, this option must be
69			specified per photon map for consistent output. This prevents erroneously
70			dumping RADIANCE scene descriptions along with point lists, which will
71	rschregle	1.9	fail to load in the 3D point cloud processor/viewer.
72	rschregle	1.7
73			.IP "\fB-c\fR \fIrcol\fR \fIgcol\fR \fIbcol\fR"
74			Specifies a custom sphere/point colour for the next photon map. The colour
75			is specified as an RGB triplet, with each component in the range (0..1].
76			Without this option, the default colour for the corresponding photon type
77			is used. This option is mutually exclusive with \fB-f\fR.
78	rschregle	1.5
79			.IP "\fB-f\fR"
80	rschregle	1.8	Boolean switch to colour each sphere/point according to the corresponding
81			photon's RGB flux instead of a constant colour. The flux is adjusted for
82			the fraction of dumped photons to maintain the total flux contained in the
83			dumped photon map. Note that no exposure is applied, and as such the
84			resulting colours can span several orders of magnitude and may require tone
85			mapping with \fIpcond(1)\fR for visualisation. This option is mutually
86			exclusive with \fB-c\fR.
87	rschregle	1.5
88			.IP "\fB-n \fInum\fR"
89			Specifies the number of spheres or points to dump for the next photon map.
90			The dump is performed by random sampling with \fInum\fR as target count,
91			hence the number actually output will be approximate. \fINum\fR may be
92			suffixed by a case-insensitive multiplier for convenience, where
93			\fIk\fR = 10^3 and \fIm\fR = 10^6, although the latter may lead to problems
94			when processing the output geometry with \fIoconv(1)\fR. The default number
95			is 10k.
96	greg	1.1
97			.IP "\fB-r \fIradscale\fR"
98			Specifies a relative scale factor \fIradscale\fR for the sphere radius. The
99			sphere radius is determined automatically from an estimated average distance
100			between spheres so as to reduce clustering, assuming a uniform distribution.
101	rschregle	1.5	In cases where the distribution is substantially nonuniform (e.g. highly
102	greg	1.1	localised caustics) the radius can be manually corrected with this option.
103	rschregle	1.5	The default value is 1.0. This option is ignored for point list output
104			in conjuction with \fB-a\fR.
105	rschregle	1.2
106	greg	1.1	.SH NOTES
107	rschregle	1.5	The RADIANCE scene output may contain many overlapping spheres in areas with
108			high photon density, particularly in caustics. This results in inefficient
109			and slow octree generation with \fIoconv(1)\fR. Generally this can be
110			improved by reducing \fInum\fR and/or \fIradscale\fR.
111	greg	1.1
112			.SH EXAMPLES
113	rschregle	1.4	Visualise the distribution of global and caustic photons superimposed
114	rschregle	1.2	on the scene geometry with 5000 pale red and 10000 pale blue spheres,
115			respectively:
116	greg	1.1	.IP
117	rschregle	1.2	pmapdump -n 5k -c 1 0.4 0.4 global.pm -n 10k -c 0.4 0.4 1 caustic.pm \|
118	rschregle	1.5	oconv - scene.rad > scene_pm.oct
119	greg	1.1	.PP
120	rschregle	1.4	Visualise the caustic photon distribution superimposed on the scene geometry
121			with 10000 spheres coloured according to the photons' respective RGB flux:
122			.IP
123	rschregle	1.5	pmapdump -n 10k -f caustic.pm \| oconv - scene.rad > scene_pm.oct
124	rschregle	1.4	.PP
125	rschregle	1.7	But Capt. B wants 'em bigger:
126			.IP
127			pmapdump -r 4.0 bonzo.pm > bonzo_bigballz.rad
128			.PP
129	rschregle	1.5	RADIANCE scene dumps may also be viewed on their own by simply piping the
130			output of \fIpmapdump\fR directly into \fIobjview(1)\fR (using the default
131			number of spheres in this example):
132	greg	1.1	.IP
133			pmapdump zombo.pm \| objview
134	rschregle	1.5	.PP
135	rschregle	1.7	Instead of a RADIANCE scene, dump photons as a (really long) point list to
136	rschregle	1.9	an ASCII file for import into a 3D point cloud processor/viewer:
137	rschregle	1.5	.IP
138	rschregle	1.7	pmapdump -a -f -n 1m lotsa.pm > lotsa_pointz.txt
139	greg	1.1
140			.SH AUTHOR
141			Roland Schregle (roland.schregle@{hslu.ch,gmail.com})
142
143			.SH COPYRIGHT
144	rschregle	1.9	(c) Fraunhofer Institute for Solar Energy Systems,
145			.br
146			(c) Lucerne University of Applied Sciences and Arts,
147			.br
148			(c) Tokyo University of Science.
149
150			.SH ACKNOWLEDGEMENTS
151			Development of the RADIANCE photon mapping extension was supported by:
152	greg	1.1
153	rschregle	1.9	.RS
154			\fIFraunhofer Institute for Solar Energy Systems\fR
155			funded by
156			the German Research Foundation (\fIDFG LU204/10-2\fR, "Fassadenintegrierte
157			Regelsysteme (FARESYS)"),
158
159			\fILucerne University of Applied Sciences and Arts\fR
160			funded by
161			the Swiss National Science Foundation (\fISNSF 147053\fR, "Daylight redirecting components"),
162
163			\fITokyo University of Science\fR
164			funded by the JSPS Grants-in-Aid for Scientific
165			Research Programme (\fIKAKENHI JP19KK0115\fR, "Three-dimensional light flow").
166			.RE
167
168			Many thanks also to the many individuals who tested the code and provided
169			valuable feedback. Special greetz to Don Gregorio, PAB and Capt.\~B!
170	greg	1.1
171			.SH "SEE ALSO"
172			mkpmap(1), objview(1), oconv(1), rpict(1), rvu(1),
173	rschregle	1.9	.br
174	rschregle	1.5	\fIThe RADIANCE Photon Map Manual\fR,
175	rschregle	1.9	.br
176			\fIDevelopment and Integration of the RADIANCE Photon Map Extension:
177			Technical Report\fR,
178			.br
179			\fIThe RADIANCE Out-of-Core Photon Map: Technical Report\fR,
180			.br
181			\fIBonzo Daylighting Tool a.k.a. EvilDRC [TM]\fR
182	greg	1.1