man/man1/dctimestep.1

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