man/man1/bsdf2klems.1

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