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 sun position. The output map layer contains
103 the cast shadow areas arising from sun shine and elevations. The user
104 can define the sun position either directly or the module calculates it
105 from given location and date/time parameters using the NREL sun posi‐
106 tion algorithm. So either "A:"-parameters to specify the exact known
107 sun position or "B:-parameters" to specify date/time for sun position
108 calculation by r.sunmask itself have to be used.
109 The module performs sunset/sunrise checks and refraction correction for
111 sun position calculation. Local coordinate systems are internally
112 transformed to latitude/longitude for the SOLPOS algorithm. The eleva‐
113 tion is not considered in the sunset/sunrise calculations.
114
116 r.sunmask and daylight savings: Rather than converting the local time
117 to GMT, the SOLPOS algorithm uses what is called Local Standard Time,
118 which is generally politically defined as an offset from GMT. So the
119 key is the offset from GMT, which the solpos Time Zone parameter. If
120 the user specifies clock time (different for winter and summer), s/he
121 would have to change the Time Zone parameter seasonally in r.sunmask
122 (timezone parameter). See also Daylight saving time by region and coun‐
123 try.
124 Note: In latitude/longitude locations the position coordinates pair
126 (east/west) has to be specified in decimal degree (not D:M:S). If not
127 specified, the map center’s coordinates will be used. Also g.region -l
128 displays the map center’s coordinates in latitude/longitude (or g.re‐
129 gion -c in the actual coordinate system).
130 Note for module usage with the -g flag, when performing calculations
132 close to sunset/sunrise:
133 [...]
134 sunangleabovehorizont=0.434240
135 sunrise=07:59:19
136 sunset=16:25:17
137 Time (07:59:02) is before sunrise (07:59:19)!
138 WARNING: Nothing to calculate. Please verify settings.
139 No map calculation requested. Finished.
140 In above calculation it appears to be a mistake as the program indi‐
141 cates that we are before sunrise while the sun angle above horizon is
142 already positive. The reason is that sun angle above horizon is calcu‐
143 lated with correction for atmosphere refraction while sunrise and sun‐
144 set are calculated without correction for atmosphere refraction. The
145 output without -g flag contains related indications.
146
148 Example for North Carolina sample data set for the calculation of sun
149 position angles and more:
150 # set the region to a place near Raleigh (NC)
151 g.region raster=elev_lid792_1m -p
152 # compute only sun position and no output map
153 r.sunmask -s elev_lid792_1m year=2012 month=2 \
154 day=22 hour=10 minute=30 timezone=-5
155 Using map center coordinates: 638650.000000 220375.000000
156 Calculating sun position... (using solpos (V. 11 April 2001) from NREL)
157 2012/02/22, daynum: 53, time: 10:30:00 (decimal time: 10.500000)
158 long: -78.678856, lat: 35.736160, timezone: -5.000000
159 Solar position: sun azimuth: 143.006409, sun angle above horz. (refraction corrected): 36.233879
160 Sunrise time (without refraction): 06:58:11
161 Sunset time (without refraction): 17:58:47
162 # with -g flag, useful for eval() shell function
163 r.sunmask -s -g elev_lid792_1m year=2012 month=2 \
164 day=22 hour=10 minute=30 timezone=-5
165 Using map center coordinates: 638650.000000 220375.000000
166 Calculating sun position... (using solpos (V. 11 April 2001) from NREL)
167 date=2012/02/22
168 daynum=53
169 time=10:30:00
170 decimaltime=10.500000
171 longitudine=-78.678856
172 latitude=35.736160
173 timezone=-5.000000
174 sunazimuth=143.006409
175 sunangleabovehorizon=36.233879
176 sunrise=06:58:11
177 sunset=17:58:47
178
180 Acknowledgements: National Renewable Energy Laboratory for their SOLPOS
181 2.0 sun position algorithm.
182
184 g.region, r.sun, r.sunhours, r.slope.aspect
185
187 Janne Soimasuo, Finland 1994
188 update to FP by Huidae Cho 2001
189 SOLPOS algorithm feature added by Markus Neteler 2001
190
192 Available at: r.sunmask source code (history)
193 Accessed: Saturday Jan 21 21:15:15 2023
195 Main index | Raster index | Topics index | Keywords index | Graphical
197 index | Full index
198 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
200GRASS 8.2.1 r.sunmask(1)