Provided by: grass-doc_8.3.0-1_all bug

NAME

       r.sunmask  - Calculates cast shadow areas from sun position and elevation raster map.
       Either exact sun position (A) is specified, or date/time to calculate the sun position (B)
       by r.sunmask itself.

KEYWORDS

       raster, solar, sun position, shadow

SYNOPSIS

       r.sunmask
       r.sunmask --help
       r.sunmask  [-zsg]  elevation=name   [output=name]     [altitude=float]     [azimuth=float]
       [year=integer]     [month=integer]     [day=integer]    [hour=integer]    [minute=integer]
       [second=integer]    [timezone=integer]    [east=value]     [north=value]     [--overwrite]
       [--help]  [--verbose]  [--quiet]  [--ui]

   Flags:
       -z
           Do not ignore zero elevation

       -s
           Calculate sun position only and exit

       -g
           Print the sun position output in shell script style

       --overwrite
           Allow output files to overwrite existing files

       --help
           Print usage summary

       --verbose
           Verbose module output

       --quiet
           Quiet module output

       --ui
           Force launching GUI dialog

   Parameters:
       elevation=name [required]
           Name of input elevation raster map

       output=name
           Name for output raster map

       altitude=float
           Altitude of the sun in degrees above the horizon (A)
           Options: 0-89.999

       azimuth=float
           Azimuth of the sun in degrees from north (A)
           Options: 0-360

       year=integer
           Year (B)
           Options: 1950-2050

       month=integer
           Month (B)
           Options: 0-12

       day=integer
           Day (B)
           Options: 0-31

       hour=integer
           Hour (B)
           Options: 0-24

       minute=integer
           Minutes (B)
           Options: 0-60

       second=integer
           Seconds (B)
           Options: 0-60
           Default: 0

       timezone=integer
           Timezone
           East positive, offset from GMT, also use to adjust daylight savings

       east=value
           Easting coordinate (point of interest)
           Default: map center

       north=value
           Northing coordinate (point of interest)
           Default: map center

DESCRIPTION

       r.sunmask creates an output map layer based on an input elevation raster map layer and the
       sun position. The output map layer contains the cast shadow areas arising from  sun  shine
       and  elevations.  The  user  can  define  the  sun  position either directly or the module
       calculates it from given location and date/time parameters using  the  NREL  sun  position
       algorithm.  So  either  "A:"-parameters  to  specify  the  exact  known  sun  position  or
       "B:-parameters" to specify date/time for sun position calculation by r.sunmask itself have
       to be used.

       The  module  performs  sunset/sunrise  checks  and  refraction correction for sun position
       calculation. Local coordinate systems are internally transformed to latitude/longitude for
       the SOLPOS algorithm. The elevation is not considered in the sunset/sunrise calculations.

NOTES

       r.sunmask  and  daylight savings: Rather than converting the local time to GMT, the SOLPOS
       algorithm uses what is called Local Standard Time, which is generally politically  defined
       as  an  offset  from  GMT.   So the key is the offset from GMT, which the solpos Time Zone
       parameter. If the user specifies clock time (different for winter and summer), s/he  would
       have  to  change the Time Zone parameter seasonally in r.sunmask (timezone parameter). See
       also Daylight saving time by region and country.

       Note: In latitude/longitude locations the position coordinates pair (east/west) has to  be
       specified  in  decimal  degree (not D:M:S). If not specified, the map center’s coordinates
       will  be  used.   Also  g.region   -l   displays   the   map   center’s   coordinates   in
       latitude/longitude (or g.region -c in the actual coordinate system).

       Note   for  module  usage  with  the  -g  flag,  when  performing  calculations  close  to
       sunset/sunrise:
        [...]
        sunangleabovehorizont=0.434240
        sunrise=07:59:19
        sunset=16:25:17
        Time (07:59:02) is before sunrise (07:59:19)!
        WARNING: Nothing to calculate. Please verify settings.
        No map calculation requested. Finished.
       In above calculation it appears to be a mistake as  the  program  indicates  that  we  are
       before  sunrise while the sun angle above horizon is already positive.  The reason is that
       sun angle above horizon is calculated with  correction  for  atmosphere  refraction  while
       sunrise and sunset are calculated without correction for atmosphere refraction. The output
       without -g flag contains related indications.

EXAMPLE

       Example for North Carolina sample data set for the calculation of sun position angles  and
       more:
       # set the region to a place near Raleigh (NC)
       g.region raster=elev_lid792_1m -p
       # compute only sun position and no output map
       r.sunmask -s elev_lid792_1m year=2012 month=2 \
                 day=22 hour=10 minute=30 timezone=-5
       Using map center coordinates: 638650.000000 220375.000000
       Calculating sun position... (using solpos (V. 11 April 2001) from NREL)
       2012/02/22, daynum: 53, time: 10:30:00 (decimal time: 10.500000)
       long: -78.678856, lat: 35.736160, timezone: -5.000000
       Solar position: sun azimuth: 143.006409, sun angle above horz. (refraction corrected): 36.233879
       Sunrise time (without refraction): 06:58:11
       Sunset time  (without refraction): 17:58:47
       # with -g flag, useful for eval() shell function
       r.sunmask -s -g elev_lid792_1m  year=2012 month=2 \
                 day=22 hour=10 minute=30 timezone=-5
       Using map center coordinates: 638650.000000 220375.000000
       Calculating sun position... (using solpos (V. 11 April 2001) from NREL)
       date=2012/02/22
       daynum=53
       time=10:30:00
       decimaltime=10.500000
       longitudine=-78.678856
       latitude=35.736160
       timezone=-5.000000
       sunazimuth=143.006409
       sunangleabovehorizon=36.233879
       sunrise=06:58:11
       sunset=17:58:47

Acknowledgements

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

SEE ALSO

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

AUTHORS

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

SOURCE CODE

       Available at: r.sunmask source code (history)

       Accessed: Tuesday Jun 27 11:13:14 2023

       Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

       © 2003-2023 GRASS Development Team, GRASS GIS 8.3.0 Reference Manual