1r.horizon(1)                  Grass User's Manual                 r.horizon(1)
2
3
4

NAME

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

KEYWORDS

16       raster, solar, sun position
17

SYNOPSIS

19       r.horizon
20       r.horizon --help
21       r.horizon   [-dc]   elevation=name    [direction=float]    [step=float]
22       [start=float]     [end=float]     [bufferzone=float]     [e_buff=float]
23       [w_buff=float]    [n_buff=float]   [s_buff=float]   [maxdistance=float]
24       [output=basename]       [coordinates=east,north]       [distance=float]
25       [file=name]   [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]
26
27   Flags:
28       -d
29           Write output in degrees (default is radians)
30
31       -c
32           Write output in compass orientation (default is CCW, East=0)
33
34       --overwrite
35           Allow output files to overwrite existing files
36
37       --help
38           Print usage summary
39
40       --verbose
41           Verbose module output
42
43       --quiet
44           Quiet module output
45
46       --ui
47           Force launching GUI dialog
48
49   Parameters:
50       elevation=name [required]
51           Name of input elevation raster map
52
53       direction=float
54           Direction in which you want to know the horizon height
55
56       step=float
57           Angle step size for multidirectional horizon [degrees]
58
59       start=float
60           Start angle for multidirectional horizon [degrees]
61           Default: 0.0
62
63       end=float
64           End angle for multidirectional horizon [degrees]
65           Default: 360.0
66
67       bufferzone=float
68           For  horizon  rasters, read from the DEM an extra buffer around the
69           present region
70
71       e_buff=float
72           For horizon rasters, read from the DEM an extra buffer eastward the
73           present region
74
75       w_buff=float
76           For horizon rasters, read from the DEM an extra buffer westward the
77           present region
78
79       n_buff=float
80           For horizon rasters, read from the DEM an  extra  buffer  northward
81           the present region
82
83       s_buff=float
84           For  horizon  rasters,  read from the DEM an extra buffer southward
85           the present region
86
87       maxdistance=float
88           The maximum distance to consider when finding the horizon height
89
90       output=basename
91           Name for output basename raster map(s)
92
93       coordinates=east,north
94           Coordinate for which you want to calculate the horizon
95
96       distance=float
97           Sampling distance step coefficient (0.5-1.5)
98           Default: 1.0
99
100       file=name
101           Name of file for output (use output=- for stdout)
102           Default: -
103

DESCRIPTION

