1r.horizon(1) GRASS GIS 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 ’co‐
10 ord’ option. The horizon height (in radians). 2. Computes one or more
11 raster maps of the horizon height in a single direction. The input for
12 this is the angle (in degrees), which is measured counterclockwise with
13 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 an‐
118 gle starting with 0 towards East and moving counterclockwise (North is
119 90, etc.). The calculation takes into account the actual projection, so
120 the angles are corrected for direction distortions imposed by it. The
121 directions are thus aligned to those of the geographic projection and
122 not the coordinate system given by the rows and columns of the raster
123 map. This correction implies that the resulting cardinal directions
124 represent true orientation towards the East, North, West and South. The
125 only exception of this feature is LOCATION with x,y coordinate system,
126 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 re‐
178 sults, 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 de‐
182 fined 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 al‐
187 lows you to specify the same size of buffer for all cardinal directions
188 and the parameters e_buff, n_buff, s_buff, and w_buff allow you to
189 specify a buffer size individually for each of the four directions. The
190 buffer parameters influence only size of the read elevation map, while
191 the analysis in the raster mode will be done only for the area speci‐
192 fied 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 op‐
198 tion 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 The output with the -d flag is azimuth degree (-90 to 90, where 0 is
227 parallel with the focal cell). In case of negative horizon values ob‐
228 tained this indicates that the horizon height is below the cell it is
229 computed from.
230
232 The examples are intended for the North Carolina sample dataset.
233 Single point mode
235 Example 1: determine horizon angle in 225 degree direction (output of
236 horizon angles CCW from East):
237 g.region raster=elevation -p
238 r.horizon elevation=elevation direction=215 step=0 bufferzone=200 \
239 coordinates=638871.6,223384.4 maxdistance=5000
240 Example 2: determine horizon values starting at 90 deg (North), step
242 size of 5 deg, saving result as CSV file:
243 r.horizon elevation=elevation direction=90 step=5 bufferzone=200 \
244 coordinates=638871.6,223384.4 maxdistance=5000 file=horizon.csv
245 Example 3: test point near highway intersection, saving result as CSV
247 file for plotting the horizon around the highway intersection:
248 g.region n=223540 s=220820 w=634650 e=638780 res=10 -p
249 r.horizon elevation=elevation direction=0 step=5 bufferzone=200 \
250 coordinates=636483.54,222176.25 maxdistance=5000 -d file=horizon.csv
251 Test point near high way intersection (North Carolina sample dataset)
252 Horizon angles for test point (CCW from East)
254 We can plot horizon in polar coordinates using Matplotlib in Python:
256 import numpy as np
257 import matplotlib.pyplot as plt
258 horizon = np.genfromtxt(’horizon.csv’, delimiter=’,’)
259 horizon = horizon[1:, :]
260 ax = plt.subplot(111, polar=True)
261 bars = ax.plot(horizon[:, 0] / 180 * np.pi,
262 (90 - horizon[:, 1]) / 180 * np.pi)
263 # uncomment the 2 following lines when using -c flag
264 # ax.set_theta_direction(-1)
265 # ax.set_theta_zero_location(’N’)
266 plt.show()
267 Horizon plot in polar coordinates.
268 Raster map mode
270 Raster map mode (output maps "horangle*" become input for r.sun):
271 g.region raster=elevation -p
272 # we put a bufferzone of 10% of maxdistance around the study area
273 # compute only direction between 90 and 270 degrees
274 r.horizon elevation=elevation step=30 start=90 end=300 \
275 bufferzone=200 output=horangle maxdistance=5000
276
278 Hofierka J., 1997. Direct solar radiation modelling within an open GIS
279 environment. Proceedings of JEC-GI’97 conference in Vienna, Austria,
280 IOS Press Amsterdam, 575-584
281 Hofierka J., Huld T., Cebecauer T., Suri M., 2007. Open Source Solar
283 Radiation Tools for Environmental and Renewable Energy Applications,
284 International Symposium on Environmental Software Systems, Prague, 2007
285 Neteler M., Mitasova H., 2004. Open Source GIS: A GRASS GIS Approach,
287 Springer, New York. ISBN: 1-4020-8064-6, 2nd Edition 2004 (reprinted
288 2005), 424 pages
289 Project PVGIS, European Commission, DG Joint Research Centre 2001-2007
291 Suri M., Hofierka J., 2004. A New GIS-based Solar Radiation Model and
293 Its Application for Photovoltaic Assessments. Transactions in GIS,
294 8(2), 175-190
295
297 r.sun, r.sunmask, r.viewshed
298
300 Thomas Huld, Joint Research Centre of the European Commission, Ispra,
301 Italy
302 Tomas Cebecauer, Joint Research Centre of the European Commission, Is‐
304 pra, Italy
305 Jaroslav Hofierka, GeoModel s.r.o., Bratislava, Slovakia
307 Marcel Suri, Joint Research Centre of the European Commission, Ispra,
308 Italy
309 © 2007, Thomas Huld, Tomas Cebecauer, Jaroslav Hofierka, Marcel Suri
311 Thomas.Huld@jrc.it Tomas.Cebecauer@jrc.it hofierka@geomodel.sk Mar‐
312 cel.Suri@jrc.it
313
315 Available at: r.horizon source code (history)
316 Accessed: Saturday Jan 21 21:14:39 2023
318 Main index | Raster index | Topics index | Keywords index | Graphical
320 index | Full index
321 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
323GRASS 8.2.1 r.horizon(1)