man/man1/rfluxmtx.1

.\" RCSid "$Id: rfluxmtx.1,v 1.7 2015/03/12 18:24:11 greg Exp $"
.TH RFLUXMTX 1 07/22/14 RADIANCE
.SH NAME
rfluxmtx - compute flux transfer matrix(es) for RADIANCE scene
.SH SYNOPSIS
.B rfluxmtx
[
.B \-v
][
.B "rcontrib options"
]
.B "{ sender.rad | - }"
.B receivers.rad
.B "[ -i system.oct ]"
.B "[ system.rad .. ]"
.SH DESCRIPTION
.I Rfluxmtx
samples rays uniformly over the surface given in
.I sender.rad
and records rays arriving at surfaces in the file
.I receivers.rad,
producing a flux transfer matrix per receiver.
A system octree to which the receivers will be appended may be given with a
.I \-i
option following the receiver file.
Additional system surfaces may be given in one or more
.I system.rad
files, which are compiled before the receiver file into an octree sent to the
.I rcontrib(1)
program to do the actual work.
If a single hyphen ('-') is given in place of the sender file, then
.I rfluxmtx
passes ray samples from its standard input directly to
.I rcontrib
without interpretation.
By default, all resulting matrix data are interleaved and sent to the standard output
in ASCII format, but this behavior is typically overridden using inline options
as described below.
.PP
The
.I \-v
option turns on verbose reporting for the number of samples and the executed
.I rcontrib
command.
All other supported options are passed on to
.I rcontrib(1).
However, the
.I \-f,
.I \-e,
.I \-p,
.I \-b,
.I \-bn,
.I \-m,
and
.I \-M
options are controlled by
.I rfluxmtx
and may not be set by the user.
Also, the
.I \-x,
.I \-y,
and
.I \-ld
options are ignored unless
.I rfluxmtx
is invoked in the pass-through mode,
in which case they may be needed to generate RADIANCE views from
.I vwrays(1).
The sample count, unless set by the
.I \-c
option, defaults to 10000 when a sender file is given, or to 1 for pass-through mode.
.SH VARIABLES
The sender and receiver scene files given to
.I rfluxmtx
contain controlling parameters in special comments of the form:
.nf

        #@rfluxmtx variable=value ..

