| 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°, when the sun is directly overhead, to 0°, |
| 29 |
when the sun is on the horizon. Values lower than 0° 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° and 360°. Specifically, an azimuth of 0° means |
| 37 |
the sun is in the north, 90° in the east, 180° in the south and |
| 38 |
270° 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 |