man/man1/dctimestep.1

.\" RCSid $Id: dctimestep.1,v 1.8 2014/02/08 01:28:05 greg Exp $"
.TH DCTIMESTEP 1 12/09/09 RADIANCE
.SH NAME
dctimestep - compute annual simulation time-step(s) via matrix multiplication
.SH SYNOPSIS
.B dctimestep
[
.B "\-n nsteps"
][
.B "\-o ospec"
][
.B "\-i{f|d|h}
][
.B "\-o{f|d}
]
.B DCspec
[
.B skyf
]
.br
.B dctimestep
[
.B "\-n nsteps"
][
.B "\-o ospec"
][
.B "\-i{f|d|h}
][
.B "\-o{f|d}
]
.B Vspec
.B Tbsdf.xml
.B Dmat.dat
[
.B skyf
]
.SH DESCRIPTION
.I Dctimestep
has two invocation forms.
In the first form,
.I dctimestep
is given a daylight coefficient specification and an optional sky
vector or matrix, which may be read from the standard input if unspecified.
The daylight coefficients are multiplied against these sky values
and the results are written to the standard output.
This may be a list of color values or a combined Radiance image,
as explained below.
.PP
In the second form,
.I dctimestep
takes four input files, forming a matrix expression.
The first argument is the View matrix file that specifies how window output
directions are related to some set of measured values, such as an array of
illuminance points or images.
This matrix is usually computed by
.I rcontrib(1)
for a particular set of windows or skylight openings.
The second argument is the window transmission matrix, or BSDF, given as
a standard XML description.
The third argument is the Daylight matrix file that defines how sky patches
relate to input directions on the same opening.
This is usually computed using
.I genklemsamp(1)
with
.I rcontrib
in a separate run for each window or skylight orientation.
The last file is the sky contribution vector or matrix,
typically computed by
.I genskyvec(1)
or
.I gendaymtx(1),
and may be passed on the standard input.
This data is assumed by default to be in ASCII format, whereas the
formats of the View and Daylight matrices
are detected automatically if given as binary data.
The
.I \-if
or
.I \-id
option may be used to specify that sky data is in float or double
format, respectively, which is more efficient for large matrices.
The
.I \-ih
option says to check the header to determine the data type.
(Note that binary double data may not be read from stdin without a header.)\0
.PP
The standard output of
.I dctimestep
is either a color vector with as many RGB triplets
as there are rows in the View matrix, or a combined
.I Radiance
picture.
Which output is produced depends on the first argument.
A regular file name will be loaded and interpreted as a matrix to
generate a color results vector.
A file specification containing a '%d' format string will be
interpreted as a list of
.I Radiance
component pictures, which will be summed according to the computed
vector.
.PP
The
.I \-n
option may be used to compute multiple time steps in a
single invocation.
The sky input file must contain the number of
columns specified in each sky patch row, whether it is read
from the standard input or from a file.
The columns do not need to be given on the same
line, so long as the number of values totals 3*Nsteps*Npatches.
Input starts from the first patch at the first time step, then the
first patch at the second time step, and so on.
If the input matrix has a header, then you may use
.I \-n 0
to get the number of columns from the header rather than specifying it.
.PP
The
.I \-o
option may be used to specify a file or a set of output files
to use rather than the standard output.
If the given specification contains a '%d' format string, this
will be replaced by the time step index, starting from 1.
In this way, multiple output pictures may be produced,
or separate result vectors (one per time step).
If the standard output is used or the
.I \-o
option specifies a single output file, then an information header
will precede the output.
This can be removed if desired using the
.I getinfo\(1\)
command with a single hyphen ('-') argument.
.PP
The
.I \-of
or
.I \-od
option may be used to specify IEEE float or double binary output
data, respectively.
This enables
.I dctimestep
to be used as a pure matrix multiplier, as the output file with
header specifying the format is suitable for subsequent calls.
.SH EXAMPLES
To compute workplane illuminances at 3:30pm on Feb 10th:
.IP "" .2i
gensky 2 10 15:30 | genskyvec | dctimestep workplaneDC.dmx > Ill_02-10-1530.dat
.PP
To compute an image at 10am on the equinox from a set of component images:
.IP "" .2i
gensky 3 21 10 | genskyvec | dctimestep dcomp%03d.hdr > view_03-21-10.hdr
.PP
To compute a set of illuminance contributions for Window 1 on
the Winter solstice at 2pm:
.IP "" .2i
gensky 12 21 14 | genskyvec | dctimestep IllPts.vmx Blinds20.xml Window1.dmx > Ill_12-21-14.dat
.PP
To compute Window2's contribution to an interior view at 12 noon on the Summer solstice:
.IP "" .2i
gensky 6 21 12 | genskyvec | dctimestep view%03d.hdr Blinds30.xml
Window2.dmx > view_6-21-12.hdr
.PP
To generate an hourly matrix of sensor value contributions from Skylight3
using a 3-phase calculation, where output columns are time steps:
.IP "" .2i
gendaymtx -of Tampa.wea | dctimestep -if -n 8760 WPpts.vmx
shade3.xml Skylight3.dmx > wp_win3.dat
.IP "" .2i
.PP
Generate a series of pictures corresponding to timesteps
in an annual simulation:
.IP "" .2i
gendaymtx NYCity.wea | dctimestep -n 8760 -o tstep%04d.hdr dcomp%03d.hdr
.PP
To multiply two color matrices (second matrix is IEEE-float with
145 RGB columns) into a IEEE-double result (also 145 RGB columns):
.IP "" .2i
getinfo - < Inp2.fmx | dctimestep -n 145 -if -od Inp1.fmx > Inp1xInp2.dmx
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
gendaymtx(1), genklemsamp(1), genskyvec(1), getinfo(1),
mkillum(1), rcollate(1), rcontrib(1), rtrace(1), vwrays(1)
Revision:	1.9
Committed:	Fri May 30 00:00:54 2014 UTC (10 years, 11 months ago) by greg
Branch:	MAIN
CVS Tags:	rad4R2, rad4R2P1
Changes since 1.8:	+11 -5 lines
Log Message:	Added NROWS, NCOLS and NCOMP to matrix headers
#	User	Rev	Content
1	greg	1.9	.\" RCSid $Id: dctimestep.1,v 1.8 2014/02/08 01:28:05 greg Exp $"
2	greg	1.1	.TH DCTIMESTEP 1 12/09/09 RADIANCE
3			.SH NAME
4	greg	1.4	dctimestep - compute annual simulation time-step(s) via matrix multiplication
5	greg	1.1	.SH SYNOPSIS
6			.B dctimestep
7	greg	1.4	[
8			.B "\-n nsteps"
9			][
10			.B "\-o ospec"
11	greg	1.5	][
12	greg	1.9	.B "\-i{f\|d\|h}
13	greg	1.8	][
14			.B "\-o{f\|d}
15	greg	1.4	]
16	greg	1.2	.B DCspec
17			[
18	greg	1.4	.B skyf
19	greg	1.2	]
20			.br
21			.B dctimestep
22	greg	1.4	[
23			.B "\-n nsteps"
24			][
25			.B "\-o ospec"
26	greg	1.5	][
27	greg	1.9	.B "\-i{f\|d\|h}
28	greg	1.8	][
29			.B "\-o{f\|d}
30	greg	1.4	]
31	greg	1.1	.B Vspec
32			.B Tbsdf.xml
33			.B Dmat.dat
34			[
35	greg	1.4	.B skyf
36	greg	1.1	]
37			.SH DESCRIPTION
38			.I Dctimestep
39	greg	1.2	has two invocation forms.
40			In the first form,
41			.I dctimestep
42			is given a daylight coefficient specification and an optional sky
43	greg	1.4	vector or matrix, which may be read from the standard input if unspecified.
44			The daylight coefficients are multiplied against these sky values
45			and the results are written to the standard output.
46	greg	1.2	This may be a list of color values or a combined Radiance image,
47			as explained below.
48			.PP
49			In the second form,
50			.I dctimestep
51	greg	1.1	takes four input files, forming a matrix expression.
52			The first argument is the View matrix file that specifies how window output
53			directions are related to some set of measured values, such as an array of
54			illuminance points or images.
55			This matrix is usually computed by
56	greg	1.3	.I rcontrib(1)
57	greg	1.1	for a particular set of windows or skylight openings.
58			The second argument is the window transmission matrix, or BSDF, given as
59			a standard XML description.
60			The third argument is the Daylight matrix file that defines how sky patches
61			relate to input directions on the same opening.
62			This is usually computed using
63			.I genklemsamp(1)
64			with
65	greg	1.3	.I rcontrib
66	greg	1.1	in a separate run for each window or skylight orientation.
67	greg	1.6	The last file is the sky contribution vector or matrix,
68			typically computed by
69			.I genskyvec(1)
70			or
71			.I gendaymtx(1),
72			and may be passed on the standard input.
73			This data is assumed by default to be in ASCII format, whereas the
74			formats of the View and Daylight matrices
75			are detected automatically if given as binary data.
76	greg	1.5	The
77			.I \-if
78			or
79			.I \-id
80			option may be used to specify that sky data is in float or double
81	greg	1.6	format, respectively, which is more efficient for large matrices.
82	greg	1.9	The
83			.I \-ih
84			option says to check the header to determine the data type.
85			(Note that binary double data may not be read from stdin without a header.)\0
86	greg	1.1	.PP
87	greg	1.9	The standard output of
88	greg	1.1	.I dctimestep
89	greg	1.8	is either a color vector with as many RGB triplets
90	greg	1.1	as there are rows in the View matrix, or a combined
91			.I Radiance
92			picture.
93	greg	1.2	Which output is produced depends on the first argument.
94	greg	1.1	A regular file name will be loaded and interpreted as a matrix to
95			generate a color results vector.
96			A file specification containing a '%d' format string will be
97			interpreted as a list of
98			.I Radiance
99			component pictures, which will be summed according to the computed
100			vector.
101	greg	1.4	.PP
102			The
103			.I \-n
104			option may be used to compute multiple time steps in a
105			single invocation.
106			The sky input file must contain the number of
107			columns specified in each sky patch row, whether it is read
108	greg	1.6	from the standard input or from a file.
109	greg	1.4	The columns do not need to be given on the same
110			line, so long as the number of values totals 3NstepsNpatches.
111			Input starts from the first patch at the first time step, then the
112			first patch at the second time step, and so on.
113	greg	1.9	If the input matrix has a header, then you may use
114			.I \-n 0
115			to get the number of columns from the header rather than specifying it.
116	greg	1.4	.PP
117			The
118			.I \-o
119			option may be used to specify a file or a set of output files
120			to use rather than the standard output.
121			If the given specification contains a '%d' format string, this
122			will be replaced by the time step index, starting from 1.
123			In this way, multiple output pictures may be produced,
124	greg	1.6	or separate result vectors (one per time step).
125	greg	1.8	If the standard output is used or the
126			.I \-o
127			option specifies a single output file, then an information header
128			will precede the output.
129			This can be removed if desired using the
130			.I getinfo\(1\)
131			command with a single hyphen ('-') argument.
132			.PP
133			The
134			.I \-of
135			or
136			.I \-od
137			option may be used to specify IEEE float or double binary output
138			data, respectively.
139			This enables
140			.I dctimestep
141			to be used as a pure matrix multiplier, as the output file with
142			header specifying the format is suitable for subsequent calls.
143	greg	1.1	.SH EXAMPLES
144	greg	1.2	To compute workplane illuminances at 3:30pm on Feb 10th:
145			.IP "" .2i
146			gensky 2 10 15:30 \| genskyvec \| dctimestep workplaneDC.dmx > Ill_02-10-1530.dat
147			.PP
148			To compute an image at 10am on the equinox from a set of component images:
149			.IP "" .2i
150	greg	1.6	gensky 3 21 10 \| genskyvec \| dctimestep dcomp%03d.hdr > view_03-21-10.hdr
151	greg	1.2	.PP
152	greg	1.1	To compute a set of illuminance contributions for Window 1 on
153			the Winter solstice at 2pm:
154			.IP "" .2i
155			gensky 12 21 14 \| genskyvec \| dctimestep IllPts.vmx Blinds20.xml Window1.dmx > Ill_12-21-14.dat
156			.PP
157			To compute Window2's contribution to an interior view at 12 noon on the Summer solstice:
158			.IP "" .2i
159	greg	1.6	gensky 6 21 12 \| genskyvec \| dctimestep view%03d.hdr Blinds30.xml
160			Window2.dmx > view_6-21-12.hdr
161			.PP
162			To generate an hourly matrix of sensor value contributions from Skylight3
163			using a 3-phase calculation, where output columns are time steps:
164			.IP "" .2i
165			gendaymtx -of Tampa.wea \| dctimestep -if -n 8760 WPpts.vmx
166			shade3.xml Skylight3.dmx > wp_win3.dat
167			.IP "" .2i
168			.PP
169			Generate a series of pictures corresponding to timesteps
170			in an annual simulation:
171			.IP "" .2i
172			gendaymtx NYCity.wea \| dctimestep -n 8760 -o tstep%04d.hdr dcomp%03d.hdr
173	greg	1.8	.PP
174			To multiply two color matrices (second matrix is IEEE-float with
175			145 RGB columns) into a IEEE-double result (also 145 RGB columns):
176			.IP "" .2i
177			getinfo - < Inp2.fmx \| dctimestep -n 145 -if -od Inp1.fmx > Inp1xInp2.dmx
178	greg	1.1	.SH AUTHOR
179			Greg Ward
180			.SH "SEE ALSO"
181	greg	1.8	gendaymtx(1), genklemsamp(1), genskyvec(1), getinfo(1),
182	greg	1.7	mkillum(1), rcollate(1), rcontrib(1), rtrace(1), vwrays(1)