Debian Codegraph @

raster/r.horizon/r.horizon.html

raw
1 <h2>DESCRIPTION</h2>
2
3 <b>r.horizon</b> computes the angular height of terrain horizon in
4 radians. It reads a raster of elevation data and outputs the horizon
5 outline in one of two modes:
6
7 <ul>
8 <li> point: as a series of horizon
9 heights in the specified directions from the given point(s). The results are
10 written to the stdout.</li>
11 <li> raster: in this case the output is
12 one or more raster maps, with each point in a raster giving the horizon
13 height in a specific direction. One raster is created for each direction.</li>
14 </ul>
15
16 <p>
17 The directions are given as azimuthal angles (in degrees), with
18 the angle starting with 0 towards East and moving counterclockwise
19 (North is 90, etc.). The calculation takes into account the actual
20 projection, so the angles are corrected for direction distortions
21 imposed by it. The directions are thus aligned to those of the
22 geographic projection and not the coordinate system given by the rows
23 and columns of the raster map. This correction implies that the
24 resulting cardinal directions represent true orientation towards the
25 East, North, West and South. The only exception of this feature is
26 x,y coordinate system, where this correction is
27 not applied.
28
29 <p>
30 Using the <b>-c</b> flag, the azimuthal angles will be printed in compass
31 orientation (North=0, clockwise).
32
33 <p>
34 Activating the <b>-l</b> flag allows additionally printing the distance
35 to each horizon angle.
36
37 <h3>Input parameters:</h3>
38 <p>The <i>elevation</i> parameter is an input elevation raster map. If
39 the buffer options are used (see below), this raster should extend
40 over the area that accommodate the presently defined region plus
41 defined buffer zones.
42
43 <p>The <i>step</i> parameter gives the angle step (in degrees)
44 between successive azimuthal directions for the calculation of the
45 horizon. Thus, a value of 5 for the <i>step</i> will give a total of
46 360/5=72 directions (72 raster maps if used in the raster map mode).
47
48 <p>The <i>start</i> parameter gives the angle start (in degrees)
49 for the calculation of the horizon. The default value is 0 (East with
50 North being 90 etc.).
51
52 <p>The <i>end</i> parameter gives the angle end (in degrees)
53 for the calculation of the horizon. The end point is omitted!
54 So for example if we run r.horizon with step=10, start=30 and end=70
55 the raster maps generated by r.horizon will be only for angles:
56 30, 40, 50, 60. The default value is 360.
57
58 <p>The <i>direction</i> parameter gives the initial direction of the
59 first output. This parameter acts as an direction angle offset. For
60 example, if you want to get horizon angles for directions 45 and 225
61 degrees, the <i>direction</i> should be set to 45 and <i>step</i> to
62 180. If you only want one single direction, use this parameter to
63 specify desired direction of horizon angle, and set the <i>step</i>
64 size to 0 degrees. Otherwise all angles for a given starting <i>direction</i>
65 with step of <i>step</i> are calculated.
66
67 <p>The <i>distance</i> controls the sampling distance step size for the
68 search for horizon along the line of sight. The default value is 1.0
69 meaning that the step size will be taken from the raster resolution.
70 Setting the value below 1.0 might slightly improve results for
71 directions apart from the cardinal ones, but increasing the
72 processing load of the search algorithm.
73
74 <p>The <i>maxdistance</i> value gives a maximum distance to move away
75 from the origin along the line of sight in order to search for the
76 horizon height.
77 <!-- check next statement in the source code -->
78 The default <i>maxdistance</i> is the full map extent.
79
80 The smaller this value the faster the calculation but
81 the higher the risk that you may miss a terrain feature that can
82 contribute significantly to the horizon outline. Note that a viewshed
83 can be calculated with <em>r.viewshed</em>.
84
85 <p>The <i>coordinate</i> parameter takes one or
86 multiple pairs of easting-northing values
87 in the current coordinate system and calculates the values of angular
88 height of the horizon around each point. To achieve the
89 consistency of the results, the point coordinate is
90 aligned to the midpoint of the closest elevation raster cell.
91
92 <p>If an analyzed point (or raster cell) lies close to the edge of
93 the defined region, the horizon calculation may not be realistic,
94 since it may not see some significant terrain features which could
95 have contributed to the horizon, because these features are outside
96 the region. There are to options how to set the size of the buffer
97 that is used to increase the area of the horizon analysis. The
98 <i>bufferzone</i> parameter allows you to specify the same size of
99 buffer for all cardinal directions and the parameters <i>e_buff</i>,
100 <i>n_buff</i>, <i>s_buff</i>, and <i>w_buff</i> allow you to specify
101 a buffer size individually for each of the four directions. The
102 buffer parameters influence only size of the read elevation map,
103 while the analysis in the raster mode will be done only for the
104 area specified by the current region definition.
105
106 <p>The <i>output</i> parameter defines the basename of the output
107 horizon raster maps. The raster name of each horizon direction
108 raster will be constructed as <i>basename_</i>ANGLE, where ANGLE
109 is the angle in degrees with the direction. If you use <b>r.horizon</b>
110 in the point mode this option will be ignored.
111
112 <p>The <i>file</i> parameter allows saving the resulting horizon
113 angles in a comma separated ASCII file with option <b>format=plain</b>
114 or in a JSON file with option <b>format=json</b> (point mode only). If
115 you use <b>r.horizon</b> in the raster map mode this option will be ignored.
116
117 <p>At the moment the elevation and maximum distance must be measured in meters,
118 even if you use geographical coordinates (longitude/latitude). If your
119 projection is based on distance (easting and northing), these too must
120 be in meters. The buffer parameters must be in the same units as the
121 raster coordinates (e.g., for latitude-longitude buffers are
122 measured in degrees).
123
124 <h2>NOTES</h2>
125
126 <h3>Method</h3>
127
128 The calculation method is based on the method used in <b>r.sun</b>
129 to calculate shadows. It starts at a very shallow angle and walks
130 along the line of sight and asks at each step whether the line of
131 sight &quot;hits&quot; the terrain. If so, the angle is increased to
132 allow the line of sight to pass just above the terrain at that point.
133 This is continued until the line of sight reaches a height that is
134 higher than any point in the region or until it reaches the border of
135 the region (see also the <i>bufferzone,e_buff</i>, <i>n_buff</i>,
136 <i>s_buff</i>, and <i>w_buff</i>). The number of lines of sight (azimuth
137 directions) is determined from the <i>direction</i> and
138 <i>step</i> parameters. The method takes into account the curvature
139 of the Earth whereby remote features will seem to be lower than they
140 actually are. It also accounts for the changes of angles towards
141 cardinal directions caused by the projection (see above).
142
143 <p>
144 The output with the <b>-d</b> flag is azimuth degree (-90 to 90, where
145 0 is parallel with the focal cell).
146
147 <p> All horizon values are positive (or zero). While negative values are
148 in theory possible, <b>r.horizon</b> currently does not support them.
149
150
151 <h3>Performance</h3>
152 Parallel processing is implemented for the raster mode.
153 To enable parallel processing, the user can specify the number of threads
154 to be used with the <b>nprocs</b> parameter.
155 Figures below show benchmark results running on
156 Intel® Core™ i5-13600K CPU @ 3.5GHz.
157 See benchmark scripts
158 in the source code for more details.
159
160 <p>
161 The iterations of the algorithm used in <b>r.horizon</b>
162 depends on the topography. As a result, the benchmark results may vary
163 depending on the topography of the study area.
164
165 <div align="center" style="margin: 10px">
166 <img src="rhorizon_raster_time.png"
167 alt="time for r.horizon with different map sizes" border="0">
168 <img src="rhorizon_raster_speedup.png"
169 alt="speedup for r.horizon with different map sizes" border="0">
170 <img src="rhorizon_raster_efficiency.png"
171 alt="efficiency for r.horizon with different map sizes" border="0">
172 <br>
173 <i>Figure: Benchmark shows execution time, parallel speedup and
174 efficiency for different numbers of cells (1M, 2M, 4M, and 8M).</i>
175 </div>
176
177
178 <h2>EXAMPLES</h2>
179
180 The examples are intended for the North Carolina sample dataset.
181
182 <h3>Point mode</h3>
183
184 <b>Example 1</b>: determine horizon angle in 225 degree direction (output
185 of horizon angles CCW from East):
186
187 <div class="code"><pre>
188 g.region raster=elevation -p
189 r.horizon elevation=elevation direction=215 step=0 bufferzone=200 \
190 coordinates=638871.6,223384.4 maxdistance=5000
191 </pre></div>
192 <p>
193 <b>Example 2</b>: determine horizon values starting at 90 deg (North),
194 step size of 5 deg, saving result as CSV file:
195
196 <div class="code"><pre>
197 r.horizon elevation=elevation direction=90 step=5 bufferzone=200 \
198 coordinates=638871.6,223384.4 maxdistance=5000 file=horizon.csv
199 </pre></div>
200
201 <p>
202 <b>Example 3</b>: test point near highway intersection, saving result
203 as CSV file for plotting the horizon around the highway intersection:
204
205 <div class="code"><pre>
206 g.region n=223540 s=220820 w=634650 e=638780 res=10 -p
207 r.horizon elevation=elevation direction=0 step=5 bufferzone=200 \
208 coordinates=636483.54,222176.25 maxdistance=5000 -d file=horizon.csv
209 </pre></div>
210
211 <center>
212 <img src="rhorizon_shaded_dem_point.png"><br>
213 Test point near high way intersection (North Carolina sample dataset)
214 <p>
215 <img src="rhorizon_singlepoint_plot.png"><br>
216 Horizon angles for test point (CCW from East)
217 </center>
218
219 <p>We can plot horizon in polar coordinates using Matplotlib in Python:
220 <div class="code"><pre>
221 import numpy as np
222 import matplotlib.pyplot as plt
223
224 horizon = np.genfromtxt('horizon.csv', delimiter=',')
225 horizon = horizon[1:, :]
226
227 ax = plt.subplot(111, polar=True)
228 bars = ax.plot(horizon[:, 0] / 180 * np.pi,
229 (90 - horizon[:, 1]) / 180 * np.pi)
230 # uncomment the 2 following lines when using -c flag
231 # ax.set_theta_direction(-1)
232 # ax.set_theta_zero_location('N')
233 plt.show()
234 </pre></div>
235
236 <center>
237 <img src="rhorizon_polar_plot.png"><br>
238 Horizon plot in polar coordinates.
239 </center>
240
241 <h3>Raster map mode</h3>
242
243 Raster map mode (output maps "horangle*" become input for <em>r.sun</em>):
244 <div class="code"><pre>
245 g.region raster=elevation -p
246
247 # we put a bufferzone of 10% of maxdistance around the study area
248 # compute only direction between 90 and 270 degrees
249 r.horizon elevation=elevation step=30 start=90 end=300 \
250 bufferzone=200 output=horangle maxdistance=5000
251 </pre></div>
252
253 <h2>REFERENCES</h2>
254
255 <p>Hofierka J., 1997. Direct solar radiation modelling within an
256 open GIS environment. Proceedings of JEC-GI'97 conference in Vienna,
257 Austria, IOS Press Amsterdam, 575-584
258
259 <p>Hofierka J., Huld T., Cebecauer T., Suri M., 2007. Open Source Solar
260 Radiation Tools for Environmental and Renewable Energy Applications,
261 <a href="https://www.researchgate.net/profile/Ralf-Denzer-2/publication/269166795_Environmental_Software_Systems_Volume_7_Second_Edition/links/54847f450cf283750c370758/Environmental-Software-Systems-Volume-7-Second-Edition.pdf#page=464">International Symposium on
262 Environmental Software Systems</a>, Prague, 2007
263 <p>Neteler M., Mitasova H., 2004. Open Source GIS: A GRASS GIS
264 Approach, <a href="https://link.springer.com/book/10.1007/978-0-387-68574-8">Springer</a>, New York.
265 ISBN: 1-4020-8064-6, 2nd Edition 2004 (reprinted 2005), 424 pages
266
267 <p>Project <a href="https://joint-research-centre.ec.europa.eu/photovoltaic-geographical-information-system-pvgis_en">PVGIS</a>, European
268 Commission, DG Joint Research Centre 2001-2007
269 <p>Suri M., Hofierka J., 2004.
270 A New GIS-based Solar Radiation Model and Its Application for
271 Photovoltaic Assessments. <a href="http://web.archive.org/web/20060212122544/http://www.blackwellpublishing.com:80/toc.asp?ref=1361-1682">Transactions
272 in GIS</a>, 8(2), 175-190 (DOI: <a href="https://doi.org/10.1111/j.1467-9671.2004.00174.x">10.1111/j.1467-9671.2004.00174.x</a>)
273
274 <h2>SEE ALSO</h2>
275
276 <em>
277 <a href="r.sun.html">r.sun</a>,
278 <a href="r.sunmask.html">r.sunmask</a>,
279 <a href="r.viewshed.html">r.viewshed</a>
280 </em>
281
282 <h2>AUTHORS</h2>
283
284 Thomas Huld, Joint Research Centre of
285 the European Commission, Ispra, Italy
286 <br>
287 <p>Tomas Cebecauer, Joint Research Centre
288 of the European Commission, Ispra, Italy
289 <br>
290 <p>Jaroslav Hofierka, GeoModel s.r.o.,
291 Bratislava, Slovakia <br>Marcel Suri, Joint Research Centre of the
292 European Commission, Ispra, Italy
293 <p>&copy; 2007, Thomas Huld, Tomas Cebecauer, Jaroslav Hofierka, Marcel Suri
294
295 <a href="mailto:[email protected]">[email protected]</a>
296 <a href="mailto:[email protected]">[email protected]</a>
297 <a href="mailto:[email protected]">[email protected]</a>
298 <a href="mailto:[email protected]">[email protected]</a>