man/man1/genBSDF.1

.\" RCSid $Id: genBSDF.1,v 1.23 2023/12/12 16:31:45 greg Exp $
.TH GENBSDF 1 9/3/2010 RADIANCE
.SH NAME
genBSDF - generate BSDF description from Radiance or MGF input
.SH SYNOPSIS
.B genBSDF
[
.B "\-c Nsamp"
][
.B "\-n Nproc"
][
.B "\-r 'rcontrib opts...'"
][
.B "\-W"
][
.B "\-s 'x=string;y=string'"
][
.B "\-t{3|4} Nlog2"
][
.B "{+|-}C"
][
.B "{+|-}a"
][
.B "{+|-}forward"
][
.B "{+|-}backward"
][
.B "{+|-}mgf"
][
.B "{+|-}geom unit"
][
.B "\-dim Xmin Xmax Ymin Ymax Zmin Zmax"
]
[
.B "geom .."
]
.br
or
.br
.B genBSDF
.B "\-recover tempdir"
.SH DESCRIPTION
.I GenBSDF
computes a bidirectional scattering distribution function from
a Radiance or MGF scene description given on the input.
The program assumes the input is in Radiance format unless the
.I \+mgf
option is specified.
The output conforms to the LBNL Window 6 XML standard for BSDF data,
and will include an MGF representation of the input geometry if the
.I \+geom
option is given, followed by one of "meter," "foot," "inch,"
"centimeter," or "millimeter," depending on the scene units.
The default is to include the provided geometry,
which is assumed to be in meters.
Geometry output can be supressed with the
.I \-geom
option, which must also be followed by one of the above length units.
.PP
Normally,
.I genBSDF
computes components needed by a backwards ray-tracing process,
.I \+backward.
If both forward and backward (front and back) distributions are needed, the
.I \+forward
option may be given.
To turn off backward components, use the
.I \-backward
option.
Computing both components takes about twice as long as one component, but
is recommended when rays will be impinging from either side.
.PP
The
.I \+C
option specifies that the output XML should include tristimulus
color information, which is interpreted by the rendering programs.
The default option
.I \-C
reduces all BSDF data to grayscale.
If the input is spectral and a
.I \-cs
parameter of 9 or more is specified as part of the rendering
.I \-r
option list, then full spectral result will be 
reduced to an XYZ-equivalent CIE color space in the XML output.
.PP
The
.I \-a
option turns off reciprocity averaging for tensor tree output.
Normally on (+a), this ensures that each tensor-tree hemisphere follows symmetry
implied by Helmholtz reciprocity, and is designed to reduce ray sampling noise.
However, for some systems, reciprocity averaging can actually make the output worse.
.PP
The geometry must fit a rectangular profile, whose width is along the X-axis,
height is in the Y-axis, and depth is in the Z-axis.
The positive Z-axis points into the room, and the input geometry should
not extend into the room.
(I.e., it should not contain any positive Z values, since the putative 
emitting surface is assumed to lie at Z=0.)\0
The entire window system should be modeled, including sills and
edge geometry anticipated in the final installation, otherwise
accuracy will be impaired.
Similarly, materials in the description should be carefully measured.
.PP
Normally, the input geometry will be positioned according to its actual
bounding box, but this may be overridden with the
.I \-dim
option.
Use this in cases where the fenestration system is designed to fit a
smaller (or larger) opening or is offset somehow.
.PP
The variance in the results may be reduced by increasing the number of
samples per incident direction using the
.I \-c
option.
This value defaults to 2000 samples distributed over the incoming plane
for each of the 145 Klems hemisphere directions.
.PP
On multi-core machines, processing time may be reduced by the
.I \-n
option, which specifies the number of simultaneous
processes to run in
.I rcontrib(1).
The
.I \-r
option may be used to specify a set of quoted arguments to be
included on the
.I rcontrib
command line.
.PP
The
.I \-W
option is passed to
.I wrapBSDF(1)
to prepare the XML file for WINDOW6.
Any
.I \-s
parameters are passed to the
.I \-f
option of
.I wrapBSDF,
controlling XML fields such as
the Manufacturer (e.g., -s m=MF) and device Name (e.g, -s n=NM).
.PP
The
.I \-t4
mode computes a non-uniform BSDF represented as a rank 4 tensor tree,
suitable for use in the Radiance rendering tools.
The parameter given to this option is the log to the base 2 of the
sampling resolution in each dimension, and must be an integer.
The
.I \-c
setting should be adjusted so that an appropriate number of samples
lands in each region.
A
.I \-t4
parameter of 5 corresponds to 32x32 or 1024 output regions, so a
.I \-c
setting of 10240 would provide 10 samples per region on average.
Increasing the resolution to 6 corresponds to 64x64 or 4096
regions, so the
.I \-c
setting would need to be increased by a factor of 4 to provide
the same accuracy in each region.
.PP
The
.I \-t3
mode is similar to
.I \-t4
but computes a rank 3 tensor tree rather than rank 4.
This provides a much faster computation, but only works
in special circumstances.
Specifically, do NOT use this option if the system is not in fact isotropic.
I.e., only use
.I \-t3
when you are certain that the system has a high degree of radial symmetry.
Again, the parameter to this option sets the maximum resolution as
a power of 2 in each dimension, but in this case there is one less
dimension being sampled.
.PP
The
.I \-recover
option is available for continuing calculations that were killed by
the system or the user.
Unfortunately, genBSDF puts its temporary files in a directory
that is often cleaned up after reboot, so this may not always work.
.SH EXAMPLE
To create a BSDF description including geometry from a set of venetian blinds:
.IP "" .2i
genblinds blind_white blind1 .07 3 1.5 30 40 | xform -rz -90 -rx 90 > blind1.rad
.br
genBSDF -r @rtc.opt blind_white.mat glazing.rad blind1.rad > blind1.xml
.PP
To create a non-uniform, anisotropic BSDF distribution with a maximum
resolution of 128x128 from the same description:
.IP "" .2i
genBSDF -r @rtc.opt -t4 7 -c 160000 blind_white.mat glazing.rad blind1.rad > blind12.xml
.SH NOTES
The variable resolution (tensor tree) BSDF representation is not supported
by all software and applicatons, and should be used with caution.
It provides practical, high-resolution data for use in the
Radiance rendering programs, but does not work in the matrix formulation
of the daylight coefficient method for example.
Also, third party tools generally expect or require a fixed number of sample
directions using the Klems directions or similar.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
dctimestep(1), gendaymtx(1), genklemsamp(1), genskyvec(1), mkillum(1),
pkgBSDF(1), rcomb(1), rcontrib(1), rfluxmtx(1), rmtxop(1), rtrace(1) wrapBSDF(1)
Revision:	1.24
Committed:	Wed Apr 2 00:55:27 2025 UTC (6 months, 4 weeks ago) by greg
Branch:	MAIN
CVS Tags:	rad6R0, HEAD
Changes since 1.23:	+9 -3 lines
Log Message:	feat(genBSDF): Added support for -r "-cs M" to employ M spectral samples
#	User	Rev	Content
1	greg	1.24	.\" RCSid $Id: genBSDF.1,v 1.23 2023/12/12 16:31:45 greg Exp $
2	greg	1.1	.TH GENBSDF 1 9/3/2010 RADIANCE
3			.SH NAME
4			genBSDF - generate BSDF description from Radiance or MGF input
5			.SH SYNOPSIS
6			.B genBSDF
7			[
8			.B "\-c Nsamp"
9			][
10			.B "\-n Nproc"
11			][
12	greg	1.10	.B "\-r 'rcontrib opts...'"
13	greg	1.4	][
14	greg	1.14	.B "\-W"
15			][
16	greg	1.15	.B "\-s 'x=string;y=string'"
17	greg	1.14	][
18	greg	1.6	.B "\-t{3\|4} Nlog2"
19			][
20	greg	1.17	.B "{+\|-}C"
21			][
22	greg	1.20	.B "{+\|-}a"
23			][
24	greg	1.3	.B "{+\|-}forward"
25			][
26			.B "{+\|-}backward"
27			][
28	greg	1.1	.B "{+\|-}mgf"
29			][
30	greg	1.7	.B "{+\|-}geom unit"
31	greg	1.1	][
32			.B "\-dim Xmin Xmax Ymin Ymax Zmin Zmax"
33			]
34			[
35			.B "geom .."
36			]
37	greg	1.19	.br
38			or
39			.br
40			.B genBSDF
41			.B "\-recover tempdir"
42	greg	1.1	.SH DESCRIPTION
43			.I GenBSDF
44	greg	1.3	computes a bidirectional scattering distribution function from
45	greg	1.1	a Radiance or MGF scene description given on the input.
46			The program assumes the input is in Radiance format unless the
47			.I \+mgf
48			option is specified.
49			The output conforms to the LBNL Window 6 XML standard for BSDF data,
50			and will include an MGF representation of the input geometry if the
51			.I \+geom
52	greg	1.7	option is given, followed by one of "meter," "foot," "inch,"
53			"centimeter," or "millimeter," depending on the scene units.
54			The default is to include the provided geometry,
55			which is assumed to be in meters.
56			Geometry output can be supressed with the
57			.I \-geom
58			option, which must also be followed by one of the above length units.
59	greg	1.1	.PP
60	greg	1.3	Normally,
61			.I genBSDF
62			computes components needed by a backwards ray-tracing process,
63			.I \+backward.
64			If both forward and backward (front and back) distributions are needed, the
65			.I \+forward
66			option may be given.
67			To turn off backward components, use the
68			.I \-backward
69			option.
70	greg	1.12	Computing both components takes about twice as long as one component, but
71			is recommended when rays will be impinging from either side.
72	greg	1.3	.PP
73	greg	1.17	The
74			.I \+C
75	greg	1.24	option specifies that the output XML should include tristimulus
76			color information, which is interpreted by the rendering programs.
77	greg	1.18	The default option
78			.I \-C
79	greg	1.17	reduces all BSDF data to grayscale.
80	greg	1.24	If the input is spectral and a
81			.I \-cs
82			parameter of 9 or more is specified as part of the rendering
83			.I \-r
84			option list, then full spectral result will be
85			reduced to an XYZ-equivalent CIE color space in the XML output.
86	greg	1.17	.PP
87	greg	1.20	The
88			.I \-a
89			option turns off reciprocity averaging for tensor tree output.
90	greg	1.21	Normally on (+a), this ensures that each tensor-tree hemisphere follows symmetry
91			implied by Helmholtz reciprocity, and is designed to reduce ray sampling noise.
92			However, for some systems, reciprocity averaging can actually make the output worse.
93	greg	1.20	.PP
94	greg	1.1	The geometry must fit a rectangular profile, whose width is along the X-axis,
95			height is in the Y-axis, and depth is in the Z-axis.
96			The positive Z-axis points into the room, and the input geometry should
97			not extend into the room.
98			(I.e., it should not contain any positive Z values, since the putative
99			emitting surface is assumed to lie at Z=0.)\0
100			The entire window system should be modeled, including sills and
101			edge geometry anticipated in the final installation, otherwise
102			accuracy will be impaired.
103			Similarly, materials in the description should be carefully measured.
104			.PP
105			Normally, the input geometry will be positioned according to its actual
106			bounding box, but this may be overridden with the
107			.I \-dim
108			option.
109			Use this in cases where the fenestration system is designed to fit a
110			smaller (or larger) opening or is offset somehow.
111			.PP
112			The variance in the results may be reduced by increasing the number of
113			samples per incident direction using the
114			.I \-c
115			option.
116	greg	1.9	This value defaults to 2000 samples distributed over the incoming plane
117	greg	1.1	for each of the 145 Klems hemisphere directions.
118			.PP
119	greg	1.11	On multi-core machines, processing time may be reduced by the
120	greg	1.1	.I \-n
121			option, which specifies the number of simultaneous
122			processes to run in
123	greg	1.10	.I rcontrib(1).
124	greg	1.4	The
125			.I \-r
126			option may be used to specify a set of quoted arguments to be
127			included on the
128	greg	1.10	.I rcontrib
129	greg	1.4	command line.
130	greg	1.6	.PP
131			The
132	greg	1.14	.I \-W
133	greg	1.15	option is passed to
134			.I wrapBSDF(1)
135			to prepare the XML file for WINDOW6.
136			Any
137			.I \-s
138			parameters are passed to the
139	greg	1.14	.I \-f
140	greg	1.15	option of
141			.I wrapBSDF,
142			controlling XML fields such as
143			the Manufacturer (e.g., -s m=MF) and device Name (e.g, -s n=NM).
144	greg	1.14	.PP
145			The
146	greg	1.6	.I \-t4
147			mode computes a non-uniform BSDF represented as a rank 4 tensor tree,
148			suitable for use in the Radiance rendering tools.
149			The parameter given to this option is the log to the base 2 of the
150			sampling resolution in each dimension, and must be an integer.
151			The
152			.I \-c
153			setting should be adjusted so that an appropriate number of samples
154			lands in each region.
155			A
156			.I \-t4
157			parameter of 5 corresponds to 32x32 or 1024 output regions, so a
158			.I \-c
159	greg	1.9	setting of 10240 would provide 10 samples per region on average.
160	greg	1.6	Increasing the resolution to 6 corresponds to 64x64 or 4096
161			regions, so the
162			.I \-c
163			setting would need to be increased by a factor of 4 to provide
164			the same accuracy in each region.
165			.PP
166			The
167			.I \-t3
168			mode is similar to
169			.I \-t4
170			but computes a rank 3 tensor tree rather than rank 4.
171			This provides a much faster computation, but only works
172			in special circumstances.
173			Specifically, do NOT use this option if the system is not in fact isotropic.
174			I.e., only use
175			.I \-t3
176			when you are certain that the system has a high degree of radial symmetry.
177			Again, the parameter to this option sets the maximum resolution as
178			a power of 2 in each dimension, but in this case there is one less
179			dimension being sampled.
180	greg	1.19	.PP
181			The
182			.I \-recover
183			option is available for continuing calculations that were killed by
184			the system or the user.
185			Unfortunately, genBSDF puts its temporary files in a directory
186			that is often cleaned up after reboot, so this may not always work.
187	greg	1.1	.SH EXAMPLE
188			To create a BSDF description including geometry from a set of venetian blinds:
189			.IP "" .2i
190	greg	1.2	genblinds blind_white blind1 .07 3 1.5 30 40 \| xform -rz -90 -rx 90 > blind1.rad
191	greg	1.1	.br
192	greg	1.4	genBSDF -r @rtc.opt blind_white.mat glazing.rad blind1.rad > blind1.xml
193	greg	1.6	.PP
194			To create a non-uniform, anisotropic BSDF distribution with a maximum
195			resolution of 128x128 from the same description:
196			.IP "" .2i
197			genBSDF -r @rtc.opt -t4 7 -c 160000 blind_white.mat glazing.rad blind1.rad > blind12.xml
198			.SH NOTES
199			The variable resolution (tensor tree) BSDF representation is not supported
200			by all software and applicatons, and should be used with caution.
201			It provides practical, high-resolution data for use in the
202			Radiance rendering programs, but does not work in the matrix formulation
203			of the daylight coefficient method for example.
204			Also, third party tools generally expect or require a fixed number of sample
205			directions using the Klems directions or similar.
206	greg	1.1	.SH AUTHOR
207			Greg Ward
208			.SH "SEE ALSO"
209	greg	1.13	dctimestep(1), gendaymtx(1), genklemsamp(1), genskyvec(1), mkillum(1),
210	greg	1.23	pkgBSDF(1), rcomb(1), rcontrib(1), rfluxmtx(1), rmtxop(1), rtrace(1) wrapBSDF(1)