| 1 |
.\" RCSid $Id: pvsum.1,v 1.4 2025/05/22 21:39:42 greg Exp $"
|
| 2 |
.TH PVSUM 1 12/09/09 RADIANCE
|
| 3 |
.SH NAME
|
| 4 |
pvsum - sum component Radiance pictures based on vector or matrix
|
| 5 |
.SH SYNOPSIS
|
| 6 |
.B pvsum
|
| 7 |
[
|
| 8 |
.B "\-o ospec"
|
| 9 |
][
|
| 10 |
.B "\-o{f|c}
|
| 11 |
][
|
| 12 |
.B "\-N nproc"
|
| 13 |
][
|
| 14 |
.B "-m cacheGB"
|
| 15 |
]
|
| 16 |
.B ispec
|
| 17 |
[
|
| 18 |
.B mtx
|
| 19 |
]
|
| 20 |
.SH DESCRIPTION
|
| 21 |
.I Pvsum
|
| 22 |
is an efficient tool for summing Radiance pictures
|
| 23 |
into one or more output pictures.
|
| 24 |
Similar to
|
| 25 |
.I dctimestep(1),
|
| 26 |
multiple frames are produced if the input
|
| 27 |
.I mtx
|
| 28 |
has more than one column.
|
| 29 |
The number of rows in this matrix corresponds to the
|
| 30 |
number of component pictures specified in
|
| 31 |
.I ispec
|
| 32 |
with an incorporated "%d" or similar format string.
|
| 33 |
The first row in the matrix corresponds to picture 0, and
|
| 34 |
counting proceeds to one less than the number of matrix rows.
|
| 35 |
.PP
|
| 36 |
If no
|
| 37 |
.I mtx
|
| 38 |
is specified on the command line, the required data is read
|
| 39 |
from the standard input.
|
| 40 |
The input matrix
|
| 41 |
must either have a single component or match the number of components
|
| 42 |
in the input pictures, and the output pictures will match the latter component
|
| 43 |
count.
|
| 44 |
(I.e., grayscale float pictures have a component count of 1, RGB and XYZ
|
| 45 |
pictures a count of 3, and spectral pictures typically have 6 or more
|
| 46 |
components.)\0
|
| 47 |
.PP
|
| 48 |
By default, the output pixel type will match that of the input pictures,
|
| 49 |
either floating point or common-exponent byte format (i.e., RGBE, XYZE,
|
| 50 |
or Radiance_spectra).
|
| 51 |
If float output is preferred, specify the
|
| 52 |
.I \-of
|
| 53 |
option.
|
| 54 |
If common-exponent byte format is preferred, use the
|
| 55 |
.I \-oc
|
| 56 |
option.
|
| 57 |
.PP
|
| 58 |
If a
|
| 59 |
.I "\-o ospec"
|
| 60 |
argument begins with an exclamation point ('!') and contains a "%d"
|
| 61 |
format string or similar, then a separate command will be executed
|
| 62 |
for each output stream.
|
| 63 |
If no
|
| 64 |
.I \-o
|
| 65 |
option is given, all data is sent to the standard output,
|
| 66 |
which may be a sequence of Radiance pictures as understood by
|
| 67 |
.I ra_rgbe(1)
|
| 68 |
in the case of a multi-column input matrix.
|
| 69 |
(Note that there is currently no Radiance tool that fully
|
| 70 |
handles a concatenated series of float or spectral pictures.)\0
|
| 71 |
.PP
|
| 72 |
The
|
| 73 |
.I \-N
|
| 74 |
option may be used to specify the number of
|
| 75 |
processes to employ in the summations.
|
| 76 |
This setting has an upper limit equal to
|
| 77 |
the count of matrix columns, but
|
| 78 |
the optimal number of processes depends on several factors.
|
| 79 |
Setting the process count above the number of physical cores may
|
| 80 |
offer some benefit on large input collections if
|
| 81 |
their total size significantly exceeds the available system RAM.
|
| 82 |
.PP
|
| 83 |
Alternatively, one can set
|
| 84 |
.I \-N
|
| 85 |
to the number of cores and the
|
| 86 |
.I \-m
|
| 87 |
option to the free memory cache available in GBytes.
|
| 88 |
(This will be less than the total RAM, due to the operating
|
| 89 |
system and other processes.)\0
|
| 90 |
When
|
| 91 |
.I \-m
|
| 92 |
is set,
|
| 93 |
.I pvsum
|
| 94 |
will make multiple accumulation passes as needed to stay within
|
| 95 |
the available cache space.
|
| 96 |
.PP
|
| 97 |
Experimentation with these settings is encouraged.
|
| 98 |
.SH EXAMPLES
|
| 99 |
To compute Window2's contribution to an interior view at 12 noon on the
|
| 100 |
summer solstice:
|
| 101 |
.IP "" .2i
|
| 102 |
gensky 6 21 12 | genskyvec | rmtxop Blinds30.xml
|
| 103 |
Window2.dmx - | pvsum view%03d.hdr > view_6-21-12.hdr
|
| 104 |
.PP
|
| 105 |
To compute a set of hourly spectral pictures at SFO airport
|
| 106 |
from a weather tape and set of Tregenza component pictures using
|
| 107 |
10 processes and 6.5 GBytes of memory:
|
| 108 |
.IP "" .2i
|
| 109 |
gensdaymtx -of sfo.epw | pvsum -o timestep%04d.hsr -N 10 -m 6.5 tregcomp%03d.hsr
|
| 110 |
.SH NOTES
|
| 111 |
This tool overlaps with
|
| 112 |
.I dctimestep,
|
| 113 |
but provides some missing capabilities and performance features.
|
| 114 |
Foremost,
|
| 115 |
.I pvsum
|
| 116 |
reads and can produce spectral pictures and matrices, whereas
|
| 117 |
.I dctimestep
|
| 118 |
expects and requires 3-component pictures and matrices throughout.
|
| 119 |
In addition,
|
| 120 |
.I pvsum
|
| 121 |
accelerates picture sums on systems with more
|
| 122 |
memory and CPU cores.
|
| 123 |
Operations are simplified by focusing on the Daylight Coefficient
|
| 124 |
command form, where the DC matrix is represented as a collection of
|
| 125 |
pictures.
|
| 126 |
Finally,
|
| 127 |
.I pvsum
|
| 128 |
offers more flexible floating-point support and
|
| 129 |
can output to commands as well as files.
|
| 130 |
.SH AUTHOR
|
| 131 |
Greg Ward
|
| 132 |
.SH "SEE ALSO"
|
| 133 |
dcglare(1), dctimestep(1), gendaymtx(1), gensdaymtx(1), genskyvec(1), getinfo(1),
|
| 134 |
mkillum(1), ra_rgbe(1), rcollate(1), rcomb(1), rcontrib(1), rcrop(1),
|
| 135 |
rfluxmtx(1), rmtxop(1), rtrace(1), rxfluxmtx(1), vwrays(1)
|
