man/man1/rfluxmtx.1

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