man/man1/bsdf2ttree.1

.\" RCSid $Id: bsdf2ttree.1,v 1.5 2015/02/20 18:26:08 greg Exp $
.TH BSDF2TTREE 1 4/24/2013 RADIANCE
.SH NAME
bsdf2ttree - generate XML tensor tree description of a BSDF
.SH SYNOPSIS
.B bsdf2ttree
[
.B "\-pC"
][
.B "{+|-}a"
][
.B "\-g Nlog2"
][
.B "\-t pctcull"
][
.B "\-l maxlobes"
]
[
.B "bsdf.sir .."
]
.br
or
.br
.B bsdf2ttree
.B "\-t{3|4}"
[
.B "\-pC"
][
.B "{+|-}a"
][
.B "\-g Nlog2"
][
.B "\-t pctcull"
][
.B "{+|-}forward"
][
.B "{+|-}backward"
][
.B "\-e expr"
][
.B "\-f file"
]
.B bsdf_func
.SH DESCRIPTION
.I Bsdf2ttree
produces a tensor tree representation of a
bidirectional scattering distribution function (BSDF)
based on an intermediate representation (in the first form) or
a functional description (in the second form).
A complete XML description is written to the standard output,
which is normally redirected to a file.
.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 \-a
option turns off reciprocity averaging for isotropic scattering or anisotropic reflection.
Normally on (+a), this ensures that the tensor BRDF obeys Helmholtz reciprocity.
However, in certain rare cases, reciprocity averaging can cause unwanted noise in the output.
.PP
The maximum resolution of the tensor tree may be controlled by the
.I \-g
option, which defaults to a value of 6.
This corresponds to a peak resolution of 2^6 (64) in each dimension.
Due to memory and time constraints, it is not recommended to set
.I \-g
higher than 7, which corresponds to a 128x128x128x128 initial sampling,
or 268 million values.
.PP
The initial sampling is pared down by the percentage specified with the
.I \-t
option, which defaults to 90.
Setting this parameter to -1 turns culling off entirely, which may be
useful for comparisons.
.PP
The first invocation form takes a intermediate scattering representation
as produced by
.I pabopto2bsdf(1)
or similar, and produces a tensor tree 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.
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
In the second invocation form,
.I bsdf2ttree
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.
If the
.I \-t3
option is specified, the defined function is assumed to be isotropic.
If the
.I \-t4
option is given, the function is assumed to be anisotropic.
.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 high-resolution tensor tree with 85% culling:
.IP "" .2i
bsdf2ttree -g 7 -t 85 transmitted.sir reflected.sir > combined.xml
.PP
To create a low-res BSDF corresponding to a one-sided,
isotropic Phong distribution:
.IP "" .2i
bsdf2ttree -g 5 -t3 -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"
bsdf2klems(1), icalc(1), genBSDF(1), pkgBSDF(1), rcontrib(1),
rfluxmtx(1), wrapBSDF(1)
Revision:	1.6
Committed:	Wed May 31 17:25:21 2017 UTC (7 years, 11 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R1
Changes since 1.5:	+11 -1 lines
Log Message:	Added {+\|-}a option to genBSDF and bsdf2ttree to control reciprocity averaging
#	User	Rev	Content
1	greg	1.6	.\" RCSid $Id: bsdf2ttree.1,v 1.5 2015/02/20 18:26:08 greg Exp $
2	greg	1.1	.TH BSDF2TTREE 1 4/24/2013 RADIANCE
3			.SH NAME
4			bsdf2ttree - generate XML tensor tree description of a BSDF
5			.SH SYNOPSIS
6			.B bsdf2ttree
7			[
8	greg	1.4	.B "\-pC"
9			][
10	greg	1.6	.B "{+\|-}a"
11			][
12	greg	1.1	.B "\-g Nlog2"
13			][
14	greg	1.3	.B "\-t pctcull"
15			][
16			.B "\-l maxlobes"
17	greg	1.1	]
18			[
19			.B "bsdf.sir .."
20			]
21			.br
22			or
23			.br
24			.B bsdf2ttree
25			.B "\-t{3\|4}"
26			[
27	greg	1.4	.B "\-pC"
28			][
29	greg	1.6	.B "{+\|-}a"
30			][
31	greg	1.1	.B "\-g Nlog2"
32			][
33	greg	1.3	.B "\-t pctcull"
34	greg	1.1	][
35			.B "{+\|-}forward"
36			][
37			.B "{+\|-}backward"
38			][
39	greg	1.3	.B "\-e expr"
40	greg	1.1	][
41	greg	1.3	.B "\-f file"
42	greg	1.1	]
43			.B bsdf_func
44			.SH DESCRIPTION
45			.I Bsdf2ttree
46			produces a tensor tree representation of a
47			bidirectional scattering distribution function (BSDF)
48			based on an intermediate representation (in the first form) or
49			a functional description (in the second form).
50			A complete XML description is written to the standard output,
51			which is normally redirected to a file.
52			.PP
53	greg	1.4	The
54			.I \-p
55			option by itself turns off the progress bar, whose length may be set
56			by an immediately following integer argument.
57			(The default progress bar length is 79 characters.)\0
58			.PP
59	greg	1.6	The
60			.I \-a
61			option turns off reciprocity averaging for isotropic scattering or anisotropic reflection.
62			Normally on (+a), this ensures that the tensor BRDF obeys Helmholtz reciprocity.
63			However, in certain rare cases, reciprocity averaging can cause unwanted noise in the output.
64			.PP
65	greg	1.1	The maximum resolution of the tensor tree may be controlled by the
66			.I \-g
67			option, which defaults to a value of 6.
68			This corresponds to a peak resolution of 2^6 (64) in each dimension.
69			Due to memory and time constraints, it is not recommended to set
70			.I \-g
71			higher than 7, which corresponds to a 128x128x128x128 initial sampling,
72			or 268 million values.
73			.PP
74			The initial sampling is pared down by the percentage specified with the
75			.I \-t
76			option, which defaults to 90.
77			Setting this parameter to -1 turns culling off entirely, which may be
78			useful for comparisons.
79			.PP
80			The first invocation form takes a intermediate scattering representation
81			as produced by
82			.I pabopto2bsdf(1)
83			or similar, and produces a tensor tree representation with as many
84			components as there are independent input distributions.
85			Each intermediate scattering file contains one of
86			the four components, and if the first component
87			is isotropic, all components must be isotropic.
88			A similar rule holds for anisotropic inputs.
89	greg	1.3	The
90			.I \-l
91			option may be used to specify the maximum number of lobes in any
92			interpolated radial basis function.
93			The default value is 15000, which generally keeps the interpolation tractable.
94			Setting the value to 0 turns off this limit.
95	greg	1.1	.PP
96			In the second invocation form,
97			.I bsdf2ttree
98			takes a functional specification of a BSDF.
99	greg	1.2	The named function should accept 6 parameters corresponding to the
100	greg	1.1	normalized incident and exiting vectors, respectively.
101			By convention, these vectors point away from the surface, and a positive
102			Z-component corresponds to the front side.
103			The Y-component corresponds to the "up" orientation of the surface,
104			as specified in the eventual scene description that references the XML
105			output.
106	greg	1.2	If the function only takes 3 parameters, then the variables "Dx", "Dy",
107			and "Dz" will be assigned to the reverse of the outgoing direction at
108			each evaluation.
109			(I.e., the vector will point into the surface and
110			Dz will be negative on the front side.)\0
111			This simplifies conversion of functional BSDF specifications using the
112			legacy material primitives "plasfunc", "metfunc", and "transfunc".
113	greg	1.1	.PP
114			The function is defined by one or more
115			.I \-e
116			and
117			.I \-f
118			options, and should obey both Helmholtz reciprocity and
119			integrate to less than 1 over each projected incident hemisphere
120			for energy conservation.
121			If the
122			.I \-t3
123			option is specified, the defined function is assumed to be isotropic.
124			If the
125			.I \-t4
126			option is given, the function is assumed to be anisotropic.
127			.PP
128			Similar to the
129			.I genBSDF(1)
130			command,
131			the
132			.I \+backward
133			option (default) specifies that rays arriving from the front side of
134			the surface will be tested for reflection and transmission.
135			If both forward and backward (front and back) distributions are needed, the
136			.I \+forward
137			option may be given.
138			To turn off the backward components, use the
139			.I \-backward
140			option.
141			Computing both incident hemispheres takes about twice as long as one, but
142			is recommended when rays will be impinging from either side.
143			.SH EXAMPLE
144			To take two components of an intermediate BSDF representation and create
145			a high-resolution tensor tree with 85% culling:
146			.IP "" .2i
147			bsdf2ttree -g 7 -t 85 transmitted.sir reflected.sir > combined.xml
148			.PP
149			To create a low-res BSDF corresponding to a one-sided,
150			isotropic Phong distribution:
151			.IP "" .2i
152			bsdf2ttree -g 5 -t3 -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	greg	1.5	bsdf2klems(1), icalc(1), genBSDF(1), pkgBSDF(1), rcontrib(1),
157			rfluxmtx(1), wrapBSDF(1)