man/man1/bsdf2ttree.1

.\" RCSid $Id: bsdf2ttree.1,v 1.7 2018/05/04 23:56:49 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 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
.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 256.
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.
.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:
.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 ENVIRONMENT
RAYPATH         the directories to check for auxiliary files.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
bsdf2klems(1), icalc(1), genBSDF(1), pkgBSDF(1), rcontrib(1),
rfluxmtx(1), wrapBSDF(1)
Revision:	1.8
Committed:	Mon May 18 20:08:57 2020 UTC (5 years, 1 month ago) by greg
Branch:	MAIN
CVS Tags:	rad5R3
Changes since 1.7:	+18 -1 lines
Log Message:	Added -n and -s options to bsdf2ttree to control super-sampling
#	Content
1	.\" RCSid $Id: bsdf2ttree.1,v 1.7 2018/05/04 23:56:49 greg Exp $
2	.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	.B "\-pC"
9	][
10	.B "{+\|-}a"
11	][
12	.B "\-g Nlog2"
13	][
14	.B "\-t pctcull"
15	][
16	.B "\-n nss"
17	][
18	.B "\-s thresh"
19	][
20	.B "\-l maxlobes"
21	]
22	[
23	.B "bsdf.sir .."
24	]
25	.br
26	or
27	.br
28	.B bsdf2ttree
29	.B "\-t{3\|4}"
30	[
31	.B "\-pC"
32	][
33	.B "{+\|-}a"
34	][
35	.B "\-g Nlog2"
36	][
37	.B "\-t pctcull"
38	][
39	.B "\-n nss"
40	][
41	.B "\-s thresh"
42	][
43	.B "{+\|-}forward"
44	][
45	.B "{+\|-}backward"
46	][
47	.B "\-e expr"
48	][
49	.B "\-f file"
50	]
51	.B bsdf_func
52	.SH DESCRIPTION
53	.I Bsdf2ttree
54	produces a tensor tree representation of a
55	bidirectional scattering distribution function (BSDF)
56	based on an intermediate representation (in the first form) or
57	a functional description (in the second form).
58	A complete XML description is written to the standard output,
59	which is normally redirected to a file.
60	.PP
61	The
62	.I \-p
63	option by itself turns off the progress bar, whose length may be set
64	by an immediately following integer argument.
65	(The default progress bar length is 79 characters.)\0
66	.PP
67	The
68	.I \-a
69	option turns off reciprocity averaging for isotropic scattering or anisotropic reflection.
70	Normally on (+a), this ensures that the tensor BRDF obeys Helmholtz reciprocity.
71	However, in certain rare cases, reciprocity averaging can cause unwanted noise in the output.
72	.PP
73	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	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	The default number of super-samples is 256.
93	The difference threshold for super-sampling is controlled by the
94	.I \-s
95	option, and defaults to 0.35.
96	.PP
97	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	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	.PP
113	In the second invocation form,
114	.I bsdf2ttree
115	takes a functional specification of a BSDF.
116	The named function should accept 6 parameters corresponding to the
117	normalized incident and exiting vectors, respectively.
118	By convention, these vectors point away from the surface, and a positive
119	Z-component corresponds to the front side.
120	The Y-component corresponds to the "up" orientation of the surface,
121	as specified in the eventual scene description that references the XML
122	output.
123	If the function only takes 3 parameters, then the variables "Dx", "Dy",
124	and "Dz" will be assigned to the reverse of the outgoing direction at
125	each evaluation.
126	(I.e., the vector will point into the surface and
127	Dz will be negative on the front side.)\0
128	This simplifies conversion of functional BSDF specifications using the
129	legacy material primitives "plasfunc", "metfunc", and "transfunc".
130	.PP
131	The function is defined by one or more
132	.I \-e
133	and
134	.I \-f
135	options, and should obey both Helmholtz reciprocity and
136	integrate to less than 1 over each projected incident hemisphere
137	for energy conservation.
138	The variable and function definitions in each
139	.I \-f source
140	file are read and compiled from the RADIANCE library where it is found.
141	If the
142	.I \-t3
143	option is specified, the defined function is assumed to be isotropic.
144	If the
145	.I \-t4
146	option is given, the function is assumed to be anisotropic.
147	.PP
148	Similar to the
149	.I genBSDF(1)
150	command,
151	the
152	.I \+backward
153	option (default) specifies that rays arriving from the front side of
154	the surface will be tested for reflection and transmission.
155	If both forward and backward (front and back) distributions are needed, the
156	.I \+forward
157	option may be given.
158	To turn off the backward components, use the
159	.I \-backward
160	option.
161	Computing both incident hemispheres takes about twice as long as one, but
162	is recommended when rays will be impinging from either side.
163	.SH EXAMPLE
164	To take two components of an intermediate BSDF representation and create
165	a high-resolution tensor tree with 85% culling:
166	.IP "" .2i
167	bsdf2ttree -g 7 -t 85 transmitted.sir reflected.sir > combined.xml
168	.PP
169	To create a low-res BSDF corresponding to a one-sided,
170	isotropic Phong distribution:
171	.IP "" .2i
172	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
173	.SH ENVIRONMENT
174	RAYPATH the directories to check for auxiliary files.
175	.SH AUTHOR
176	Greg Ward
177	.SH "SEE ALSO"
178	bsdf2klems(1), icalc(1), genBSDF(1), pkgBSDF(1), rcontrib(1),
179	rfluxmtx(1), wrapBSDF(1)