man/man1/pvsum.1

.\" RCSid $Id: pvsum.1,v 1.4 2025/05/22 21:39:42 greg Exp $"
.TH PVSUM 1 12/09/09 RADIANCE
.SH NAME
pvsum - sum component Radiance pictures based on vector or matrix
.SH SYNOPSIS
.B pvsum
[
.B "\-o ospec"
][
.B "\-o{f|c}
][
.B "\-N nproc"
][
.B "-m cacheGB"
]
.B ispec
[
.B mtx
]
.SH DESCRIPTION
.I Pvsum
is an efficient tool for summing Radiance pictures
into one or more output pictures.
Similar to
.I dctimestep(1),
multiple frames are produced if the input
.I mtx
has more than one column.
The number of rows in this matrix corresponds to the
number of component pictures specified in
.I ispec
with an incorporated "%d" or similar format string.
The first row in the matrix corresponds to picture 0, and
counting proceeds to one less than the number of matrix rows.
.PP
If no
.I mtx
is specified on the command line, the required data is read
from the standard input.
The input matrix
must either have a single component or match the number of components
in the input pictures, and the output pictures will match the latter component
count.
(I.e., grayscale float pictures have a component count of 1, RGB and XYZ
pictures a count of 3, and spectral pictures typically have 6 or more
components.)\0
.PP
By default, the output pixel type will match that of the input pictures,
either floating point or common-exponent byte format (i.e., RGBE, XYZE,
or Radiance_spectra).
If float output is preferred, specify the
.I \-of
option.
If common-exponent byte format is preferred, use the
.I \-oc
option.
.PP
If a
.I "\-o ospec"
argument begins with an exclamation point ('!') and contains a "%d"
format string or similar, then a separate command will be executed
for each output stream.
If no
.I \-o
option is given, all data is sent to the standard output,
which may be a sequence of Radiance pictures as understood by
.I ra_rgbe(1)
in the case of a multi-column input matrix.
(Note that there is currently no Radiance tool that fully
handles a concatenated series of float or spectral pictures.)\0
.PP
The
.I \-N
option may be used to specify the number of
processes to employ in the summations.
This setting has an upper limit equal to
the count of matrix columns, but
the optimal number of processes depends on several factors.
Setting the process count above the number of physical cores may
offer some benefit on large input collections if
their total size significantly exceeds the available system RAM.
.PP
Alternatively, one can set
.I \-N
to the number of cores and the
.I \-m
option to the free memory cache available in GBytes.
(This will be less than the total RAM, due to the operating
system and other processes.)\0
When
.I \-m
is set,
.I pvsum
will make multiple accumulation passes as needed to stay within
the available cache space.
.PP
Experimentation with these settings is encouraged.
.SH EXAMPLES
To compute Window2's contribution to an interior view at 12 noon on the 
summer solstice:
.IP "" .2i
gensky 6 21 12 | genskyvec | rmtxop Blinds30.xml
Window2.dmx - | pvsum view%03d.hdr > view_6-21-12.hdr
.PP
To compute a set of hourly spectral pictures at SFO airport
from a weather tape and set of Tregenza component pictures using
10 processes and 6.5 GBytes of memory:
.IP "" .2i
gensdaymtx -of sfo.epw | pvsum -o timestep%04d.hsr -N 10 -m 6.5 tregcomp%03d.hsr
.SH NOTES
This tool overlaps with
.I dctimestep,
but provides some missing capabilities and performance features.
Foremost,
.I pvsum
reads and can produce spectral pictures and matrices, whereas
.I dctimestep
expects and requires 3-component pictures and matrices throughout.
In addition,
.I pvsum
accelerates picture sums on systems with more
memory and CPU cores.
Operations are simplified by focusing on the Daylight Coefficient
command form, where the DC matrix is represented as a collection of
pictures.
Finally,
.I pvsum
offers more flexible floating-point support and
can output to commands as well as files.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
dcglare(1), dctimestep(1), gendaymtx(1), gensdaymtx(1), genskyvec(1), getinfo(1),
mkillum(1), ra_rgbe(1), rcollate(1), rcomb(1), rcontrib(1), rcrop(1),
rfluxmtx(1), rmtxop(1), rtrace(1), rxfluxmtx(1), vwrays(1)
Revision:	1.5
Committed:	Wed Oct 29 02:48:50 2025 UTC (6 weeks, 3 days ago) by greg
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.4:	+28 -10 lines
Log Message:	feat(pvsum): Added -m option to optimize speed and memory usage
#	User	Rev	Content
1	greg	1.5	.\" RCSid $Id: pvsum.1,v 1.4 2025/05/22 21:39:42 greg Exp $"
2	greg	1.1	.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	greg	1.5	][
14			.B "-m cacheGB"
15	greg	1.1	]
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	greg	1.3	(Note that there is currently no Radiance tool that fully
70			handles a concatenated series of float or spectral pictures.)\0
71	greg	1.1	.PP
72			The
73			.I \-N
74	greg	1.5	option may be used to specify the number of
75	greg	1.1	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	greg	1.5	.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	greg	1.1	.SH EXAMPLES
99	greg	1.5	To compute Window2's contribution to an interior view at 12 noon on the
100			summer solstice:
101	greg	1.1	.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	greg	1.2	from a weather tape and set of Tregenza component pictures using
107	greg	1.5	10 processes and 6.5 GBytes of memory:
108	greg	1.1	.IP "" .2i
109	greg	1.5	gensdaymtx -of sfo.epw \| pvsum -o timestep%04d.hsr -N 10 -m 6.5 tregcomp%03d.hsr
110	greg	1.1	.SH NOTES
111	greg	1.2	This tool overlaps with
112	greg	1.1	.I dctimestep,
113	greg	1.5	but provides some missing capabilities and performance features.
114	greg	1.4	Foremost,
115	greg	1.1	.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	greg	1.4	In addition,
120	greg	1.1	.I pvsum
121	greg	1.5	accelerates picture sums on systems with more
122	greg	1.4	memory and CPU cores.
123	greg	1.5	Operations are simplified by focusing on the Daylight Coefficient
124	greg	1.1	command form, where the DC matrix is represented as a collection of
125			pictures.
126	greg	1.4	Finally,
127			.I pvsum
128			offers more flexible floating-point support and
129			can output to commands as well as files.
130	greg	1.1	.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	greg	1.5	rfluxmtx(1), rmtxop(1), rtrace(1), rxfluxmtx(1), vwrays(1)