man/man1/mkpmap.1

.\" RCSid "$Id: mkpmap.1,v 1.4 2017/03/30 11:54:53 rschregle Exp $"
.TH MKPMAP 1 "$Date: 2017/03/30 11:54:53 $ $Revision: 1.4 $" RADIANCE

.SH NAME
mkpmap - generate RADIANCE photon map

.SH SYNOPSIS
mkpmap \fB\-apg\fR|\fB\-apc\fR|\fB\-apv\fR|\fB\-apd\fR|\fB\-app\fR|\fB\-apC\fR
\fIfile nphotons\fR [\fIbwidth\fR] ...
       [options] \fIoctree\fR

.SH DESCRIPTION
\fIMkpmap\fR takes a RADIANCE scene description as an octree and
performs Monte Carlo forward path tracing from the light sources,
depositing indirect ray hitpoints along with their energy (flux) as
"photons". The resulting localised energy distribution represents a
global illumination solution which is written to a file for subsequent
evaluation by \fIrpict(1), rtrace(1)\fR and \fIrvu(1)\fR in a backward
raytracing pass. The photon map(s) can be reused for multiple viewpoints
and sensor locations as long as the geometry remains unchanged.

.SH OPTIONS
\fIMkpmap\fR can generate different types of photon maps depending on
the materials present in the scene. In most cases, these can be
specified independently or in combination on the command line. If
multiple photon maps of the same type are specified, the last instance
takes precedence.

.IP "\fB\-apg \fIfile nphotons\fR"
Generate a global photon map containing approximately \fInphotons\fR
photons, and output to \fIfile\fR. This accounts for all
indirect illumination, from both specular and diffuse scattering, on
surfaces with a diffuse component. This is the most general type of
photon map and replaces the ambient calculation in \fIrpict(1),
rtrace(1)\fR and \fIrvu(1)\fR.

.IP "\fB\-apc \fIfile nphotons\fR"
Generate a separate caustic photon map containing approximately
\fInphotons\fR photons, and output to file \fIfile\fR. This is a
subset of the global photon map intended for direct visualisation at
primary rays,  This accounts for all indirect illumination on diffuse
surfaces from specular scattering, which usually exhibits a large
gradient and requires a higher resolution than the global photon map,
typically containing the tenfold number of photons.

.IP "\fB\-apv \fIfile nphotons\fR"
Generate a volume photon map containing approximately \fInphotons\fR
photons, and output to file \fIfile\fR. These account for indirect
inscattering in participating media such as \fBmist\fR and complement
the direct inscattering computed by \fIrpict(1), rtrace(1)\fR and
\fIrvu(1)\fR. See also the \fB\-me\fR, \fB\-ma\fR and \fB\-mg\fR options
below.

.IP "\fB\-apd \fIfile nphotons\fR"
Generate a direct photon map containing approximately \fInphotons\fR
photons, and output to file \fIfile\fR. This only accounts for direct
illumination and is intended for debugging and validation of photon emission
from the light sources, as the quality is too low for actual rendering.

.IP "\fB\-apC \fIfile nphotons\fR" 
Generate a contribution photon map containing approximately
\fInphotons\fR photons, and output to file \fIfile\fR. This may then be
used by \fIrcontrib(1)\fR to compute light source contributions.
.IP
With this option, \fImkpmap\fR uses a modified photon distribution
algorithm that ensures all light sources contribute approximately the
same number of photons. Each photon indexes a primary hitpoint, incident
direction, and emitting light source which can be used to bin
contributions per light source and direction.
.IP
\fIMkpmap\fR cannot generate a contribution photon map in combination with
others in a single run, as it uses a different distribution algorithm. Other
photon maps specified on the command line will be ignored.

.IP "\fB\-app \fIfile nphotons bwidth\fR"
Generate a precomputed global photon map containing a fraction of
\fInphotons\fR photons (specified with the \fB\-apP\fR option, see
below), and output to file \fIfile\fR. This is a special case of the
global photon map where the irradiance is evaluated for a fraction of
the photon positions using \fIbwidth\fR nearest photons, and stored as
photon flux; the remaining photons are discarded as their contributions
have been accounted for. 
.IP 
This obviates the explicit irradiance
evaluation by \fIrpict(1), rtrace(1)\fR and \fIrvu(1)\fR, thus providing
a speedup at the expense of accuracy. The resulting error is tolerable
if the indirect illumination has a low gradient, as is usually the case
with diffuse illumination.

