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, 3 months ago) by greg
Branch:	MAIN
Log Message:	docs: added man page for pabopto2bsdf
#	Content
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)