| 1 |
greg |
1.1 |
.\" RCSid "$Id: mkpmap.1,v 1.16 2015/01/13 15:21:23 taschreg Exp taschreg $"
|
| 2 |
|
|
.TH MKPMAP 1 "$Date: 2015/01/13 15:21:23 $ $Revision: 1.16 $" RADIANCE
|
| 3 |
|
|
|
| 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 |
|
|
.IP "\fB\-apC \fIfile nphotons \fB(EXPERIMENTAL)\fR"
|
| 61 |
|
|
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 |
|
|
as a dummy (i.e. invisible) sensor surface. Photons will be deposited on
|
| 146 |
|
|
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 |
|
|
Read dummy sensor surface modifiers from the file \fImodfile\fR as a more
|
| 160 |
|
|
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 |
|
|
.IP "\fB\-t \fIinterval\fR"
|
| 211 |
|
|
Output a progress report every \fIinterval\fR seconds. This includes
|
| 212 |
|
|
statistics about the currently emitting light source (including number of
|
| 213 |
|
|
partitions), the total number of photons emitted, the number of each type
|
| 214 |
|
|
stored, the percentage of the completed pass (pre or main), and the elapsed
|
| 215 |
|
|
time.
|
| 216 |
|
|
|
| 217 |
|
|
.SH NOTES
|
| 218 |
|
|
|
| 219 |
|
|
.SS Parametrisation
|
| 220 |
|
|
\fIMkpmap\fR recognises multiplier suffixes (k = 1000, m = 1000000) to
|
| 221 |
|
|
facilitate the specification of \fInphotons\fR, both in upper and lower
|
| 222 |
|
|
case.
|
| 223 |
|
|
.PP
|
| 224 |
|
|
|
| 225 |
|
|
.SS Distribution Algorithm
|
| 226 |
|
|
The photon distribution algorithm estimates the number of required
|
| 227 |
|
|
photons to emit to arrive at the specified target count \fInphotons\fR
|
| 228 |
|
|
per photon map using a distribution prepass followed by a main pass.
|
| 229 |
|
|
As a result, \fImkpmap\fR generates the \fBapproximate\fR number of photons
|
| 230 |
|
|
specified, which can vary by up to 10% for typical scenes, but can be
|
| 231 |
|
|
higher for scenes with unusually high or low reflectance. In this case,
|
| 232 |
|
|
the predistribution factor \fB\-apD\fR should be increased for scenes
|
| 233 |
|
|
with low reflectance, and reduced for those with high reflectance.
|
| 234 |
|
|
.PP
|
| 235 |
|
|
There are situations which may prevent certain (or any)
|
| 236 |
|
|
photon types from being generated, depending on the light source and material
|
| 237 |
|
|
configuration. This typically occurs when attempting to generate a caustic
|
| 238 |
|
|
photon map without specular materials present in the scene, or a volume
|
| 239 |
|
|
photon map without participating media. Ill-configured light sources may also
|
| 240 |
|
|
prevent indirect rays from reaching a surface, and thus no photons being
|
| 241 |
|
|
deposited. In these cases, \fImkpmap\fR will make a number of distribution
|
| 242 |
|
|
attempts before terminating with an error. This can be adjusted with the
|
| 243 |
|
|
\fB\-apM\fR option.
|
| 244 |
|
|
|
| 245 |
|
|
.SS Material Support
|
| 246 |
|
|
The \fIplasfunc\fR, \fImetfunc\fR, \fItransfunc\fR, \fIbrtdfunc\fR,
|
| 247 |
|
|
\fIplasdata\fR, \fImetdata\fR and \fItransdata\fR materials are not
|
| 248 |
|
|
supported by the photon mapping extension. Use the newer \fIbsdf\fR material
|
| 249 |
|
|
instead.
|
| 250 |
|
|
.PP
|
| 251 |
|
|
Virtual light sources (normally enabled with the \fImirror\fR material) are
|
| 252 |
|
|
disabled with the photon map, as the resulting caustics are already accounted
|
| 253 |
|
|
for.
|
| 254 |
|
|
|
| 255 |
|
|
.SS Dummy Sensor Surfaces
|
| 256 |
|
|
Since photons are surface bound, the density estimate is only asymptotically
|
| 257 |
|
|
correct when performed at points which lie on the scene geometry. The
|
| 258 |
|
|
irradiance is underestimated for arbitrarily placed points when photons are
|
| 259 |
|
|
collected from distant surfaces. \fIMkpmap\fR offers a workaround with a
|
| 260 |
|
|
dummy sensor surface using the \fIantimatter\fR material; see the \fB-aps\fR
|
| 261 |
|
|
and \fB-apS\fR options for details.
|
| 262 |
|
|
|
| 263 |
|
|
.SH EXAMPLES
|
| 264 |
|
|
The following command generates a global photon map \fIbonzo.gpm\fR and a
|
| 265 |
|
|
caustic photon map \fIbonzo.cpm\fR containing approximately 10000 and 100000
|
| 266 |
|
|
photons, respectively, with progress report every 5 seconds:
|
| 267 |
|
|
.IP
|
| 268 |
|
|
mkpmap \-apg bonzo.gpm 10k \-apc bonzo.cpm 100k -t 5 bonzo.oct
|
| 269 |
|
|
.PP
|
| 270 |
|
|
Generate a global photon map containing 80000 photons, then precompute the
|
| 271 |
|
|
diffuse irradiance for 1/4 of these with a bandwidth of 40 photons:
|
| 272 |
|
|
.IP
|
| 273 |
|
|
mkpmap \-app bonzo-precomp.gpm 80k 40 \-apP 0.25 bonzo.oct
|
| 274 |
|
|
.PP
|
| 275 |
|
|
Generate 1 million global photons by emitting them from external light
|
| 276 |
|
|
sources of type \fIsource\fR into a reference room via a fenestration
|
| 277 |
|
|
with modifier \fIglazingMat\fR:
|
| 278 |
|
|
.IP
|
| 279 |
|
|
mkpmap \-apg refRoom.gpm 1m \-apo glazingMat refRoom.oct
|
| 280 |
|
|
.PP
|
| 281 |
|
|
Generate a contribution photon map containing 200000 photons suitable for
|
| 282 |
|
|
obtaining light source contributions with \fIrcontrib(1)\fR:
|
| 283 |
|
|
.IP
|
| 284 |
|
|
mkpmap \-apl bonzo-contrib.gpm 200k bonzo.oct
|
| 285 |
|
|
|
| 286 |
|
|
.SH BUGS
|
| 287 |
|
|
The focus of a spotlight source, as defined by the length of its direction
|
| 288 |
|
|
vector, is ignored by the photon map; photons are unconditionally emitted
|
| 289 |
|
|
from the light source surface, which can lead to deviations from standard
|
| 290 |
|
|
RADIANCE.
|
| 291 |
|
|
.PP
|
| 292 |
|
|
Light sources simply absorb incoming photons.
|
| 293 |
|
|
|
| 294 |
|
|
.SH AUTHOR
|
| 295 |
|
|
Roland Schregle (roland.schregle@{hslu.ch,gmail.com})
|
| 296 |
|
|
|
| 297 |
|
|
.SH COPYRIGHT
|
| 298 |
|
|
(c) Fraunhofer Institute for Solar Energy Systems, Lucerne University of
|
| 299 |
|
|
Applied Sciences and Arts.
|
| 300 |
|
|
|
| 301 |
|
|
.SH ACKNOWLEDGEMENT
|
| 302 |
|
|
Development of the RADIANCE photon mapping extension was sponsored by the
|
| 303 |
|
|
German Research Foundation (DFG) and the Swiss National Science Foundation
|
| 304 |
|
|
(SNF).
|
| 305 |
|
|
|
| 306 |
|
|
.SH "SEE ALSO"
|
| 307 |
|
|
rpict(1), rtrace(1), rvu(1), rcontrib(1),
|
| 308 |
|
|
\fIThe RADIANCE Photon Map Manual\fR
|
| 309 |
|
|
|
