From 5cf6f5a21659cb934d8cdce91c2bbae4501097a5 Mon Sep 17 00:00:00 2001 From: "Gregory J. Ward" Date: Thu, 25 Feb 2021 04:48:19 +0000 Subject: [PATCH] docs: added man page for pabopto2bsdf --- doc/man/man1/bsdf2klems.1 | 6 +- doc/man/man1/bsdf2rad.1 | 4 +- doc/man/man1/bsdf2ttree.1 | 6 +- doc/man/man1/bsdfview.1 | 4 +- doc/man/man1/pabopto2bsdf.1 | 214 ++++++++++++++++++++++++++++++++++++ 5 files changed, 224 insertions(+), 10 deletions(-) create mode 100644 doc/man/man1/pabopto2bsdf.1 diff --git a/doc/man/man1/bsdf2klems.1 b/doc/man/man1/bsdf2klems.1 index 8c17d8f19..6d9e975fe 100644 --- a/doc/man/man1/bsdf2klems.1 +++ b/doc/man/man1/bsdf2klems.1 @@ -1,4 +1,4 @@ -.\" RCSid $Id: bsdf2klems.1,v 1.7 2019/03/19 22:03:24 greg Exp $ +.\" RCSid $Id: bsdf2klems.1,v 1.8 2021/02/25 04:48:19 greg Exp $ .TH BSDF2KLEMS 1 4/24/2013 RADIANCE .SH NAME bsdf2klems - generate XML Klems matrix description of a BSDF @@ -172,5 +172,5 @@ RAYPATH the directories to check for auxiliary files. Greg Ward .SH "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) +genskyvec(1), mkillum(1), genBSDF(1), pabopto2bsdf(1), pabopto2xyz(1), +pkgBSDF(1), rcontrib(1), rfluxmtx(1), rmtxop(1), wrapBSDF(1) diff --git a/doc/man/man1/bsdf2rad.1 b/doc/man/man1/bsdf2rad.1 index 02ace989b..61b1ec221 100644 --- a/doc/man/man1/bsdf2rad.1 +++ b/doc/man/man1/bsdf2rad.1 @@ -1,4 +1,4 @@ -.\" RCSid "$Id: bsdf2rad.1,v 1.3 2020/01/22 21:50:56 greg Exp $" +.\" RCSid "$Id: bsdf2rad.1,v 1.4 2021/02/25 04:48:19 greg Exp $" .TH BSDF2RAD 1 8/11/2017 RADIANCE .SH NAME bsdf2rad - create a RADIANCE visualization of a BSDF representation @@ -97,4 +97,4 @@ oconv -f refl.rad | rpict -vf good.vf > refl_good.hdr Greg Ward .SH "SEE ALSO" bsdf2klems(1), bsdf2ttree(1), genBSDF(1), -bsdfview(1), oconv(1), pabopto2bsdf(1), rad(1), rpict(1), rvu(1) +bsdfview(1), oconv(1), pabopto2bsdf(1), pabopto2xyz(1), rad(1), rpict(1), rvu(1) diff --git a/doc/man/man1/bsdf2ttree.1 b/doc/man/man1/bsdf2ttree.1 index f9f7fb044..b904d78a8 100644 --- a/doc/man/man1/bsdf2ttree.1 +++ b/doc/man/man1/bsdf2ttree.1 @@ -1,4 +1,4 @@ -.\" RCSid $Id: bsdf2ttree.1,v 1.9 2020/11/13 19:21:11 greg Exp $ +.\" RCSid $Id: bsdf2ttree.1,v 1.10 2021/02/25 04:48:19 greg Exp $ .TH BSDF2TTREE 1 4/24/2013 RADIANCE .SH NAME bsdf2ttree - generate XML tensor tree description of a BSDF @@ -178,5 +178,5 @@ RAYPATH the directories to check for auxiliary files. .SH AUTHOR Greg Ward .SH "SEE ALSO" -bsdf2klems(1), icalc(1), genBSDF(1), pkgBSDF(1), rcontrib(1), -rfluxmtx(1), wrapBSDF(1) +bsdf2klems(1), icalc(1), genBSDF(1), pabopto2bsdf(1), pabopto2xyz(1), +pkgBSDF(1), rcontrib(1), rfluxmtx(1), wrapBSDF(1) diff --git a/doc/man/man1/bsdfview.1 b/doc/man/man1/bsdfview.1 index 308c672a7..bb4be6a8c 100644 --- a/doc/man/man1/bsdfview.1 +++ b/doc/man/man1/bsdfview.1 @@ -1,4 +1,4 @@ -.\" RCSid "$Id: bsdfview.1,v 1.6 2018/07/20 00:50:40 greg Exp $" +.\" RCSid "$Id: bsdfview.1,v 1.7 2021/02/25 04:48:19 greg Exp $" .TH BSDFVIEW 1 8/11/2017 RADIANCE .SH NAME bsdfview - view a BSDF representation @@ -121,4 +121,4 @@ This may be useful for comparing different BSDF sources. Greg Ward .SH "SEE ALSO" bsdf2klems(1), bsdf2rad(1), bsdf2ttree(1), genBSDF(1), -objview(1), oconv(1), pabopto2bsdf(1), rad(1), rvu(1), trad(1) +objview(1), oconv(1), pabopto2bsdf(1), pabopto2xyz(1), rad(1), rvu(1), trad(1) diff --git a/doc/man/man1/pabopto2bsdf.1 b/doc/man/man1/pabopto2bsdf.1 new file mode 100644 index 000000000..b102c3d30 --- /dev/null +++ b/doc/man/man1/pabopto2bsdf.1 @@ -0,0 +1,214 @@ +.\" 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) \ No newline at end of file