man/man1/pabopto2bsdf.1

.\" RCSid "$Id: pabopto2bsdf.1,v 1.8 2021/05/14 17:57:59 greg Exp $"
.TH PABOPTO2BSDF 1 2/24/2021 RADIANCE
.SH NAME
pabopto2bsdf - convert BSDF measurements to a scattering interpolant representation
.SH SYNOPSIS
.B pabopto2bsdf
[
.B \-t
][
.B "\-n nproc"
][
.B "\-s symmetry"
][
.B "\-g angle | 'A'"
]
.B "meas1 meas2 .."
.SH DESCRIPTION
.I Pabopto2bsdf
takes two or more pab-opto
.I Mountain
files, each nominally containing
different incident beam angles or sampling patterns,
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" matrix for each pair of 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 they are to
be used in a simulation.
(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.
.PP
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
will assume a 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", or 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.
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 final BSDF
is 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 not appropriate.
.PP
If a
.I \-g
option is present, it will cull scattered measurements that are nearer
to grazing than the given angle in degrees.
If the word "auto" (which can be abbreviated as 'a' or 'A') is given
instead of an angle, then the near-grazing angle will be determined
by the lowest incident angle measurement present in the input data.
This is sometimes necessary to eliminate noise and edge effects that
some measurements exhibit near grazing.
.PP
The
.I Mountain
software operates the pg2 goniophotometer to
capture BSDF scattering data in separate text files for each incident
angle, 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 final sample name read
will be the one 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 "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, meaning that "up"
is phi=0.
To get the standard RADIANCE coordinates for BSDFs, "#upphi" should
be set to 90 (degrees).
.TP
.BR #colorimetry:
Two colorimetry values are currently understood: "CIE-Y" and "CIE-XYZ".
The default "CIE-Y" colorimetry
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 NOTES
If the BSDF is being mirrored and there is no measured theta=0 incident
angle data file, this part of the distribution is filled in
by a special procedure.
This is important because there is no way to extrapolate missing
data at normal incidence.
.PP
The BSDF is extrapolated past the last measured theta angles towards
grazing using a constant value plus a single Gaussian lobe if one can
be reasonably fit to the near-grazing data.
This lobe will always be in the mirror direction in the case of
reflection, or the "through" direction in the case
of transmission.
The magnitude and width of this lobe is stored in the output header,
along with the constant value.
Both the lobe and the constant are neutral values, even with CIE-XYZ
colorimetry.
.PP
While there is no explicit handling of infrared or solar radiometry,
any single-channel BSDF will be created the same, and the final XML
file generated by
.I bsdf2klems
or
.I bsdf2ttree
can be edited to specify a different radiometry.
The interpolation process in
.I pabopto2bsdf
is not affected by this.
.PP
The standard BSDF coordinates in RADIANCE have the theta=0 direction
corresponding to the front-side surface normal.
The phi=0 direction points to the right as seen from the front, and
phi=90 degrees corresponds to the "up" orientation for the sample.
The same theta and phi are used for incoming and scattered angles,
so theta=180 is the opposite side surface normal.
This differs from the WINDOW, which use separate
coordinate systems for the front and the back.
To confusing things further, notions of "front" and "back" are
opposite in WINDOW and RADIANCE.
In RADIANCE, the normal of a window surface usually faces the
interior of a space.
.PP
In the
.I genBSDF(1)
utility, the world coordinate system follows trigonometric
conventions with theta=0 aligning to the Z-axis,
the X-axis matches (theta,phi)=(90,0), and the Y-axis
corresponds to (theta,phi)=(90,90).
The latter is thought of as the "up" direction for the sample.
This usually needs to be rotated into position, since most
RADIANCE models use the Z-axis as the world "up" direction.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
bsdf2klems(1), bsdf2rad(1), bsdf2ttree(1), bsdfview(1), genBSDF(1),
pabopto2xyz(1)
Revision:	1.9
Committed:	Wed Aug 25 04:42:38 2021 UTC (3 years, 8 months ago) by greg
Branch:	MAIN
Changes since 1.8:	+2 -1 lines
Log Message:	docs: added paragraph break
#	User	Rev	Content
1	greg	1.9	.\" RCSid "$Id: pabopto2bsdf.1,v 1.8 2021/05/14 17:57:59 greg Exp $"
2	greg	1.1	.TH PABOPTO2BSDF 1 2/24/2021 RADIANCE
3			.SH NAME
4	greg	1.2	pabopto2bsdf - convert BSDF measurements to a scattering interpolant representation
5	greg	1.1	.SH SYNOPSIS
6			.B pabopto2bsdf
7			[
8			.B \-t
9			][
10			.B "\-n nproc"
11			][
12			.B "\-s symmetry"
13	greg	1.5	][
14	greg	1.6	.B "\-g angle \| 'A'"
15	greg	1.1	]
16			.B "meas1 meas2 .."
17			.SH DESCRIPTION
18			.I Pabopto2bsdf
19			takes two or more pab-opto
20			.I Mountain
21	greg	1.8	files, each nominally containing
22			different incident beam angles or sampling patterns,
23			and produces a Scattering Interpolant Representation (SIR)
24	greg	1.1	on the standard output for further processing.
25			The binary SIR contains a Radial Basis Function fitting
26			each incident BSDF data file
27	greg	1.8	and a "transport plan" matrix for each pair of neighboring RBF
28	greg	1.1	directions in a spherical Delaunay mesh.
29			.PP
30			The SIR provides a complete 4-dimensional
31			BSDF description that may be resampled for other
32			formats such as Klems and tensor tree.
33			However, a separate run of
34			.I pabopto2bsdf
35			is needed to produce an SIR for each
36			incident and scattered hemisphere pair.
37			At most, there will be 4 such hemisphere pairs for
38			front reflection, back reflection, front transmission,
39			and back transmission.
40			Theoretically, only one transmission direction is required,
41	greg	1.3	but it is often safest to measure both if they are to
42	greg	1.2	be used in a simulation.
43			(See
44	greg	1.1	.I bsdf2klems(1)
45			and
46			.I bsdf2ttree(1)
47			for details.
48			The
49			.I bsdf2rad(1)
50			and
51			.I bsdfview(1)
52	greg	1.2	tools are also useful for visualizaing SIR and XML files.)
53	greg	1.1	.PP
54			The
55			.I pabopto2bsdf
56			.I \-t
57			option reverses the assumed sample orientation front-to-back,
58			and is discussed below under the "#intheta" header entry.
59	greg	1.9	.PP
60	greg	1.1	Multi-processing may be used to accelerate the program
61			on systems that support it via the
62			.I \-n
63			option.
64			.PP
65			BSDF symmetry may be specified with the
66			.I \-s
67			option, which is one of "isotropic", "quadrilateral",
68			"bilateral", "up", or "anisotropic".
69			Any of these may be abbreviated with as little as a single
70			letter, and case is ignored.
71			.PP
72			Normally,
73			.I pabopto2bsdf
74	greg	1.2	will assume a BSDF symmetry from the incident phi angles provided.
75	greg	1.1	If every input data file uses the same incident phi angle, the
76	greg	1.2	BSDF is assumed to be "isotropic", or rotationally symmetric.
77	greg	1.1	If input phi angles only cover one quarter of the incident hemisphere,
78			then the sample is assumed to have quadrilateral symmetry.
79			Similarly, half-hemisphere coverage implies "bilateral" symmetry,
80			although it is also compatible with "up" symmetry, which must be specified
81			on the command line.
82			The difference is crucial.
83			Similar to quadrilateral symmetry, bilateral symmetry is "mirrored,"
84			meaning that the sample material looks identical when viewed in a mirror.
85			However, "up" symmetry means that the sample looks the same when
86			rotated by 180-degree (upside-down), but does not look the same in a mirror.
87			The "up" symmetry was a late addition, and involves rotating and copying the
88			input data, treating the result as anisotropic.
89			It is therefore less efficient, and should only be used when necessary.
90	greg	1.2	Finally, if the incident hemisphere is fully covered, the final BSDF
91			is anisotropic.
92	greg	1.1	.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	greg	1.2	option must be specified if the default mirroring is not appropriate.
101	greg	1.1	.PP
102	greg	1.5	If a
103			.I \-g
104			option is present, it will cull scattered measurements that are nearer
105			to grazing than the given angle in degrees.
106			If the word "auto" (which can be abbreviated as 'a' or 'A') is given
107			instead of an angle, then the near-grazing angle will be determined
108			by the lowest incident angle measurement present in the input data.
109			This is sometimes necessary to eliminate noise and edge effects that
110			some measurements exhibit near grazing.
111			.PP
112	greg	1.1	The
113			.I Mountain
114			software operates the pg2 goniophotometer to
115	greg	1.2	capture BSDF scattering data in separate text files for each incident
116			angle, beginning with a header
117	greg	1.1	whose lines each start with a pound sign ('#').
118			Some header settings require colons and others do not, as indicated below.
119			The
120			.i pabopto2bsdf
121			program understands the following lines from each header and ignores
122			the rest:
123			.TP
124			.BR #sample_name
125			A double-quoted string containing the name associated with this sample.
126	greg	1.7	If input files contain different sample names, the final sample name read
127			will be the one passed to the SIR output.
128	greg	1.1	.TP
129			.BR #format:
130			The data format, typically one of "theta phi DSF" or "theta phi BSDF".
131			These differ only in their inclusion of a cosine factor.
132			The word "BRDF" or "BTDF" is accepted in place of "BSDF".
133			Any other specification or a format missing generates an error.
134			.TP
135			.BR #intheta
136			The incident theta (polar) angle in degrees, measured from the sample's
137			surface normal.
138			Theta values should be between 0 and 180, where values less than 90
139			are considered incident to the "front" side of the sample, and
140			theta values greater than 90 are incident to the "back" side in
141			the standard coordinate system.
142	greg	1.2	Notions of "front" and "back" may be reversed using the
143	greg	1.1	.I -t
144			option if desired.
145			.TP
146			.BR #inphi
147			The incident phi (azimuthal) angle in degrees counter-clockwise as
148			seen from the "front" side of the sample.
149			.TP
150			.BR #incident_angle
151			The incident theta and phi angles are each given in this header
152			line, offered as an alternative to separate "#intheta" and "#inphi"
153			angles.
154			The interpretation is the same as above.
155			.TP
156			.BR #upphi
157			If present, this phi angle that corresponds to
158			the sample "up" orientation.
159	greg	1.2	By default, it is assumed to be 0, meaning that "up"
160	greg	1.1	is phi=0.
161			To get the standard RADIANCE coordinates for BSDFs, "#upphi" should
162	greg	1.2	be set to 90 (degrees).
163	greg	1.1	.TP
164			.BR #colorimetry:
165	greg	1.2	Two colorimetry values are currently understood: "CIE-Y" and "CIE-XYZ".
166			The default "CIE-Y" colorimetry
167	greg	1.1	takes each DSF or BSDF value as photometric.
168			If "CIE-XYZ" is specified, then the DSF or BSDF values must be triplets
169			corresponding to CIE XYZ values.
170			Such files are typically produced by the
171			.I pabopto2xyz(1)
172			tool rather than
173			.I Mountain,
174			directly.
175			.PP
176			The BSDF scattering data follows the header in unspecified order,
177			where each line in the file
178			contains the scattered theta and phi angles measured in the same
179			coordinate system as incident theta and phi, followed by the DSF
180			or BSDF value, which may either be a single photometric quantity
181			for "CIE-Y" colorimetry or a triplet if the colorimetry is "CIE-XYZ".
182			A minimal incident BSDF data file might contain:
183			.sp
184			.nf
185			#incident_angle 82.5 180
186			#format: theta phi DSF
187			84.968 125.790 0.009744
188			84.889 125.610 0.007737
189			84.805 125.427 0.008569
190			...
191			.fi
192			.sp
193			The above header is equivalent to the more complete version below:
194			.sp
195			.nf
196			#format: theta phi DSF
197			#incident_angle 82.5 180
198			#intheta 82.5
199			#inphi 180
200			#upphi 0
201			#colorimetry: CIE-Y
202			84.968 125.790 0.009744
203			84.889 125.610 0.007737
204			84.805 125.427 0.008569
205			...
206			.fi
207			.sp
208			The ordering of the header and data lines is unimportant,
209			but all header lines must precede all data lines in each input file.
210			.SH EXAMPLE
211			To generate an SIR file from a collection of transmission measurements
212			of a material with 180-degree symmetry using 4 processes:
213			.IP "" .2i
214			pabopto2bsdf -n 4 -s up f*_Tvis.txt > front_trans.sir
215			.PP
216			To combine this with front reflection measurements into a Klems BSDF file:
217			.IP "" .2i
218			pabopto2bsdf -n 4 -s up f*_Rvis.txt > front_refl.sir
219			.br
220			bsdf2klems front_trans.sir front_refl.sir > Klems_bsdf.xml
221	greg	1.2	.SH NOTES
222			If the BSDF is being mirrored and there is no measured theta=0 incident
223			angle data file, this part of the distribution is filled in
224			by a special procedure.
225			This is important because there is no way to extrapolate missing
226			data at normal incidence.
227			.PP
228			The BSDF is extrapolated past the last measured theta angles towards
229			grazing using a constant value plus a single Gaussian lobe if one can
230			be reasonably fit to the near-grazing data.
231			This lobe will always be in the mirror direction in the case of
232			reflection, or the "through" direction in the case
233			of transmission.
234			The magnitude and width of this lobe is stored in the output header,
235			along with the constant value.
236			Both the lobe and the constant are neutral values, even with CIE-XYZ
237			colorimetry.
238			.PP
239			While there is no explicit handling of infrared or solar radiometry,
240			any single-channel BSDF will be created the same, and the final XML
241			file generated by
242			.I bsdf2klems
243			or
244			.I bsdf2ttree
245			can be edited to specify a different radiometry.
246			The interpolation process in
247			.I pabopto2bsdf
248			is not affected by this.
249			.PP
250			The standard BSDF coordinates in RADIANCE have the theta=0 direction
251			corresponding to the front-side surface normal.
252			The phi=0 direction points to the right as seen from the front, and
253			phi=90 degrees corresponds to the "up" orientation for the sample.
254			The same theta and phi are used for incoming and scattered angles,
255			so theta=180 is the opposite side surface normal.
256			This differs from the WINDOW, which use separate
257			coordinate systems for the front and the back.
258			To confusing things further, notions of "front" and "back" are
259			opposite in WINDOW and RADIANCE.
260			In RADIANCE, the normal of a window surface usually faces the
261			interior of a space.
262			.PP
263			In the
264			.I genBSDF(1)
265			utility, the world coordinate system follows trigonometric
266			conventions with theta=0 aligning to the Z-axis,
267			the X-axis matches (theta,phi)=(90,0), and the Y-axis
268	greg	1.4	corresponds to (theta,phi)=(90,90).
269	greg	1.2	The latter is thought of as the "up" direction for the sample.
270			This usually needs to be rotated into position, since most
271			RADIANCE models use the Z-axis as the world "up" direction.
272	greg	1.1	.SH AUTHOR
273			Greg Ward
274			.SH "SEE ALSO"
275	greg	1.2	bsdf2klems(1), bsdf2rad(1), bsdf2ttree(1), bsdfview(1), genBSDF(1),
276	greg	1.3	pabopto2xyz(1)