Provided by: grass-doc_6.4.3-3_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, sun position

SYNOPSIS

       r.sunmask
       r.sunmask help
       r.sunmask  [-zvsg]  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]
       [--verbose]  [--quiet]

   Flags:
       -z
           Don't ignore zero elevation

       -v
           Verbose output (also print out sun position etc.)

       -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

       --verbose
           Verbose module output

       --quiet
           Quiet module output

   Parameters:
       elevation=name
           Name of elevation raster map

       output=name
           Name for output raster map

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

       azimuth=float
           Azimuth of the sun from the north, degrees (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

       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 convert time to GMT, the solpos algorithm uses
       what is called Local Standard Time, which is generally defined politically  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),  he/she  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.

       Note for module usage with -g flag and 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 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 rast=elev_lid792_1m -p
       # compute the sun position
       r.sunmask -s --v elev_lid792_1m out=dummy year=2012 month=2 \
                 day=22 hour=10 minute=30 sec=0 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.006424, sun angle above horz. (refraction corrected):
       36.233883
       Sunrise time (without refraction): 06:58:11
       Sunset time  (without refraction): 17:58:47
       # with -g flag
       r.sunmask -s -g --v elev_lid792_1m out=dummy year=2012 month=2 \
                 day=22 hour=10 minute=30 sec=0 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.006424
       sunangleabovehorizon=36.233883
       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.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: 2012-03-29 01:32:53 -0700 (Thu, 29 Mar 2012) $

       Full index

       © 2003-2013 GRASS Development Team