-
Notifications
You must be signed in to change notification settings - Fork 25
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: added man page for pabopto2bsdf
- Loading branch information
1 parent
a230773
commit 5cf6f5a
Showing
5 changed files
with
224 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |