man/man1/rxfluxmtx.1

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