man/man1/gensky.1

.\" RCSid "$Id: gensky.1,v 1.6 2007/09/04 17:36:40 greg Exp $"
.TH GENSKY 1 4/24/98 RADIANCE
.SH NAME
gensky - generate a RADIANCE description of the sky
.SH SYNOPSIS
.B "gensky month day time"
[
.B options
]
.br
.B "gensky -ang altitude azimuth"
[
.B options
]
.br
.B "gensky -defaults"
.SH DESCRIPTION
.I Gensky
produces a RADIANCE scene description for the CIE standard
sky distribution at the given month, day and time.
By default, the time is interpreted as local standard
time on a 24-hour clock.
The time value may be given either as decimal hours, or using a
colon to separate hours and minutes.
If the time is immediately followed (no white space)
by a North American or European time zone designation,
then this determines the standard meridian, which may
be specified alternatively with the
.I \-m
option.
The following time zones are understood, with their corresponding
hour differences from Greenwich Mean Time:
.sp .5
.nf
Standard time:
YST   PST   MST   CST   EST   GMT
 9     8     7     6     5     0

CET   EET   AST   GST   IST   JST  NZST
\-1    \-2    \-3    \-4    \-5.5  \-9   \-12

Daylight savings time:
YDT   PDT   MDT   CDT   EDT   BST
 8     7     6     5     4     \-1

CEST  EEST  ADT   GDT   IDT   JDT  NZDT
 \-2    \-3   \-4    \-5   \-6.5   \-10  \-13
.fi
.PP
If the time is preceded by a plus sign ('+'), then it is interpreted
as local solar time instead.
It is very important to specify the correct latitude and longitude
(unless local solar time is given) using the
.I \-a
and
.I \-o
options to get the correct solar angles.
.PP
The second form gives the solar angles explicitly.
The altitude is measured in degrees above the horizon, and the
azimuth is measured in degrees west of South.
.PP
The third form prints the default option values.
.PP
The output sky distribution is given as a brightness function,
.I skyfunc.
Its value is in watts/steradian/meter2.
The x axis points east,
the y axis points north, and the z axis corresponds to the zenith.
The actual material and surface(s) used for the sky is left
up to the user.
For a hemispherical blue sky, the description might be:
.sp
.nf
!gensky 4 1 14

skyfunc glow skyglow
0
0
4 .99 .99 1.1 0

