Provided by: grass-doc_7.8.2-1build3_all bug

NAME

       r.horizon  - Computes horizon angle height from a digital elevation model.
       The  module  has  two  different modes of operation: 1. Computes the entire horizon around a single point
       whose coordinates are given with the ’coord’ option. The horizon height (in radians). 2. Computes one  or
       more  raster  maps  of  the  horizon  height  in  a single direction. The input for this is the angle (in
       degrees), which is measured counterclockwise with east=0, north=90 etc. The output is the horizon  height
       in radians.

KEYWORDS

       raster, solar, sun position

SYNOPSIS

       r.horizon
       r.horizon --help
       r.horizon   [-dc]   elevation=name    [direction=float]     [step=float]     [start=float]    [end=float]
       [bufferzone=float]       [e_buff=float]        [w_buff=float]        [n_buff=float]        [s_buff=float]
       [maxdistance=float]     [output=basename]     [coordinates=east,north]    [distance=float]    [file=name]
       [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

   Flags:
       -d
           Write output in degrees (default is radians)

       -c
           Write output in compass orientation (default is CCW, East=0)

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

       direction=float
           Direction in which you want to know the horizon height

       step=float
           Angle step size for multidirectional horizon [degrees]

       start=float
           Start angle for multidirectional horizon [degrees]
           Default: 0.0

       end=float
           End angle for multidirectional horizon [degrees]
           Default: 360.0

       bufferzone=float
           For horizon rasters, read from the DEM an extra buffer around the present region

       e_buff=float
           For horizon rasters, read from the DEM an extra buffer eastward the present region

       w_buff=float
           For horizon rasters, read from the DEM an extra buffer westward the present region

       n_buff=float
           For horizon rasters, read from the DEM an extra buffer northward the present region

       s_buff=float
           For horizon rasters, read from the DEM an extra buffer southward the present region

       maxdistance=float
           The maximum distance to consider when finding the horizon height

       output=basename
           Name for output basename raster map(s)

       coordinates=east,north
           Coordinate for which you want to calculate the horizon

       distance=float
           Sampling distance step coefficient (0.5-1.5)
           Default: 1.0

       file=name
           Name of file for output (use output=- for stdout)
           Default: -

DESCRIPTION

       r.horizon computes the angular height of terrain horizon in radians. It reads a raster of elevation  data
       and outputs the horizon outline in one of two modes:

           •   single  point:  as  a series of horizon heights in the specified directions from the given point.
               The results are written to the stdout.

           •   raster: in this case the output is one or more raster maps, with each point in  a  raster  giving
               the horizon height in a specific direction. One raster is created for each direction.

       The  directions  are  given as azimuthal angles (in degrees), with the angle starting with 0 towards East
       and moving counterclockwise  (North  is  90,  etc.).  The  calculation  takes  into  account  the  actual
       projection,  so the angles are corrected for direction distortions imposed by it. The directions are thus
       aligned to those of the geographic projection and not the coordinate system given by the rows and columns
       of  the  raster  map.  This  correction  implies  that  the  resulting cardinal directions represent true
       orientation towards the East, North, West and South. The only exception of this feature is LOCATION  with
       x,y coordinate system, where this correction is not applied.

       Using the -c flag, the azimuthal angles will be printed in compass orientation (North=0, clockwise).

   Input parameters:
       The  elevation  parameter  is  an input elevation raster map. If the buffer options are used (see below),
       this raster should extend over the area that accommodate the presently defined region plus defined buffer
       zones.

       The  step  parameter  gives  the  angle step (in degrees) between successive azimuthal directions for the
       calculation of the horizon. Thus, a value of 5 for the step will give a total of 360/5=72 directions  (72
       raster maps if used in the raster map mode).

       The  start  parameter  gives the angle start (in degrees) for the calculation of the horizon. The default
       value is 0 (East with North being 90 etc.).

       The end parameter gives the angle end (in degrees) for the calculation of the horizon. The end  point  is
       omitted!   So for example if we run r.horizon with step=10, start=30 and end=70 the raster maps generated
       by r.horizon will be only for angles: 30, 40, 50, 60. The default value is 360.

       The direction parameter gives the initial direction of the  first  output.  This  parameter  acts  as  an
       direction angle offset. For example, if you want to get horizon angles for directions 45 and 225 degrees,
       the direction should be set to 45 and step to 180. If you  only  want  one  single  direction,  use  this
       parameter  to  specify  desired direction of horizon angle, and set the step size to 0 degrees. Otherwise
       all angles for a given starting direction with step of step are calculated.

       The distance controls the sampling distance step size for the search for horizon along the line of sight.
       The  default  value  is 1.0 meaning that the step size will be taken from the raster resolution.  Setting
       the value below 1.0 might slightly improve results for directions  apart  from  the  cardinal  ones,  but
       increasing the processing load of the search algorithm.

       The  maxdistance  value  gives a maximum distance to move away from the origin along the line of sight in
       order to search for the horizon height.  The default maxdistance is the full  map  extent.   The  smaller
       this  value  the  faster the calculation but the higher the risk that you may miss a terrain feature that
       can contribute significantly to the horizon  outline.  Note  that  a  viewshed  can  be  calculated  with
       r.viewshed.

       The  coordinate  parameter  takes  a pair of easting-northing values in the current coordinate system and
       calculates the values of angular height of the horizon around this point. To achieve the  consistency  of
       the results, the point coordinate is aligned to the midpoint of the closest elevation raster cell.

       If  an  analyzed  point  (or  raster  cell)  lies  close  to  the edge of the defined region, the horizon
       calculation may not be realistic, since it may not see some significant terrain features which could have
       contributed  to  the  horizon, because these features are outside the region. There are to options how to
       set the size of the buffer that is used to increase the area of  the  horizon  analysis.  The  bufferzone
       parameter  allows  you  to specify the same size of buffer for all cardinal directions and the parameters
       e_buff, n_buff, s_buff, and w_buff allow you to specify a buffer size individually for each of  the  four
       directions.  The  buffer  parameters influence only size of the read elevation map, while the analysis in
       the raster mode will be done only for the area specified by the current region definition.

       The output parameter defines the basename of the output horizon raster maps.  The  raster  name  of  each
       horizon  direction raster will be constructed as basename_ANGLE, where ANGLE is the angle in degrees with
       the direction. If you use r.horizon in the single point mode this option will be ignored.

       The file parameter allows saving the resulting horizon angles in a comma  separated  ASCII  file  (single
       point mode only). If you use r.horizon in the raster map mode this option will be ignored.

       At the moment the elevation and maximum distance must be measured in meters, even if you use geographical
       coordinates (longitude/latitude). If your projection is based on distance (easting and  northing),  these
       too  must  be in meters. The buffer parameters must be in the same units as the raster coordinates (e.g.,
       for latitude-longitude locations buffers are measured in degree unit).

METHOD

       The calculation method is based on the method used in r.sun to calculate shadows. It  starts  at  a  very
       shallow  angle  and  walks along the line of sight and asks at each step whether the line of sight "hits"
       the terrain. If so, the angle is increased to allow the line of sight to pass just above the  terrain  at
       that  point.  This is continued until the line of sight reaches a height that is higher than any point in
       the region or until it reaches the border of the region (see also the bufferzone,e_buff, n_buff,  s_buff,
       and  w_buff).  The the number of lines of sight (azimuth directions) is determined from the direction and
       step parameters. The method takes into account the curvature of the Earth whereby  remote  features  will
       seem  to  be  lower  than  they actually are. It also accounts for the changes of angles towards cardinal
       directions caused by the projection (see above).

EXAMPLES

       The examples are intended for the North Carolina sample dataset.

   Single point mode
       Example 1: determine horizon angle in 225 degree direction (output of horizon angles CCW from East):
       g.region raster=elevation -p
       r.horizon elevation=elevation direction=215 step=0 bufferzone=200 \
           coordinates=638871.6,223384.4 maxdistance=5000

       Example 2: determine horizon values starting at 90 deg (North), step size of 5 deg, saving result as  CSV
       file:
       r.horizon elevation=elevation direction=90 step=5 bufferzone=200 \
           coordinates=638871.6,223384.4 maxdistance=5000 file=horizon.csv

       Example  3:  test  point  near  highway  intersection, saving result as CSV file for plotting the horizon
       around the highway intersection:
       g.region n=223540 s=220820 w=634650 e=638780 res=10 -p
       r.horizon elevation=elevation direction=0 step=5 bufferzone=200 \
           coordinates=636483.54,222176.25 maxdistance=5000 -d file=horizon.csv
       Test point near high way intersection (North Carolina sample dataset)

       Horizon angles for test point (CCW from East)

       We can plot horizon in polar coordinates using Matplotlib in Python:
       import numpy as np
       import matplotlib.pyplot as plt
       horizon = np.genfromtxt(’horizon.csv’, delimiter=’,’)
       horizon = horizon[1:, :]
       ax = plt.subplot(111, polar=True)
       bars = ax.plot(horizon[:, 0] / 180 * np.pi,
                      (90 - horizon[:, 1]) / 180 * np.pi)
       # uncomment the 2 following lines when using -c flag
       # ax.set_theta_direction(-1)
       # ax.set_theta_zero_location(’N’)
       plt.show()
       Horizon plot in polar coordinates.

   Raster map mode
       Raster map mode (output maps "horangle*" become input for r.sun):
       g.region raster=elevation -p
       # we put a bufferzone of 10% of maxdistance around the study area
       # compute only direction between 90 and 270 degrees
       r.horizon elevation=elevation step=30 start=90 end=300 \
           bufferzone=200 output=horangle maxdistance=5000

REFERENCES

       Hofierka J., 1997. Direct solar radiation modelling  within  an  open  GIS  environment.  Proceedings  of
       JEC-GI’97 conference in Vienna, Austria, IOS Press Amsterdam, 575-584

       Hofierka  J.,  Huld  T., Cebecauer T., Suri M., 2007. Open Source Solar Radiation Tools for Environmental
       and Renewable Energy Applications, International Symposium on  Environmental  Software  Systems,  Prague,
       2007

       Neteler  M.,  Mitasova  H.,  2004.  Open  Source  GIS:  A  GRASS GIS Approach, Springer, New York.  ISBN:
       1-4020-8064-6, 2nd Edition 2004 (reprinted 2005), 424 pages

       Project PVGIS, European Commission, DG Joint Research Centre 2001-2007

       Suri M., Hofierka J., 2004.  A New GIS-based Solar Radiation Model and Its Application  for  Photovoltaic
       Assessments. Transactions in GIS, 8(2), 175-190

SEE ALSO

        r.sun, r.sunmask, r.viewshed

AUTHORS

       Thomas Huld, Joint Research Centre of the European Commission, Ispra, Italy

       Tomas Cebecauer, Joint Research Centre of the European Commission, Ispra, Italy

       Jaroslav Hofierka, GeoModel s.r.o., Bratislava, Slovakia
       Marcel Suri, Joint Research Centre of the European Commission, Ispra, Italy

       ©   2007,   Thomas   Huld,   Tomas   Cebecauer,   Jaroslav   Hofierka,   Marcel  Suri  Thomas.Huld@jrc.it
       Tomas.Cebecauer@jrc.it hofierka@geomodel.sk Marcel.Suri@jrc.it

SOURCE CODE

       Available at: r.horizon source code (history)

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

       © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual