Page MenuHomec4science
Files F97152190

mkpmap.1
No OneTemporary
Actions

File Metadata

Created
Thu, Jan 2, 23:38

mkpmap.1
View Options

.\" RCSid "$Id: mkpmap.1,v 1.16 2021/04/14 11:28:36 rschregle Exp $"
.TH MKPMAP 1 "$Date: 2021/04/14 11:28:36 $ $Revision: 1.16 $" 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|\fB\-apt\fR|\fB\-apT\fR|\fB\-apV\fR] \fIfile nphotons\fR
.RS
[\fIbwidth\fR [\fIvelocity\fR]] ... [options] \fIoctree\fR
.RE
.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\-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\-apC \fIfile nphotons bwidth comp\fR [BUILD OPTION]"
Generate a precomputed contribution photon map containing a fraction of
\fInphotons\fR photons (specified with the \fB\-apP\fR option, see
below), and output to file \fIfile\fR. Only light sources may contribute,
and are specified via their modifier(s) with a subsequent \fB-m\fR option
(see below). Each precomputed photon accumulates contributions from the
\fIbwidth\fR nearest photons into bins (specified with the \fB-bn\fR option,
see below). If \fIbwidth\fR is less than the number of bins, a warning is
issued, since some bins will be zero.
.IP
Ideally, \fIbwidth\fR should be a multiple of the number of bins. If too
many bins (default 50%) are still zero, a warning about an excessive empty
bin ratio is issued, indicating potentially biased contributions, and that
the number of photons and/or the bandwidth should be increased further.
However, if very small contributions are indeed expected in some bins,
this warning should be taken with a grain of salt.
.IP
Precomputed contribution photon maps can be used by \fIrcontrib(1)\fR to
very efficiently evaluate binned light source contributions (e.g. from sky
patches) at multiple points by looking up the single nearest precomputed
photon. In contribution mode, \fImkpmap\fR is therefore designed to behave
similarly to \fIrcontrib\fR. To ensure the latter obtains binning parameters consistent with those used in the precomputation, \fImkpmap\fR outputs an
option file \fIfile.opt\fR which must be passed to \fIrcontrib\fR
via its \fB@\fR option.
.IP
The \fIcomp\fR parameter specifies a compression ratio for the binned
contributions in the range [0, 1], where 1 corresponds to maximum compression,
and 0 implies no compression at all. Compression is recommended as it gives the
user control over the size of the binned contributions, which are saved in a
separate file for each modifier; depending on the number of photons and bins,
these files can become very large. Note however that \fImkpmap\fR uses a
\fBlossy\fR wavelet compression, which can introduce artefacts at
higher compression ratios if the lighting is complex (e.g. exhibits high
gradients). In typical scenarios, a compression ratio of 0.7-0.8 yields an
acceptable compromise between accuracy and space savings.
.IP
With this option, \fImkpmap\fR uses a modified photon distribution
algorithm that increases the odds that all selected light sources contribute
approximately the same number of photons. Because of this, \fImkpmap\fR cannot generate a contribution photon map in combination with others in a single run,
and other photon maps specified on the command line will be ignored.
.IP
\fBNOTE: This option requires out-of-core storage, which is currently not
enabled in the default build, nor is it supported on Windows. On platforms
that do support it, precomputed contribution photon mapping can be enabled at
compile time with -DPMAP_OOC -DPMAP_CONTRIB.\fR
.IP "\fB\-apt \fIfile nphotons velocity\fR [BUILD OPTION]"
Generate a transient photon map with the given propagation velocity.
This is a variant of the global photon map with the distinction that
photons can be located in space and time. When a transient photon interacts
with a surface, its time of flight, subject to its velocity, is recorded along with its position (technically, this is internally expressed as the photon path length to simplify the spatio-temporal distance metric used for photon
lookups).
The velocity is expressed in units of 1/sec in relation to the
scale of the simulation geometry. For reference, the speed of light in a
vacuum is 299792458 metres/sec (or 3e8 if you're not Stephen Hawking).
The velocity is currently treated as constant in all media, and is
consequently not adapted for the index of refraction in \fIdielectric\fR
and \fIinterface\fR materials. Relativistic effects are also not accounted
for, since Stephen Hawking doesn't use RADIANCE anyway.
Transient photon maps are particularly useful to study the propagation of
light in extreme slow motion. See also \fIrpict(1)\fR for details on how
transient photons can be rendered at specific points in time.
\fBNOTE: This option is experimental and requires in-core (kd-tree) storage,
which is enabled in the default build; it is currently not supported with
optional out-of-core storage (-DPMAP_OOC).
.IP "\fB\-apT \fIfile nphotons velocity\fR [BUILD OPTION]"
Generate a transient lightflow photon map. This photon map combines the
attributes of lightflow and transient photons, i.e. transient rendering at
arbitrary locations in a volume (requiring a participating medium). See
options \fB\-apt\fR and \fB\-apV\fR for details.
\fBNOTE: This option is experimental and requires in-core (kd-tree) storage
and enabled photon flow. This must be enabled at compile time with
-DPMAP_PHOTONFLOW. It is currently not supported with optional out-of-core
storage (-DPMAP_OOC).
.IP "\fB\-apV \fIfile nphotons\fR [BUILD OPTION]"
Generate a "lightflow" photon map containing \fInphotons\fR photons. This is
a specialised variant of the volume photon map (see the \fB-apv\fR option
above) designed to evaluate cubic illuminance at arbitrary positions
in space. In addition, the photon propagation in space can be visualised
with the output of \fIpmapdump(1)\fR. Note however, that illuminance from
lightflow is generally less accurate than using a global photon map with a dedicated virtual sensor plane in conjunction with the \fB\-apS\fR option.
.IP
As with regular volume photon mapping, lightflow photons require
a participating medium in which they are deposited. Unlike regular volume
photon mapping however, lightflow photons do not interact with the
participating medium, and are neither scattered nor absorbed; consequently,
the photon trajectories -- and therefore the light transport as a whole -- is
unaffected by the participating medium.
.IP
Lightflow photon mapping implies an albedo and eccentricity of 1
(corresponding to the options \fB-ma\fR and \fB-mg\fR, respectively)
in participating media. The coefficient of extinction, which can be defined
locally for a \fImist\fR primitive, or globally via the \fB-me\fR option, is a
free parameter that determines the density of the deposited photons. It is
generally desirable to keep this parameter low to minimise clustering, at the
expense of slower photon distribution. Setting this parameter too high can
result in excessive linear clustering of photons along their trajectories,
leading to a "ray effect" and local bias in the evaluated illuminance (this is
readily apparent on visual inspection with \fBpmapdump(1)\fR). This parameter
also depends on the scale of the space in which the photons are deposited.
.IP
An undesirable side effect of lightflow photon mapping is that photon
distribution may overflow, particularly in dense media with high extinction
values. In this case, the predistribution factor (see option \fB-apD\fR)
should be reduced accordingly. Future releases of \fImkpmap\fR may adjust
this parameter automatically.
.IP
A lightflow photon map can be visualised with \fIpmapdump(1)\fR or evaluated
as cubic illuminance with \fIrtrace(1)\fR.
.IP
\fBNOTE: This option is experimental and not enabled in the default build.
It must be enabled at compile time with -DPMAP_PHOTONFLOW.\fR
.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\-aph \fImod\fR"
Defines all polygons using the material modifier \fImod\fR as part of
a polyhedral region of interest (ROI). Photons will only be stored
within the volume enclosed by these surfaces. Multiple instances of
this option may be specified with cumulative effect to aggregate
surfaces into a polyhedron. An error is issued if the identified geometry
is not polygonal.
This option is useful to constrain photons to only lie in relevant
regions of a scene, but may increase the photon distribution time.
.IP
\fBNOTE: No check is made to ensure the polyhedron is closed and not
degenerated (particularly due to overlapping polygons) -- this is the
user's responsibility.\fR
.IP
\fBWARNING: this option is an optimisation for advanced users which may
yield biased results outside the defined ROI. Use with caution!\fR
.IP "\fB\-apH \fImodfile\fR"
Reads modifiers comprising polyhedral regions of interest (ROIs) from
\fImodfile\fR, separated by whitespace. This is convenient to group
modifiers per ROI if the geometry is complex and uses multiple materials.
See option \fB\-aph\fR above for details and caveats on using polyhedral ROIs.
.IP "\fB\-api \fImin_x min_y min_z max_x max_y max_z\fR"
Defines a rectangular region of interest (ROI) 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 ROIs.
This option is useful to constrain photons to only lie in relevant
regions of a scene, but may increase the photon distribution time.
.IP
\fBWARNING: this option is an optimisation for advanced users which may
yield biased results outside the defined ROI. Use with caution!\fR
.IP "\fB-apI \fIpos_x pos_y pos_z rad\fR"
Similar to \fB\-api\fR, but with a spherical region of interest of given
radius, centred at the given coordinates.
.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
an aborted prepass may indicate an anomaly in the geometry or an
incompatibility with the specified photon map types (see \fBNOTES\fR below).
.IP "\fB\-apo\fR[\fB+\fR|\fB-\fR|\fB0\fR] \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
aperture (e.g. fenestration, skylight) acting as a port.
.IP
In a typical daylight simulation scenario, a fenestration acts as a port to
admit photons into an interior after emission from sky and solar sources.
Multiple instances of this option may be specified.
.IP
By default, ports are oriented to emit from their front side, as defined
by their surface normal. This can be overridden by
specifying a trivalent suffix as follows:
.RS
.IP \fB+\fR:
Forward emission; this is equivalent to the abovementioned default behaviour.
.IP \fB-\fR:
Backward emission; the port is reversed and photons are emitted from the
back side.
.IP \fB0\fR:
Bidirectional emission; photons are emitted from both sides of the port.
.RE
.IP
Some typical situations that call for a reversed photon port include, for
example:
.RS
.IP (a)
Using fenestrations as ports that were (for whatever
reason) defined with outward facing normals,
.IP (b)
Using a \fBmist\fR
primitive as a port, since this requires outward facing normals in order to
register the photons as having entered the volume,
.IP (c)
Reorienting a port associated with a \fBbsdf\fR modifier, since inverting
its normal would also reorient the BSDF and alter its behaviour.
.RE
.IP
Other oddball scenarios are conceivable. If in doubt, specify a
bidirectional port orientation for a slight performance penalty,
as photon emission is attempted from both sides. For well-defined
port geometry with inward-facing normals, just use the default;
doan' mess with da normalz.
.IP
Photon port geometry is discretised according to the
\fB\-dp\fR and \fB\-ds\fR options. These parameters aid in resolving
spatially and directionally varying illuminance received by the port
from distant light sources, e.g due to partial occlusion
or when using climate-based sky models.
.IP "\fB\-apO\fR[\fB+\fR|\fB-\fR|\fB0\fR] \fImodfile\fR"
Read photon port modifiers from the file \fImodfile\fR as a more convenient
alternative to multiple instances of \fB\-apo\fR. The specified orientation
is applied to all modifiers in the file.
.IP "\fB\-apP \fIprecomp\fR"
Fraction of global or contribution photons to precompute, in the range ]0,1],
when using the \fB\-app\fR resp. \fB-apC\fR options.
.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\fR[\fB+\fR|\fB-\fR|\fB0\fR] \fImod\fR"
Specifies a modifier \fImod\fR defined as \fIantimatter\fR material to act
as a virtual (i.e. invisible) sensor 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. Note that \fImkpmap\fR reports an error if the
specified modifier is not an \fIantimatter\fR material.
.IP
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.
.IP
By default, virtual sensors are oriented to deposit photons incident
from their front side, as defined by their surface normal.
This can be overridden by specifying a trivalent suffix as follows:
.RS
.IP \fB+\fR:
Forward orientation; this is equivalent to the abovementioned default
behaviour.
.IP \fB-\fR:
Backward orientation; the sensor is reversed and only receives photons
incident from the back.
.IP \fB0\fR:
Bidirectional orientation; the sensor receives photons from both sides.
.RE
.IP "\fB\-apS\fR[\fB+\fR|\fB-\fR|\fB0\fR] \fImodfile\fR"
Read virtual sensor surface modifiers from the file \fImodfile\fR as a more
convenient alternative to multiple instances of \fB\-aps\fR. The specified
orientation is applied to all modifiers in the file.
.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\-am \fImaxdist\fR"
Maximum search radius for precomputed photon lookups in conjuction with the
\fB\-app\fR or \fB\-apC\fR options. See the discussion of \fB\-am\fR in
\fIrcontrib(1)\fR for details.
.IP "\fB\-bn \fInbins\fR"
Set the number of bins for precomputed contribution photons in conjunction
with the \fB\-apC\fR option to\fInbins\fR. Analogous to \fIrcontrib(1)\fR,
the bins discretise the hemisphere of incident directions of contributions
in the vicinity of each precomputed photon. Each bin covers a range of
incident directions using the Shirley-Chiu disk-to-square mapping, whose
orientation can be defined with the \fB\-e\fR option.
This mapping is hardwired for precomputed contribution photons, and cannot be
changed. Effectively, \fInbins\fR specifies the mapping resolution.
.IP
The number of bins \fInbins\fR must be an integer squared, otherwise it will be
automatically rounded to the nearest such value.
If \fB\-bn\fR isn't specified, the default number of bins is 1, in which case
binning is disabled, and each photon carries the integrated contributions from
all directions. The binning is effective for the next contribution modifier
specified with the \fB\-m\fR option (q.v.).
.IP
See also the discussion on binning in \fIrcontrib(1)\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"
Angular resolution for sampling the spatial emission distribution of a
modified light source or photon port (e.g. via \fIbrightfunc\fR), in samples
per steradian.
This is required to numerically integrate the flux emitted by the light
source and construct a probability density function for photon emission.
The accuracy of photon emission from a modified source or port
therefore depends on this parameter. The resolution may need to be increased
with complex emission distributions in combination with caustics.
.IP "\fB\-ds \fIpartsize\fR"
Light source partition size ratio; a local light source object (or photon
port in case of a distant source) 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
to be reduced for modified light sources (e.g. via \fIbrightfunc\fR) with
high spatial variance, or for partially occluded photon ports.
.IP "\fB\-e \fIexpr\fR"
Parse expression \fIexpr\fR to globally initialise binning variables for all
contribution modifiers in conjunction with the \fB\-apC\fR option. For a list
of relevant variables, see option \fB\-p\fR below.
.IP "\fB\-ef \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\-m \fImod\fR"
Include modifier \fImod\fR in the precomputed contribution photon
map in conjunction with the \fB\-apC\fR option. This must be a light
source modifier, as photons can only carry contributions from their
emitting light sources; an error is issued if this is not the case.
The most recent binning options \fB\-bn\fR
and \fB\-p\fR apply to this modifier, and can be individually
specified for subsequent modifiers.
.IP "\fB\-M \fImodfile\fR"
Similar to \fB\-m\fR, but load a list of contribution modifiers from
\fImodfile\fR. The most recent instances of binning parameters \fI\-bn\fR
and \fI\-p\fR are applied to all modifiers.
.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
(so doan' even try). This option is currently not available on Windows --
tuff luck.
.IP "\fB\-p \fI\fR"
Define per-modifier parameters \var{var_1\fIexpr\fR for the
Shirley-Chiu mapping used to bin precomputed contribution photons in
conjunction with the \fB\-apC\fR option. These parameters apply to the next
contribution modifier specified with the \fB\-m\fR option, and can be
individually redefined for subsequent modifiers. The companion option
\fB\-e\fR can be used to set global parameters for all modifiers.
The following variables can be set to define the mapping orientation:
.RS
.IP \fIRHS\fR:
1 for right-handed coordinate system (default), -1 for left-handed.
.IP "\fIrNx, rNy, rNz\fR":
surface normal (defines theta = 0, default [0, 0, 1])
.IP "\fIUx, Uy, Uz\fR":
up vector (defines phi = 0, default [0, 1, 0])
.RE
.IP
See also this option's discussion in \fIrcontrib(1)\fR.
.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.
.IP \fB\-v\fR[\fB+\fR|\fB-\fR]\fR
Boolean option to control \fImkpmap\fR's console output. If disabled (the
default), the output is terse, except for warnings and errors. If enabled,
the output is verbose, and includes information on distribution prepasses,
photon ports, and light source partitioning. Verbose mode can generate
excessive chatter and should only be used for diagnostic purposes,
for example if \fImkpmap\fR seemingly hangs (which can happen if many
light source partitions need to be processed).
It is a good idea to redirect verbose output with the \fB\-ef\fR option,
since excessive console output will actually slow \fImkpmap\fR down.
.IP "\fB\-V\fR[\fB+\fR|\fB-\fR]\fR"
Boolean option to precompute contributions (enabled) or
normalised coefficients (disabled, the default) in conjunction
with the \fB\-apC\fR option.
See also this option's discussion in \fIrcontrib(1)\fR.
.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
Not all materials are fully supported by the photon map extension. The
\fIplasfunc\fR, \fImetfunc\fR, \fItransfunc\fR, \fIplasdata\fR,
\fImetdata\fR and \fItransdata\fR materials currently only scatter photons
diffusely, and will not produce caustics. The \fIbrtdfunc\fR material only
produces caustics via ideal (mirror) specular reflection and transmission.
For more realistic scattering behaviour, 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 generally surface bound, the density estimate is only
asymptotically correct when performed at points which lie on the scene
geometry (unless lightflow photons are used, see option \fB\-apV\fR).
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 10 million contribution photons from all light sources with modifier
\fIbonzoLite\fR, precompute 1 million of these by accumulating the
contributions from the 2600 nearest photons into 256 bins, and compress them
by 75%. Then accumulate these precomputed contributions for a grid of sensor
positions in \fIrcontrib\fR. Note that the relevant binning parameters and
modifiers are passed via the option file \fIbonzo-contrib.Cpm.opt\fR:
.IP
mkpmap \-apC bonzo-contrib.Cpm 10m 2600 0.75 \-apP 0.1 \-bn 256
\-m bonzoLite \-V+ bonzo.oct
.IP
rcontrib \-ap bonzo-contrib.Cpm \-o %s.dat @bonzo-contrib.Cpm.opt
bonzo.oct < sensors.pos
.PP
Generate 10 million transient photons travelling at the approximate
speed of light (in m/s, assuming the geometry in bonzo.oct is in the same
units):
.IP
mkpmap \-apt bonzo-trans.tpm 10m 3e8 bonzo.oct
.PP
Generate 25 million "light flow" photons in a global participating medium with
extinction 0.001 (note reduced predistribution factor to prevent overflow):
.IP
mkpmap \-apV bonzo-lflo.Vpm 25m \-apD .001 \-me .001 .001 .001 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.
.PP
Light sources and photon ports consisting of arbitrary polygons are poorly
supported by \fImkpmap\fR, and (inefficiently) rejection sampled. This may
result in significantly fewer photons than specified, but no significant bias.
It is recommended to use triangulated or quadilateral geometry.
.PP
The current transient photon map implementation makes simplifying assumptions;
the photon velocity is treated as constant in all media, and is consequently
not adapted for the index of refraction in \fIdielectric\fR and \fIinterface\fR
materials. Relativistic effects are also not considered.
.SH AUTHOR
Roland Schregle (roland.schregle@{hslu.ch, gmail.com})
.SH COPYRIGHT
(c) Fraunhofer Institute for Solar Energy Systems,
.br
(c) Lucerne University of Applied Sciences and Arts (Hochschule Luzern),
.br
(c) Tokyo University of Science.
.SH ACKNOWLEDGEMENTS
Development of the RADIANCE photon mapping extension was supported by:
.RS
\fIFraunhofer Institute for Solar Energy Systems\fR funded by
the German Research Foundation (\fIDFG LU-204/10-2\fR: "Fassadenintegrierte
Regelsysteme (FARESYS)"),
\fILucerne University of Applied Sciences and Arts (Hochschule Luzern)\fR
funded by the Swiss National Science Foundation (\fISNSF 147053\fR: "Daylight
redirecting components" and \fISNSF 179067\fR: "Lightfields for spatio-temporal glare assessment"),
\fITokyo University of Science\fR funded by the JSPS Grants-in-Aid for Scientific
Research Programme (\fIKAKENHI JP19KK0115\fR: "Three-dimensional light flow in architectural spaces") under the supervision of Prof. Nozomu Yoshizawa.
.RE
In particular, the author thanks Prof. Stephen Wittkopf and Dr. Lars Grobe
for resuming development at Hochschule Luzern, and Prof. Nozomu Yoshizawa
for the opportunity to collaborate with the Tokyo University of Science.
Many thanks also to the many individuals who tested the code and provided
valuable feedback. Special greetz to Don Gregorio, PAB and Capt.\~B!
.SH "SEE ALSO"
rpict(1), rtrace(1), rvu(1), rcontrib(1),
.br
\fIThe RADIANCE Photon Map Manual\fR,
.br
\fIDevelopment and Integration of the RADIANCE Photon Map Extension:
Technical Report\fR,
.br
\fIThe RADIANCE Out-of-Core Photon Map: Technical Report\fR,
.br
\fIBonzo Daylighting Tool a.k.a. EvilDRC [TM]\fR

Event Timeline

c4science · Help