man/man1/rxfluxmtx.1

.\" RCSid "$Id: rxfluxmtx.1,v 1.3 2025/11/10 23:35:55 greg Exp $"
.TH RXFLUXMTX 1 10/23/2025 RADIANCE
.SH NAME
rxfluxmtx - compute flux transfer matrix(es) for RADIANCE scene
.SH SYNOPSIS
.B rxfluxmtx
[
.B \-W
][
.B "-bj frac"
] [
.B "rcontrib options"
]
.B "{ sender.rad | view | - }"
.B receivers.rad
.B "[ -i system.oct ]"
.B "[ system.rad .. ]"
.SH DESCRIPTION
.I rxfluxmtx
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 used
to perform the simulation.
.PP
If a single hyphen ('-') is given in place of the view or sender file, then
.I rxfluxmtx
computes matrix rows based upon the provided ray sample origins and directions,
which may be surface normals if the
.I \-I+
option is applied.
The
.I \-y
option is required to specify the number of output rows for pass-through mode.
.PP
Alternatively, a view specification may be given on the command-line
to produce coefficient picture output, in which case both the
.I \-x
and
.I \-y
options must be present to set the desired picture dimensions.
The related
.I \-pj,
.I \-pd,
and
.I \-pa
options may be used to set the pixel jitter, depth-of-field, and
aspect ratio, respectively.
This avoids the need to call
.I vwrays(1),
as required by
.I rfluxmtx.
.PP
The
.I \-W+
option turns on verbose mode, and the
.I \-t
option sets the number of seconds between progress reports, similar to
.I rcontrib(1).
Likewise, the
.I \-c
option specifies the number of times to repeat each sample.
However, the
.I rcontrib
options
.I \-p,
.I \-b,
.I \-bn,
.I \-m,
and
.I \-M
options are controlled by
.I rxfluxmtx
and may not be set by the user.
.PP
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).
It is best used in combination with the
.I \-c
and
.I \-pj
options described above.
(The default jitter is 0, leaving sharp bin boundaries.)\0
.PP
The sample count, unless set by the
.I \-c
option, defaults to 10000 when a sender file is given, or to 1 for 
view and pass-through modes.
.SH VARIABLES
The sender and receiver scene files given to
.I rxfluxmtx
contain controlling parameters in special comments of the form:
.nf

        #@rxfluxmtx variable=value ..
or:
        #@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 specification.
