.\" RCSid "$Id: pabopto2bsdf.1,v 1.1 2021/02/25 04:48:19 greg Exp $"
.TH PABOPTO2BSDF 1 2/24/2021 RADIANCE
.SH NAME
pabopto2bsdf - convert pab-opto BSDF measurements to scattering interpolant representation
.SH SYNOPSIS
.B pabopto2bsdf
[
.B \-t
][
.B "\-n nproc"
][
.B "\-s symmetry"
]
.B "meas1 meas2 .."
.SH DESCRIPTION
.I Pabopto2bsdf
takes two or more pab-opto
.I Mountain
files, each corresponding
to a different incident beam angle, and produces a
Scattering Interpolant Representation (SIR)
on the standard output for further processing.
The binary SIR contains a Radial Basis Function fitting
each incident BSDF data file
and a "transport plan" between neighboring RBF
directions in a spherical Delaunay mesh.
.PP
The SIR provides a complete 4-dimensional
BSDF description that may be resampled for other
formats such as Klems and tensor tree.
However, a separate run of
.I pabopto2bsdf
is needed to produce an SIR for each
incident and scattered hemisphere pair.
At most, there will be 4 such hemisphere pairs for
front reflection, back reflection, front transmission,
and back transmission.
Theoretically, only one transmission direction is required,
but it is often safest to measure both if both directions
will be used in a simulation.
.PP
See
.I bsdf2klems(1)
and
.I bsdf2ttree(1)
for details.
The
.I bsdf2rad(1)
and
.I bsdfview(1)
tools are also useful for visualizaing SIR and XML files.
.PP
The
.I pabopto2bsdf
.I \-t
option reverses the assumed sample orientation front-to-back,
and is discussed below under the "#intheta" header entry.
Multi-processing may be used to accelerate the program
on systems that support it via the
.I \-n
option.
.PP
BSDF symmetry may be specified with the
.I \-s
option, which is one of "isotropic", "quadrilateral",
"bilateral", "up", or "anisotropic".
Any of these may be abbreviated with as little as a single
letter, and case is ignored.
.PP
Normally,
.I pabopto2bsdf
attempts to deduce BSDF symmetry from the incident phi angles
provided.
If every input data file uses the same incident phi angle, the
BSDF is assumed to be "isotropic", meaning rotationally symmetric.
If input phi angles only cover one quarter of the incident hemisphere,
then the sample is assumed to have quadrilateral symmetry.
Similarly, half-hemisphere coverage implies "bilateral" symmetry,
although it is also compatible with "up" symmetry, which must be specified
on the command line.
The difference is crucial.
Similar to quadrilateral symmetry, bilateral symmetry is "mirrored,"
meaning that the sample material looks identical when viewed in a mirror.
However, "up" symmetry means that the sample looks the same when
rotated by 180-degree (upside-down), but does not look the same in a mirror.
Although bilateral symmetry is a superset of "up" symmetry,
we assume the former when provided only half of the input hemisphere.
The "up" symmetry was a late addition, and involves rotating and copying the
input data, treating the result as anisotropic.
It is therefore less efficient, and should only be used when necessary.
Finally, if the incident hemisphere is fully covered, the BSDF is also anisotropic.
.PP
If a
.I \-s
symmetry option is specified and it does not agree with the input
data provided, an error message is issued and no output is produced.
Note that only the "up" and "bilateral" symmetry options have
identical input coverage, so this is the only time the
.I \-s
option must be specified if the default mirroring is inappropriate.
.PP
The
.I Mountain
software operates the pg2 goniophotometer to
capture BSDF scattering data in separate files for each incident
angle in a text file beginning with a header
whose lines each start with a pound sign ('#').
Some header settings require colons and others do not, as indicated below.
The
.i pabopto2bsdf
program understands the following lines from each header and ignores
the rest:
.TP
.BR #sample_name
A double-quoted string containing the name associated with this sample.
If input files contain different sample names, the one read
will be the sample name passed to the SIR output.
.TP
.BR #format:
The data format, typically one of "theta phi DSF" or "theta phi BSDF".
These differ only in their inclusion of a cosine factor.
The word "BRDF" or "BTDF" is accepted in place of "BSDF".
Any other specification or a format missing generates an error.
.TP
.BR #intheta
The incident theta (polar) angle in degrees, measured from the sample's
surface normal.
Theta values should be between 0 and 180, where values less than 90
are considered incident to the "front" side of the sample, and
theta values greater than 90 are incident to the "back" side in
the standard coordinate system.
Notions of sample "front" and "back" may be reversed using the
.I -t
option if desired.
.TP
.BR #inphi
The incident phi (azimuthal) angle in degrees counter-clockwise as
seen from the "front" side of the sample.
.TP
.BR #incident_angle
The incident theta and phi angles are each given in this header
line, offered as an alternative to separate "#intheta" and "#inphi"
angles.
The interpretation is the same as above.
.TP
.BR #upphi
If present, this phi angle that corresponds to
the sample "up" orientation.
By default, it is assumed to be 0 degrees, meaning that "up"
is phi=0.
To get the standard RADIANCE coordinates for BSDFs, "#upphi" should
be set to 90.
.TP
.BR #colorimetry:
Two colorimetry values are currently understood, "CIE-Y" and "CIE-XYZ".
The default colorimetry of "CIE-Y", which may be left unspecified,
takes each DSF or BSDF value as photometric.
If "CIE-XYZ" is specified, then the DSF or BSDF values must be triplets
corresponding to CIE XYZ values.
Such files are typically produced by the
.I pabopto2xyz(1)
tool rather than
.I Mountain,
directly.
.PP
The BSDF scattering data follows the header in unspecified order,
where each line in the file
contains the scattered theta and phi angles measured in the same
coordinate system as incident theta and phi, followed by the DSF
or BSDF value, which may either be a single photometric quantity
for "CIE-Y" colorimetry or a triplet if the colorimetry is "CIE-XYZ".
A minimal incident BSDF data file might contain:
.sp
.nf
#incident_angle 82.5 180
#format: theta phi DSF
84.968 125.790 0.009744
84.889 125.610 0.007737
84.805 125.427 0.008569
 ...
.fi
.sp
The above header is equivalent to the more complete version below:
.sp
.nf
#format: theta phi DSF
#incident_angle 82.5 180
#intheta 82.5
#inphi 180
#upphi 0
#colorimetry: CIE-Y
84.968 125.790 0.009744
84.889 125.610 0.007737
84.805 125.427 0.008569
 ...
.fi
.sp
The ordering of the header and data lines is unimportant,
but all header lines must precede all data lines in each input file.
.SH EXAMPLE
To generate an SIR file from a collection of transmission measurements
of a material with 180-degree symmetry using 4 processes:
.IP "" .2i
pabopto2bsdf -n 4 -s up f*_Tvis.txt > front_trans.sir
.PP
To combine this with front reflection measurements into a Klems BSDF file:
.IP "" .2i
pabopto2bsdf -n 4 -s up f*_Rvis.txt > front_refl.sir
.br
bsdf2klems front_trans.sir front_refl.sir > Klems_bsdf.xml
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
bsdf2klems(1), bsdf2rad(1), bsdf2ttree(1), bsdfview(1), pabopto2xyz(1)