1r.sunmask(1)                GRASS GIS User's Manual               r.sunmask(1)
2
3
4

NAME

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

KEYWORDS

12       raster, solar, sun position, shadow
13

SYNOPSIS

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
23   Flags:
24       -z
25           Do not ignore zero elevation
26
27       -s
28           Calculate sun position only and exit
29
30       -g
31           Print the sun position output in shell script style
32
33       --overwrite
34           Allow output files to overwrite existing files
35
36       --help
37           Print usage summary
38
39       --verbose
40           Verbose module output
41
42       --quiet
43           Quiet module output
44
45       --ui
46           Force launching GUI dialog
47
48   Parameters:
49       elevation=name [required]
50           Name of input elevation raster map
51
52       output=name
53           Name for output raster map
54
55       altitude=float
56           Altitude of the sun in degrees above the horizon (A)
57           Options: 0-89.999
58
59       azimuth=float
60           Azimuth of the sun in degrees from north (A)
61           Options: 0-360
62
63       year=integer
64           Year (B)
65           Options: 1950-2050
66
67       month=integer
68           Month (B)
69           Options: 0-12
70
71       day=integer
72           Day (B)
73           Options: 0-31
74
75       hour=integer
76           Hour (B)
77           Options: 0-24
78
79       minute=integer
80           Minutes (B)
81           Options: 0-60
82
83       second=integer
84           Seconds (B)
85           Options: 0-60
86           Default: 0
87
88       timezone=integer
89           Timezone
90           East positive, offset from GMT, also use to adjust daylight savings
91
92       east=value
93           Easting coordinate (point of interest)
94           Default: map center
95
96       north=value
97           Northing coordinate (point of interest)
98           Default: map center
99

DESCRIPTION

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
110       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

NOTES

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
125       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
131       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

EXAMPLE

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

Acknowledgements

180       Acknowledgements: National Renewable Energy Laboratory for their SOLPOS
181       2.0 sun position algorithm.
182

SEE ALSO

184        g.region, r.sun, r.sunhours, r.slope.aspect
185

AUTHORS

187       Janne Soimasuo, Finland 1994
188       update to FP by Huidae Cho 2001
189       SOLPOS algorithm feature added by Markus Neteler 2001
190

SOURCE CODE

192       Available at: r.sunmask source code (history)
193
194       Accessed: Saturday Jan 21 21:15:15 2023
195
196       Main index | Raster index | Topics index | Keywords index  |  Graphical
197       index | Full index
198
199       © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
200
201
202
203GRASS 8.2.1                                                       r.sunmask(1)
Impressum