Debian Codegraph @

raster/r.sunmask/r.sunmask.html

raw
1 <h2>DESCRIPTION</h2>
2
3 <em>r.sunmask</em> creates an output map layer based on an input elevation
4 raster map layer and the position of the sun. The output map layer contains the
5 cast shadow areas resulting from sunlight and elevation. The user can either
6 specify the sun position directly or the module calculates it from given
7 location and date/time parameters using the SOLPOS (Solar and Moon Position Algorithm)
8 developed by the
9 <a href="https://www.nrel.gov/">National Renewable Energy Laboratory</a>
10 (NREL). SOLPOS operates in two modes, either
11
12 <ul>
13 <li>(A) parameters to specify the exact known position of the sun, or</li>
14 <li>(B) parameters to specify the date/time for the sun position calculation
15 by <em>r.sunmask</em> itself</li>
16 </ul>
17 must be used.
18
19 <p>
20 The module performs sunset/sunrise checks and refraction correction for
21 sun position calculation. Local coordinate systems are internally transformed
22 to latitude/longitude for the SOLPOS algorithm. Elevation is not taken into
23 account for sunset/sunrise calculations.
24
25 <p>
26 The solar zenith angle ("sun angle above horizon") is defined as the angle
27 between the horizon and the vertical (directly overhead or zenith). Its
28 values can range from 90&deg;, when the sun is directly overhead, to 0&deg;,
29 when the sun is on the horizon. Values lower than 0&deg; indicate that the
30 sun is below the horizon.
31
32 <p>
33 The solar azimuth angle ("sun azimuth") defines the direction of the sun.
34 It is the angle between north and the projection of the sun's rays onto the
35 horizontal plane. This angle is measured in a clockwise direction and can
36 vary between 0&deg; and 360&deg;. Specifically, an azimuth of 0&deg; means
37 the sun is in the north, 90&deg; in the east, 180&deg; in the south and
38 270&deg; in the west.
39
40 <h2>NOTES</h2>
41
42 <em>r.sunmask</em> and daylight saving time: Instead of converting the
43 local time to GMT, the SOLPOS algorithm uses what is known as Local
44 Standard Time, which is generally defined as an offset from GMT.
45 So the key is the offset from GMT, which is the solpos Time
46 Zone parameter. If the user specifies clock time (different for
47 winter and summer), s/he would have to change the Time Zone parameter in
48 <em>r.sunmask</em> (<b>timezone</b> parameter) seasonally. See also
49 <a href="https://en.wikipedia.org/wiki/Daylight_saving_time_by_country">Daylight saving time by region and country</a>.
50 <p>
51
52 <p>
53 Note: In latitude/longitude projects the position coordinates pair
54 (east/west) has to be specified in decimal degree (not DD:MM:SS). If
55 not specified, the map center's coordinates will be used.
56 Also <em>g.region -l</em> displays the map center's coordinates in
57 latitude/longitude (or <em>g.region -c</em> in the actual coordinate
58 system).
59
60 <p>
61 Note for module usage with the <em>-g</em> flag, when performing calculations
62 close to sunset/sunrise:
63
64 <div class="code"><pre>
65 [...]
66 sunangleabovehorizont=0.434240
67 sunrise=07:59:19
68 sunset=16:25:17
69 Time (07:59:02) is before sunrise (07:59:19)!
70 WARNING: Nothing to calculate. Please verify settings.
71 No map calculation requested. Finished.
72 </pre></div>
73
74 In above calculation it appears to be a mistake as
75 the program indicates that we are before sunrise while
76 the <i>sun angle above horizon</i> is already positive.
77 The reason is that <i>sun angle above horizon</i> is
78 calculated with correction for atmosphere refraction while
79 <i>sunrise</i> and <i>sunset</i> are calculated <b>without</b>
80 correction for atmosphere refraction. The output without
81 <em>-g</em> flag contains related indications.
82
83 <h2>EXAMPLE</h2>
84
85 Example for North Carolina sample data set for the calculation
86 of sun position angles and more:
87
88 <div class="code"><pre>
89 # set the region to a place near Raleigh (NC)
90 g.region raster=elev_lid792_1m -p
91
92 # compute only sun position and no output map
93 r.sunmask -s elev_lid792_1m year=2012 month=2 \
94 day=22 hour=10 minute=30 timezone=-5
95 Using map center coordinates: 638650.000000 220375.000000
96 Calculating sun position... (using solpos (V. 11 April 2001) from NREL)
97 2012/02/22, daynum: 53, time: 10:30:00 (decimal time: 10.500000)
98 long: -78.678856, lat: 35.736160, timezone: -5.000000
99 Solar position: sun azimuth: 143.006409, sun angle above horz. (refraction corrected): 36.233879
100 Sunrise time (without refraction): 06:58:11
101 Sunset time (without refraction): 17:58:47
102
103 # with -g flag, useful for eval() shell function
104 r.sunmask -s -g elev_lid792_1m year=2012 month=2 \
105 day=22 hour=10 minute=30 timezone=-5
106 Using map center coordinates: 638650.000000 220375.000000
107 Calculating sun position... (using solpos (V. 11 April 2001) from NREL)
108 date=2012/02/22
109 daynum=53
110 time=10:30:00
111 decimaltime=10.500000
112 longitudine=-78.678856
113 latitude=35.736160
114 timezone=-5.000000
115 sunazimuth=143.006409
116 sunangleabovehorizon=36.233879
117 sunrise=06:58:11
118 sunset=17:58:47
119 </pre></div>
120
121 <h2>Acknowledgements</h2>
122
123 Acknowledgements: National Renewable Energy Laboratory for their
124 <a href="https://www.nrel.gov/grid/solar-resource/solpos.html">SOLPOS 2.0</a> sun position
125 algorithm.
126
127 <h2>SEE ALSO</h2>
128
129 <em>
130 <a href="g.region.html">g.region</a>,
131 <a href="r.sun.html">r.sun</a>,
132 <a href="r.sunhours.html">r.sunhours</a>,
133 <a href="r.slope.aspect.html">r.slope.aspect</a>
134 </em>
135
136 <h2>AUTHORS</h2>
137
138 Janne Soimasuo, Finland, 1994<br>
139 update to FP by Huidae Cho, 2001<br>
140 SOLPOS algorithm feature added by Markus Neteler, 2001