BSDF2KLEMS(1)

NAME
bsdf2klems - generate XML Klems matrix description of a BSDF

SYNOPSIS
bsdf2klems [ -n spp ][ -h|-q ][ -pC ][ -l maxlobes ] [ bsdf.sir .. ]
or
bsdf2klems [ -n spp ][ -h|-q ][ -pC ] bsdf_in.xml
or
bsdf2klems [ -n spp ][ -h|-q ][ -pC ][ {+|-}forward ][ {+|-}backward ][ -e expr ][ -f file ] bsdf_func

DESCRIPTION
Bsdf2klems produces a Klems matrix representation of a bidirectional scattering distribution function (BSDF) based on an intermediate representation (in the first form), an input XML representation (in the second form), or a functional description (in the third form). A complete XML description is written to the standard output, which is normally redirected to a file.

The Klems matrix representation divides the input and output hemisphere into a default 145 patches. The -h option may be used to reduce this number to 73 patches per hemisphere. The -q option may be used to reduce this number to 41 patches. Neither option is recommended unless the distribution is known to be approximately diffuse.

The -p option by itself turns off the progress bar, whose length may be set by an immediately following integer argument. (The default progress bar length is 79 characters.)

The -l option may be used to specify the maximum number of lobes in any interpolated radial basis function. The default value is 15000, which generally keeps the interpolation tractable. Setting the value to 0 turns off this limit.

Normally, multiple samples are taken from random points on each input and output patch to improve accuracy. The number of samples to take for each input-output patch pair may be controlled using the -n option, which defaults to 256.

The first invocation form takes a intermediate scattering representation as produced by pabopto2bsdf(1) or similar, and produces a Klems representation with as many components as there are independent input distributions. Each intermediate scattering file contains one of the four components, and if the first component is isotropic, all components must be isotropic. A similar rule holds for anisotropic inputs. Only the center of each incident patches is sampled, due to the time required to interpolate incident positions.

In the second invocation form, an input XML representation is resampled to produce the desired Klems matrix representation. This is primarily used to convert a tensor tree representation into a matrix for annual daylighting simulations. Any components in the input are reproduced on output, and inline geometric descriptions are passed unchanged.

In the third invocation form, bsdf2klems takes a functional specification of a BSDF. The named function should accept 6 parameters corresponding to the normalized incident and exiting vectors, respectively. By convention, these vectors point away from the surface, and a positive Z-component corresponds to the front side. The Y-component corresponds to the "up" orientation of the surface, as specified in the eventual scene description that references the XML output. If the function only takes 3 parameters, then the variables "Dx", "Dy", and "Dz" will be assigned to the reverse of the outgoing direction at each evaluation. (I.e., the vector will point into the surface and Dz will be negative on the front side.) This simplifies conversion of functional BSDF specifications using the legacy material primitives "plasfunc", "metfunc", and "transfunc".

The function is defined by one or more -e and -f options, and should obey both Helmholtz reciprocity and integrate to less than 1 over each projected incident hemisphere for energy conservation. The variable and function definitions in each -f source file are read and compiled from the RADIANCE library where it is found.

Similar to the genBSDF(1) command, the +backward option (default) specifies that rays arriving from the front side of the surface will be tested for reflection and transmission. If both forward and backward (front and back) distributions are needed, the +forward option may be given. To turn off the backward components, use the -backward option. Computing both incident hemispheres takes about twice as long as one, but is recommended when rays will be impinging from either side.

EXAMPLE
To take two components of an intermediate BSDF representation and create a full Klems matrix representation:

    bsdf2klems transmitted.sir reflected.sir > combined.xml

To reduce a tensor tree representation into a half-Klems matrix representation:

    bsdf2klems -h ttree.xml > klems_half.xml

To create a low-res BSDF corresponding to a one-sided, isotropic Phong distribution:

    bsdf2klems -e 'phong(ix,iy,iz,ox,oy,oz) = if(iz, .1+((iz+oz)/sqrt((ix+ox)^2+(iy+oy)^2+(iz+oz)^2))^50, 0)' phong > phong.xml

ENVIRONMENT
RAYPATH    the directories to check for auxiliary files.

AUTHOR
Greg Ward

SEE ALSO
bsdf2ttree(1), dctimestep(1), icalc(1), gendaymtx(1), genklemsamp(1), genskyvec(1), mkillum(1), genBSDF(1), pkgBSDF(1), rcontrib(1), rfluxmtx(1), rmtxop(1), wrapBSDF(1)