.IP "\fB\-apD \fIpredistrib\fR"
Photon predistribution factor; this is the fraction of \fInphotons\fR
which are emitted in a distribution prepass in order to estimate the
remaining number of photons to emit in the main pass to approximately
yield a photon map of size \fInphotons\fR. 
.IP
Setting this too high may
yield more than \fInphotons\fR in the initial pass with highly
reflective geometry. Note that this value may exceed 1, which may be
useful if the resulting photon map size greatly deviates from
\fInphotons\fR with a very low average reflectance.

.IP "\fB\-apP \fIprecomp\fR"
Fraction of global photons to precompute in the range ]0,1] when using the
\fB\-app\fR option.

.IP "\fB\-apm \fImaxbounce\fR"
Maximum number of bounces (scattering events) along a photon path before
being considered "runaway" and terminated. Photons paths are normally
terminated via \fIRussian Roulette\fR, depending on their albedo. With
unrealistically high albedos, this is not guaranteed, and this options
imposes a hard limit to avoid an infinite loop.

.IP "\fB\-apM \fImaxprepass\fR"
Maximum number of iterations of the distribution prepass before terminating
if some photon maps are still empty. This option is rarely needed as a
an aborted prepass indicates an anomaly in the geometry or an
incompatibility with the specified photon map types (see \fBNOTES\fR below).

.IP "\fB\-apo \fImod\fR"
Specifies a modifier \fImod\fR to act as a \fIphoton port\fR. All
objects using this modifier will emit photons directly in lieu of any
light sources defined with the \fIsource\fR material. This greatly
accelerates photon distribution in scenes where photons have to enter a
space which separates them from the emitting light source via an
opening, or port. 
.IP
A typical application is daylight simulation, where a
fenestration acts as port to admit photons into an interior after
emission from an external light source. Multiple instances of this
option may be specified.
.IP
Note that port objects must be defined with their surface normals
pointing \fIinside\fR as per \fImkillum\fR convention.

.IP "\fB\-apO \fImodfile\fR"
Read photon port modifiers from the file \fImodfile\fR as a more convenient
alternative to multiple instances of \fB\-apo\fR.

.IP "\fB\-apr \fIseed\fR"
Seed for the random number generator. This is necessary for generating 
different photon distributions for the same octree and photon map size.

.IP "\fB\-aps \fImod\fR"
Specifies a modifier \fImod\fR defined as \fIantimatter\fR material to act
as a virtual (i.e.  invisible) receiver surface.  Photons will be deposited on
all surfaces using this modifier, just like regular materials, but will then
be transferred through the surface without undergoing scattering; the
surface therefore does not affect the light transport and simply acts as an
invisible photon receiver.  This is useful when photon irradiance is to be
evaluated at points which do not lie on regular geometry, e.g.  at workplane
height with \firtrace\fR's \fB-I\fR option.  Without this workaround,
photons would be collected from parallel but distant planes, leading to
underestimation.  Note that photons are only deposited when incident from
the front side of the sensor surface, i.e.  when entering the
\fIantimatter\fR, thus the surface normal is relevant.  \fIMkpmap\fR reports
an error if the specified modifier is not an \fIantimatter\fR material.

.IP "\fB\-apS \fImodfile\fR"
Read virtual receiver surface modifiers from the file \fImodfile\fR as a more
convenient alternative to multiple instances of \fB\-aps\fR.

.IP "\fB\-bv\fR[\fB+\fR|\fB-\fR]"
Toggles backface visibility; enabling this causes photons to be stored and
possibly scattered if they strike the back of a surface, otherwise they
are unconditionally absorbed and discarded.

.IP "\fB\-dp \fIsampleres\fR"
Resolution for sampling the spatial emission distribution of a modified
light source (e.g. via \fIbrightfunc\fR), in samples per steradian. This
is required for numerically integrating the flux emitted by the light
source and for constructing a probability density function for photon
emission. The accuracy of photon emission from modified sources
therefore depends on this parameter. This parameter may need increasing
with complex emission distributions in combination with caustics.

.IP "\fB\-ds \fIpartsize\fR"
Light source partition size ratio; a light source object is spatially 
partitioned to distribute the photon emission over its surface. This
parameter specifies the ratio of the size (per dimension) of each
partition to the scene cube, and may need increasing for modified light 
sources (e.g. via \fIbrightfunc\fR) with high spatial variation.