.fi
At minimum, both sender and receiver must specify one of the
hemisphere sampling types, and there must be at least
one surface in each file.
.TP 10n
.BI h =u
Set hemisphere sampling to "uniform," meaning a single bin
of (cosine-distributed) samples.
In the case of distant "source" primitives, this is the only
sampling method that supports arbitrary receiver sizes.
The other methods below require a full hemispherical source.
.TP
.BI h =kf
Divide the hemisphere using the LBNL/Klems "full" sampling basis.
(Use "h=-kf" for left-handed coordinates.)
.TP
.BI h =kh
Divide the hemisphere using the LBNL/Klems "half" sampling basis.
(Use "h=-kh" for left-handed coordinates.)
.TP
.BI h =kq
Divide the hemisphere using the LBNL/Klems "quarter" sampling basis.
(Use "h=-kq" for left-handed coordinates.)
.TP
.BI h =rN
Divide the hemisphere using Reinhart's substructuring of the Tregenza
sky pattern with
.I N
divisions in each dimension.
If it is not given,
.I N
defaults to 1, which is just the Tregenza sky.
(Use "h=-rN" for left-handed coordinates.)
.TP
.BI h =scN
Subdivide the hemisphere using the Shirley-Chiu square-to-disk mapping with an
.I NxN
grid over the square.
(Use "h=-scN" for left-handed coordinates.)
.TP
.BI u =[-]{X|Y|Z|ux,uy,uz}
Orient the "up" direction for the hemisphere using the indicated axis or direction
vector.
.TP
.BI o =output.mtx
Send the matrix data for this receiver to the indicated output file.
The file format will be determined by the command-line
.I \-fio
option and will include an information header unless the
.I \-h
option was used to turn headers off.
(The output file specification is ignored for senders.)\0
.PP
In normal execution, only a single sender surface is sampled, but it may be
comprised of any number of subsurfaces, as in a triangle mesh or similar.
The surface normal will be computed as the average of all the constituent
subsurfaces.
The subsurfaces themselves must be planar, thus only
.I polygon
and
.I ring
surface primitives are supported.
Other primitives will be silently ignored and will have no effect on the calculation.
.PP
In the receiver file, the
.I source
primitive is supported as well, and multiple receivers (and multiple output
matrices) may be identified by different modifier names.
(Make sure that surfaces using the same modifier are grouped together.)\0
Though it may be counter-intuitive, receivers are often light sources,
since samples end up there in a backwards ray-tracing system such as RADIANCE.
When using local geometry, the overall aperture shape should be close to flat.
Large displacements may give rise to errors due to a convex receiver's
larger profile at low angles of incidence.
.PP
Rays always emanate from the back side of the sender surface and arrive at the
front side of receiver surfaces.
In this way, a receiver surface may be reused as a sender in a subsequent
.I rfluxmtx
calculation and the resulting matrices will concatenate properly.
(Note that it is important to keep receiver surfaces together, otherwise a
"duplicate modifier" error will result.)\0
.SH EXAMPLES
To generate a flux transfer matrix connecting input and output apertures
on a light pipe:
.IP "" .3i
rfluxmtx int_aperture.rad ext_aperture.rad lpipe.rad > lpipe.mtx
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
genBSDF(1), getinfo(1), rcalc(1), rcollate(1), rcontrib(1), rmtxop(1),
vwrays(1), wrapBSDF(1)
Revision:	1.8
Committed:	Fri Mar 27 18:58:06 2015 UTC (10 years, 1 month ago) by greg
Branch:	MAIN
CVS Tags:	rad5R0
Changes since 1.7:	+6 -1 lines
Log Message:	Hopeful fix to bugs in genBSDF due to lack of left-handed coordinates
#	User	Rev	Content
1	greg	1.8	.\" RCSid "$Id: rfluxmtx.1,v 1.7 2015/03/12 18:24:11 greg Exp $"
2	greg	1.1	.TH RFLUXMTX 1 07/22/14 RADIANCE
3			.SH NAME
4			rfluxmtx - compute flux transfer matrix(es) for RADIANCE scene
5			.SH SYNOPSIS
6			.B rfluxmtx
7			[
8			.B \-v
9			][
10			.B "rcontrib options"
11			]
12			.B "{ sender.rad \| - }"
13			.B receivers.rad
14	greg	1.4	.B "[ -i system.oct ]"
15			.B "[ system.rad .. ]"
16	greg	1.1	.SH DESCRIPTION
17			.I Rfluxmtx
18			samples rays uniformly over the surface given in
19			.I sender.rad
20			and records rays arriving at surfaces in the file
21			.I receivers.rad,
22			producing a flux transfer matrix per receiver.
23	greg	1.4	A system octree to which the receivers will be appended may be given with a
24			.I \-i
25			option following the receiver file.
26			Additional system surfaces may be given in one or more
27			.I system.rad
28			files, which are compiled before the receiver file into an octree sent to the
29	greg	1.1	.I rcontrib(1)
30			program to do the actual work.
31			If a single hyphen ('-') is given in place of the sender file, then
32			.I rfluxmtx
33			passes ray samples from its standard input directly to
34			.I rcontrib
35			without interpretation.
36			By default, all resulting matrix data are interleaved and sent to the standard output
37			in ASCII format, but this behavior is typically overridden using inline options
38			as described below.
39			.PP
40			The
41			.I \-v
42			option turns on verbose reporting for the number of samples and the executed
43			.I rcontrib
44			command.
45			All other supported options are passed on to
46			.I rcontrib(1).
47			However, the
48			.I \-f,
49			.I \-e,
50			.I \-p,
51			.I \-b,
52			.I \-bn,
53			.I \-m,
54			and
55			.I \-M
56			options are controlled by
57			.I rfluxmtx
58			and may not be set by the user.
59			Also, the
60			.I \-x,
61			.I \-y,
62			and
63			.I \-ld
64			options are ignored unless
65			.I rfluxmtx
66			is invoked in the pass-through mode,
67			in which case they may be needed to generate RADIANCE views from
68			.I vwrays(1).
69			The sample count, unless set by the
70			.I \-c
71	greg	1.2	option, defaults to 10000 when a sender file is given, or to 1 for pass-through mode.
72	greg	1.1	.SH VARIABLES
73			The sender and receiver scene files given to
74			.I rfluxmtx
75	greg	1.3	contain controlling parameters in special comments of the form:
76	greg	1.1	.nf
77
78			#@rfluxmtx variable=value ..
79
80			.fi
81			At minimum, both sender and receiver must specify one of the
82			hemisphere sampling types, and there must be at least
83			one surface in each file.
84			.TP 10n
85			.BI h =u
86			Set hemisphere sampling to "uniform," meaning a single bin
87			of (cosine-distributed) samples.
88	greg	1.3	In the case of distant "source" primitives, this is the only
89	greg	1.1	sampling method that supports arbitrary receiver sizes.
90			The other methods below require a full hemispherical source.
91			.TP
92			.BI h =kf
93			Divide the hemisphere using the LBNL/Klems "full" sampling basis.
94	greg	1.8	(Use "h=-kf" for left-handed coordinates.)
95	greg	1.1	.TP
96			.BI h =kh
97			Divide the hemisphere using the LBNL/Klems "half" sampling basis.
98	greg	1.8	(Use "h=-kh" for left-handed coordinates.)
99	greg	1.1	.TP
100			.BI h =kq
101			Divide the hemisphere using the LBNL/Klems "quarter" sampling basis.
102	greg	1.8	(Use "h=-kq" for left-handed coordinates.)
103	greg	1.1	.TP
104			.BI h =rN
105			Divide the hemisphere using Reinhart's substructuring of the Tregenza
106			sky pattern with
107			.I N
108			divisions in each dimension.
109			If it is not given,
110			.I N
111			defaults to 1, which is just the Tregenza sky.
112	greg	1.8	(Use "h=-rN" for left-handed coordinates.)
113	greg	1.1	.TP
114			.BI h =scN
115			Subdivide the hemisphere using the Shirley-Chiu square-to-disk mapping with an
116			.I NxN
117			grid over the square.
118	greg	1.8	(Use "h=-scN" for left-handed coordinates.)
119	greg	1.1	.TP
120			.BI u =[-]{X\|Y\|Z\|ux,uy,uz}
121			Orient the "up" direction for the hemisphere using the indicated axis or direction
122			vector.
123			.TP
124			.BI o =output.mtx
125			Send the matrix data for this receiver to the indicated output file.
126			The file format will be determined by the command-line
127			.I \-fio
128			option and will include an information header unless the
129			.I \-h
130			option was used to turn headers off.
131			(The output file specification is ignored for senders.)\0
132			.PP
133			In normal execution, only a single sender surface is sampled, but it may be
134			comprised of any number of subsurfaces, as in a triangle mesh or similar.
135			The surface normal will be computed as the average of all the constituent
136			subsurfaces.
137	greg	1.2	The subsurfaces themselves must be planar, thus only
138	greg	1.1	.I polygon
139			and
140			.I ring
141			surface primitives are supported.
142			Other primitives will be silently ignored and will have no effect on the calculation.
143			.PP
144			In the receiver file, the
145			.I source
146			primitive is supported as well, and multiple receivers (and multiple output
147	greg	1.7	matrices) may be identified by different modifier names.
148			(Make sure that surfaces using the same modifier are grouped together.)\0
149	greg	1.1	Though it may be counter-intuitive, receivers are often light sources,
150			since samples end up there in a backwards ray-tracing system such as RADIANCE.
151	greg	1.2	When using local geometry, the overall aperture shape should be close to flat.
152			Large displacements may give rise to errors due to a convex receiver's
153			larger profile at low angles of incidence.
154	greg	1.1	.PP
155	greg	1.3	Rays always emanate from the back side of the sender surface and arrive at the
156	greg	1.1	front side of receiver surfaces.
157			In this way, a receiver surface may be reused as a sender in a subsequent
158			.I rfluxmtx
159			calculation and the resulting matrices will concatenate properly.
160			(Note that it is important to keep receiver surfaces together, otherwise a
161			"duplicate modifier" error will result.)\0
162			.SH EXAMPLES
163			To generate a flux transfer matrix connecting input and output apertures
164			on a light pipe:
165			.IP "" .3i
166	greg	1.5	rfluxmtx int_aperture.rad ext_aperture.rad lpipe.rad > lpipe.mtx
167	greg	1.1	.SH AUTHOR
168			Greg Ward
169			.SH "SEE ALSO"
170	greg	1.6	genBSDF(1), getinfo(1), rcalc(1), rcollate(1), rcontrib(1), rmtxop(1),
171			vwrays(1), wrapBSDF(1)