.TH r.horizon 1grass "" "GRASS 6.4.4" "Grass User's Manual"
.SH NAME
\fI\fBr.horizon\fR\fR  - Horizon angle computation from a digital elevation model.
.br
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.
.SH KEYWORDS
raster, sun position
.SH SYNOPSIS
\fBr.horizon\fR
.br
\fBr.horizon help\fR
.br
\fBr.horizon\fR [\-\fBd\fR] \fBelevin\fR=\fIstring\fR  [\fBdirection\fR=\fIfloat\fR]   [\fBhorizonstep\fR=\fIfloat\fR]   [\fBbufferzone\fR=\fIfloat\fR]   [\fBe_buff\fR=\fIfloat\fR]   [\fBw_buff\fR=\fIfloat\fR]   [\fBn_buff\fR=\fIfloat\fR]   [\fBs_buff\fR=\fIfloat\fR]   [\fBmaxdistance\fR=\fIfloat\fR]   [\fBhorizon\fR=\fIstring\fR]   [\fBcoord\fR=\fIeast,north\fR]   [\fBdist\fR=\fIfloat\fR]   [\-\-\fBverbose\fR]  [\-\-\fBquiet\fR] 
.SS Flags:
.IP "\fB\-d\fR" 4m
.br
Write output in degrees (default is radians)
.IP "\fB\-\-verbose\fR" 4m
.br
Verbose module output
.IP "\fB\-\-quiet\fR" 4m
.br
Quiet module output
.PP
.SS Parameters:
.IP "\fBelevin\fR=\fIstring\fR" 4m
.br
Name of the input elevation raster map [meters]
.IP "\fBdirection\fR=\fIfloat\fR" 4m
.br
Direction in which you want to know the horizon height
.IP "\fBhorizonstep\fR=\fIfloat\fR" 4m
.br
Angle step size for multidirectional horizon [degrees]
.IP "\fBbufferzone\fR=\fIfloat\fR" 4m
.br
For horizon rasters, read from the DEM an extra buffer around the present region
.IP "\fBe_buff\fR=\fIfloat\fR" 4m
.br
For horizon rasters, read from the DEM an extra buffer eastward the present region
.IP "\fBw_buff\fR=\fIfloat\fR" 4m
.br
For horizon rasters, read from the DEM an extra buffer westward the present region
.IP "\fBn_buff\fR=\fIfloat\fR" 4m
.br
For horizon rasters, read from the DEM an extra buffer northward the present region
.IP "\fBs_buff\fR=\fIfloat\fR" 4m
.br
For horizon rasters, read from the DEM an extra buffer southward the present region
.IP "\fBmaxdistance\fR=\fIfloat\fR" 4m
.br
The maximum distance to consider when finding the horizon height
.IP "\fBhorizon\fR=\fIstring\fR" 4m
.br
Prefix of the horizon raster output maps
.IP "\fBcoord\fR=\fIeast,north\fR" 4m
.br
Coordinate for which you want to calculate the horizon
.IP "\fBdist\fR=\fIfloat\fR" 4m
.br
Sampling distance step coefficient (0.5-1.5)
.br
Default: \fI1.0\fR
.PP
.SH DESCRIPTION
\fBr.horizon\fR 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:
.RS
.IP
 single point: as a series of horizon 
heights in the specified directions from the given point. The results are
written to the stdout.
.IP
 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.
.RE
.PP
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. 
.SS Flags:
.IP "\fB\-d\fR
.br
Output horizon height in degrees (the default is radians)
.PP
.SS Input parameters:
.PP
The \fIelevin\fR 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. 
.PP
The \fIhorizonstep\fR parameter gives the angle step (in degrees)
between successive azimuthal directions for the calculation of the
horizon. Thus, a value of 5 for the \fIhorizonstep\fR will give a total of
360/5=72 directions (72 raster maps if used in the raster mode). 
.PP
The \fIdirection\fR 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 \fIdirection\fR should be set to 45 and \fIhorizonstep\fR to
180. If you only want one single direction, use this parameter to
specify desired direction of horizon angle, and set the \fIhorizonstep\fR
size to 0 degrees. Otherwise all angles for a given starting \fIdirection\fR
with step of \fIhorizon_step\fR are calculated.
.PP
The \fIdist \fRcontrols 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. 
.PP
The \fImaxdistance\fR 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.
.PP
The \fIcoord\fR 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. 
.PP
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
\fIbufferzone\fR parameter allows you to specify the same size of
buffer for all cardinal directions and the parameters \fIe_buff\fR,
\fIn_buff\fR, \fIs_buff\fR, and \fIw_buff\fR 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.
.PP
The \fIhorizon \fRparameter gives the prefix of the output
horizon raster maps. The raster name of each horizon direction
raster will be constructed as \fIhorizon_\fRNNN , where NNN counts
upwards from 0 to total number of directions. If you use \fBr.horizon\fR
in the single point mode this option will be ignored. 
.PP
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.
.SH METHOD
.PP
The calculation method is based on the method used in \fBr.sun\fR
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 \fIbufferzone,e_buff\fR, \fIn_buff\fR,
\fIs_buff\fR, and \fIw_buff\fR). The the number of lines of sight (azimuth 
directions) is determined from the \fIdirection\fR and
\fIhorizonstep\fR 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). 
.SH EXAMPLES
Single point mode:
\fC
.DS
.br
# determine horizon in 225 degree direction:
.br
r.horizon elevin=elevation direction=215 horizonstep=0 bufferzone=200 \(rs
.br
    coordinate=638871.6,223384.4
.br
.br
# determine horizon values starting at 215 deg, with step size of 30 deg:
.br
r.horizon elevin=elevation direction=215 horizonstep=30 bufferzone=200 \(rs
.br
coordinate=637500.0,221750.0
.DE
\fR
Raster map mode (for r.sun):
\fC
.DS
.br
# we put a bufferzone of 10% of maxdistance around the study area
.br
r.horizon elevin=elevation horizonstep=30 bufferzone=200 horizon=horangle \(rs
.br
    maxdistance=2000
.br
.DE
\fR
.SH SEE ALSO
\fI
r.sun,
r.sunmask,
r.los
\fR
.SH REFERENCES
.PP
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 
.PP
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
.PP
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 
.PP
Project PVGIS, European 
Commission, DG Joint Research Centre 2001-2007
.PP
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
.SH AUTHORS
Thomas Huld, Joint Research Centre of
the European Commission, Ispra, Italy 
.br
Tomas Cebecauer, Joint Research Centre
of the European Commission, Ispra, Italy 
.br
Jaroslav Hofierka, GeoModel s.r.o.,
Bratislava, Slovakia 
.br
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 
.PP
\fILast changed: $Date: 2013-12-29 22:35:45 +0100 (Sun, 29 Dec 2013) $\fR 
.PP
Full index
.PP
© 2003-2014 GRASS Development Team