man/man1/pvsum.1

.\" RCSid $Id: pvsum.1,v 1.2 2025/03/27 17:03:41 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 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 on Unix systems 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.
Experimentation with this setting is therefore 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:
.IP "" .2i
gensdaymtx -of sfo.epw | pvsum -o timestep%04d.hsr -N 10 tregcomp%03d.hsr
.SH NOTES
This tool overlaps with
.I dctimestep,
but provides some important capabilities.
First,
.I pvsum
reads and can produce spectral pictures and matrices, whereas
.I dctimestep
expects and requires 3-component pictures and matrices throughout.
Changing the data structures in
.I dctimestep
proved too difficult and likely to
lead to a less efficient implementation, especially on systems with
limited memory.
In contrast,
.I pvsum
accelerates picture sums on Unix systems with more
memory and processint ability.
Second, operation was simplified by focusing on the Daylight Coefficient
command form, where the DC matrix is represented as a collection of
pictures.
By excluding the other operation modes of
.I dctimestep,
new functionality could be explored and optimized,
such as floating-point support and
sending 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), vwrays(1)
Revision:	1.3
Committed:	Fri Mar 28 16:36:31 2025 UTC (5 weeks, 3 days ago) by greg
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.2:	+3 -3 lines
Log Message:	docs: Minor fixes
#	User	Rev	Content
1	greg	1.3	.\" RCSid $Id: pvsum.1,v 1.2 2025/03/27 17:03:41 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			]
14			.B ispec
15			[
16			.B mtx
17			]
18			.SH DESCRIPTION
19			.I Pvsum
20			is an efficient tool for summing Radiance pictures
21			into one or more output pictures.
22			Similar to
23			.I dctimestep(1),
24			multiple frames are produced if the input
25			.I mtx
26			has more than one column.
27			The number of rows in this matrix corresponds to the
28			number of component pictures specified in
29			.I ispec
30			with an incorporated "%d" or similar format string.
31			The first row in the matrix corresponds to picture 0, and
32			counting proceeds to one less than the number of matrix rows.
33			.PP
34			If no
35			.I mtx
36			is specified on the command line, the required data is read
37			from the standard input.
38			The input matrix
39			must either have a single component or match the number of components
40			in the input pictures, and the output pictures will match the latter component
41			count.
42			(I.e., grayscale float pictures have a component count of 1, RGB and XYZ
43			pictures a count of 3, and spectral pictures typically have 6 or more
44			components.)\0
45			.PP
46			By default, the output pixel type will match that of the input pictures,
47			either floating point or common-exponent byte format (i.e., RGBE, XYZE,
48			or Radiance_spectra).
49			If float output is preferred, specify the
50			.I \-of
51			option.
52			If common-exponent byte format is preferred, use the
53			.I \-oc
54			option.
55			.PP
56			If a
57			.I "\-o ospec"
58			argument begins with an exclamation point ('!') and contains a "%d"
59			format string or similar, then a separate command will be executed
60			for each output stream.
61			If no
62			.I \-o
63			option is given, all data is sent to the standard output,
64			which may be a sequence of Radiance pictures as understood by
65			.I ra_rgbe(1)
66			in the case of a multi-column input matrix.
67	greg	1.3	(Note that there is currently no Radiance tool that fully
68			handles a concatenated series of float or spectral pictures.)\0
69	greg	1.1	.PP
70			The
71			.I \-N
72			option may be used on Unix systems to specify the number of
73			processes to employ in the summations.
74			This setting has an upper limit equal to
75			the count of matrix columns, but
76			the optimal number of processes depends on several factors.
77			Setting the process count above the number of physical cores may
78			offer some benefit on large input collections if
79			their total size significantly exceeds the available system RAM.
80			Experimentation with this setting is therefore encouraged.
81			.SH EXAMPLES
82			To compute Window2's contribution to an interior view at 12 noon on the summer solstice:
83			.IP "" .2i
84			gensky 6 21 12 \| genskyvec \| rmtxop Blinds30.xml
85			Window2.dmx - \| pvsum view%03d.hdr > view_6-21-12.hdr
86			.PP
87			To compute a set of hourly spectral pictures at SFO airport
88	greg	1.2	from a weather tape and set of Tregenza component pictures using
89			10 processes:
90	greg	1.1	.IP "" .2i
91	greg	1.2	gensdaymtx -of sfo.epw \| pvsum -o timestep%04d.hsr -N 10 tregcomp%03d.hsr
92	greg	1.1	.SH NOTES
93	greg	1.2	This tool overlaps with
94	greg	1.1	.I dctimestep,
95			but provides some important capabilities.
96			First,
97			.I pvsum
98			reads and can produce spectral pictures and matrices, whereas
99			.I dctimestep
100			expects and requires 3-component pictures and matrices throughout.
101			Changing the data structures in
102			.I dctimestep
103			proved too difficult and likely to
104			lead to a less efficient implementation, especially on systems with
105			limited memory.
106			In contrast,
107			.I pvsum
108			accelerates picture sums on Unix systems with more
109			memory and processint ability.
110			Second, operation was simplified by focusing on the Daylight Coefficient
111			command form, where the DC matrix is represented as a collection of
112			pictures.
113	greg	1.2	By excluding the other operation modes of
114	greg	1.1	.I dctimestep,
115	greg	1.2	new functionality could be explored and optimized,
116			such as floating-point support and
117			sending output to commands as well as files.
118	greg	1.1	.SH AUTHOR
119			Greg Ward
120			.SH "SEE ALSO"
121			dcglare(1), dctimestep(1), gendaymtx(1), gensdaymtx(1), genskyvec(1), getinfo(1),
122			mkillum(1), ra_rgbe(1), rcollate(1), rcomb(1), rcontrib(1), rcrop(1),
123			rfluxmtx(1), rmtxop(1), rtrace(1), vwrays(1)