man/man1/pabopto2bsdf.1

.\" RCSid "$Id: mgf2rad.1,v 1.3 2007/09/04 17:36:40 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)
Revision:	1.1
Committed:	Thu Feb 25 04:48:19 2021 UTC (4 years, 2 months ago) by greg
Branch:	MAIN
Log Message:	docs: added man page for pabopto2bsdf
#	User	Rev	Content
1	greg	1.1	.\" RCSid "$Id: mgf2rad.1,v 1.3 2007/09/04 17:36:40 greg Exp $"
2			.TH PABOPTO2BSDF 1 2/24/2021 RADIANCE
3			.SH NAME
4			pabopto2bsdf - convert pab-opto BSDF measurements to scattering interpolant representation
5			.SH SYNOPSIS
6			.B pabopto2bsdf
7			[
8			.B \-t
9			][
10			.B "\-n nproc"
11			][
12			.B "\-s symmetry"
13			]
14			.B "meas1 meas2 .."
15			.SH DESCRIPTION
16			.I Pabopto2bsdf
17			takes two or more pab-opto
18			.I Mountain
19			files, each corresponding
20			to a different incident beam angle, and produces a
21			Scattering Interpolant Representation (SIR)
22			on the standard output for further processing.
23			The binary SIR contains a Radial Basis Function fitting
24			each incident BSDF data file
25			and a "transport plan" between neighboring RBF
26			directions in a spherical Delaunay mesh.
27			.PP
28			The SIR provides a complete 4-dimensional
29			BSDF description that may be resampled for other
30			formats such as Klems and tensor tree.
31			However, a separate run of
32			.I pabopto2bsdf
33			is needed to produce an SIR for each
34			incident and scattered hemisphere pair.
35			At most, there will be 4 such hemisphere pairs for
36			front reflection, back reflection, front transmission,
37			and back transmission.
38			Theoretically, only one transmission direction is required,
39			but it is often safest to measure both if both directions
40			will be used in a simulation.
41			.PP
42			See
43			.I bsdf2klems(1)
44			and
45			.I bsdf2ttree(1)
46			for details.
47			The
48			.I bsdf2rad(1)
49			and
50			.I bsdfview(1)
51			tools are also useful for visualizaing SIR and XML files.
52			.PP
53			The
54			.I pabopto2bsdf
55			.I \-t
56			option reverses the assumed sample orientation front-to-back,
57			and is discussed below under the "#intheta" header entry.
58			Multi-processing may be used to accelerate the program
59			on systems that support it via the
60			.I \-n
61			option.
62			.PP
63			BSDF symmetry may be specified with the
64			.I \-s
65			option, which is one of "isotropic", "quadrilateral",
66			"bilateral", "up", or "anisotropic".
67			Any of these may be abbreviated with as little as a single
68			letter, and case is ignored.
69			.PP
70			Normally,
71			.I pabopto2bsdf
72			attempts to deduce BSDF symmetry from the incident phi angles
73			provided.
74			If every input data file uses the same incident phi angle, the
75			BSDF is assumed to be "isotropic", meaning rotationally symmetric.
76			If input phi angles only cover one quarter of the incident hemisphere,
77			then the sample is assumed to have quadrilateral symmetry.
78			Similarly, half-hemisphere coverage implies "bilateral" symmetry,
79			although it is also compatible with "up" symmetry, which must be specified
80			on the command line.
81			The difference is crucial.
82			Similar to quadrilateral symmetry, bilateral symmetry is "mirrored,"
83			meaning that the sample material looks identical when viewed in a mirror.
84			However, "up" symmetry means that the sample looks the same when
85			rotated by 180-degree (upside-down), but does not look the same in a mirror.
86			Although bilateral symmetry is a superset of "up" symmetry,
87			we assume the former when provided only half of the input hemisphere.
88			The "up" symmetry was a late addition, and involves rotating and copying the
89			input data, treating the result as anisotropic.
90			It is therefore less efficient, and should only be used when necessary.
91			Finally, if the incident hemisphere is fully covered, the BSDF is also anisotropic.
92			.PP
93			If a
94			.I \-s
95			symmetry option is specified and it does not agree with the input
96			data provided, an error message is issued and no output is produced.
97			Note that only the "up" and "bilateral" symmetry options have
98			identical input coverage, so this is the only time the
99			.I \-s
100			option must be specified if the default mirroring is inappropriate.
101			.PP
102			The
103			.I Mountain
104			software operates the pg2 goniophotometer to
105			capture BSDF scattering data in separate files for each incident
106			angle in a text file beginning with a header
107			whose lines each start with a pound sign ('#').
108			Some header settings require colons and others do not, as indicated below.
109			The
110			.i pabopto2bsdf
111			program understands the following lines from each header and ignores
112			the rest:
113			.TP
114			.BR #sample_name
115			A double-quoted string containing the name associated with this sample.
116			If input files contain different sample names, the one read
117			will be the sample name passed to the SIR output.
118			.TP
119			.BR #format:
120			The data format, typically one of "theta phi DSF" or "theta phi BSDF".
121			These differ only in their inclusion of a cosine factor.
122			The word "BRDF" or "BTDF" is accepted in place of "BSDF".
123			Any other specification or a format missing generates an error.
124			.TP
125			.BR #intheta
126			The incident theta (polar) angle in degrees, measured from the sample's
127			surface normal.
128			Theta values should be between 0 and 180, where values less than 90
129			are considered incident to the "front" side of the sample, and
130			theta values greater than 90 are incident to the "back" side in
131			the standard coordinate system.
132			Notions of sample "front" and "back" may be reversed using the
133			.I -t
134			option if desired.
135			.TP
136			.BR #inphi
137			The incident phi (azimuthal) angle in degrees counter-clockwise as
138			seen from the "front" side of the sample.
139			.TP
140			.BR #incident_angle
141			The incident theta and phi angles are each given in this header
142			line, offered as an alternative to separate "#intheta" and "#inphi"
143			angles.
144			The interpretation is the same as above.
145			.TP
146			.BR #upphi
147			If present, this phi angle that corresponds to
148			the sample "up" orientation.
149			By default, it is assumed to be 0 degrees, meaning that "up"
150			is phi=0.
151			To get the standard RADIANCE coordinates for BSDFs, "#upphi" should
152			be set to 90.
153			.TP
154			.BR #colorimetry:
155			Two colorimetry values are currently understood, "CIE-Y" and "CIE-XYZ".
156			The default colorimetry of "CIE-Y", which may be left unspecified,
157			takes each DSF or BSDF value as photometric.
158			If "CIE-XYZ" is specified, then the DSF or BSDF values must be triplets
159			corresponding to CIE XYZ values.
160			Such files are typically produced by the
161			.I pabopto2xyz(1)
162			tool rather than
163			.I Mountain,
164			directly.
165			.PP
166			The BSDF scattering data follows the header in unspecified order,
167			where each line in the file
168			contains the scattered theta and phi angles measured in the same
169			coordinate system as incident theta and phi, followed by the DSF
170			or BSDF value, which may either be a single photometric quantity
171			for "CIE-Y" colorimetry or a triplet if the colorimetry is "CIE-XYZ".
172			A minimal incident BSDF data file might contain:
173			.sp
174			.nf
175			#incident_angle 82.5 180
176			#format: theta phi DSF
177			84.968 125.790 0.009744
178			84.889 125.610 0.007737
179			84.805 125.427 0.008569
180			...
181			.fi
182			.sp
183			The above header is equivalent to the more complete version below:
184			.sp
185			.nf
186			#format: theta phi DSF
187			#incident_angle 82.5 180
188			#intheta 82.5
189			#inphi 180
190			#upphi 0
191			#colorimetry: CIE-Y
192			84.968 125.790 0.009744
193			84.889 125.610 0.007737
194			84.805 125.427 0.008569
195			...
196			.fi
197			.sp
198			The ordering of the header and data lines is unimportant,
199			but all header lines must precede all data lines in each input file.
200			.SH EXAMPLE
201			To generate an SIR file from a collection of transmission measurements
202			of a material with 180-degree symmetry using 4 processes:
203			.IP "" .2i
204			pabopto2bsdf -n 4 -s up f*_Tvis.txt > front_trans.sir
205			.PP
206			To combine this with front reflection measurements into a Klems BSDF file:
207			.IP "" .2i
208			pabopto2bsdf -n 4 -s up f*_Rvis.txt > front_refl.sir
209			.br
210			bsdf2klems front_trans.sir front_refl.sir > Klems_bsdf.xml
211			.SH AUTHOR
212			Greg Ward
213			.SH "SEE ALSO"
214			bsdf2klems(1), bsdf2rad(1), bsdf2ttree(1), bsdfview(1), pabopto2xyz(1)