man/man1/bsdf2klems.1

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