.IP "\fB\-e \fIfile\fR"
Redirect diagnostics and progress reports to \fIfile\fR instead of the
console.

.IP "\fB\-fo\fR[\fB+\fR|\fB-\fR]"
Toggles overwriting of output files. By default, \fImkpmap\fR will not
overwrite an already existing photon map file. This is to prevent
inadvertently destroying the results of potentially lengthy photon
mapping runs.

.IP "\fB\-i \fIinc\fR"
Photon heap size increment; the photon heap is enlarged by this amount
when storage overflows during photon distribution. No need to fiddle
with this under ordinary circumstances.

.IP "\fB\-ma \fIralb galb balb\fR"
Set the global scattering albedo for participating media in conjunction
with the \fB\-apv\fR option. See \fIrpict(1)\fR for details.

.IP "\fB\-me \fIrext gext bext\fR"
Set the global extinction coefficient for participating media in conjunction
with the \fB\-apv\fR option. See \fIrpict(1)\fR for details.

.IP "\fB\-mg \fIgecc\fR"
Set the global scattering eccentricity for participating media in conjunction
with the \fB\-apv\fR option. See \fIrpict(1)\fR for details.

.IP "\fB\-n \fInproc\fR"
Use \fInproc\fR processes for parallel photon distribution. There is no
benefit in specifying more than the number of physical CPU cores available.
This option is currently not available on Windows.

.IP "\fB\-t \fIinterval\fR"
Output a progress report every \fIinterval\fR seconds. This includes 
statistics about the currently emitting light source (including number of
partitions), the total number of photons emitted, the number of each type 
stored, the percentage of the completed pass (pre or main), and the elapsed
time.

.SH NOTES

.SS Parametrisation
\fIMkpmap\fR recognises multiplier suffixes (k = 1000, m = 1000000) to 
facilitate the specification of \fInphotons\fR, both in upper and lower
case.
.PP

.SS Distribution Algorithm
The photon distribution algorithm estimates the number of required
photons to emit to arrive at the specified target count \fInphotons\fR
per photon map using a distribution prepass followed by a main pass.
As a result, \fImkpmap\fR generates the \fBapproximate\fR number of photons
specified, which can vary by up to 10% for typical scenes, but can be
higher for scenes with unusually high or low reflectance. In this case,
the predistribution factor \fB\-apD\fR should be increased for scenes
with low reflectance, and reduced for those with high reflectance.
.PP
There are situations which may prevent certain (or any)
photon types from being generated, depending on the light source and material
configuration. This typically occurs when attempting to generate a caustic
photon map without specular materials present in the scene, or a volume 
photon map without participating media. Ill-configured light sources may also
prevent indirect rays from reaching a surface, and thus no photons being 
deposited. In these cases, \fImkpmap\fR will make a number of distribution
attempts before terminating with an error. This can be adjusted with the 
\fB\-apM\fR option.

.SS Material Support
The \fIplasfunc\fR, \fImetfunc\fR, \fItransfunc\fR, \fIbrtdfunc\fR,
\fIplasdata\fR, \fImetdata\fR and \fItransdata\fR materials are not
supported by the photon mapping extension. Use the newer \fIbsdf\fR material
instead.
.PP
Virtual light sources (normally enabled with the \fImirror\fR material) are
disabled with the photon map, as the resulting caustics are already accounted
for.

.SS Virtual Receiver Surfaces
Since photons are surface bound, the density estimate is only asymptotically
correct when performed at points which lie on the scene geometry.  The
irradiance is underestimated for arbitrarily placed points when photons are
collected from distant surfaces.  \fIMkpmap\fR offers a workaround with a
virtual receiver surface using the \fIantimatter\fR material; see the \fB-aps\fR
and \fB-apS\fR options for details.

.SH EXAMPLES
The following command generates a global photon map \fIbonzo.gpm\fR and a 
caustic photon map \fIbonzo.cpm\fR containing approximately 10000 and 100000 
photons, respectively, with progress report every 5 seconds:
.IP
mkpmap \-apg bonzo.gpm 10k \-apc bonzo.cpm 100k -t 5 bonzo.oct
.PP
Generate a global photon map containing 80000 photons, then precompute the
diffuse irradiance for 1/4 of these with a bandwidth of 40 photons:
.IP
mkpmap \-app bonzo-precomp.gpm 80k 40 \-apP 0.25 bonzo.oct
.PP
Generate 1 million global photons by emitting them from external light 
sources of type \fIsource\fR into a reference room via a fenestration 
with modifier \fIglazingMat\fR:
.IP
mkpmap \-apg refRoom.gpm 1m \-apo glazingMat refRoom.oct
.PP
Generate a contribution photon map containing 200000 photons suitable for 
obtaining light source contributions with \fIrcontrib(1)\fR:
.IP
mkpmap \-apC bonzo-contrib.gpm 200k bonzo.oct

