man/man1/pmapdump.1

.\" RCSid "$Id: pmapdump.1,v 1.3 2018/11/21 19:42:20 rschregle Exp $"
.TH PMAPDUMP 1 "$Date: 2018/11/21 19:42:20 $ $Revision: 1.3 $" RADIANCE

.SH NAME
pmapdump - generate RADIANCE scene description of photon map distribution

.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 
         ...

.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.
.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:
.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.

.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-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-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].
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.

.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.

.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_pmdump.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
.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):
.IP
pmapdump zombo.pm | objview

.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

Revision:	1.4
Committed:	Thu Jan 10 18:29:34 2019 UTC (6 years, 3 months ago) by rschregle
Branch:	MAIN
Changes since 1.3:	+35 -16 lines
Log Message:	Documented change to 'glow' material and new -f option
#	User	Rev	Content
1	rschregle	1.4	.\" RCSid "$Id: pmapdump.1,v 1.3 2018/11/21 19:42:20 rschregle Exp $"
2			.TH PMAPDUMP 1 "$Date: 2018/11/21 19:42:20 $ $Revision: 1.3 $" RADIANCE
3	greg	1.1
4			.SH NAME
5			pmapdump - generate RADIANCE scene description of photon map distribution
6
7			.SH SYNOPSIS
8	rschregle	1.2	pmapdump [\fB-n\fR \fInspheres1\fR] [\fB-r\fR \fIradscale1\fR]
9	rschregle	1.4	[\fB-f\fR \| \fB-c\fR \fIrcol1\fR \fIgcol1\fR \fIbcol1\fR] \fIpmap1\fR
10			[\fB-n\fR \fInspheres2\fR] [\fB-r\fR \fIradscale2\fR]
11			[\fB-f\fR \| \fB-c\fR \fIrcol2\fR \fIgcol2\fR \fIbcol2\fR] \fIpmap2\fR
12			...
13	greg	1.1
14			.SH DESCRIPTION
15			\fIpmapdump\fR takes one or more photon map files generated with
16			\fImkpmap(1)\fR as input and sends a RADIANCE scene description of their
17	rschregle	1.4	photon distributions to the standard output. Photons are represented as
18			spheres of material type \fIglow\fR. These can be visualised with
19	greg	1.1	e.g. \fIobjview(1)\fR, \fIrpict(1)\fR, or \fIrvu(1)\fR to assess the
20	rschregle	1.4	location and local density of photons in relation to the scene geometry. No
21			additional light sources are necessary, as the spheres representing the
22			photons are self-luminous.
23	greg	1.1	.PP
24			An arbitrary number of photon maps can be specified on the command line and
25	rschregle	1.4	the respective photon type is determined automagically. Per default, the
26			different photon types are visualised as colour coded spheres according to
27			the following default schema:
28	greg	1.1	.IP
29			\fIBlue\fR: global photons
30			.br
31			\fICyan\fR: precomputed global photons
32			.br
33			\fIRed\fR: caustic photons
34			.br
35			\fIGreen\fR: volume photons
36			.br
37			\fIMagenta\fR: direct photons
38			.br
39			\fIYellow\fR: contribution photons
40	rschregle	1.2	.PP
41			These colours can be overridden for individual photon maps with the \fB-c\fR
42	rschregle	1.4	option (see below). Alternatively, photons can be individually coloured
43			according to their actual RGB flux with the \fB-f\fR option (see below);
44			while this makes it difficult to discern photon types, it can be used to
45			quantitatively analyse colour bleeding effects.
46	greg	1.1
47			.SH OPTIONS
48			Options are effective for the photon map file immediately following on the
49			command line, and are reset to their defaults after completion of each dump.
50			As such they may be set individually for each photon map.
51
52			.IP "\fB-n \fInspheres\fR"
53			Specifies the number of spheres to dump for the next photon map. The dump
54			is performed by random sampling with \fInspheres\fR as target count, hence
55			the number actually output will be approximate. \fINspheres\fR may be
56			followed by a multiplier suffix for convenience, where \fIk\fR = 10^3 and
57			\fIm\fR = 10^6, although the latter may lead to problems when processing the
58			output geometry with \fIoconv(1)\fR. The default number of spheres is 10k.
59
60			.IP "\fB-r \fIradscale\fR"
61			Specifies a relative scale factor \fIradscale\fR for the sphere radius. The
62			sphere radius is determined automatically from an estimated average distance
63			between spheres so as to reduce clustering, assuming a uniform distribution.
64			In cases where the distribution is substantially nonuniform (e.g. highly
65			localised caustics) the radius can be manually corrected with this option.
66			The default value is 1.0.
67
68	rschregle	1.2	.IP "\fB-c\fR \fIrcol\fR \fIgcol\fR \fIbcol\fR"
69	rschregle	1.3	Specifies a custom sphere colour for the next photon map. The colour is
70	rschregle	1.2	specified as an RGB triplet, with each component in the range (0..1].
71			Without this option, the default colour for the corresponding photon type
72	rschregle	1.4	is used. This option is mutually exclusive with \fB-f\fR.
73
74			.IP "\fB-f\fR"
75			Boolean switch to colour each sphere according to the corresponding photon's
76			RGB flux instead of a constant colour. Note that the resulting colours can
77			span several orders of magnitude and may require tone mapping with
78			\fIpcond(1)\fR for visualisation. This option is mutually exclusive with
79			\fB-c\fR.
80	rschregle	1.2
81	greg	1.1	.SH NOTES
82			The output may contain many overlapping spheres in areas with high photon
83			density, particularly in caustics. This results in inefficient and slow
84			octree generation with \fIoconv(1)\fR. Generally this can be improved by
85			reducing \fInspheres\fR and/or \fIradscale\fR.
86
87			.SH EXAMPLES
88	rschregle	1.4	Visualise the distribution of global and caustic photons superimposed
89	rschregle	1.2	on the scene geometry with 5000 pale red and 10000 pale blue spheres,
90			respectively:
91	greg	1.1	.IP
92	rschregle	1.2	pmapdump -n 5k -c 1 0.4 0.4 global.pm -n 10k -c 0.4 0.4 1 caustic.pm \|
93	greg	1.1	oconv - scene.rad > scene_pmdump.oct
94			.PP
95	rschregle	1.4	Visualise the caustic photon distribution superimposed on the scene geometry
96			with 10000 spheres coloured according to the photons' respective RGB flux:
97			.IP
98			pmapdump -n 10k -f caustic.pm \| oconv - scene.rad > scene_pmdump.oct
99			.PP
100			Dumps may also be viewed on their own by piping the output of \fIpmapdump\fR
101			directly into \fIobjview(1)\fR (using the default number of spheres in this
102			example):
103	greg	1.1	.IP
104			pmapdump zombo.pm \| objview
105
106			.SH AUTHOR
107			Roland Schregle (roland.schregle@{hslu.ch,gmail.com})
108
109			.SH COPYRIGHT
110			(c) Fraunhofer Institute for Solar Energy Systems, Lucerne University of
111			Applied Sciences and Arts.
112
113			.SH ACKNOWLEDGEMENT
114			Development of the RADIANCE photon mapping extension was sponsored by the
115			German Research Foundation (DFG) and the Swiss National Science Foundation
116			(SNF).
117
118			.SH "SEE ALSO"
119			mkpmap(1), objview(1), oconv(1), rpict(1), rvu(1),
120			\fIThe RADIANCE Photon Map Manual\fR
121