105       r.horizon computes the angular height of terrain horizon in radians. It
106       reads a raster of elevation data and outputs the horizon outline in one
107       of two modes:
108
109           ·   single point: as a series of horizon heights in  the  specified
110               directions from the given point. The results are written to the
111               stdout.
112
113           ·   raster: in this case the output is one  or  more  raster  maps,
114               with each point in a raster giving the horizon height in a spe‐
115               cific direction. One raster is created for each direction.
116
117       The directions are given as azimuthal angles  (in  degrees),  with  the
118       angle  starting  with 0 towards East and moving counterclockwise (North
119       is 90, etc.). The calculation takes into account the actual projection,
120       so  the  angles  are corrected for direction distortions imposed by it.
121       The directions are thus aligned to those of the  geographic  projection
122       and  not  the  coordinate  system  given by the rows and columns of the
123       raster map. This correction implies that the resulting cardinal  direc‐
124       tions  represent  true  orientation  towards  the East, North, West and
125       South. The only exception of this feature is LOCATION with x,y  coordi‐
126       nate system, where this correction is not applied.
127
128       Using the -c flag, the azimuthal angles will be printed in compass ori‐
129       entation (North=0, clockwise).
130
131   Input parameters:
132       The elevation parameter is an input elevation raster map. If the buffer
133       options  are  used (see below), this raster should extend over the area
134       that accommodate the  presently  defined  region  plus  defined  buffer
135       zones.
136
137       The step parameter gives the angle step (in degrees) between successive
138       azimuthal directions for the calculation of the horizon. Thus, a  value
139       of  5  for the step will give a total of 360/5=72 directions (72 raster
140       maps if used in the raster map mode).
141
142       The start parameter gives the angle start (in degrees) for the calcula‐
143       tion  of  the horizon. The default value is 0 (East with North being 90
144       etc.).
145
146       The end parameter gives the angle end (in degrees) for the  calculation
147       of  the  horizon.  The  end point is omitted!  So for example if we run
148       r.horizon with step=10, start=30 and end=70 the raster  maps  generated
149       by r.horizon will be only for angles: 30, 40, 50, 60. The default value
150       is 360.
151
152       The direction parameter gives the initial direction of the  first  out‐
153       put.  This parameter acts as an direction angle offset. For example, if
154       you want to get horizon angles for directions 45 and 225  degrees,  the
155       direction  should  be  set  to 45 and step to 180. If you only want one
156       single direction, use this parameter to specify  desired  direction  of
157       horizon angle, and set the step size to 0 degrees. Otherwise all angles
158       for a given starting direction with step of step are calculated.
159
160       The distance controls the sampling distance step size  for  the  search
161       for  horizon  along the line of sight. The default value is 1.0 meaning
162       that the step size will be taken from the raster  resolution.   Setting
163       the value below 1.0 might slightly improve results for directions apart
164       from the cardinal ones, but  increasing  the  processing  load  of  the
165       search algorithm.
166
167       The  maxdistance  value  gives a maximum distance to move away from the
168       origin along the line of sight in  order  to  search  for  the  horizon
169       height.   The  default maxdistance is the full map extent.  The smaller
170       this value the faster the calculation but the higher the risk that  you
171       may  miss  a  terrain  feature that can contribute significantly to the
172       horizon outline. Note that a viewshed can be  calculated  with  r.view‐
173       shed.
174
175       The coordinate parameter takes a pair of easting-northing values in the
176       current coordinate system and calculates the values of  angular  height
177       of  the  horizon  around  this point. To achieve the consistency of the
178       results, the point coordinate is aligned to the midpoint of the closest
179       elevation raster cell.
180
181       If  an  analyzed  point  (or raster cell) lies close to the edge of the
182       defined region, the horizon calculation may not be realistic, since  it
183       may not see some significant terrain features which could have contrib‐
184       uted to the horizon, because these features  are  outside  the  region.
185       There  are to options how to set the size of the buffer that is used to
186       increase the area of the horizon  analysis.  The  bufferzone  parameter
187       allows  you  to specify the same size of buffer for all cardinal direc‐
188       tions and the parameters e_buff, n_buff, s_buff, and w_buff  allow  you
189       to  specify a buffer size individually for each of the four directions.
190       The buffer parameters influence only size of the  read  elevation  map,
191       while  the  analysis  in the raster mode will be done only for the area
192       specified by the current region definition.
193
194       The output parameter defines the basename of the output horizon  raster
195       maps.  The  raster  name  of each horizon direction raster will be con‐
196       structed as basename_ANGLE, where ANGLE is the angle  in  degrees  with
197       the  direction.  If  you  use  r.horizon  in the single point mode this
198       option will be ignored.
199
200       The file parameter allows saving the  resulting  horizon  angles  in  a
201       comma separated ASCII file (single point mode only). If you use r.hori‐
202       zon in the raster map mode this option will be ignored.
203
204       At the moment the elevation and maximum distance must  be  measured  in
205       meters,  even if you use geographical coordinates (longitude/latitude).
206       If your projection is based on distance (easting and  northing),  these
207       too  must be in meters. The buffer parameters must be in the same units
208       as the raster coordinates (e.g., for latitude-longitude locations  buf‐
209       fers are measured in degree unit).
210

METHOD

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

EXAMPLES

