xenial (1) r.sunmask.1grass.gz

Provided by: grass-doc_7.0.3-1build1_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

AUTHOR

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

       Last changed: $Date: 2014-12-19 22:55:37 +0100 (Fri, 19 Dec 2014) $

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

       © 2003-2016 GRASS Development Team, GRASS GIS 7.0.3 Reference Manual