man/man1/rfluxmtx.1

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