man/man1/genBSDF.1

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