man/man1/bsdf2ttree.1

.\" RCSid $Id: bsdf2ttree.1,v 1.12 2023/09/12 16:40:57 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 "\-n nss"
][
.B "\-s thresh"
][
.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 "\-n nss"
][
.B "\-s thresh"
][
.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 on reciprocity averaging for isotropic scattering or anisotropic reflection.
Normally off (-a), this enforces each tensor-tree hemisphere to follow symmetry
implied by Helmholtz reciprocity, and is designed to reduce noise in measured data.
However, for some data, reciprocity averaging can make the output worse.
.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
.I \-n
option controls the number of super-samples to send in patches whose
difference to its neighbors exceeds some threshold.
The default number of super-samples is 64.
The difference threshold for super-sampling is controlled by the
.I \-s
option, and defaults to 0.35.
.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.
Parameter options may be altered between input files, in case a different
resolution or culling percentage is indicated for transmission versus
reflection for example.
.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.
The variable and function definitions in each
.I \-f source
file are read and compiled from the RADIANCE library where it is found.
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 on transmission and 95%
culling on reflection:
.IP "" .2i
bsdf2ttree -g 7 -t 85 transmitted.sir -t 95 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 ENVIRONMENT
RAYPATH         the directories to check for auxiliary files.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
bsdf2klems(1), icalc(1), genBSDF(1), pabopto2bsdf(1), pabopto2xyz(1),
pkgBSDF(1), rcontrib(1), rfluxmtx(1), wrapBSDF(1)
Revision:	1.13
Committed:	Wed May 21 20:42:48 2025 UTC (5 months, 2 weeks ago) by greg
Branch:	MAIN
CVS Tags:	rad6R0, HEAD
Changes since 1.12:	+2 -2 lines
Log Message:	perf(bsdf2ttree): Changed default -n from 256 down to 64 for faster calcs
#	User	Rev	Content
1	greg	1.13	.\" RCSid $Id: bsdf2ttree.1,v 1.12 2023/09/12 16:40:57 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	greg	1.8	.B "\-n nss"
17			][
18			.B "\-s thresh"
19			][
20	greg	1.3	.B "\-l maxlobes"
21	greg	1.9	][
22	greg	1.1	.B "bsdf.sir .."
23			]
24			.br
25			or
26			.br
27			.B bsdf2ttree
28			.B "\-t{3\|4}"
29			[
30	greg	1.4	.B "\-pC"
31			][
32	greg	1.6	.B "{+\|-}a"
33			][
34	greg	1.1	.B "\-g Nlog2"
35			][
36	greg	1.3	.B "\-t pctcull"
37	greg	1.1	][
38	greg	1.8	.B "\-n nss"
39			][
40			.B "\-s thresh"
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 Bsdf2ttree
53			produces a tensor tree representation of a
54			bidirectional scattering distribution function (BSDF)
55			based on an intermediate representation (in the first form) or
56			a functional description (in the second form).
57			A complete XML description is written to the standard output,
58			which is normally redirected to a file.
59			.PP
60	greg	1.4	The
61			.I \-p
62			option by itself turns off the progress bar, whose length may be set
63			by an immediately following integer argument.
64			(The default progress bar length is 79 characters.)\0
65			.PP
66	greg	1.6	The
67	greg	1.12	.I \+a
68			option turns on reciprocity averaging for isotropic scattering or anisotropic reflection.
69			Normally off (-a), this enforces each tensor-tree hemisphere to follow symmetry
70	greg	1.11	implied by Helmholtz reciprocity, and is designed to reduce noise in measured data.
71	greg	1.12	However, for some data, reciprocity averaging can make the output worse.
72	greg	1.6	.PP
73	greg	1.1	The maximum resolution of the tensor tree may be controlled by the
74			.I \-g
75			option, which defaults to a value of 6.
76			This corresponds to a peak resolution of 2^6 (64) in each dimension.
77			Due to memory and time constraints, it is not recommended to set
78			.I \-g
79			higher than 7, which corresponds to a 128x128x128x128 initial sampling,
80			or 268 million values.
81			.PP
82			The initial sampling is pared down by the percentage specified with the
83			.I \-t
84			option, which defaults to 90.
85			Setting this parameter to -1 turns culling off entirely, which may be
86			useful for comparisons.
87			.PP
88	greg	1.8	The
89			.I \-n
90			option controls the number of super-samples to send in patches whose
91			difference to its neighbors exceeds some threshold.
92	greg	1.13	The default number of super-samples is 64.
93	greg	1.8	The difference threshold for super-sampling is controlled by the
94			.I \-s
95			option, and defaults to 0.35.
96			.PP
97	greg	1.1	The first invocation form takes a intermediate scattering representation
98			as produced by
99			.I pabopto2bsdf(1)
100			or similar, and produces a tensor tree representation with as many
101			components as there are independent input distributions.
102			Each intermediate scattering file contains one of
103			the four components, and if the first component
104			is isotropic, all components must be isotropic.
105			A similar rule holds for anisotropic inputs.
106	greg	1.3	The
107			.I \-l
108			option may be used to specify the maximum number of lobes in any
109			interpolated radial basis function.
110			The default value is 15000, which generally keeps the interpolation tractable.
111			Setting the value to 0 turns off this limit.
112	greg	1.9	Parameter options may be altered between input files, in case a different
113			resolution or culling percentage is indicated for transmission versus
114			reflection for example.
115	greg	1.1	.PP
116			In the second invocation form,
117			.I bsdf2ttree
118			takes a functional specification of a BSDF.
119	greg	1.2	The named function should accept 6 parameters corresponding to the
120	greg	1.1	normalized incident and exiting vectors, respectively.
121			By convention, these vectors point away from the surface, and a positive
122			Z-component corresponds to the front side.
123			The Y-component corresponds to the "up" orientation of the surface,
124			as specified in the eventual scene description that references the XML
125			output.
126	greg	1.2	If the function only takes 3 parameters, then the variables "Dx", "Dy",
127			and "Dz" will be assigned to the reverse of the outgoing direction at
128			each evaluation.
129			(I.e., the vector will point into the surface and
130			Dz will be negative on the front side.)\0
131			This simplifies conversion of functional BSDF specifications using the
132			legacy material primitives "plasfunc", "metfunc", and "transfunc".
133	greg	1.1	.PP
134			The function is defined by one or more
135			.I \-e
136			and
137			.I \-f
138			options, and should obey both Helmholtz reciprocity and
139			integrate to less than 1 over each projected incident hemisphere
140			for energy conservation.
141	greg	1.7	The variable and function definitions in each
142			.I \-f source
143			file are read and compiled from the RADIANCE library where it is found.
144	greg	1.1	If the
145			.I \-t3
146			option is specified, the defined function is assumed to be isotropic.
147			If the
148			.I \-t4
149			option is given, the function is assumed to be anisotropic.
150			.PP
151			Similar to the
152			.I genBSDF(1)
153			command,
154			the
155			.I \+backward
156			option (default) specifies that rays arriving from the front side of
157			the surface will be tested for reflection and transmission.
158			If both forward and backward (front and back) distributions are needed, the
159			.I \+forward
160			option may be given.
161			To turn off the backward components, use the
162			.I \-backward
163			option.
164			Computing both incident hemispheres takes about twice as long as one, but
165			is recommended when rays will be impinging from either side.
166			.SH EXAMPLE
167			To take two components of an intermediate BSDF representation and create
168	greg	1.9	a high-resolution tensor tree with 85% culling on transmission and 95%
169			culling on reflection:
170	greg	1.1	.IP "" .2i
171	greg	1.9	bsdf2ttree -g 7 -t 85 transmitted.sir -t 95 reflected.sir > combined.xml
172	greg	1.1	.PP
173			To create a low-res BSDF corresponding to a one-sided,
174			isotropic Phong distribution:
175			.IP "" .2i
176			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
177	greg	1.7	.SH ENVIRONMENT
178			RAYPATH the directories to check for auxiliary files.
179	greg	1.1	.SH AUTHOR
180			Greg Ward
181			.SH "SEE ALSO"
182	greg	1.10	bsdf2klems(1), icalc(1), genBSDF(1), pabopto2bsdf(1), pabopto2xyz(1),
183			pkgBSDF(1), rcontrib(1), rfluxmtx(1), wrapBSDF(1)