man/man1/mkpmap.1

.\" RCSid "$Id: mkpmap.1,v 1.9 2018/02/06 16:02:22 rschregle Exp $"
.TH MKPMAP 1 "$Date: 2018/02/06 16:02:22 $ $Revision: 1.9 $" 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. When used
with \fIrtrace(1)\fR or \fIrpict(1)\fR, contribution photon maps behave as
regular global photon maps and yield cumulative contributions from all light
sources.
.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\-api \fIxmin ymin zmin xmax ymax zmax\fR"
Define a region of interest within which to store photons exclusively;
photons will only be stored within the volume bounded by the given minimum
and maximum coordinates.  Multiple instances of this option may be specified
with cumulative effect to define compound regions of interest.  This is
useful for constraining photons to only the relevant regions of a scene, but
may increase the photon distribution time.
.IP
\fBWARNING: this is an optimisation option for advanced users (an elite
group collectively known as \fIZe Ekspertz\fB) and may yield biased results. 
Use with caution!\fR

.IP "\fB\-apm \fImaxbounce\fR"
Synonymous with \fB\-lr\fR for backwards compatibility. May be removed in
future releases.

.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\-apP \fIprecomp\fR"
Fraction of global photons to precompute in the range ]0,1] when using the
\fB\-app\fR option.

.IP "\fB\-apr \fIseed\fR"
Seed for the random number generator. This is useful for generating 
different photon distributions for the same octree and photon map size,
notably in progressive applications.

.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\-ae \fImod\fR"
Add \fImod\fR to the ambient exclude list, so that it will be ignored by the
photon map.  Objects having \fImod\fR as their modifier will not have
photons deposited on them.  Multiple modifiers may be given, each as separate
instances of this option.
.IP
\fBWARNING: this is an optimisation option for advanced users and may yield
biased results. It may also significantly increase photon distribution
times. Use with caution!\fR

.IP "\fB\-aE \fIfile\fR"
Same as \fI-ae\fR, except modifiers to be exluded are read from \fIfile\fR,
separated by whitespace.  The RAYPATH environment variable determines which
directories are searched for this file.

.IP "\fB\-ai \fImod\fR"
Add \fImod\fR to the ambient include list, so that it will contribute to the
photon map. Only objects having \fImod\fR as their modifier will have
photons deposited on them. Multiple modifiers may be given, each as separate
instances of this option. Note that the ambient include and exclude options
are mutually exclusive. 
.IP
\fBWARNING: this is an optimisation option for advanced users and may yield
biased results. It may also significantly increase photon distribution
times. Use with caution!\fR

.IP "\fB\-aI \fIfile\fR"
Same as \fI-ai\fR, except modifiers to be included are read from \fIfile\fR,
separated by whitespace. The RAYPATH environment variable determines which
directories are searched for this file.

.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\-ld \fImaxdist\fR"
Limit cumulative distance travelled by a photon along its path to
\fImaxdist\fR.  Photon hits within this distance will be stored, and the
photon is terminated once its path length exceeds this limit.  This is
useful for setting radial regions of interest around emitting/reflecting
geometry, but may increase the photon distribution time.  
.IP
\fBWARNING: this is an optimisation option for advanced users (an elite
group collectively known as \fIZe Ekspertz\fB) and may yield biased results. 
Use with caution!\fR

.IP "\fB\-lr \fImaxbounce\fR"
Limit number of bounces (scattering events) along a photon path to
\fImaxbounce\fR 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
option imposes a hard limit to avoid an infinite loop.
.IP
\fBWARNING: this is an optimisation option for advanced users (an elite
group collectively known as \fIZe Ekspertz\fB) and may yield biased results. 
Use with caution!\fR