skyglow source sky
0
0
4 0 0 1 180
.fi
.sp
Often,
.I skyfunc
will actually be used to characterize the light coming in from
a window.
.PP
In addition to the specification of
a sky distribution function,
.I gensky
suggests an ambient value in a comment at the beginning of the
description to use with the
.I \-av
option of the RADIANCE rendering programs.
(See rvu(1) and rpict(1).)
This value is the cosine-weighted radiance of the sky in
watts/steradian/meter2.
.PP
.I Gensky
supports the following options.
.TP 10n
.BR \-y \ year
If the year is specified, a more accurate solar position algorithm
[Michalsky 1988] will be used in place of the formula in the IES
Lighting Handbook.
.TP
.BR \-s
Sunny sky without sun.
The sky distribution will correspond to a standard CIE clear day.
.TP
.BR \+s
Sunny sky with sun.
In addition to the sky distribution function, a source
description of the sun is generated.
.TP
.BR \-c
Cloudy sky.
The sky distribution will correspond to a standard CIE overcast day.
.TP
.BR \-i
Intermediate sky without sun.
The sky will correspond to a standard CIE intermediate day.
.TP
.BR \+i
Intermediate sky with sun.
In addition to the sky distribution, a (somewhat subdued) sun
is generated.
.TP
.BR \-u
Uniform cloudy sky.
The sky distribution will be completely uniform.
.TP
.BI -g \ rfl
Average ground reflectance is
.I rfl.
This value is used to compute
.I skyfunc
when Dz is negative.
Ground plane brightness is the same for
.I \-s
as for
.I \+s.
(Likewise for
.I \-i
and
.I \+i,
but see the
.I \-r
option below.)
.TP
.BI -b \ brt
The zenith brightness is
.I brt.
Zenith radiance (in watts/steradian/meter2) is normally computed
from the sun angle and sky turbidity (for sunny sky).
It can be given directly instead, using this option.
.TP
.BI -B \ irrad
Same as
.I \-b,
except zenith brightness is computed from the horizontal
diffuse irradiance (in watts/meter2).
.TP
.BI -r \ rad
The solar radiance is
.I rad.
Solar radiance (in watts/steradian/meter2) is normally computed from
the solar altitude.
This option may be used to override the default calculation.
If a value of zero is given, no sun description is produced, and the
contribution of direct solar to ground brightness is neglected.
.TP
.BI -R \ irrad
Same as
.I \-r,
except solar radiance is computed from the horizontal direct
irradiance (in watts/meter2).
.TP
.BI -t \ trb
The turbidity factor is
.I trb.
Greater turbidity factors
correspond to greater atmospheric scattering.
A turbidity factor of 1.0 indicates an ideal clear atmosphere (i.e.
a completely dark sky).
Values less than 1.0 are physically impossible.
.PP
The following options do not apply when the solar
altitude and azimuth are given explicitly.
.TP
.BI -a \ lat
The site latitude is
.I lat
degrees north.
(Use negative angle for south latitude.)
This is used in the calculation of sun angle.
.TP
.BI -o \ lon
The site longitude is
.I lon
degrees west.
(Use negative angle for east longitude.)
This is used in the calculation of solar time and sun angle.
Be sure to give the corresponding standard meridian also!
If solar time is given directly, then this option has no effect.
.TP
.BI -m \ mer
The site standard meridian is
.I mer
degrees west of Greenwich.
(Use negative angle for east.)
This is used in the calculation of solar time.
Be sure to give the correct longitude also!
If a time zone or solar time is given directly, then this option has no effect.
.SH EXAMPLE
To produce a sunny sky for July 4th at 2:30pm Eastern daylight time at a
site latitude of 42 degrees, 89 degrees west longitude:
.IP "" .2i
gensky 7 4 14:30EDT +s \-a 42 \-o 89
.PP
To produce a sunny sky distribution for a specific sun position but
without the sun description:
.IP "" .2i
gensky \-ang 23 \-40 \-s
.SH FILES
/usr/local/lib/ray/skybright.cal
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
rpict(1), rvu(1), xform(1)
Revision:	1.7
Committed:	Thu Nov 7 23:16:17 2019 UTC (5 years, 5 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R4, rad5R3, HEAD
Changes since 1.6:	+6 -1 lines
Log Message:	Added year specification for more accurate Michalsky solar position
#	User	Rev	Content
1	greg	1.7	.\" RCSid "$Id: gensky.1,v 1.6 2007/09/04 17:36:40 greg Exp $"
2	greg	1.1	.TH GENSKY 1 4/24/98 RADIANCE
3			.SH NAME
4			gensky - generate a RADIANCE description of the sky
5			.SH SYNOPSIS
6			.B "gensky month day time"
7			[
8			.B options
9			]
10			.br
11			.B "gensky -ang altitude azimuth"
12			[
13			.B options
14			]
15			.br
16			.B "gensky -defaults"
17			.SH DESCRIPTION
18			.I Gensky
19			produces a RADIANCE scene description for the CIE standard
20			sky distribution at the given month, day and time.
21			By default, the time is interpreted as local standard
22			time on a 24-hour clock.
23			The time value may be given either as decimal hours, or using a
24			colon to separate hours and minutes.
25			If the time is immediately followed (no white space)
26			by a North American or European time zone designation,
27			then this determines the standard meridian, which may
28			be specified alternatively with the
29			.I \-m
30			option.
31			The following time zones are understood, with their corresponding
32			hour differences from Greenwich Mean Time:
33			.sp .5
34			.nf
35			Standard time:
36			YST PST MST CST EST GMT
37			9 8 7 6 5 0
38
39			CET EET AST GST IST JST NZST
40	greg	1.6	\-1 \-2 \-3 \-4 \-5.5 \-9 \-12
41	greg	1.1
42			Daylight savings time:
43			YDT PDT MDT CDT EDT BST
44	greg	1.6	8 7 6 5 4 \-1
45	greg	1.1
46			CEST EEST ADT GDT IDT JDT NZDT
47	greg	1.6	\-2 \-3 \-4 \-5 \-6.5 \-10 \-13
48	greg	1.1	.fi
49			.PP
50			If the time is preceded by a plus sign ('+'), then it is interpreted
51			as local solar time instead.
52			It is very important to specify the correct latitude and longitude
53			(unless local solar time is given) using the
54			.I \-a
55			and
56			.I \-o
57			options to get the correct solar angles.
58			.PP
59			The second form gives the solar angles explicitly.
60			The altitude is measured in degrees above the horizon, and the
61			azimuth is measured in degrees west of South.
62			.PP
63			The third form prints the default option values.
64			.PP
65			The output sky distribution is given as a brightness function,
66			.I skyfunc.
67			Its value is in watts/steradian/meter2.
68			The x axis points east,
69			the y axis points north, and the z axis corresponds to the zenith.
70			The actual material and surface(s) used for the sky is left
71			up to the user.
72			For a hemispherical blue sky, the description might be:
73			.sp
74			.nf
75			!gensky 4 1 14
76
77			skyfunc glow skyglow
78			0
79			0
80	greg	1.2	4 .99 .99 1.1 0
81	greg	1.1
82			skyglow source sky
83			0
84			0
85			4 0 0 1 180
86			.fi
87			.sp
88			Often,
89			.I skyfunc
90			will actually be used to characterize the light coming in from
91			a window.
92			.PP
93			In addition to the specification of
94			a sky distribution function,
95			.I gensky
96			suggests an ambient value in a comment at the beginning of the
97			description to use with the
98			.I \-av
99			option of the RADIANCE rendering programs.
100	greg	1.4	(See rvu(1) and rpict(1).)
101	greg	1.1	This value is the cosine-weighted radiance of the sky in
102			watts/steradian/meter2.
103			.PP
104			.I Gensky
105			supports the following options.
106			.TP 10n
107	greg	1.7	.BR \-y \ year
108			If the year is specified, a more accurate solar position algorithm
109			[Michalsky 1988] will be used in place of the formula in the IES
110			Lighting Handbook.
111			.TP
112	greg	1.1	.BR \-s
113			Sunny sky without sun.
114			The sky distribution will correspond to a standard CIE clear day.
115			.TP
116			.BR \+s
117			Sunny sky with sun.
118			In addition to the sky distribution function, a source
119			description of the sun is generated.
120			.TP
121			.BR \-c
122			Cloudy sky.
123			The sky distribution will correspond to a standard CIE overcast day.
124			.TP
125			.BR \-i
126			Intermediate sky without sun.
127			The sky will correspond to a standard CIE intermediate day.
128			.TP
129			.BR \+i
130			Intermediate sky with sun.
131			In addition to the sky distribution, a (somewhat subdued) sun
132			is generated.
133			.TP
134			.BR \-u
135			Uniform cloudy sky.
136			The sky distribution will be completely uniform.
137			.TP
138			.BI -g \ rfl
139			Average ground reflectance is
140			.I rfl.
141			This value is used to compute
142			.I skyfunc
143			when Dz is negative.
144			Ground plane brightness is the same for
145			.I \-s
146			as for
147			.I \+s.
148			(Likewise for
149			.I \-i
150			and
151			.I \+i,
152			but see the
153			.I \-r
154			option below.)
155			.TP
156			.BI -b \ brt
157			The zenith brightness is
158			.I brt.
159			Zenith radiance (in watts/steradian/meter2) is normally computed
160			from the sun angle and sky turbidity (for sunny sky).
161			It can be given directly instead, using this option.
162			.TP
163			.BI -B \ irrad
164			Same as
165			.I \-b,
166			except zenith brightness is computed from the horizontal
167			diffuse irradiance (in watts/meter2).
168			.TP
169			.BI -r \ rad
170			The solar radiance is
171			.I rad.
172			Solar radiance (in watts/steradian/meter2) is normally computed from
173			the solar altitude.
174			This option may be used to override the default calculation.
175			If a value of zero is given, no sun description is produced, and the
176			contribution of direct solar to ground brightness is neglected.
177			.TP
178			.BI -R \ irrad
179			Same as
180			.I \-r,
181			except solar radiance is computed from the horizontal direct
182			irradiance (in watts/meter2).
183			.TP
184			.BI -t \ trb
185			The turbidity factor is
186			.I trb.
187			Greater turbidity factors
188			correspond to greater atmospheric scattering.
189			A turbidity factor of 1.0 indicates an ideal clear atmosphere (i.e.
190			a completely dark sky).
191			Values less than 1.0 are physically impossible.
192			.PP
193			The following options do not apply when the solar
194			altitude and azimuth are given explicitly.
195			.TP
196			.BI -a \ lat
197			The site latitude is
198			.I lat
199			degrees north.
200			(Use negative angle for south latitude.)
201			This is used in the calculation of sun angle.
202			.TP
203			.BI -o \ lon
204			The site longitude is
205			.I lon
206			degrees west.
207			(Use negative angle for east longitude.)
208			This is used in the calculation of solar time and sun angle.
209			Be sure to give the corresponding standard meridian also!
210			If solar time is given directly, then this option has no effect.
211			.TP
212			.BI -m \ mer
213			The site standard meridian is
214			.I mer
215			degrees west of Greenwich.
216			(Use negative angle for east.)
217			This is used in the calculation of solar time.
218			Be sure to give the correct longitude also!
219	greg	1.5	If a time zone or solar time is given directly, then this option has no effect.
220	greg	1.1	.SH EXAMPLE
221			To produce a sunny sky for July 4th at 2:30pm Eastern daylight time at a
222			site latitude of 42 degrees, 89 degrees west longitude:
223			.IP "" .2i
224	greg	1.6	gensky 7 4 14:30EDT +s \-a 42 \-o 89
225	greg	1.1	.PP
226			To produce a sunny sky distribution for a specific sun position but
227			without the sun description:
228			.IP "" .2i
229	greg	1.6	gensky \-ang 23 \-40 \-s
230	greg	1.1	.SH FILES
231			/usr/local/lib/ray/skybright.cal
232			.SH AUTHOR
233			Greg Ward
234			.SH "SEE ALSO"
235	greg	1.4	rpict(1), rvu(1), xform(1)