ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/doc/man/man1/pmapdump.1
Revision: 1.7
Committed: Tue Jan 22 19:50:09 2019 UTC (6 years, 3 months ago) by rschregle
Branch: MAIN
Changes since 1.6: +25 -19 lines
Log Message:
Minor revisions & clarifications

File Contents

# Content
1 .\" RCSid "$Id: pmapdump.1,v 1.6 2019/01/22 18:31:28 rschregle Exp $"
2 .TH PMAPDUMP 1 "$Date: 2019/01/22 18:31:28 $ $Revision: 1.6 $" RADIANCE
3
4 .SH NAME
5 pmapdump - generate RADIANCE scene description or point list representing
6 photon positions and (optionally) flux
7
8 .SH SYNOPSIS
9 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
16 .SH DESCRIPTION
17 \fIpmapdump\fR takes one or more photon map files generated with
18 \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 .PP
31 An arbitrary number of photon maps can be specified on the command line and
32 the respective photon type is determined automagically. Per default, the
33 different photon types are visualised as colour coded spheres/points
34 according to the following default schema:
35 .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 .PP
48 These colours can be overridden for individual photon maps with the \fB-c\fR
49 option (see below). Alternatively, photons can be individually coloured
50 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 quantitatively analyse colour bleeding effects, for example.
53
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 As such they must be set individually for each photon map.
58
59 .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 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 fail to load in the 3D point cloud viewer.
72
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
79 .IP "\fB-f\fR"
80 Boolean switch to colour each sphere/point according to the corresponding
81 photon's RGB flux instead of a constant colour. Note that no exposure is
82 applied, and as such the resulting colours can span several orders of
83 magnitude and may require tone mapping with \fIpcond(1)\fR for
84 visualisation. This option is mutually exclusive with \fB-c\fR.
85
86 .IP "\fB-n \fInum\fR"
87 Specifies the number of spheres or points to dump for the next photon map.
88 The dump is performed by random sampling with \fInum\fR as target count,
89 hence the number actually output will be approximate. \fINum\fR may be
90 suffixed by a case-insensitive multiplier for convenience, where
91 \fIk\fR = 10^3 and \fIm\fR = 10^6, although the latter may lead to problems
92 when processing the output geometry with \fIoconv(1)\fR. The default number
93 is 10k.
94
95 .IP "\fB-r \fIradscale\fR"
96 Specifies a relative scale factor \fIradscale\fR for the sphere radius. The
97 sphere radius is determined automatically from an estimated average distance
98 between spheres so as to reduce clustering, assuming a uniform distribution.
99 In cases where the distribution is substantially nonuniform (e.g. highly
100 localised caustics) the radius can be manually corrected with this option.
101 The default value is 1.0. This option is ignored for point list output
102 in conjuction with \fB-a\fR.
103
104 .SH NOTES
105 The RADIANCE scene output may contain many overlapping spheres in areas with
106 high photon density, particularly in caustics. This results in inefficient
107 and slow octree generation with \fIoconv(1)\fR. Generally this can be
108 improved by reducing \fInum\fR and/or \fIradscale\fR.
109
110 .SH EXAMPLES
111 Visualise the distribution of global and caustic photons superimposed
112 on the scene geometry with 5000 pale red and 10000 pale blue spheres,
113 respectively:
114 .IP
115 pmapdump -n 5k -c 1 0.4 0.4 global.pm -n 10k -c 0.4 0.4 1 caustic.pm |
116 oconv - scene.rad > scene_pm.oct
117 .PP
118 Visualise the caustic photon distribution superimposed on the scene geometry
119 with 10000 spheres coloured according to the photons' respective RGB flux:
120 .IP
121 pmapdump -n 10k -f caustic.pm | oconv - scene.rad > scene_pm.oct
122 .PP
123 But Capt. B wants 'em bigger:
124 .IP
125 pmapdump -r 4.0 bonzo.pm > bonzo_bigballz.rad
126 .PP
127 RADIANCE scene dumps may also be viewed on their own by simply piping the
128 output of \fIpmapdump\fR directly into \fIobjview(1)\fR (using the default
129 number of spheres in this example):
130 .IP
131 pmapdump zombo.pm | objview
132 .PP
133 Instead of a RADIANCE scene, dump photons as a (really long) point list to
134 an ASCII file for import into a 3D point cloud viewer:
135 .IP
136 pmapdump -a -f -n 1m lotsa.pm > lotsa_pointz.txt
137
138 .SH AUTHOR
139 Roland Schregle (roland.schregle@{hslu.ch,gmail.com})
140
141 .SH COPYRIGHT
142 (c) Fraunhofer Institute for Solar Energy Systems, Lucerne University of
143 Applied Sciences and Arts.
144
145 .SH ACKNOWLEDGEMENT
146 Development of the RADIANCE photon mapping extension was sponsored by the
147 German Research Foundation (DFG) and the Swiss National Science Foundation
148 (SNF). Greetz to Capt. B!
149
150 .SH "SEE ALSO"
151 mkpmap(1), objview(1), oconv(1), rpict(1), rvu(1),
152 \fIThe RADIANCE Photon Map Manual\fR,
153 \fIBonzo Daylighting Tool [TM]\fR
154
155