1r.horizon(1) Grass User's Manual r.horizon(1)
2
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
16 raster, solar, sun position
17
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 Flags:
28 -d
29 Write output in degrees (default is radians)
30 -c
32 Write output in compass orientation (default is CCW, East=0)
33 --overwrite
35 Allow output files to overwrite existing files
36 --help
38 Print usage summary
39 --verbose
41 Verbose module output
42 --quiet
44 Quiet module output
45 --ui
47 Force launching GUI dialog
48 Parameters:
50 elevation=name [required]
51 Name of input elevation raster map
52 direction=float
54 Direction in which you want to know the horizon height
55 step=float
57 Angle step size for multidirectional horizon [degrees]
58 start=float
60 Start angle for multidirectional horizon [degrees]
61 Default: 0.0
62 end=float
64 End angle for multidirectional horizon [degrees]
65 Default: 360.0
66 bufferzone=float
68 For horizon rasters, read from the DEM an extra buffer around the
69 present region
70 e_buff=float
72 For horizon rasters, read from the DEM an extra buffer eastward the
73 present region
74 w_buff=float
76 For horizon rasters, read from the DEM an extra buffer westward the
77 present region
78 n_buff=float
80 For horizon rasters, read from the DEM an extra buffer northward
81 the present region
82 s_buff=float
84 For horizon rasters, read from the DEM an extra buffer southward
85 the present region
86 maxdistance=float
88 The maximum distance to consider when finding the horizon height
89 output=basename
91 Name for output basename raster map(s)
92 coordinates=east,north
94 Coordinate for which you want to calculate the horizon
95 distance=float
97 Sampling distance step coefficient (0.5-1.5)
98 Default: 1.0
99 file=name
101 Name of file for output (use output=- for stdout)
102 Default: -
103
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 · 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 · 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 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 Using the -c flag, the azimuthal angles will be printed in compass ori‐
129 entation (North=0, clockwise).
130 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 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 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 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 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 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 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 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 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 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 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 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
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
227 The examples are intended for the North Carolina sample dataset.
228 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 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 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 Horizon angles for test point (CCW from East)
249 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 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
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 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 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 Project PVGIS, European Commission, DG Joint Research Centre 2001-2007
286 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
292 r.sun, r.sunmask, r.viewshed
293
295 Thomas Huld, Joint Research Centre of the European Commission, Ispra,
296 Italy
297 Tomas Cebecauer, Joint Research Centre of the European Commission,
299 Ispra, Italy
300 Jaroslav Hofierka, GeoModel s.r.o., Bratislava, Slovakia
302 Marcel Suri, Joint Research Centre of the European Commission, Ispra,
303 Italy
304 © 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
310 Available at: r.horizon source code (history)
311 Main index | Raster index | Topics index | Keywords index | Graphical
313 index | Full index
314 © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual
316GRASS 7.8.2 r.horizon(1)