Single or double quotes may be used to contain strings with spaces, and
the usual "%s" and "%d" formats incorporate the modifier name and/or
bin number, as with
.I rcontrib.
Command (piped) output is not supported.
.PP
If no output_spec directive is given, it must be specified by a
.I \-o
setting on the command-line, since output to stdout is not supported.
The input and output file formats are controlled by the
.I \-fio
option, which may use a single letter for identical i/o formats.
The input format matters only in pass-through mode, for which
ASCII input is supported.
The default setting is
.I \-faf.
ASCII output is unsupported, since it interferes with
efficient recovery when using the
.I \-r
option.
.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 rxfluxmtx
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
rxfluxmtx -o lpipe.mtx int_aperture.rad ext_aperture.rad lpipe.rad
.PP
To generate a set of DC view component pictures with 9 jittered samples/pixel:
.IP "" .2i
rxfluxmtx -vf v1.vf -x 512 -y 512 -c 9 -pj .8 -fc reinhart_M4.rad -i scene1.oct
.PP
To compute a workplane irradiance matrix for each window in a space:
.IP "" .2i
rxfluxmtx -faf - windows_kf.rad -i scene2.oct < workplane_pts.txt
.SH NOTES
The main differences between
.I rfluxmtx(1)
and
.I rxfluxmtx
is that the latter does not run a separate
.I rcontrib
process.
Instead, it relies on a unix-only C++ class definition that offers full
control over i/o.
This allows an unlimited number of receivers, a
.I \-r
recovery option, and streamlines operations.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
genBSDF(1), getinfo(1), pvsum(1), rcalc(1), rcollate(1), rcomb(1), rcontrib(1),
rcrop(1), rfluxmtx(1), rmtxop(1), vwrays(1), wrapBSDF(1)
Revision:	1.4
Committed:	Fri Nov 14 23:51:42 2025 UTC (23 hours, 23 minutes ago) by greg
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.3:	+18 -1 lines
Log Message:	feat(rfluxmtx,rxfluxmtx): Added bin sample jittering for smoother visual results
#	User	Rev	Content
1	greg	1.4	.\" RCSid "$Id: rxfluxmtx.1,v 1.3 2025/11/10 23:35:55 greg Exp $"
2	greg	1.1	.TH RXFLUXMTX 1 10/23/2025 RADIANCE
3			.SH NAME
4			rxfluxmtx - compute flux transfer matrix(es) for RADIANCE scene
5			.SH SYNOPSIS
6			.B rxfluxmtx
7			[
8			.B \-W
9	greg	1.4	][
10			.B "-bj frac"
11	greg	1.1	] [
12			.B "rcontrib options"
13			]
14			.B "{ sender.rad \| view \| - }"
15			.B receivers.rad
16			.B "[ -i system.oct ]"
17			.B "[ system.rad .. ]"
18			.SH DESCRIPTION
19			.I rxfluxmtx
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			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 used
31			to perform the simulation.
32			.PP
33			If a single hyphen ('-') is given in place of the view or sender file, then
34			.I rxfluxmtx
35			computes matrix rows based upon the provided ray sample origins and directions,
36			which may be surface normals if the
37			.I \-I+
38			option is applied.
39			The
40			.I \-y
41			option is required to specify the number of output rows for pass-through mode.
42			.PP
43			Alternatively, a view specification may be given on the command-line
44			to produce coefficient picture output, in which case both the
45			.I \-x
46			and
47			.I \-y
48			options must be present to set the desired picture dimensions.
49			The related
50			.I \-pj,
51			.I \-pd,
52			and
53			.I \-pa
54			options may be used to set the pixel jitter, depth-of-field, and
55			aspect ratio, respectively.
56			This avoids the need to call
57			.I vwrays(1),
58			as required by
59			.I rfluxmtx.
60			.PP
61			The
62			.I \-W+
63			option turns on verbose mode, and the
64			.I \-t
65			option sets the number of seconds between progress reports, similar to
66			.I rcontrib(1).
67	greg	1.4	Likewise, the
68			.I \-c
69			option specifies the number of times to repeat each sample.
70	greg	1.1	However, the
71			.I rcontrib
72			options
73			.I \-p,
74			.I \-b,
75			.I \-bn,
76			.I \-m,
77			and
78			.I \-M
79			options are controlled by
80			.I rxfluxmtx
81			and may not be set by the user.
82			.PP
83	greg	1.4	The
84			.I \-bj
85			option sets the amount of bin jittering, which blurs the boundaries of
86			receiver bins and is generally recommended when creating a view that may
87			include direct visibility of the receiver surface(s).
88			It is best used in combination with the
89			.I \-c
90			and
91			.I \-pj
92			options described above.
93			(The default jitter is 0, leaving sharp bin boundaries.)\0
94			.PP
95	greg	1.1	The sample count, unless set by the
96			.I \-c
97			option, defaults to 10000 when a sender file is given, or to 1 for
98			view and pass-through modes.
99			.SH VARIABLES
100			The sender and receiver scene files given to
101			.I rxfluxmtx
102			contain controlling parameters in special comments of the form:
103			.nf
104
105			#@rxfluxmtx variable=value ..
106			or:
107			#@rfluxmtx variable=value ..
108
109			.fi
110			At minimum, both sender and receiver must specify one of the
111			hemisphere sampling types, and there must be at least
112			one surface in each file.
113			.TP 10n
114			.BI h =u
115			Set hemisphere sampling to "uniform," meaning a single bin
116			of (cosine-distributed) samples.
117			In the case of distant "source" primitives, this is the only
118			sampling method that supports arbitrary receiver sizes.
119			The other methods below require a full hemispherical source.
120			.TP
121			.BI h =kf
122			Divide the hemisphere using the LBNL/Klems "full" sampling basis.
123			(Use "h=-kf" for left-handed coordinates.)
124			.TP
125			.BI h =kh
126			Divide the hemisphere using the LBNL/Klems "half" sampling basis.
127			(Use "h=-kh" for left-handed coordinates.)
128			.TP
129			.BI h =kq
130			Divide the hemisphere using the LBNL/Klems "quarter" sampling basis.
131			(Use "h=-kq" for left-handed coordinates.)
132			.TP
133			.BI h =rN
134			Divide the hemisphere using Reinhart's substructuring of the Tregenza
135			sky pattern with
136			.I N
137			divisions in each dimension.
138			If it is not given,
139			.I N
140			defaults to 1, which is just the Tregenza sky.
141			(Use "h=-rN" for left-handed coordinates.)
142			.TP
143			.BI h =cie
144			Divide the hemisphere into CIE sky scanner directions, which is
145			similar to Tregenza but with different starting azimuths and
146			reversing row direction at each new altitude.
147			(Use "h=-cie" for left-handed coordinates.)
148			.TP
149			.BI h =scN
150			Subdivide the hemisphere using the Shirley-Chiu square-to-disk mapping with an
151			.I NxN
152			grid over the square.
153			(Use "h=-scN" for left-handed coordinates.)
154			.TP
155			.BI u =[-]{X\|Y\|Z\|ux,uy,uz}
156			Orient the "up" direction for the hemisphere using the indicated axis or direction
157			vector.
158			.TP
159			.BI o =output_spec
160	greg	1.2	Send the matrix data for this receiver to the indicated file specification.
161			Single or double quotes may be used to contain strings with spaces, and
162			the usual "%s" and "%d" formats incorporate the modifier name and/or
163			bin number, as with
164			.I rcontrib.
165	greg	1.1	Command (piped) output is not supported.
166	greg	1.2	.PP
167			If no output_spec directive is given, it must be specified by a
168			.I \-o
169			setting on the command-line, since output to stdout is not supported.
170			The input and output file formats are controlled by the
171	greg	1.1	.I \-fio
172	greg	1.2	option, which may use a single letter for identical i/o formats.
173			The input format matters only in pass-through mode, for which
174	greg	1.1	ASCII input is supported.
175	greg	1.3	The default setting is
176			.I \-faf.
177	greg	1.1	ASCII output is unsupported, since it interferes with
178	greg	1.3	efficient recovery when using the
179	greg	1.1	.I \-r
180	greg	1.3	option.
181	greg	1.1	.PP
182			In normal execution, only a single sender surface is sampled, but it may be
183			comprised of any number of subsurfaces, as in a triangle mesh or similar.
184			The surface normal will be computed as the average of all the constituent
185			subsurfaces.
186			The subsurfaces themselves must be planar, thus only
187			.I polygon
188			and
189			.I ring
190			surface primitives are supported.
191			Other primitives will be silently ignored and will have no effect on the calculation.
192			.PP
193			In the receiver file, the
194			.I source
195			primitive is supported as well, and multiple receivers (and multiple output
196			matrices) may be identified by different modifier names.
197			(Make sure that surfaces using the same modifier are grouped together,
198			and that the modifiers are unique and not used elsewhere in the
199			scene description.)\0
200			Though it may be counter-intuitive, receivers are often light sources,
201			since samples end up there in a backwards ray-tracing system such as RADIANCE.
202			When using local geometry, the overall aperture shape should be close to flat.
203			Large displacements may give rise to errors due to a convex receiver's
204			larger profile at low angles of incidence.
205			.PP
206			Rays always emanate from the back side of the sender surface and arrive at the
207			front side of receiver surfaces.
208			In this way, a receiver surface may be reused as a sender in a subsequent
209			.I rxfluxmtx
210			calculation and the resulting matrices will concatenate properly.
211			(Note that it is important to keep receiver surfaces together, otherwise a
212			"duplicate modifier" error will result.)\0
213			.SH EXAMPLES
214			To generate a flux transfer matrix connecting input and output apertures
215			on a light pipe:
216			.IP "" .2i
217	greg	1.3	rxfluxmtx -o lpipe.mtx int_aperture.rad ext_aperture.rad lpipe.rad
218	greg	1.1	.PP
219	greg	1.2	To generate a set of DC view component pictures with 9 jittered samples/pixel:
220	greg	1.1	.IP "" .2i
221	greg	1.2	rxfluxmtx -vf v1.vf -x 512 -y 512 -c 9 -pj .8 -fc reinhart_M4.rad -i scene1.oct
222	greg	1.1	.PP
223			To compute a workplane irradiance matrix for each window in a space:
224			.IP "" .2i
225			rxfluxmtx -faf - windows_kf.rad -i scene2.oct < workplane_pts.txt
226			.SH NOTES
227			The main differences between
228			.I rfluxmtx(1)
229			and
230			.I rxfluxmtx
231			is that the latter does not run a separate
232			.I rcontrib
233			process.
234			Instead, it relies on a unix-only C++ class definition that offers full
235			control over i/o.
236			This allows an unlimited number of receivers, a
237			.I \-r
238	greg	1.3	recovery option, and streamlines operations.
239	greg	1.1	.SH AUTHOR
240			Greg Ward
241			.SH "SEE ALSO"
242			genBSDF(1), getinfo(1), pvsum(1), rcalc(1), rcollate(1), rcomb(1), rcontrib(1),
243			rcrop(1), rfluxmtx(1), rmtxop(1), vwrays(1), wrapBSDF(1)