.SH BUGS
The focus of a spotlight source, as defined by the length of its direction
vector, is ignored by the photon map; photons are unconditionally emitted
from the light source surface, which can lead to deviations from standard
RADIANCE.
.PP
Light sources simply absorb incoming photons.

.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"
rpict(1), rtrace(1), rvu(1), rcontrib(1), 
\fIThe RADIANCE Photon Map Manual\fR

Revision:	1.5
Committed:	Thu Mar 30 11:58:17 2017 UTC (8 years, 7 months ago) by rschregle
Branch:	MAIN
CVS Tags:	rad5R1
Changes since 1.4:	+3 -2 lines
Log Message:	Added caveats for Windows to mkpmap manpage
#	User	Rev	Content
1	rschregle	1.5	.\" RCSid "$Id: mkpmap.1,v 1.4 2017/03/30 11:54:53 rschregle Exp $"
2			.TH MKPMAP 1 "$Date: 2017/03/30 11:54:53 $ $Revision: 1.4 $" RADIANCE
3	greg	1.1
4			.SH NAME
5			mkpmap - generate RADIANCE photon map
6
7			.SH SYNOPSIS
8			mkpmap \fB\-apg\fR\|\fB\-apc\fR\|\fB\-apv\fR\|\fB\-apd\fR\|\fB\-app\fR\|\fB\-apC\fR
9			\fIfile nphotons\fR [\fIbwidth\fR] ...
10			[options] \fIoctree\fR
11
12			.SH DESCRIPTION
13			\fIMkpmap\fR takes a RADIANCE scene description as an octree and
14			performs Monte Carlo forward path tracing from the light sources,
15			depositing indirect ray hitpoints along with their energy (flux) as
16			"photons". The resulting localised energy distribution represents a
17			global illumination solution which is written to a file for subsequent
18			evaluation by \fIrpict(1), rtrace(1)\fR and \fIrvu(1)\fR in a backward
19			raytracing pass. The photon map(s) can be reused for multiple viewpoints
20			and sensor locations as long as the geometry remains unchanged.
21
22			.SH OPTIONS
23			\fIMkpmap\fR can generate different types of photon maps depending on
24			the materials present in the scene. In most cases, these can be
25			specified independently or in combination on the command line. If
26			multiple photon maps of the same type are specified, the last instance
27			takes precedence.
28
29			.IP "\fB\-apg \fIfile nphotons\fR"
30			Generate a global photon map containing approximately \fInphotons\fR
31			photons, and output to \fIfile\fR. This accounts for all
32			indirect illumination, from both specular and diffuse scattering, on
33			surfaces with a diffuse component. This is the most general type of
34			photon map and replaces the ambient calculation in \fIrpict(1),
35			rtrace(1)\fR and \fIrvu(1)\fR.
36
37			.IP "\fB\-apc \fIfile nphotons\fR"
38			Generate a separate caustic photon map containing approximately
39			\fInphotons\fR photons, and output to file \fIfile\fR. This is a
40			subset of the global photon map intended for direct visualisation at
41			primary rays, This accounts for all indirect illumination on diffuse
42			surfaces from specular scattering, which usually exhibits a large
43			gradient and requires a higher resolution than the global photon map,
44			typically containing the tenfold number of photons.
45
46			.IP "\fB\-apv \fIfile nphotons\fR"
47			Generate a volume photon map containing approximately \fInphotons\fR
48			photons, and output to file \fIfile\fR. These account for indirect
49			inscattering in participating media such as \fBmist\fR and complement
50			the direct inscattering computed by \fIrpict(1), rtrace(1)\fR and
51			\fIrvu(1)\fR. See also the \fB\-me\fR, \fB\-ma\fR and \fB\-mg\fR options
52			below.
53
54			.IP "\fB\-apd \fIfile nphotons\fR"
55			Generate a direct photon map containing approximately \fInphotons\fR
56			photons, and output to file \fIfile\fR. This only accounts for direct
57			illumination and is intended for debugging and validation of photon emission
58			from the light sources, as the quality is too low for actual rendering.
59
60	rschregle	1.4	.IP "\fB\-apC \fIfile nphotons\fR"
61	greg	1.1	Generate a contribution photon map containing approximately
62			\fInphotons\fR photons, and output to file \fIfile\fR. This may then be
63			used by \fIrcontrib(1)\fR to compute light source contributions.
64			.IP
65			With this option, \fImkpmap\fR uses a modified photon distribution
66			algorithm that ensures all light sources contribute approximately the
67			same number of photons. Each photon indexes a primary hitpoint, incident
68			direction, and emitting light source which can be used to bin
69			contributions per light source and direction.
70			.IP
71			\fIMkpmap\fR cannot generate a contribution photon map in combination with
72			others in a single run, as it uses a different distribution algorithm. Other
73			photon maps specified on the command line will be ignored.
74
75			.IP "\fB\-app \fIfile nphotons bwidth\fR"
76			Generate a precomputed global photon map containing a fraction of
77			\fInphotons\fR photons (specified with the \fB\-apP\fR option, see
78			below), and output to file \fIfile\fR. This is a special case of the
79			global photon map where the irradiance is evaluated for a fraction of
80			the photon positions using \fIbwidth\fR nearest photons, and stored as
81			photon flux; the remaining photons are discarded as their contributions
82			have been accounted for.
83			.IP
84			This obviates the explicit irradiance
85			evaluation by \fIrpict(1), rtrace(1)\fR and \fIrvu(1)\fR, thus providing
86			a speedup at the expense of accuracy. The resulting error is tolerable
87			if the indirect illumination has a low gradient, as is usually the case
88			with diffuse illumination.
89
90			.IP "\fB\-apD \fIpredistrib\fR"
91			Photon predistribution factor; this is the fraction of \fInphotons\fR
92			which are emitted in a distribution prepass in order to estimate the
93			remaining number of photons to emit in the main pass to approximately
94			yield a photon map of size \fInphotons\fR.
95			.IP
96			Setting this too high may
97			yield more than \fInphotons\fR in the initial pass with highly
98			reflective geometry. Note that this value may exceed 1, which may be
99			useful if the resulting photon map size greatly deviates from
100			\fInphotons\fR with a very low average reflectance.
101
102			.IP "\fB\-apP \fIprecomp\fR"
103			Fraction of global photons to precompute in the range ]0,1] when using the
104			\fB\-app\fR option.
105
106			.IP "\fB\-apm \fImaxbounce\fR"
107			Maximum number of bounces (scattering events) along a photon path before
108			being considered "runaway" and terminated. Photons paths are normally
109			terminated via \fIRussian Roulette\fR, depending on their albedo. With
110			unrealistically high albedos, this is not guaranteed, and this options
111			imposes a hard limit to avoid an infinite loop.
112
113			.IP "\fB\-apM \fImaxprepass\fR"
114			Maximum number of iterations of the distribution prepass before terminating
115			if some photon maps are still empty. This option is rarely needed as a
116			an aborted prepass indicates an anomaly in the geometry or an
117			incompatibility with the specified photon map types (see \fBNOTES\fR below).
118
119			.IP "\fB\-apo \fImod\fR"
120			Specifies a modifier \fImod\fR to act as a \fIphoton port\fR. All
121			objects using this modifier will emit photons directly in lieu of any
122			light sources defined with the \fIsource\fR material. This greatly
123			accelerates photon distribution in scenes where photons have to enter a
124			space which separates them from the emitting light source via an
125			opening, or port.
126			.IP
127			A typical application is daylight simulation, where a
128			fenestration acts as port to admit photons into an interior after
129			emission from an external light source. Multiple instances of this
130			option may be specified.
131			.IP
132			Note that port objects must be defined with their surface normals
133			pointing \fIinside\fR as per \fImkillum\fR convention.
134
135			.IP "\fB\-apO \fImodfile\fR"
136			Read photon port modifiers from the file \fImodfile\fR as a more convenient
137			alternative to multiple instances of \fB\-apo\fR.
138
139			.IP "\fB\-apr \fIseed\fR"
140			Seed for the random number generator. This is necessary for generating
141			different photon distributions for the same octree and photon map size.
142
143			.IP "\fB\-aps \fImod\fR"
144			Specifies a modifier \fImod\fR defined as \fIantimatter\fR material to act
145	rschregle	1.2	as a virtual (i.e. invisible) receiver surface. Photons will be deposited on
146	greg	1.1	all surfaces using this modifier, just like regular materials, but will then
147			be transferred through the surface without undergoing scattering; the
148			surface therefore does not affect the light transport and simply acts as an
149			invisible photon receiver. This is useful when photon irradiance is to be
150			evaluated at points which do not lie on regular geometry, e.g. at workplane
151			height with \firtrace\fR's \fB-I\fR option. Without this workaround,
152			photons would be collected from parallel but distant planes, leading to
153			underestimation. Note that photons are only deposited when incident from
154			the front side of the sensor surface, i.e. when entering the
155			\fIantimatter\fR, thus the surface normal is relevant. \fIMkpmap\fR reports
156			an error if the specified modifier is not an \fIantimatter\fR material.
157
158			.IP "\fB\-apS \fImodfile\fR"
159	rschregle	1.2	Read virtual receiver surface modifiers from the file \fImodfile\fR as a more
160	greg	1.1	convenient alternative to multiple instances of \fB\-aps\fR.
161
162			.IP "\fB\-bv\fR[\fB+\fR\|\fB-\fR]"
163			Toggles backface visibility; enabling this causes photons to be stored and
164			possibly scattered if they strike the back of a surface, otherwise they
165			are unconditionally absorbed and discarded.
166
167			.IP "\fB\-dp \fIsampleres\fR"
168			Resolution for sampling the spatial emission distribution of a modified
169			light source (e.g. via \fIbrightfunc\fR), in samples per steradian. This
170			is required for numerically integrating the flux emitted by the light
171			source and for constructing a probability density function for photon
172			emission. The accuracy of photon emission from modified sources
173			therefore depends on this parameter. This parameter may need increasing
174			with complex emission distributions in combination with caustics.
175
176			.IP "\fB\-ds \fIpartsize\fR"
177			Light source partition size ratio; a light source object is spatially
178			partitioned to distribute the photon emission over its surface. This
179			parameter specifies the ratio of the size (per dimension) of each
180			partition to the scene cube, and may need increasing for modified light
181			sources (e.g. via \fIbrightfunc\fR) with high spatial variation.
182
183			.IP "\fB\-e \fIfile\fR"
184			Redirect diagnostics and progress reports to \fIfile\fR instead of the
185			console.
186
187			.IP "\fB\-fo\fR[\fB+\fR\|\fB-\fR]"
188			Toggles overwriting of output files. By default, \fImkpmap\fR will not
189			overwrite an already existing photon map file. This is to prevent
190			inadvertently destroying the results of potentially lengthy photon
191			mapping runs.
192
193			.IP "\fB\-i \fIinc\fR"
194			Photon heap size increment; the photon heap is enlarged by this amount
195			when storage overflows during photon distribution. No need to fiddle
196			with this under ordinary circumstances.
197
198			.IP "\fB\-ma \fIralb galb balb\fR"
199			Set the global scattering albedo for participating media in conjunction
200			with the \fB\-apv\fR option. See \fIrpict(1)\fR for details.
201
202			.IP "\fB\-me \fIrext gext bext\fR"
203			Set the global extinction coefficient for participating media in conjunction
204			with the \fB\-apv\fR option. See \fIrpict(1)\fR for details.
205
206			.IP "\fB\-mg \fIgecc\fR"
207			Set the global scattering eccentricity for participating media in conjunction
208			with the \fB\-apv\fR option. See \fIrpict(1)\fR for details.
209
210	rschregle	1.3	.IP "\fB\-n \fInproc\fR"
211			Use \fInproc\fR processes for parallel photon distribution. There is no
212			benefit in specifying more than the number of physical CPU cores available.
213	rschregle	1.5	This option is currently not available on Windows.
214	rschregle	1.3
215	greg	1.1	.IP "\fB\-t \fIinterval\fR"
216			Output a progress report every \fIinterval\fR seconds. This includes
217			statistics about the currently emitting light source (including number of
218			partitions), the total number of photons emitted, the number of each type
219			stored, the percentage of the completed pass (pre or main), and the elapsed
220			time.
221
222			.SH NOTES
223
224			.SS Parametrisation
225			\fIMkpmap\fR recognises multiplier suffixes (k = 1000, m = 1000000) to
226			facilitate the specification of \fInphotons\fR, both in upper and lower
227			case.
228			.PP
229
230			.SS Distribution Algorithm
231			The photon distribution algorithm estimates the number of required
232			photons to emit to arrive at the specified target count \fInphotons\fR
233			per photon map using a distribution prepass followed by a main pass.
234			As a result, \fImkpmap\fR generates the \fBapproximate\fR number of photons
235			specified, which can vary by up to 10% for typical scenes, but can be
236			higher for scenes with unusually high or low reflectance. In this case,
237			the predistribution factor \fB\-apD\fR should be increased for scenes
238			with low reflectance, and reduced for those with high reflectance.
239			.PP
240			There are situations which may prevent certain (or any)
241			photon types from being generated, depending on the light source and material
242			configuration. This typically occurs when attempting to generate a caustic
243			photon map without specular materials present in the scene, or a volume
244			photon map without participating media. Ill-configured light sources may also
245			prevent indirect rays from reaching a surface, and thus no photons being
246			deposited. In these cases, \fImkpmap\fR will make a number of distribution
247			attempts before terminating with an error. This can be adjusted with the
248			\fB\-apM\fR option.
249
250			.SS Material Support
251			The \fIplasfunc\fR, \fImetfunc\fR, \fItransfunc\fR, \fIbrtdfunc\fR,
252			\fIplasdata\fR, \fImetdata\fR and \fItransdata\fR materials are not
253			supported by the photon mapping extension. Use the newer \fIbsdf\fR material
254			instead.
255			.PP
256			Virtual light sources (normally enabled with the \fImirror\fR material) are
257			disabled with the photon map, as the resulting caustics are already accounted
258			for.
259
260	rschregle	1.2	.SS Virtual Receiver Surfaces
261	greg	1.1	Since photons are surface bound, the density estimate is only asymptotically
262			correct when performed at points which lie on the scene geometry. The
263			irradiance is underestimated for arbitrarily placed points when photons are
264			collected from distant surfaces. \fIMkpmap\fR offers a workaround with a
265	rschregle	1.2	virtual receiver surface using the \fIantimatter\fR material; see the \fB-aps\fR
266	greg	1.1	and \fB-apS\fR options for details.
267
268			.SH EXAMPLES
269			The following command generates a global photon map \fIbonzo.gpm\fR and a
270			caustic photon map \fIbonzo.cpm\fR containing approximately 10000 and 100000
271			photons, respectively, with progress report every 5 seconds:
272			.IP
273			mkpmap \-apg bonzo.gpm 10k \-apc bonzo.cpm 100k -t 5 bonzo.oct
274			.PP
275			Generate a global photon map containing 80000 photons, then precompute the
276			diffuse irradiance for 1/4 of these with a bandwidth of 40 photons:
277			.IP
278			mkpmap \-app bonzo-precomp.gpm 80k 40 \-apP 0.25 bonzo.oct
279			.PP
280			Generate 1 million global photons by emitting them from external light
281			sources of type \fIsource\fR into a reference room via a fenestration
282			with modifier \fIglazingMat\fR:
283			.IP
284			mkpmap \-apg refRoom.gpm 1m \-apo glazingMat refRoom.oct
285			.PP
286			Generate a contribution photon map containing 200000 photons suitable for
287			obtaining light source contributions with \fIrcontrib(1)\fR:
288			.IP
289	rschregle	1.4	mkpmap \-apC bonzo-contrib.gpm 200k bonzo.oct
290	greg	1.1
291			.SH BUGS
292			The focus of a spotlight source, as defined by the length of its direction
293			vector, is ignored by the photon map; photons are unconditionally emitted
294			from the light source surface, which can lead to deviations from standard
295			RADIANCE.
296			.PP
297			Light sources simply absorb incoming photons.
298
299			.SH AUTHOR
300			Roland Schregle (roland.schregle@{hslu.ch,gmail.com})
301
302			.SH COPYRIGHT
303			(c) Fraunhofer Institute for Solar Energy Systems, Lucerne University of
304			Applied Sciences and Arts.
305
306			.SH ACKNOWLEDGEMENT
307			Development of the RADIANCE photon mapping extension was sponsored by the
308			German Research Foundation (DFG) and the Swiss National Science Foundation
309			(SNF).
310
311			.SH "SEE ALSO"
312			rpict(1), rtrace(1), rvu(1), rcontrib(1),
313			\fIThe RADIANCE Photon Map Manual\fR
314