227       The examples are intended for the North Carolina sample dataset.
228
229   Single point mode
230       Example  1:  determine horizon angle in 225 degree direction (output of
231       horizon angles CCW from East):
232       g.region raster=elevation -p
233       r.horizon elevation=elevation direction=215 step=0 bufferzone=200 \
234           coordinates=638871.6,223384.4 maxdistance=5000
235
236       Example 2: determine horizon values starting at 90  deg  (North),  step
237       size of 5 deg, saving result as CSV file:
238       r.horizon elevation=elevation direction=90 step=5 bufferzone=200 \
239           coordinates=638871.6,223384.4 maxdistance=5000 file=horizon.csv
240
241       Example  3:  test point near highway intersection, saving result as CSV
242       file for plotting the horizon around the highway intersection:
243       g.region n=223540 s=220820 w=634650 e=638780 res=10 -p
244       r.horizon elevation=elevation direction=0 step=5 bufferzone=200 \
245           coordinates=636483.54,222176.25 maxdistance=5000 -d file=horizon.csv
246       Test point near high way intersection (North Carolina sample dataset)
247
248       Horizon angles for test point (CCW from East)
249
250       We can plot horizon in polar coordinates using Matplotlib in Python:
251       import numpy as np
252       import matplotlib.pyplot as plt
253       horizon = np.genfromtxt(’horizon.csv’, delimiter=’,’)
254       horizon = horizon[1:, :]
255       ax = plt.subplot(111, polar=True)
256       bars = ax.plot(horizon[:, 0] / 180 * np.pi,
257                      (90 - horizon[:, 1]) / 180 * np.pi)
258       # uncomment the 2 following lines when using -c flag
259       # ax.set_theta_direction(-1)
260       # ax.set_theta_zero_location(’N’)
261       plt.show()
262       Horizon plot in polar coordinates.
263
264   Raster map mode
265       Raster map mode (output maps "horangle*" become input for r.sun):
266       g.region raster=elevation -p
267       # we put a bufferzone of 10% of maxdistance around the study area
268       # compute only direction between 90 and 270 degrees
269       r.horizon elevation=elevation step=30 start=90 end=300 \
270           bufferzone=200 output=horangle maxdistance=5000
271

REFERENCES

273       Hofierka J., 1997. Direct solar radiation modelling within an open  GIS
274       environment.  Proceedings  of  JEC-GI’97 conference in Vienna, Austria,
275       IOS Press Amsterdam, 575-584
276
277       Hofierka J., Huld T., Cebecauer T., Suri M., 2007.  Open  Source  Solar
278       Radiation  Tools  for  Environmental and Renewable Energy Applications,
279       International Symposium on Environmental Software Systems, Prague, 2007
280
281       Neteler M., Mitasova H., 2004. Open Source GIS: A GRASS  GIS  Approach,
282       Springer,  New  York.  ISBN: 1-4020-8064-6, 2nd Edition 2004 (reprinted
283       2005), 424 pages
284
285       Project PVGIS, European Commission, DG Joint Research Centre 2001-2007
286
287       Suri M., Hofierka J., 2004.  A New GIS-based Solar Radiation Model  and
288       Its  Application  for  Photovoltaic  Assessments.  Transactions in GIS,
289       8(2), 175-190
290

SEE ALSO

292        r.sun, r.sunmask, r.viewshed
293

AUTHORS

295       Thomas Huld, Joint Research Centre of the European  Commission,  Ispra,
296       Italy
297
298       Tomas  Cebecauer,  Joint  Research  Centre  of the European Commission,
299       Ispra, Italy
300
301       Jaroslav Hofierka, GeoModel s.r.o., Bratislava, Slovakia
302       Marcel Suri, Joint Research Centre of the European  Commission,  Ispra,
303       Italy
304
305       ©  2007,  Thomas Huld, Tomas Cebecauer, Jaroslav Hofierka, Marcel Suri
306       Thomas.Huld@jrc.it  Tomas.Cebecauer@jrc.it  hofierka@geomodel.sk   Mar‐
307       cel.Suri@jrc.it
308

SOURCE CODE

310       Available at: r.horizon source code (history)
311
312       Main  index  | Raster index | Topics index | Keywords index | Graphical
313       index | Full index
314
315       © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual
316
317
318
319GRASS 7.8.2                                                       r.horizon(1)
Impressum