man/man1/bsdf2klems.1

.\" RCSid $Id: bsdf2klems.1,v 1.7 2019/03/19 22:03:24 greg Exp $
.TH BSDF2KLEMS 1 4/24/2013 RADIANCE
.SH NAME
bsdf2klems - generate XML Klems matrix description of a BSDF
.SH SYNOPSIS
.B bsdf2klems
[
.B "\-n spp"
][
.B "\-h|\-q"
][
.B "\-pC"
][
.B "\-l maxlobes"
]
[
.B "bsdf.sir .."
]
.br
or
.br
.B bsdf2klems
[
.B "\-n spp"
][
.B "\-h|\-q"
][
.B "\-pC"
]
.B bsdf_in.xml
.br
or
.br
.B bsdf2klems
[
.B "\-n spp"
][
.B "\-h|\-q"
][
.B "\-pC"
][
.B "{+|-}forward"
][
.B "{+|-}backward"
][
.B "\-e expr"
][
.B "\-f file"
]
.B bsdf_func
.SH DESCRIPTION
.I Bsdf2klems
produces a Klems matrix representation of a
bidirectional scattering distribution function (BSDF)
based on an intermediate representation (in the first form),
an input XML representation (in the second form),
or a functional description (in the third form).
A complete XML description is written to the standard output,
which is normally redirected to a file.
.PP
The Klems matrix representation divides the input and output
hemisphere into a default 145 patches.
The
.I \-h
option may be used to reduce this number to 73 patches per hemisphere.
The
.I \-q
option may be used to reduce this number to 41 patches.
Neither option is recommended unless the distribution is known to
be approximately diffuse.
.PP
The
.I \-p
option by itself turns off the progress bar, whose length may be set
by an immediately following integer argument.
(The default progress bar length is 79 characters.)\0
.PP
The
.I \-l
option may be used to specify the maximum number of lobes in any
interpolated radial basis function.
The default value is 15000, which generally keeps the interpolation tractable.
Setting the value to 0 turns off this limit.
.PP
Normally, multiple samples are taken from random points on each input
and output patch to improve accuracy.
The number of samples to take for each input-output patch pair may
be controlled using the
.I \-n
option, which defaults to 1024.
.PP
The first invocation form takes a intermediate scattering representation
as produced by
.I pabopto2bsdf(1)
or similar, and produces a Klems representation with as many
components as there are independent input distributions.
Each intermediate scattering file contains one of
the four components, and if the first component
is isotropic, all components must be isotropic.
A similar rule holds for anisotropic inputs.
Only the center of each incident patches is sampled, due to
the time required to interpolate incident positions.
.PP
In the second invocation form, an input XML representation
is resampled to produce the desired Klems matrix representation.
This is primarily used to convert a tensor tree representation
into a matrix for annual daylighting simulations.
Any components in the input are reproduced on output, and inline
geometric descriptions are passed unchanged.
.PP
In the third invocation form,
.I bsdf2klems
takes a functional specification of a BSDF.
The named function should accept 6 parameters corresponding to the
normalized incident and exiting vectors, respectively.
By convention, these vectors point away from the surface, and a positive
Z-component corresponds to the front side.
The Y-component corresponds to the "up" orientation of the surface,
as specified in the eventual scene description that references the XML
output.
If the function only takes 3 parameters, then the variables "Dx", "Dy",
and "Dz" will be assigned to the reverse of the outgoing direction at
each evaluation.
(I.e., the vector will point into the surface and
Dz will be negative on the front side.)\0
This simplifies conversion of functional BSDF specifications using the
legacy material primitives "plasfunc", "metfunc", and "transfunc".
.PP
The function is defined by one or more
.I \-e
and
.I \-f
options, and should obey both Helmholtz reciprocity and
integrate to less than 1 over each projected incident hemisphere
for energy conservation.
The variable and function definitions in each
.I \-f source
file are read and compiled from the RADIANCE library where it is found.
.PP
Similar to the
.I genBSDF(1)
command,
the
.I \+backward
option (default) specifies that rays arriving from the front side of
the surface will be tested for reflection and transmission.
If both forward and backward (front and back) distributions are needed, the
.I \+forward
option may be given.
To turn off the backward components, use the
.I \-backward
option.
Computing both incident hemispheres takes about twice as long as one, but
is recommended when rays will be impinging from either side.
.SH EXAMPLE
To take two components of an intermediate BSDF representation and create
a full Klems matrix representation:
.IP "" .2i
bsdf2klems transmitted.sir reflected.sir > combined.xml
.PP
To reduce a tensor tree representation into a half-Klems matrix representation:
.IP "" .2i
bsdf2klems -h ttree.xml > klems_half.xml
.PP
To create a low-res BSDF corresponding to a one-sided,
isotropic Phong distribution:
.IP "" .2i
bsdf2klems -e 'phong(ix,iy,iz,ox,oy,oz) = if(iz, .1+((iz+oz)/sqrt((ix+ox)^2+(iy+oy)^2+(iz+oz)^2))^50, 0)' phong > phong.xml
.SH ENVIRONMENT
RAYPATH         the directories to check for auxiliary files.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
bsdf2ttree(1), dctimestep(1), icalc(1), gendaymtx(1), genklemsamp(1),
genskyvec(1), mkillum(1), genBSDF(1), pabopto2bsdf(1), pabopto2xyz(1),
pkgBSDF(1), rcontrib(1), rfluxmtx(1), rmtxop(1), wrapBSDF(1)
Revision:	1.8
Committed:	Thu Feb 25 04:48:19 2021 UTC (4 years, 8 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R4, rad6R0, HEAD
Changes since 1.7:	+3 -3 lines
Log Message:	docs: added man page for pabopto2bsdf
#	User	Rev	Content
1	greg	1.8	.\" RCSid $Id: bsdf2klems.1,v 1.7 2019/03/19 22:03:24 greg Exp $
2	greg	1.1	.TH BSDF2KLEMS 1 4/24/2013 RADIANCE
3			.SH NAME
4			bsdf2klems - generate XML Klems matrix description of a BSDF
5			.SH SYNOPSIS
6			.B bsdf2klems
7			[
8			.B "\-n spp"
9			][
10			.B "\-h\|\-q"
11	greg	1.3	][
12	greg	1.4	.B "\-pC"
13			][
14	greg	1.3	.B "\-l maxlobes"
15	greg	1.1	]
16			[
17			.B "bsdf.sir .."
18			]
19			.br
20			or
21			.br
22			.B bsdf2klems
23			[
24			.B "\-n spp"
25			][
26			.B "\-h\|\-q"
27	greg	1.4	][
28			.B "\-pC"
29	greg	1.1	]
30			.B bsdf_in.xml
31			.br
32			or
33			.br
34			.B bsdf2klems
35			[
36			.B "\-n spp"
37			][
38			.B "\-h\|\-q"
39			][
40	greg	1.4	.B "\-pC"
41			][
42	greg	1.1	.B "{+\|-}forward"
43			][
44			.B "{+\|-}backward"
45			][
46	greg	1.3	.B "\-e expr"
47	greg	1.1	][
48	greg	1.3	.B "\-f file"
49	greg	1.1	]
50			.B bsdf_func
51			.SH DESCRIPTION
52			.I Bsdf2klems
53			produces a Klems matrix representation of a
54			bidirectional scattering distribution function (BSDF)
55			based on an intermediate representation (in the first form),
56			an input XML representation (in the second form),
57			or a functional description (in the third form).
58			A complete XML description is written to the standard output,
59			which is normally redirected to a file.
60			.PP
61			The Klems matrix representation divides the input and output
62			hemisphere into a default 145 patches.
63			The
64			.I \-h
65			option may be used to reduce this number to 73 patches per hemisphere.
66			The
67			.I \-q
68			option may be used to reduce this number to 41 patches.
69			Neither option is recommended unless the distribution is known to
70			be approximately diffuse.
71	greg	1.4	.PP
72			The
73			.I \-p
74			option by itself turns off the progress bar, whose length may be set
75			by an immediately following integer argument.
76			(The default progress bar length is 79 characters.)\0
77			.PP
78	greg	1.3	The
79			.I \-l
80			option may be used to specify the maximum number of lobes in any
81			interpolated radial basis function.
82			The default value is 15000, which generally keeps the interpolation tractable.
83			Setting the value to 0 turns off this limit.
84	greg	1.1	.PP
85			Normally, multiple samples are taken from random points on each input
86			and output patch to improve accuracy.
87			The number of samples to take for each input-output patch pair may
88			be controlled using the
89			.I \-n
90	greg	1.7	option, which defaults to 1024.
91	greg	1.1	.PP
92			The first invocation form takes a intermediate scattering representation
93			as produced by
94			.I pabopto2bsdf(1)
95			or similar, and produces a Klems representation with as many
96			components as there are independent input distributions.
97			Each intermediate scattering file contains one of
98			the four components, and if the first component
99			is isotropic, all components must be isotropic.
100			A similar rule holds for anisotropic inputs.
101			Only the center of each incident patches is sampled, due to
102			the time required to interpolate incident positions.
103			.PP
104			In the second invocation form, an input XML representation
105			is resampled to produce the desired Klems matrix representation.
106			This is primarily used to convert a tensor tree representation
107			into a matrix for annual daylighting simulations.
108			Any components in the input are reproduced on output, and inline
109			geometric descriptions are passed unchanged.
110			.PP
111			In the third invocation form,
112			.I bsdf2klems
113			takes a functional specification of a BSDF.
114	greg	1.2	The named function should accept 6 parameters corresponding to the
115	greg	1.1	normalized incident and exiting vectors, respectively.
116			By convention, these vectors point away from the surface, and a positive
117			Z-component corresponds to the front side.
118			The Y-component corresponds to the "up" orientation of the surface,
119			as specified in the eventual scene description that references the XML
120			output.
121	greg	1.2	If the function only takes 3 parameters, then the variables "Dx", "Dy",
122			and "Dz" will be assigned to the reverse of the outgoing direction at
123			each evaluation.
124			(I.e., the vector will point into the surface and
125			Dz will be negative on the front side.)\0
126			This simplifies conversion of functional BSDF specifications using the
127			legacy material primitives "plasfunc", "metfunc", and "transfunc".
128	greg	1.1	.PP
129			The function is defined by one or more
130			.I \-e
131			and
132			.I \-f
133			options, and should obey both Helmholtz reciprocity and
134			integrate to less than 1 over each projected incident hemisphere
135			for energy conservation.
136	greg	1.6	The variable and function definitions in each
137			.I \-f source
138			file are read and compiled from the RADIANCE library where it is found.
139	greg	1.1	.PP
140			Similar to the
141			.I genBSDF(1)
142			command,
143			the
144			.I \+backward
145			option (default) specifies that rays arriving from the front side of
146			the surface will be tested for reflection and transmission.
147			If both forward and backward (front and back) distributions are needed, the
148			.I \+forward
149			option may be given.
150			To turn off the backward components, use the
151			.I \-backward
152			option.
153			Computing both incident hemispheres takes about twice as long as one, but
154			is recommended when rays will be impinging from either side.
155			.SH EXAMPLE
156			To take two components of an intermediate BSDF representation and create
157			a full Klems matrix representation:
158			.IP "" .2i
159			bsdf2klems transmitted.sir reflected.sir > combined.xml
160			.PP
161			To reduce a tensor tree representation into a half-Klems matrix representation:
162			.IP "" .2i
163			bsdf2klems -h ttree.xml > klems_half.xml
164			.PP
165			To create a low-res BSDF corresponding to a one-sided,
166			isotropic Phong distribution:
167			.IP "" .2i
168			bsdf2klems -e 'phong(ix,iy,iz,ox,oy,oz) = if(iz, .1+((iz+oz)/sqrt((ix+ox)^2+(iy+oy)^2+(iz+oz)^2))^50, 0)' phong > phong.xml
169	greg	1.6	.SH ENVIRONMENT
170			RAYPATH the directories to check for auxiliary files.
171	greg	1.1	.SH AUTHOR
172			Greg Ward
173			.SH "SEE ALSO"
174			bsdf2ttree(1), dctimestep(1), icalc(1), gendaymtx(1), genklemsamp(1),
175	greg	1.8	genskyvec(1), mkillum(1), genBSDF(1), pabopto2bsdf(1), pabopto2xyz(1),
176			pkgBSDF(1), rcontrib(1), rfluxmtx(1), rmtxop(1), wrapBSDF(1)