man/man1/pabopto2bsdf.1

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