ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/doc/man/man1/rfluxmtx.1
Revision: 1.11
Committed: Tue Mar 15 00:25:50 2022 UTC (3 years, 1 month ago) by greg
Branch: MAIN
CVS Tags: rad5R4
Changes since 1.10: +3 -3 lines
Log Message:
feat(rcrop): Created simple cropping utility for matrices and pictures

File Contents

# User Rev Content
1 greg 1.11 .\" RCSid "$Id: rfluxmtx.1,v 1.10 2015/12/04 22:16:18 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 greg 1.10 .BI o =output_spec
125     Send the matrix data for this receiver to the indicated file or command.
126     Single or double quotes may be used to contain strings with spaces, and
127     commands must begin with an exclamation mark ('!').
128 greg 1.1 The file format will be determined by the command-line
129     .I \-fio
130     option and will include an information header unless the
131     .I \-h
132     option was used to turn headers off.
133     (The output file specification is ignored for senders.)\0
134     .PP
135     In normal execution, only a single sender surface is sampled, but it may be
136     comprised of any number of subsurfaces, as in a triangle mesh or similar.
137     The surface normal will be computed as the average of all the constituent
138     subsurfaces.
139 greg 1.2 The subsurfaces themselves must be planar, thus only
140 greg 1.1 .I polygon
141     and
142     .I ring
143     surface primitives are supported.
144     Other primitives will be silently ignored and will have no effect on the calculation.
145     .PP
146     In the receiver file, the
147     .I source
148     primitive is supported as well, and multiple receivers (and multiple output
149 greg 1.7 matrices) may be identified by different modifier names.
150 greg 1.9 (Make sure that surfaces using the same modifier are grouped together,
151     and that the modifiers are unique and not used elsewhere in the
152     scene description.)\0
153 greg 1.1 Though it may be counter-intuitive, receivers are often light sources,
154     since samples end up there in a backwards ray-tracing system such as RADIANCE.
155 greg 1.2 When using local geometry, the overall aperture shape should be close to flat.
156     Large displacements may give rise to errors due to a convex receiver's
157     larger profile at low angles of incidence.
158 greg 1.1 .PP
159 greg 1.3 Rays always emanate from the back side of the sender surface and arrive at the
160 greg 1.1 front side of receiver surfaces.
161     In this way, a receiver surface may be reused as a sender in a subsequent
162     .I rfluxmtx
163     calculation and the resulting matrices will concatenate properly.
164     (Note that it is important to keep receiver surfaces together, otherwise a
165     "duplicate modifier" error will result.)\0
166     .SH EXAMPLES
167     To generate a flux transfer matrix connecting input and output apertures
168     on a light pipe:
169     .IP "" .3i
170 greg 1.5 rfluxmtx int_aperture.rad ext_aperture.rad lpipe.rad > lpipe.mtx
171 greg 1.1 .SH AUTHOR
172     Greg Ward
173     .SH "SEE ALSO"
174 greg 1.11 genBSDF(1), getinfo(1), rcalc(1), rcollate(1), rcontrib(1), rcrop(1),
175     rmtxop(1), vwrays(1), wrapBSDF(1)