Provided by: grass-doc_6.4.3-3_all 
NAME
r.horizon - Horizon angle computation from a digital elevation model.
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, sun position
SYNOPSIS
r.horizon
r.horizon help
r.horizon [-d] elevin=string [direction=float] [horizonstep=float] [bufferzone=float]
[e_buff=float] [w_buff=float] [n_buff=float] [s_buff=float] [maxdistance=float]
[horizon=string] [coord=east,north] [dist=float] [--verbose] [--quiet]
Flags:
-d
Write output in degrees (default is radians)
--verbose
Verbose module output
--quiet
Quiet module output
Parameters:
elevin=string
Name of the input elevation raster map [meters]
direction=float
Direction in which you want to know the horizon height
horizonstep=float
Angle step size for multidirectional horizon [degrees]
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
horizon=string
Prefix of the horizon raster output maps
coord=east,north
Coordinate for which you want to calculate the horizon
dist=float
Sampling distance step coefficient (0.5-1.5)
Default: 1.0
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 rasters, 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.
Flags:
-d
Output horizon height in degrees (the default is radians)
Input parameters:
The elevin 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 horizonstep parameter gives the angle step (in degrees) between successive azimuthal directions for
the calculation of the horizon. Thus, a value of 5 for the horizonstep will give a total of 360/5=72
directions (72 rasters if used in the raster mode).
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 horizonstep to 180. If you only want one single direction, use this
parameter to specify desired direction of horizon angle, and set the horizonstep size to 0 degrees.
The dist 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 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.
The coord 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 horizon parameter gives the prefix of the output horizon raster maps. The raster name of each horizon
direction raster will be constructed as horizon_NNN , where NNN counts upwards from 0 to total number of
directions. If you use r.horizon in the single point 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.
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
horizonstep 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).
EXAMPLE
Single point mode:
r.horizon elevin=DEM horizonstep=30 direction=15 bufferzone=200 \
coord=47.302,7.365 dist=0.7 > horizon.out
Raster map mode (for r.sun):
# we put a bufferzone of 10% of maxdistance around the study area
r.horizon elevin=DEM horizonstep=30 bufferzone=200 horizon=horangle \
dist=0.7 maxdistance=2000
SEE ALSO
r.sun, r.sunmask, r.los
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
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
Last changed: $Date: 2011-11-08 03:29:50 -0800 (Tue, 08 Nov 2011) $
Full index
© 2003-2013 GRASS Development Team
GRASS 6.4.3 r.horizon(1grass)