.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, \fIDevelopment and Integration of the RADIANCE Photon Map
Extension: Technical Report\fR
Revision:	1.10
Committed:	Tue Mar 20 19:53:09 2018 UTC (7 years, 7 months ago) by rschregle
Branch:	MAIN
CVS Tags:	rad5R2
Changes since 1.9:	+34 -3 lines
Log Message:	Documented new -ae/-ai exclude/include options for mkpmap
#	User	Rev	Content
1	rschregle	1.10	.\" RCSid "$Id: mkpmap.1,v 1.9 2018/02/06 16:02:22 rschregle Exp $"
2			.TH MKPMAP 1 "$Date: 2018/02/06 16:02:22 $ $Revision: 1.9 $" 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	rschregle	1.8	used by \fIrcontrib(1)\fR to compute light source contributions. When used
64			with \fIrtrace(1)\fR or \fIrpict(1)\fR, contribution photon maps behave as
65			regular global photon maps and yield cumulative contributions from all light
66			sources.
67	greg	1.1	.IP
68			With this option, \fImkpmap\fR uses a modified photon distribution
69			algorithm that ensures all light sources contribute approximately the
70			same number of photons. Each photon indexes a primary hitpoint, incident
71			direction, and emitting light source which can be used to bin
72			contributions per light source and direction.
73			.IP
74			\fIMkpmap\fR cannot generate a contribution photon map in combination with
75			others in a single run, as it uses a different distribution algorithm. Other
76			photon maps specified on the command line will be ignored.
77
78			.IP "\fB\-app \fIfile nphotons bwidth\fR"
79			Generate a precomputed global photon map containing a fraction of
80			\fInphotons\fR photons (specified with the \fB\-apP\fR option, see
81			below), and output to file \fIfile\fR. This is a special case of the
82			global photon map where the irradiance is evaluated for a fraction of
83			the photon positions using \fIbwidth\fR nearest photons, and stored as
84			photon flux; the remaining photons are discarded as their contributions
85			have been accounted for.
86			.IP
87	rschregle	1.8	This obviates the explicit irradiance evaluation by \fIrpict(1),
88			rtrace(1)\fR and \fIrvu(1)\fR, thus providing a speedup at the expense of
89			accuracy. The resulting error is tolerable if the indirect illumination has
90			a low gradient, as is usually the case with diffuse illumination.
91	greg	1.1
92			.IP "\fB\-apD \fIpredistrib\fR"
93			Photon predistribution factor; this is the fraction of \fInphotons\fR
94			which are emitted in a distribution prepass in order to estimate the
95			remaining number of photons to emit in the main pass to approximately
96			yield a photon map of size \fInphotons\fR.
97			.IP
98	rschregle	1.8	Setting this too high may yield more than \fInphotons\fR in the initial pass
99			with highly reflective geometry. Note that this value may exceed 1, which
100			may be useful if the resulting photon map size greatly deviates from
101	greg	1.1	\fInphotons\fR with a very low average reflectance.
102
103	rschregle	1.8	.IP "\fB\-api \fIxmin ymin zmin xmax ymax zmax\fR"
104	rschregle	1.10	Define a region of interest within which to store photons exclusively;
105	rschregle	1.8	photons will only be stored within the volume bounded by the given minimum
106			and maximum coordinates. Multiple instances of this option may be specified
107			with cumulative effect to define compound regions of interest. This is
108			useful for constraining photons to only the relevant regions of a scene, but
109			may increase the photon distribution time.
110			.IP
111			\fBWARNING: this is an optimisation option for advanced users (an elite
112			group collectively known as \fIZe Ekspertz\fB) and may yield biased results.
113			Use with caution!\fR
114	greg	1.1
115			.IP "\fB\-apm \fImaxbounce\fR"
116	rschregle	1.8	Synonymous with \fB\-lr\fR for backwards compatibility. May be removed in
117			future releases.
118	greg	1.1
119			.IP "\fB\-apM \fImaxprepass\fR"
120			Maximum number of iterations of the distribution prepass before terminating
121			if some photon maps are still empty. This option is rarely needed as a
122			an aborted prepass indicates an anomaly in the geometry or an
123			incompatibility with the specified photon map types (see \fBNOTES\fR below).
124
125			.IP "\fB\-apo \fImod\fR"
126			Specifies a modifier \fImod\fR to act as a \fIphoton port\fR. All
127			objects using this modifier will emit photons directly in lieu of any
128			light sources defined with the \fIsource\fR material. This greatly
129			accelerates photon distribution in scenes where photons have to enter a
130			space which separates them from the emitting light source via an
131			opening, or port.
132			.IP
133	rschregle	1.8	A typical application is daylight simulation, where a fenestration acts as
134			port to admit photons into an interior after emission from an external light
135			source. Multiple instances of this option may be specified.
136	greg	1.1	.IP
137			Note that port objects must be defined with their surface normals
138			pointing \fIinside\fR as per \fImkillum\fR convention.
139
140			.IP "\fB\-apO \fImodfile\fR"
141			Read photon port modifiers from the file \fImodfile\fR as a more convenient
142			alternative to multiple instances of \fB\-apo\fR.
143
144	rschregle	1.8	.IP "\fB\-apP \fIprecomp\fR"
145			Fraction of global photons to precompute in the range ]0,1] when using the
146			\fB\-app\fR option.
147
148	greg	1.1	.IP "\fB\-apr \fIseed\fR"
149	rschregle	1.9	Seed for the random number generator. This is useful for generating
150			different photon distributions for the same octree and photon map size,
151			notably in progressive applications.
152	greg	1.1
153			.IP "\fB\-aps \fImod\fR"
154			Specifies a modifier \fImod\fR defined as \fIantimatter\fR material to act
155	rschregle	1.2	as a virtual (i.e. invisible) receiver surface. Photons will be deposited on
156	greg	1.1	all surfaces using this modifier, just like regular materials, but will then
157			be transferred through the surface without undergoing scattering; the
158			surface therefore does not affect the light transport and simply acts as an
159			invisible photon receiver. This is useful when photon irradiance is to be
160			evaluated at points which do not lie on regular geometry, e.g. at workplane
161	greg	1.6	height with \fIrtrace\fR's \fB-I\fR option. Without this workaround,
162	greg	1.1	photons would be collected from parallel but distant planes, leading to
163			underestimation. Note that photons are only deposited when incident from
164			the front side of the sensor surface, i.e. when entering the
165			\fIantimatter\fR, thus the surface normal is relevant. \fIMkpmap\fR reports
166			an error if the specified modifier is not an \fIantimatter\fR material.
167
168			.IP "\fB\-apS \fImodfile\fR"
169	rschregle	1.2	Read virtual receiver surface modifiers from the file \fImodfile\fR as a more
170	greg	1.1	convenient alternative to multiple instances of \fB\-aps\fR.
171
172	rschregle	1.10	.IP "\fB\-ae \fImod\fR"
173			Add \fImod\fR to the ambient exclude list, so that it will be ignored by the
174			photon map. Objects having \fImod\fR as their modifier will not have
175			photons deposited on them. Multiple modifiers may be given, each as separate
176			instances of this option.
177			.IP
178			\fBWARNING: this is an optimisation option for advanced users and may yield
179			biased results. It may also significantly increase photon distribution
180			times. Use with caution!\fR
181
182			.IP "\fB\-aE \fIfile\fR"
183			Same as \fI-ae\fR, except modifiers to be exluded are read from \fIfile\fR,
184			separated by whitespace. The RAYPATH environment variable determines which
185			directories are searched for this file.
186
187			.IP "\fB\-ai \fImod\fR"
188			Add \fImod\fR to the ambient include list, so that it will contribute to the
189			photon map. Only objects having \fImod\fR as their modifier will have
190			photons deposited on them. Multiple modifiers may be given, each as separate
191			instances of this option. Note that the ambient include and exclude options
192			are mutually exclusive.
193			.IP
194			\fBWARNING: this is an optimisation option for advanced users and may yield
195			biased results. It may also significantly increase photon distribution
196			times. Use with caution!\fR
197
198			.IP "\fB\-aI \fIfile\fR"
199			Same as \fI-ai\fR, except modifiers to be included are read from \fIfile\fR,
200			separated by whitespace. The RAYPATH environment variable determines which
201			directories are searched for this file.
202
203	greg	1.1	.IP "\fB\-bv\fR[\fB+\fR\|\fB-\fR]"
204			Toggles backface visibility; enabling this causes photons to be stored and
205			possibly scattered if they strike the back of a surface, otherwise they
206			are unconditionally absorbed and discarded.
207
208			.IP "\fB\-dp \fIsampleres\fR"
209			Resolution for sampling the spatial emission distribution of a modified
210			light source (e.g. via \fIbrightfunc\fR), in samples per steradian. This
211			is required for numerically integrating the flux emitted by the light
212			source and for constructing a probability density function for photon
213			emission. The accuracy of photon emission from modified sources
214			therefore depends on this parameter. This parameter may need increasing
215			with complex emission distributions in combination with caustics.
216
217			.IP "\fB\-ds \fIpartsize\fR"
218			Light source partition size ratio; a light source object is spatially
219			partitioned to distribute the photon emission over its surface. This
220			parameter specifies the ratio of the size (per dimension) of each
221			partition to the scene cube, and may need increasing for modified light
222			sources (e.g. via \fIbrightfunc\fR) with high spatial variation.
223
224			.IP "\fB\-e \fIfile\fR"
225			Redirect diagnostics and progress reports to \fIfile\fR instead of the
226			console.
227
228			.IP "\fB\-fo\fR[\fB+\fR\|\fB-\fR]"
229			Toggles overwriting of output files. By default, \fImkpmap\fR will not
230			overwrite an already existing photon map file. This is to prevent
231			inadvertently destroying the results of potentially lengthy photon
232			mapping runs.
233
234	rschregle	1.8	.IP "\fB\-ld \fImaxdist\fR"
235			Limit cumulative distance travelled by a photon along its path to
236			\fImaxdist\fR. Photon hits within this distance will be stored, and the
237			photon is terminated once its path length exceeds this limit. This is
238			useful for setting radial regions of interest around emitting/reflecting
239			geometry, but may increase the photon distribution time.
240			.IP
241			\fBWARNING: this is an optimisation option for advanced users (an elite
242			group collectively known as \fIZe Ekspertz\fB) and may yield biased results.
243			Use with caution!\fR
244
245			.IP "\fB\-lr \fImaxbounce\fR"
246			Limit number of bounces (scattering events) along a photon path to
247			\fImaxbounce\fR before being considered "runaway" and terminated. Photons
248			paths are normally terminated via \fIRussian Roulette\fR, depending on their
249			albedo. With unrealistically high albedos, this is not guaranteed, and this
250			option imposes a hard limit to avoid an infinite loop.
251			.IP
252			\fBWARNING: this is an optimisation option for advanced users (an elite
253			group collectively known as \fIZe Ekspertz\fB) and may yield biased results.
254			Use with caution!\fR
255
256	greg	1.1	.IP "\fB\-ma \fIralb galb balb\fR"
257			Set the global scattering albedo for participating media in conjunction
258			with the \fB\-apv\fR option. See \fIrpict(1)\fR for details.
259
260			.IP "\fB\-me \fIrext gext bext\fR"
261			Set the global extinction coefficient for participating media in conjunction
262			with the \fB\-apv\fR option. See \fIrpict(1)\fR for details.
263
264			.IP "\fB\-mg \fIgecc\fR"
265			Set the global scattering eccentricity for participating media in conjunction
266			with the \fB\-apv\fR option. See \fIrpict(1)\fR for details.
267
268	rschregle	1.3	.IP "\fB\-n \fInproc\fR"
269			Use \fInproc\fR processes for parallel photon distribution. There is no
270			benefit in specifying more than the number of physical CPU cores available.
271	rschregle	1.5	This option is currently not available on Windows.
272	rschregle	1.3
273	greg	1.1	.IP "\fB\-t \fIinterval\fR"
274			Output a progress report every \fIinterval\fR seconds. This includes
275			statistics about the currently emitting light source (including number of
276			partitions), the total number of photons emitted, the number of each type
277			stored, the percentage of the completed pass (pre or main), and the elapsed
278			time.
279
280			.SH NOTES
281
282			.SS Parametrisation
283			\fIMkpmap\fR recognises multiplier suffixes (k = 1000, m = 1000000) to
284			facilitate the specification of \fInphotons\fR, both in upper and lower
285			case.
286			.PP
287
288			.SS Distribution Algorithm
289			The photon distribution algorithm estimates the number of required
290			photons to emit to arrive at the specified target count \fInphotons\fR
291			per photon map using a distribution prepass followed by a main pass.
292			As a result, \fImkpmap\fR generates the \fBapproximate\fR number of photons
293			specified, which can vary by up to 10% for typical scenes, but can be
294			higher for scenes with unusually high or low reflectance. In this case,
295			the predistribution factor \fB\-apD\fR should be increased for scenes
296			with low reflectance, and reduced for those with high reflectance.
297			.PP
298			There are situations which may prevent certain (or any)
299			photon types from being generated, depending on the light source and material
300			configuration. This typically occurs when attempting to generate a caustic
301			photon map without specular materials present in the scene, or a volume
302			photon map without participating media. Ill-configured light sources may also
303			prevent indirect rays from reaching a surface, and thus no photons being
304			deposited. In these cases, \fImkpmap\fR will make a number of distribution
305			attempts before terminating with an error. This can be adjusted with the
306			\fB\-apM\fR option.
307
308			.SS Material Support
309			The \fIplasfunc\fR, \fImetfunc\fR, \fItransfunc\fR, \fIbrtdfunc\fR,
310			\fIplasdata\fR, \fImetdata\fR and \fItransdata\fR materials are not
311			supported by the photon mapping extension. Use the newer \fIbsdf\fR material
312			instead.
313			.PP
314			Virtual light sources (normally enabled with the \fImirror\fR material) are
315			disabled with the photon map, as the resulting caustics are already accounted
316			for.
317
318	rschregle	1.2	.SS Virtual Receiver Surfaces
319	greg	1.1	Since photons are surface bound, the density estimate is only asymptotically
320			correct when performed at points which lie on the scene geometry. The
321			irradiance is underestimated for arbitrarily placed points when photons are
322			collected from distant surfaces. \fIMkpmap\fR offers a workaround with a
323	rschregle	1.2	virtual receiver surface using the \fIantimatter\fR material; see the \fB-aps\fR
324	greg	1.1	and \fB-apS\fR options for details.
325
326			.SH EXAMPLES
327			The following command generates a global photon map \fIbonzo.gpm\fR and a
328			caustic photon map \fIbonzo.cpm\fR containing approximately 10000 and 100000
329			photons, respectively, with progress report every 5 seconds:
330			.IP
331			mkpmap \-apg bonzo.gpm 10k \-apc bonzo.cpm 100k -t 5 bonzo.oct
332			.PP
333			Generate a global photon map containing 80000 photons, then precompute the
334			diffuse irradiance for 1/4 of these with a bandwidth of 40 photons:
335			.IP
336			mkpmap \-app bonzo-precomp.gpm 80k 40 \-apP 0.25 bonzo.oct
337			.PP
338			Generate 1 million global photons by emitting them from external light
339			sources of type \fIsource\fR into a reference room via a fenestration
340			with modifier \fIglazingMat\fR:
341			.IP
342			mkpmap \-apg refRoom.gpm 1m \-apo glazingMat refRoom.oct
343			.PP
344			Generate a contribution photon map containing 200000 photons suitable for
345			obtaining light source contributions with \fIrcontrib(1)\fR:
346			.IP
347	rschregle	1.4	mkpmap \-apC bonzo-contrib.gpm 200k bonzo.oct
348	greg	1.1
349			.SH BUGS
350			The focus of a spotlight source, as defined by the length of its direction
351			vector, is ignored by the photon map; photons are unconditionally emitted
352			from the light source surface, which can lead to deviations from standard
353			RADIANCE.
354			.PP
355			Light sources simply absorb incoming photons.
356
357			.SH AUTHOR
358			Roland Schregle (roland.schregle@{hslu.ch,gmail.com})
359
360			.SH COPYRIGHT
361			(c) Fraunhofer Institute for Solar Energy Systems, Lucerne University of
362			Applied Sciences and Arts.
363
364			.SH ACKNOWLEDGEMENT
365			Development of the RADIANCE photon mapping extension was sponsored by the
366			German Research Foundation (DFG) and the Swiss National Science Foundation
367			(SNF).
368
369			.SH "SEE ALSO"
370	rschregle	1.8	rpict(1), rtrace(1), rvu(1), rcontrib(1), \fIThe RADIANCE Photon Map
371			Manual\fR, \fIDevelopment and Integration of the RADIANCE Photon Map
372			Extension: Technical Report\fR