1r.sunmask(1) GRASS GIS User's Manual r.sunmask(1)
2
6 r.sunmask - Calculates cast shadow areas from sun position and eleva‐
7 tion raster map.
8 Either exact sun position (A) is specified, or date/time to calculate
9 the sun position (B) by r.sunmask itself.
10
12 raster, solar, sun position, shadow
13
15 r.sunmask
16 r.sunmask --help
17 r.sunmask [-zsg] elevation=name [output=name] [altitude=float]
18 [azimuth=float] [year=integer] [month=integer] [day=integer]
19 [hour=integer] [minute=integer] [second=integer] [timezone=inte‐
20 ger] [east=value] [north=value] [--overwrite] [--help] [--ver‐
21 bose] [--quiet] [--ui]
22 Flags:
24 -z
25 Do not ignore zero elevation
26 -s
28 Calculate sun position only and exit
29 -g
31 Print the sun position output in shell script style
32 --overwrite
34 Allow output files to overwrite existing files
35 --help
37 Print usage summary
38 --verbose
40 Verbose module output
41 --quiet
43 Quiet module output
44 --ui
46 Force launching GUI dialog
47 Parameters:
49 elevation=name [required]
50 Name of input elevation raster map
51 output=name
53 Name for output raster map
54 altitude=float
56 Altitude of the sun in degrees above the horizon (A)
57 Options: 0-89.999
58 azimuth=float
60 Azimuth of the sun in degrees from north (A)
61 Options: 0-360
62 year=integer
64 Year (B)
65 Options: 1950-2050
66 month=integer
68 Month (B)
69 Options: 0-12
70 day=integer
72 Day (B)
73 Options: 0-31
74 hour=integer
76 Hour (B)
77 Options: 0-24
78 minute=integer
80 Minutes (B)
81 Options: 0-60
82 second=integer
84 Seconds (B)
85 Options: 0-60
86 Default: 0
87 timezone=integer
89 Timezone
90 East positive, offset from GMT, also use to adjust daylight savings
91 east=value
93 Easting coordinate (point of interest)
94 Default: map center
95 north=value
97 Northing coordinate (point of interest)
98 Default: map center
99
101 r.sunmask creates an output map layer based on an input elevation
102 raster map layer and the position of the sun. The output map layer con‐
103 tains the cast shadow areas resulting from sunlight and elevation. The
104 user can either specify the sun position directly or the module calcu‐
105 lates it from given location and date/time parameters using the SOLPOS
106 (Solar and Moon Position Algorithm) developed by the National Renewable
107 Energy Laboratory (NREL). SOLPOS operates in two modes, either
108 • (A) parameters to specify the exact known position of the sun,
110 or
111 • (B) parameters to specify the date/time for the sun position
113 calculation by r.sunmask itself
114 must be used.
115 The module performs sunset/sunrise checks and refraction correction for
117 sun position calculation. Local coordinate systems are internally
118 transformed to latitude/longitude for the SOLPOS algorithm. Elevation
119 is not taken into account for sunset/sunrise calculations.
120 The solar zenith angle ("sun angle above horizon") is defined as the
122 angle between the horizon and the vertical (directly overhead or
123 zenith). Its values can range from 90°, when the sun is directly over‐
124 head, to 0°, when the sun is on the horizon. Values lower than 0° in‐
125 dicate that the sun is below the horizon.
126 The solar azimuth angle ("sun azimuth") defines the direction of the
128 sun. It is the angle between north and the projection of the sun’s
129 rays onto the horizontal plane. This angle is measured in a clockwise
130 direction and can vary between 0° and 360°. Specifically, an azimuth
131 of 0° means the sun is in the north, 90° in the east, 180° in the
132 south and 270° in the west.
133
135 r.sunmask and daylight saving time: Instead of converting the local
136 time to GMT, the SOLPOS algorithm uses what is known as Local Standard
137 Time, which is generally defined as an offset from GMT. So the key is
138 the offset from GMT, which is the solpos Time Zone parameter. If the
139 user specifies clock time (different for winter and summer), s/he would
140 have to change the Time Zone parameter in r.sunmask (timezone parame‐
141 ter) seasonally. See also Daylight saving time by region and country.
142 Note: In latitude/longitude locations the position coordinates pair
144 (east/west) has to be specified in decimal degree (not DD:MM:SS). If
145 not specified, the map center’s coordinates will be used. Also g.re‐
146 gion -l displays the map center’s coordinates in latitude/longitude (or
147 g.region -c in the actual coordinate system).
148 Note for module usage with the -g flag, when performing calculations
150 close to sunset/sunrise:
151 [...]
152 sunangleabovehorizont=0.434240
153 sunrise=07:59:19
154 sunset=16:25:17
155 Time (07:59:02) is before sunrise (07:59:19)!
156 WARNING: Nothing to calculate. Please verify settings.
157 No map calculation requested. Finished.
158 In above calculation it appears to be a mistake as the program indi‐
159 cates that we are before sunrise while the sun angle above horizon is
160 already positive. The reason is that sun angle above horizon is calcu‐
161 lated with correction for atmosphere refraction while sunrise and sun‐
162 set are calculated without correction for atmosphere refraction. The
163 output without -g flag contains related indications.
164
166 Example for North Carolina sample data set for the calculation of sun
167 position angles and more:
168 # set the region to a place near Raleigh (NC)
169 g.region raster=elev_lid792_1m -p
170 # compute only sun position and no output map
171 r.sunmask -s elev_lid792_1m year=2012 month=2 \
172 day=22 hour=10 minute=30 timezone=-5
173 Using map center coordinates: 638650.000000 220375.000000
174 Calculating sun position... (using solpos (V. 11 April 2001) from NREL)
175 2012/02/22, daynum: 53, time: 10:30:00 (decimal time: 10.500000)
176 long: -78.678856, lat: 35.736160, timezone: -5.000000
177 Solar position: sun azimuth: 143.006409, sun angle above horz. (refraction corrected): 36.233879
178 Sunrise time (without refraction): 06:58:11
179 Sunset time (without refraction): 17:58:47
180 # with -g flag, useful for eval() shell function
181 r.sunmask -s -g elev_lid792_1m year=2012 month=2 \
182 day=22 hour=10 minute=30 timezone=-5
183 Using map center coordinates: 638650.000000 220375.000000
184 Calculating sun position... (using solpos (V. 11 April 2001) from NREL)
185 date=2012/02/22
186 daynum=53
187 time=10:30:00
188 decimaltime=10.500000
189 longitudine=-78.678856
190 latitude=35.736160
191 timezone=-5.000000
192 sunazimuth=143.006409
193 sunangleabovehorizon=36.233879
194 sunrise=06:58:11
195 sunset=17:58:47
196
198 Acknowledgements: National Renewable Energy Laboratory for their SOLPOS
199 2.0 sun position algorithm.
200
202 g.region, r.sun, r.sunhours, r.slope.aspect
203
205 Janne Soimasuo, Finland, 1994
206 update to FP by Huidae Cho, 2001
207 SOLPOS algorithm feature added by Markus Neteler, 2001
208
210 Available at: r.sunmask source code (history)
211 Accessed: Saturday Oct 28 18:18:01 2023
213 Main index | Raster index | Topics index | Keywords index | Graphical
215 index | Full index
216 © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
218GRASS 8.3.1 r.sunmask(1)