-
Notifications
You must be signed in to change notification settings - Fork 68
/
index.html
485 lines (453 loc) · 49.3 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
<head>
<style>
body {
font:13.34px helvetica,arial,freesans,clean,sans-serif;
color:black;
line-height:1.4em;
background-color: #F8F8F8;
padding: 0.7em;
}
pre {
margin:1em 0;
font-size:12px;
background-color:#eee;
border:1px solid #ddd;
padding:5px;
line-height:1.5em;
color:#444;
overflow:auto;
-webkit-box-shadow:rgba(0,0,0,0.07) 0 1px 2px inset;
-webkit-border-radius:3px;
-moz-border-radius:3px;border-radius:3px;
}
pre code {
padding:0;
font-size:12px;
background-color:#eee;
border:none;
}
code {
font-size:12px;
background-color:#f8f8ff;
color:#444;
padding:0 .2em;
border:1px solid #dedede;
}
</style>
</head>
<body>
<h1>QGIS Shape Tools Plugin</h1>
<p><strong><em>Shape Tools</em></strong> is a collection of geodesic tools that are installed in the Vector menu, on the toolbar, in the field calculator, or in the Processing Toolbox. Geodesic is the shortest path between two points on the Earth, a spheroid, or an ellipsoid. </p>
<ul>
<li><img src="images/shapes.png" width="24"> <strong>Create geodesic shapes</strong> processes a point vector layer to create circles, ellipses, lines of bearing, pie wedges, donuts, arc wedges, polygons, stars, ellipse roses, hypocyloids, polyfoils, epicyloids, radial lines, concentric rings with radial lines, and hearts based on the table's fields and parameters from the dialog box. All use geodesic math to calculate the shapes. </li>
<li><img src="images/concentricrings.png" width="24"> <strong>Interactive geodesic shapes</strong> allows the user to click on the map and capture its coordinate to create concentric rings with radial lines or donuts centered around the coordinate. All use geodesic math to calculate the shapes. </li>
<li><img alt="XY to Line" src="images/xyline.svg" /> <strong>XY to Line</strong> uses pairs of coordinates from each layer's records to create geodesic lines in between. The input can be a point vector layer or a table layer that contains pairs of coordinates.</li>
<li><img alt="Geodesic line break" src="images/idlbreak.svg" /> <strong>Geodesic line break at -180,180</strong> breaks lines at the International Date Line at -180,180 degrees longitude for a more pleasing visual look.</li>
<li><img alt="Geodesic densifier" src="images/geodesicDensifier.svg" /> <strong>Geodesic densifier</strong> densifies a line or polygon vector layer by adding geodesic points in between each line segment whenever the distance between vertices exceeds a certain threshold. This creates a geodesic path that gives it a nice smooth curved appearance. If the vector layer is a line, it can also draw a geodesic line just between the beginning and ending points.</li>
<li><img alt="Geodesic line decimate" src="images/geodesicLineDecimate.svg" /> <strong>Geodesic line decimate</strong> removes vertices in a line that who's geodesic distance is less than a certain value.</li>
<li><img alt="Geodesic point decimate" src="images/geodesicPointDecimate.svg" /> <strong>Geodesic point decimate</strong> removes points in a point layer who's geodesic distance is less than a certain value or who's time difference between points is less than a certain value.</li>
<li><img alt="Geodesic measure tool" src="images/measure.svg" /> <strong>Geodesic measure tool</strong> provides geodesic line measuring, similar to that implemented in Google Earth.</li>
<li><img alt="Geodesic measurement layer" src="images/measureLine.svg" /> <strong>Geodesic measurement layer</strong> converts a polygon or line layer a new layer with all geometries measured and labeled.</li>
<li><img alt="Geodesic transfomations tool" src="images/transformShape.svg" /> <strong>Geodesic transformations</strong> can geodesically scale, rotate, and translate points, lines and polygons. Each vector feature retains their relative dimensions no matter what the projection is.</li>
<li><img alt="Geodesic flip and rotate" src="images/flip.svg" /> <strong>Geodesic flip & rotate tools</strong> provide the following geodesic vector transformations: Flip horizontally, flip vertically, rotate by 180 degrees, rotate clockwise by 90 degrees, and rotate counter clockwise by 90 degrees.</li>
<li><img alt="Azimuth, distance digitizer" src="images/dazdigitize.svg" /> <strong>Azimuth, distance digitizer</strong> creates a new point at a certain azimuth/bearing and distance or creates a geodesic line from the point clicked to a point in the azimuth direction located at a distance.</li>
<li>
<p><img alt="Azimuth distance sequence digitizer" src="images/linedigitize.svg" /> <strong>Azimuth distance sequence digitizer</strong> digitizes a sequence of azimuth/bearing, distance pairs to create a series of points, a line, or a polygon.</p>
</li>
<li>
<p><strong>Field Calculator Expression Functions</strong></p>
<ul>
<li>st_compass() - Returns the cardinal or compass direction given an azimuth as a string.</li>
<li>st_from_meters() - Convert a length in meters to another unit.</li>
<li>st_to_meters() - Convert a length to meters.</li>
<li>st_geodesic_bearing() - Returns the geodesic azimuth starting from the first coordinate in the direction of the second coordinate.</li>
<li>st_geodesic_distance() - Returns the geodesic distance in meters between two coordinates or two geometry points.</li>
<li>st_geodesic_transform() - Geodesically transfrom a shape (point, line, polygon) using rotation, translation, and scaling.</li>
</ul>
</li>
</ul>
<h2>Contents</h2>
<ul>
<li><a href="#create-shapes">Create Geodesic Shapes</a></li>
<li><a href="#interactive-shapes">Interactive Geodesic Shapes</a></li>
<li><a href="#xy-to-line">XY to Line</a></li>
<li><a href="#geodesic-line-break">Geodesic Line Break</a></li>
<li><a href="#geodesic-densifier">Geodesic Densifier</a></li>
<li><a href="#geodesic-line-decimate">Geodesic Line Decimate</a></li>
<li><a href="#geodesic-point-decimate">Geodesic Point Decimate</a></li>
<li><a href="#geodesic-measure">Geodesic Measure Tool</a></li>
<li><a href="#geodesic-measure-layer">Geodesic Measurement Layer</a></li>
<li><a href="#geodesic-transformations">Geodesic Transformations</a></li>
<li><a href="#geodesic-flip">Geodesic Flip and Rotate Tools</a></li>
<li><a href="#azimuth-distance">Azimuth, Distance Digitizer</a></li>
<li><a href="#azimuth-distance-sequence">Azimuth Distance Sequence Digitizer</a></li>
<li><a href="#expressions">Field Calculator Expression Functions</a></li>
<li><a href="#settings">Settings</a></li>
</ul>
<h2><a name="create-shapes"></a> <img src="images/shapes.png" width="24"> Create Geodesic Shapes</h2>
<div style="text-align:center"><img src="doc/examples.png" alt="Examples"></div>
<p>All of these shapes can be accessed from the ShapeTools processing algorithms.</p>
<div style="text-align:center"><img src="doc/processing-shapes.jpg" alt="Processing Shapes"></div>
<p>They can also be accessed from the <em>Vector->Shape Tools->Create geodesic shapes</em> menu.</p>
<div style="text-align:center"><img src="doc/menu-shapes.jpg" alt="Create geodesic shapes"></div>
<p>The various shapes can be created from the feature's attributes or from default parameters in the <em>Create Shapes</em> tool. Note that if the output layer uses a temporary layer, it will not be saved with the QGIS project. You need to manually save the layer or use the <a href="http://plugins.qgis.org/plugins/MemoryLayerSaver/">Memory Layer Saver</a> plugin.</p>
<p>The following are details for creating each shape. All of the shapes are created centered around a point feature or from a point feature. Common elements are:</p>
<ul>
<li><strong>Input layer</strong> - Select the desired point vector layer.</li>
<li><strong>Output layer</strong> - Select one of <strong><em>[Create Temporary Layer]</em></strong>, <strong><em>Save to file...</em></strong>, <strong><em>Save to GeoPackage...</em></strong>, or <strong><em>Save to Database Table...</em></strong>.</li>
<li><strong>Shape Type</strong> - Specify whether the shape should be drawn as a polygon or as a line.</li>
<li><strong>Add input geometry fields to output table</strong> - If checked, the input point geometry will be added to fields in the output shape table. By default these fields are named <strong><em>geom_x</em></strong> and <strong><em>geom_y</em></strong>, but can be changed in <strong>Settings</strong>.</li>
</ul>
<h3>Ellipse</h3>
<div style="text-align:center"><img src="doc/ellipse.jpg" alt="Ellipse"></div>
<p>Select a point vector layer and an output layer or use the default temporary output layer. Then select the specific ellipse parameters. The semi-major axis of the ellipse runs along the orientation axis. The orientation of axis is measured in degrees in a clockwise direction from the north line. The units of measure for semi-major, and semi-minor lengths are defined by <strong><em>Radius units</em></strong>.</p>
<p>To the right of the semi-major axis, semi-minor axis, and orientation of axis entries are data defined override buttons <img alt="" src="doc/datadefined.jpg" />. These fields allow the values to be derived from the contents in the attribute table as shown here.</p>
<div style="text-align:center"><img src="doc/create.jpg" alt="Date defined"></div>
<p>Alternatively, the user can click on the <strong><em>Edit...</em></strong> button and use any valid expression.</p>
<h3>Line of Bearing</h3>
<p>A <strong>line of bearing</strong> is the line drawn from a starting point in the direction of the <strong>asimuth</strong> or <strong>bearing</strong> for the specified distance. The line of bearing uses geodesic math to find the shortest path and is accurate along the Earth's surface.</p>
<ul>
<li><strong>Azimuth/bearing</strong> is the angle measured in degrees, in a clockwise direction from the north line.</li>
<li><strong>Distance</strong> - The line will be drawn from the originating point plus the offset in the <strong>azimuth</strong> direction until it reaches this distance from the origin.</li>
<li><strong>Line offset from origin</strong> - In some instances you may only be interested in distances away from the point of origin. This parameter allows the user to start the line at some offset distance from the origin.</li>
<li><strong>Distance units</strong> - The unit of distance measurements of the above parameters.</li>
</ul>
<h3>Points Along a Bearing</h3>
<p>A <strong>line of bearing</strong> is the line drawn from a starting point in the direction of the <strong>azimuth</strong> or <strong>bearing</strong> for the specified distance. The line of bearing uses geodesic math to find the shortest path and is accurate along the Earth's surface. In this algoirthm rather than drawing a line, equally spaced points are created along the line.</p>
<ul>
<li><strong>Azimuth/bearing</strong> - This is the angle measured in degrees, in a clockwise direction from the north line.</li>
<li><strong>Distance</strong> - This is the distance in which points will be drawn.</li>
<li><strong>Distance from origin to the first point</strong> - In some instances you may only be interested in distances away from the point of origin. This parameter allows the user to start the points at some offset distance from the origin.</li>
<li><strong>Distance between points</strong> - This is the stepping distance between rendered points. The value must be greater than 0.</li>
<li><strong>Distance units</strong> - The unit of distance measurements of the above parameters.</li>
</ul>
<h3>Arc wedge</h3>
<p>In essence this takes a wedge of a donut shape. The parameters are similar to <strong>Pie wedge</strong> and <strong>Donut</strong>.</p>
<h3>Circle</h3>
<p>Create a circle shape. The circle radius is specified from the default value, from the attribute table, or from an expression. <strong>Number of drawing segments</strong> defines how many line segments it uses to create the circle. A larger value will produce a smoother circle, but will take more time to draw.</p>
<h3>Donut</h3>
<p>Create a donut shape. The inner and outer radius are specified from the default values, from the attribute table, or expression. If the inner radius is 0 then a solid circle is drawn. <strong>Number of drawing segments</strong> defines how many line segments it uses to create the circle. A larger value will produce a smoother circle, but will take more time to draw.</p>
<h3>Ellipse Rose</h3>
<p>Create an N-petal rose. The distance from the center to the outer petals are defined by the radius.</p>
<h3>Epicycloid</h3>
<p>Create an N-leafed epicycloid. The distance from the center to the outer edge is defined by the radius.</p>
<h3>Gear</h3>
<p>Create an N-toothed shape that look like a gear.</p>
<h3>Heart</h3>
<p>Create a mathematical heart which fits within the circle defined by its radius.</p>
<h3>Hypocycloid</h3>
<p>Create an N-pointed hypocycloid. A hypocycloid is defined as the curve traced by a point on the circumference of a circle that is rolling on the interior of another circle. The distance from the center to the outer cusps are defined by the radius.</p>
<h3>Pie Wedge</h3>
<p>If <strong>Azimuth mode</strong> it is set to <em>Use beginning and ending azimuths</em>, then the pie wedge focal point starts at the point layer's geometry extending out to the specified radius. It starts at the <strong>Starting azimuth</strong> going in a clockwise direction to the <strong>Ending azimuth</strong>. If <strong>Azimuth mode</strong> is set to <em>Use center azimuth and width</em>, then a center azimuth is specified which becomes the center of the pie wedge with an arc length of <strong>Azimuth width</strong>. The pie wedge can either be defined from the point vector layer and the selected parameters or the override to the right allows selection of an attribute to derive the values or an expression. <strong>Drawing segments</strong> is the number of line segments that would be used to draw a full circle. A wedge will use a proportionally smaller number of segments. Making this larger will give smoother results, but will be slower rendering the shapes. If the azimuth width is 360 degrees, the a donut is created.</p>
<h3>Polyfoil</h3>
<p>Create an N-leafed polyfoil. The distance from the center to the outer leafs are defined by the radius.</p>
<h3>Polygon</h3>
<p>Create an N-sided polygon centered on the vector point. The vertices of the polygon lie on a circle of the default radius.</p>
<h3>Radial lines</h3>
<p>Create N-radial lines equally spaced around the point starting from the inner radius and extending out to the outer radius.</p>
<h3>Rings with radial lines</h3>
<p>Create N-rings around a point. The number or rings, inner ring radius and distance between rings can be specified from the dialog box or from parameters in each feature. N-radial lines can be drawn from the center point to the outer ring.</p>
<h3>Star</h3>
<p>Create an N-pointed star with the outer vertices located on a circle defined by the outer radius. The inner vertices are located along the circle defined by the inner radius. One of the radius' can be negative which gives an interesting shape.</p>
<h2><a name="interactive-shapes"></a> <img src="images/concentricrings.png" width="24"> Interactive Geodesic Shapes</h2>
<p>The <strong><em>Interactive geodesic shapes</em></strong> algorithms allow the user to click on the map canvas to capture a coordinate and then generate a single shape as defined from the processing dialog box centered around the coordinate. So far there are two shapes that can be created. These can be accessed from the QGIS menu at <em>Vector->Shape Tools->Interactive geodesic shapes</em> or from the processing tool box like this.</p>
<div style="text-align:center"><img src="doc/processing-interactive.jpg" alt="Interactive geodesic shapes"></div>
<ul>
<li><img src="images/concentricrings.png" width="24"> <strong>Interactive concentric rings</strong> - This creates 'N' concentric rings about the specified coordinate with optional radial lines. Here is an example of the output.</li>
</ul>
<div style="text-align:center"><img src="doc/concentriccircles.jpg" alt="Concentric Circles"></div>
<ul>
<li><img src="images/donut.png" width="24"> <strong>Interactive donut</strong> - This creates a donut shape centered on the specified coordinate. If the inner radius is 0, it creates a circle.</li>
</ul>
<h2><a name="xy-to-line"></a> <img alt="XY to Line" src="images/xyline.svg" /> XY to Line</h2>
<p>This creates geodesic, great circle, or simple lines based on starting and ending coordinates in each table record. One of the coordinates can be from a point layer geometry or both can come from the attribute table data where each record has a starting x-coordinate, starting y-coordinate, and an ending x-coordinate and ending y-coordinate.</p>
<div style="text-align:center"><img src="doc/xytoline.jpg" alt="XY to Line"></div>
<p><strong>Input Layer</strong> - This can either be a point layer, a simple table, or any other vector data set that has two coordinates among its data fields. For example a CSV file containing starting and ending coordinates could be imported using <strong><em>Layer->Add Layer->Add Delimited Text Layer...</em></strong> located in the QGIS menu. From this dialog box the user can specify one of the coordinates for the layer's geometry or <strong>No Geometry</strong> can be used. Both types of layers will be visible to <strong>XY to Line.</strong></p>
<p><strong>Output point layer</strong> - Optional points layer that can be created in QGIS. It can contain the starting point, ending point, both points, or no points in which case it will not be created. </p>
<p><strong>Output line layer</strong> - Output line layer file that is created in QGIS.</p>
<p><strong>Input CRS for coordinates within the vector fields</strong> - CRS of the input coordinates within the table data fields.</p>
<p><strong>Output layer CRS</strong> - CRS of the output line and point layers.</p>
<p><strong>Line type</strong> - 1) <strong>Geodesic</strong> creates a highly accurate shortest path between two points. 2) <strong>Great Circle</strong> creates a <em>Great Circle</em> arc between the two points. 3) <strong>Simple Line</strong> creates a non-geodesic straight line between the two points. </p>
<p><strong>Starting point</strong> - Specify whether to use the <em>Layer's point geometry</em> (not applicable for layers that don't have Point geometry) or to specify the <strong>Starting X Field (lon)</strong> and <strong>Starting Y Field (lat)</strong> from the layer's fields.</p>
<p><strong>Ending Point</strong> - Specify whether to use the <em>Layer's geometry</em> (not applicable for layers that don't have Point geometry) or to specify the <strong>Ending X Field (lon)</strong> and <strong>Ending Y Field (lat)</strong> from the layer's fields.</p>
<p><strong>Show starting point</strong> - If checked the output point layer will include an entry for the starting point if an <strong>Output point layer</strong> has been specified.</p>
<p><strong>Show ending point</strong> - If checked the output point layer will include an entry for the ending point if an <strong>Output point layer</strong> has been specified.</p>
<p><strong>Break lines at -180, 180 boundary for better rendering</strong> - Depending on the QGIS projection when lines cross the international date line, strange behavior may occur. Checking this box breaks the line at the -180, 180 boundary in a way that it displays properly.</p>
<p>This function can also be accessed from the <strong>Processing Toolbox</strong>.</p>
<div style="text-align:center"><img src="doc/processing.jpg" alt="Processing Toolbox"></div>
<h2><a name="geodesic-line-break"></a> <img alt="Geodesic Line Break at -180,180" src="images/idlbreak.svg" /> Geodesic Line Break at -180,180</h2>
<p>If you have ever created a geospatial masterpiece that has crossings across the International Date Line at a longitude of -180°/180° and it turned out like the image on the left, you are not alone.</p>
<div style="text-align:center"><img src="doc/breaklines.jpg" alt="Break lines"></div>
<p><strong>Geodesic line break</strong> will break lines at the -180°/180° boundary along a geodesic path which is the shortest distance along the earth's surface between two points. The algorithm is very simple with just an input and output layer. The resulting output is shown in the above right side image. Depending on your data you may find it useful to also run the <strong>Geodesic Densifier</strong> on the data prior to this routine.</p>
<div style="text-align:center"><img src="doc/geodesiclinebreak.jpg" alt="Geodesic Line Break"></div>
<h2><a name="geodesic-densifier"></a> <img alt="Geodesic Densifier" src="images/geodesicDensifier.svg" /> Geodesic Densifier</h2>
<p>Densify a line or polygon vector layer by adding geodesic points in between individual line segments when its length is too great. This gives it a nice smooth curved appearance. For line vectors a geodesic line can be drawn between just the beginning and ending points.</p>
<div style="text-align:center"><img src="doc/geodesicshape.jpg" alt="Geodesic Densifier"></div>
<ul>
<li><strong>Input Layer</strong> - Select an existing line or polygon layer.</li>
<li><strong>Output Layer</strong> - Specifies the output layer that will be created in QGIS.</li>
<li><strong>Discard inner vertices (lines only)</strong> - When this is checked only the beginning and ending points are used when drawing geodesic lines. This does not apply to polygons.</li>
<li><strong>Maximum line segment length (in kilometers)</strong> - This is the maximum length of a line segment before a new vertex is added along the geodesic path. This value defaults to the length specified in the <strong>Settings</strong> menu.</li>
</ul>
<p>The following shows the before and after results of running this function on a polygon layer.</p>
<div style="text-align:center"><img src="doc/geodesicpolygon.jpg" alt="Geodesic Polygon"></div>
<p>This function can also be accessed from the <strong>Processing Toolbox</strong>.</p>
<div style="text-align:center"><img src="doc/processing.jpg" alt="Processing Toolbox"></div>
<h2><a name="geodesic-line-decimate"></a> <img alt="Geodesic Line Decimate" src="images/geodesicLineDecimate.svg" /> Geodesic Line Decimate</h2>
<p>This simplifies the geometry of a line layer by removing vertices who's distance to the previous vertex is less than the specified value. For each line, the geodesic distance is calculated between vertices and if the distance is less than the specified minimum distance then the vertex is deleted. This repeats until the distance threshold is exceeded. The only exception to this rule is if <strong><em>Preserve final vertex</em></strong> is selected in which case the final vertex is always saved.</p>
<div style="text-align:center"><img src="doc/geodesiclinedecimate.jpg" alt="Geodesic line decimate"></div>
<p>The following shows the before and after results of running this funciton on a line layer.</p>
<div style="text-align:center"><img src="doc/geodesicdecimation.jpg" alt="Geodesic decimation"></div>
<p><strong>Parameters</strong></p>
<ul>
<li><strong>Input layer</strong> - Select an existing line layer.</li>
<li><strong>Output layer</strong> - Specifies the output layer that will be created.</li>
<li><strong>Preserve final vertex</strong> - If checked then the final vertex will not be discarded. If the distance between the previous saved vertex and the final vertex is less than the minimum distance then the next to the last saved vertex will be deleted or if there are only two vertices left, than the distance between the first and final vertex may be less than the minimum distance.</li>
<li><strong>Decimation minimum distance beween vertices</strong> - Sprecifies the minimum distance between vertices. Distances less than this are deleted.</li>
<li><strong>Distance units</strong> - Specifies the units of measure for the "Decimation minimum distance betwee vertices."</li>
</ul>
<h2><a name="geodesic-point-decimate"></a> <img alt="Geodesic Point Decimate" src="images/geodesicPointDecimate.svg" /> Geodesic Point Decimate</h2>
<p>This reduces the number of points within a point vector layer by using geodesic distances mesurements between points and/or the time interval between points. This assumes that the points are ordered or that there is a property field that specifies the order of the points. Poiint can also be grouped together based on an attributed in the table in which case points from each grouping are processed separately.</p>
<p><strong>Parameters</strong></p>
<ul>
<li><strong>Input point layer</strong> - Select an existing line layer.</li>
<li><strong>Output layer</strong> - Specifies the output layer that will be created.</li>
<li><strong>Point order field</strong> - This specifies a field that defines the order of the points to be processed. A time field can be used with GPS data to order the points by the time they were acquired.</li>
<li><strong>Preserve final point</strong> - If checked then the final point in each group will not be discarded.</li>
<li><strong>Remove points that are less than the minimum distance</strong> - Enables geodesic distance decimation.<ul>
<li><strong>Minimum distance beween points</strong> - Sprecifies the minimum distance between points. Distances less than this are targeted for deletion.</li>
<li><strong>Distance units</strong> - Specifies the units of measure for the geodesic minimum distance.</li>
</ul>
</li>
<li><strong>Remove points by minimum time interval</strong> - Enables time decimation.<ul>
<li><strong>Time field</strong> - Select a DateTime field to use for time decimation. If time is specified as a string then the field will need to be converted to a DateTime fields.</li>
<li><strong>Minimum time between points</strong> - Points not meeting the minimum time difference are removed.</li>
<li><strong>Time units</strong> - Specifies the time units of the above value. The units of time can be <strong><em>Seconds</em></strong>, <strong><em>Minutes</em></strong>, <strong><em>Hours</em></strong>, and <strong><em>Days</em></strong>.</li>
</ul>
</li>
<li><strong>When both decimate by distance and time are selected, preserve points if</strong> - This specifies whether both distance and time requements must be met or only one or the other requirements are met.</li>
</ul>
<h2><a name="geodesic-measure"></a> <img alt="Geodesic Measure Tool" src="images/measure.svg" /> Geodesic Measure Tool</h2>
<p>This provides the ability to measure distances using geodesic (shortest path) algorithms. The results returned are similar to those used by Google Earth and makes for a nice baseline of distances. It also includes the heading from the first point to the second and a heading from the second point to the first. The units are in degrees. The units of distance can be kilometers, meters, centimeters, miles, yards, feet, inches, and nautical miles. Simply click on the <strong><em>Geodesic Measure Tool</em></strong> icon and start left-mouse clicking on the map to get measurements between points. A right-mouse click or ESC key press will end the measurement. Notice that the ellipsoid used to calculate measurements is listed in the lower left-hand corner. By default this is set to <strong><em>WGS 84</em></strong>, but it can be changed in the <strong><em>Settings</em></strong> menu. If snapping is enabled, then the <strong><em>Geodesic Measure Tool</em></strong> will snap to vector layer vertices and features when the mouse hovers over them.</p>
<p>While using the geodesic measure tool the user can quickly copy values of the last heading to, heading from, distance, and total distance onto the clipboard by typing one of the following keys:</p>
<ul>
<li><strong>1 or T</strong> - Copies the most recent 'Heading to' value onto the clipboard.</li>
<li><strong>2 or F</strong> - Copies the most recent 'Heading from' value onto the clipboard.</li>
<li><strong>3 or D</strong> - Copies the most recent 'Distance' value onto the clipboard.</li>
<li><strong>4 or A</strong> - Copies the 'Total distance' value onto the clipboard.</li>
</ul>
<p>The number of significant decimal digits of the value copied onto the clipboard is determined in the <strong><em>Settings</em></strong>.</p>
<div style="text-align:center"><img src="doc/geodesicmeasure.jpg" alt="Geodesic Measure Tool"></div>
<p>The <strong>Save to Layer</strong> button will create a <strong>Measurement</strong> layer that contains the distance and by default the distance label will be displayed. The number of significant digits used for the label can be configured in <strong><em>Settings</em></strong>.</p>
<div style="text-align:center"><img src="doc/geodesicmeasure2.jpg" alt="Geodesic Measure Tool"></div>
<p>By right-mouse clicking on the <strong>Measurement</strong> layer and selecting <strong>Open Attribute Table,</strong> the following attributes are available for each measured line segment; label, value, units, heading_to, heading_from, and the total distance for all line segments.</p>
<div style="text-align:center"><img src="doc/geodesicmeasure3.jpg" alt="Geodesic Measure Tool"></div>
<p>If <strong>Points of the compass</strong> settings are set to somthing other than <strong>None</strong>, then compass cardinal directions will be added to the <strong>Geodesic measure tool</strong> dialog box like this.</p>
<div style="text-align:center"><img src="doc/geodesicmeasure5.jpg" alt="Geodesic Measure Tool"></div>
<p>These attributes will also be saved when exporting by using the <strong>Save to Layer</strong> button.</p>
<div style="text-align:center"><img src="doc/geodesicmeasure6.jpg" alt="Geodesic Measure Tool"></div>
<p>By clicking on the <strong><em>Add measurement point</em></strong> icon <img alt="Add measurement point" src="images/manualpoint.png" />, a new dialog windows is displayed were precise measurement points can be added. The coordinates can be in WGS 84 (EPSG:4326), the project CRS, or some other custom projection. In the drop down menus specify the projection and the coordinate order in which the coordinates are entered.</p>
<div style="text-align:center"><img src="doc/geodesicmeasure4.jpg" alt="Add measurement point"></div>
<h2><a name="geodesic-measure-layer"></a> <img alt="Geodesic Measurement Layer" src="images/linedigitize.svg" /> Geodesic Measurement Layer</h2>
<p>This takes a polygon or line layer and measures the geodesic distances of each line segment in the lines or polygons or the total distance of all line segments in the shape's geometry. The user can choose whether each line segment is measured or the entire line/polygon geometry is measured. It creates a new line layer of line segments that contain attributes of all the measurements. If <strong>Measure total length rather than each line segment</strong> is checked, only the total distance is reported and the attributes are: label, distance, and units of measure. If measuring individual line segments, the attributes are: label, distance, units of measure, azimuth/bearing to the next point, and total distance of the geometry. If <strong>Compass direction resolution</strong> is not <strong><em>None</em></strong>, then the following attributes are added: compass abbreviated cardinal direction, compass name, and compass traditional name. If the total length check box is unchecked and a value other than <strong><em>None</em></strong> is selected for <strong>Compass direction resolution</strong> and <strong>Add compass directions to label based on above resolution</strong> is checked, compass cardinal directions are added to the <strong><em>label</em></strong> attribute. <strong>Distance units</strong> can be kilometers, meters, centimeters, miles, yards, feet, inches, or nautical miles. <strong>Use automatic styling</strong> styles the QGIS layer with the label string in the attribute table and with the text and line colors found in <strong>Settings</strong>. Select the checkbox for <strong>Retain the original feature's attributes</strong> if you want the original attributes included in the output layer; otherewise, only the calculated measurements will be included.</p>
<div style="text-align:center"><img src="doc/measurement-layer.jpg" alt="Geodesic Measurement Layer"></div>
<p>Here is an example of running this on a polygon. Notice how it measures both the outer boundary and the inner boundary.</p>
<div style="text-align:center"><img src="doc/measure-polygon.jpg" alt="Measuring a polygon"></div>
<p>Here is what the attributes table looks like.</p>
<div style="text-align:center"><img src="doc/measurement-attributes.jpg" alt="Measurement Attributes"></div>
<p>If <strong>Compass direction resolution</strong> is not <strong>None</strong> and <strong>Measure total length rather than each line segment</strong> is not checked, then additional compass cardinal direction atttibutes will be added. Here is what the attributes table looks like with <strong>Compass direction resolution</strong> is set to <strong>16 point</strong>.</p>
<div style="text-align:center"><img src="doc/measurement-attributes2.jpg" alt="Measurement Attributes"></div>
<h2><a name="geodesic-transformations"></a> <img alt="Geodesic Transformations" src="images/transformShape.svg" /> Geodesic Transformations Tool</h2>
<p>This tool provides the ability to geodesically transform a shape. It supports scaling, rotation and translation. Each of these can use data defined override expressions. The relative size and geometry of each shape will be retained regardless of the projection. </p>
<div style="text-align:center"><img src="doc/geodesictransform.jpg" alt="Geodesic Transformations"></div>
<ul>
<li><strong>Input layer</strong> - Select an existing point, line, or polygon vector layer.</li>
<li><strong>Selected features only</strong> - Checking this box will cause the algorithm to only transform the selected features.</li>
<li><strong>Rotation angle about the centroid</strong> - Rotate the feature about its centroid. A positive angle rotates in a clockwise direction.</li>
<li><strong>Scale factor about the centroid</strong> - Scale the shape about its centroid. A scale factor of 1 retains its same size.</li>
<li><strong>Translation distance</strong> - Distance the shape will be moved along a geodesic path.</li>
<li><strong>Translation azimuth</strong> - Azimuth or direction the shape will be moved along a geodesic path.</li>
<li><strong>Translation distance units</strong> - Units of distance the shape will be move.</li>
<li><strong>Output layer</strong> - The output layer that will be created in QGIS.</li>
</ul>
<p>To the right of each parameter is the data defined override button <img alt="" src="doc/datadefined.jpg" /> where the default value is overridden with a value from one of the attributes or an expression. This leads to some powerful and creative applications.</p>
<div style="text-align:center"><img src="doc/geodesictransformexample.jpg" alt="Geodesic Transformation Example"></div>
<p>This was created by clicking on the <strong><em>Rotation angle about the centroid</em></strong> data defined override button, clicking on <strong>Edit</strong> and using the expression <code><span style="font-family:'Courier New'"><b>randf( -10, 10)</b></span></code> and for <strong><em>Scale factor about the centroid</em></strong> using the expression <code><span style="font-family:'Courier New'"><b>randf(0.65, 0.85)</b></style>.</code> For each polygin in the input layer it rotates them using a random value between -10 and 10 degrees and scales them by a factor betweeen 0.65 and 0.85.</p>
<h2><a name="geodesic-flip"></a> <img alt="Geodesic Flip and Rotate Tools" src="images/flip.svg" /> Geodesic Flip and Rotate Tools</h2>
<p>This is a collection of geodesic tools that transform vector features including the ability to flip horizontally, flip vertically, rotate by 180 degrees, rotate clockwise by 90 degrees, and rotate counter clockwise by 90 degrees. The first is a processing toolbox algorithm that allows the selection of one of these five transforms.</p>
<div style="text-align:center"><img src="doc/fliptool.jpg" alt="Geodesic Flip and Rotate"></div>
<ul>
<li><strong>Input vector layer</strong> - Select an existing line, or polygon vector layer.</li>
<li><strong>Transform function</strong> - Choose the desired function: <strong><em>Flip Horizontal, Flip Vertical, Rotate 180°, Rotate 90° CW,</em></strong> or <strong><em>Rotate 90° CCW</em></strong>.</li>
<li><strong>Output layer</strong> - The output layer that will be created in QGIS.</li>
</ul>
<p>The following geodesic tools work on an editable line or polygon vector layer. If a feature is selected, these functions only operate on that feature; otherwise, it operates on all features in the layer.</p>
<ul>
<li><img alt="Flip horizontal" src="images/flipHorizontal.svg" /> <strong>Flip horizontal</strong> flips a vector feature horizontally about its centroid.</li>
<li><img alt="Flip vertical" src="images/flipVertical.svg" /> <strong>Flip vertical</strong> flips a vector feature vertically about its centroid.</li>
<li><img alt="Rotate 180" src="images/rotate180.svg" /> <strong>Rotate 180° </strong> rotates a vector feature by 180 degrees.</li>
<li><img alt="Rotate 90 CW" src="images/rotatecw.svg" /> <strong>Rotate 90° CW</strong> rotates a vector feature by 90 degrees clockwise.</li>
<li><img alt="Rotate 90 CCW" src="images/rotateccw.svg" /> <strong>Rotate 90° CCW</strong> rotates a vector feature by 90 degrees counter-clockwise.</li>
</ul>
<h2><a name="azimuth-distance"></a> <img alt="Azimuth, Distance Digitizer" src="images/dazdigitize.svg" /> Azimuth, Distance Digitizer</h2>
<p>This tool works on point and line vector layers and is enabled when they are selected and in edit mode. In either case the following dialog box is displayed when the tool is enabled and a point on the map is clicked on. If snapping is enabled (<em>Project->Snapping Options...</em>), then when the cursor hovers close to an existing point or vertex, a bounding box around the point will be displayed. Clicking near the vertex will snap its location to be used by the <strong><em>Azimuth, Distance Digitizer</em></strong> as its starting point.</p>
<div style="text-align:center"><img src="doc/azimuth-distance.jpg" alt="Azimuth, Distance Tool"></div>
<p>Azimuth is in degrees and distance is in the selected <em>Distance units of measure</em>. The following is how it interacts on point and line layers. </p>
<ul>
<li><strong>Point Vector Layer</strong> - If an editable point vector layer is selected and the map is click on, the tool will create a point in the azimuth direction and at the specified distance. The point clicked on can be also included in the output layer.</li>
<li><strong>Line Vector Layer</strong> - If an editable line vector layer is selected and the map is click on, the tool will create a geodesic line from the clicked point along the azimuth and distance path.</li>
</ul>
<h2><a name="azimuth-distance-sequence"></a> <img alt="Azimuth Distance Sequence Digitizer" src="images/dazdigitize.svg" /> Azimuth Distance Sequence Digitizer</h2>
<div style="text-align:center"><img src="doc/az-sequence.jpg" alt="Azimuth, Distance Sequence Digitizer"></div>
<p>This is similar to the <strong>Azimuth, Distance Digitizer</strong>, but it provides the ability to click on the map as a starting point and then give a series of bearings and distances in the order of 'bearing 1, distance 1, bearing 2, distance 2, ... bearing N, distance N' and it will create a path. This is useful in some survey work. If older surveying used magnetic north, it can be compensated for by the <strong>Bearing / declination adjustment</strong>. Magnetic declination changes over time, but the <a href="https://www.ngdc.noaa.gov/geomag-web/#declination">NOAA Magnetic Field Calculator</a> provides an easy interface to estimate the magnetic north declination at a certain latitude, longitude and time, all the way back to 1590. West declination will be a negative number and east declination is a positive number. If a polygon layer is selected then the resulting shape automatically closes the polygon such that the beginning and ending points are the same. If a line layer is selected then you have the option of automatically adding a line segment from the last point in the sequence to the first point. If a point layer is selected, then only the nodes will be added to the layer. If snapping is enabled (<em>Project->Snapping Options...</em>), then when the cursor hovers close to an existing point or vertex, a bounding box around the point will be displayed. Clicking near the vertex will snap its location to be used by the <strong><em>Azimuth, Distance Sequence Digitizer</em></strong> as its starting point.</p>
<h2><a name="expressions"></a>Expression Functions</h2>
<p><strong>Shape Tools</strong> includes the following field calculator functions:</p>
<p><b>st_from_meters()</b> converts a distance measurement from meters into the specified measurement unit.</p>
<ul>
<li>Syntax<ul>
<li><b>st_from_meters</b>(<i>length</i>, <i>units</i>)<ul>
<li><i>length</i> → the length in meters to be converted.</li>
<li><i>units</i> → conversion unit<ul>
<li>'cm' → centimeters</li>
<li>'m' → meters</li>
<li>'km' → kilometers</li>
<li>'in' → inches</li>
<li>'ft' → feet</li>
<li>'yard' → yards</li>
<li>'mi' → miles</li>
<li>'nm' → nautical miles</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li>Example<ul>
<li><b>st_from_meters</b>(1000, 'km') → returns 1.0</li>
</ul>
</li>
</ul>
<p><b>st_to_meters()</b> converts a distance measurement into meters.</p>
<ul>
<li>Syntax<ul>
<li><b>st_to_meters</b>(<i>length</i>, <i>units</i>)<ul>
<li><i>length</i> → the length to be converted into meters.</li>
<li><i>units</i> → conversion unit<ul>
<li>'cm' → centimeters</li>
<li>'m' → meters</li>
<li>'km' → kilometers</li>
<li>'in' → inches</li>
<li>'ft' → feet</li>
<li>'yard' → yards</li>
<li>'mi' → miles</li>
<li>'nm' → nautical miles</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li>Example<ul>
<li><b>st_to_meters</b>(1, 'km') → returns 1000.0.</li>
</ul>
</li>
</ul>
<p><b>st_geodesic_distance()</b> returns the geodesic distance in meters between two y, x (latitude, longitude) coordinates or two geometry points.</p>
<ul>
<li>Syntax<ul>
<li><b>st_geodesic_distance</b>(<i>y1, x1, y2, x2[, crs='EPSG:4326']</i>)</li>
<li><b>st_geodesic_distance</b>(<i>geom1, geom2[, crs='EPSG:4326']</i>)</li>
<li><i>y1</i> → the y or latitude coordinate for the first point.</li>
<li><i>x1</i> → the x or longitude coordinate for the first point.</li>
<li><i>y2</i> → the y or latitude coordinate for the second point.</li>
<li><i>x2</i> → the x or longitude coordinate for the second point.</li>
<li><i>geom1</i> → the first point geometry.</li>
<li><i>geom2</i> → the second point geometry.</li>
<li><i>crs</i> → optional coordinate reference system of the y, x coordinates or geom1 and geom2. Default value is 'EPSG:4326' if not specified.</li>
</ul>
</li>
<li>Examples<ul>
<li><b>st_geodesic_distance</b>(40.0124, -105.2713, 39.7407, -104.9880) → 38696.715933</li>
<li><b>st_geodesic_distance</b>(4867744, -11718747, 4828332, -11687210, 'EPSG:3857') → 38697.029390</li>
<li><b>st_geodesic_distance</b>(<b>make_point</b>(-105.2713, 40.0124), <b>make_point</b>(-104.9880, 39.7407)) → 38696.715933</li>
<li><b>st_geodesic_distance</b>(<b>make_point</b>(-11718747, 4867744), <b>make_point</b>(-11687210, 4828332), 'EPSG:3857') → 38697.029390</li>
</ul>
</li>
</ul>
<p><b>st_geodesic_bearing()</b> returns the geodesic azimuth or bearing starting from the first y, x (latitude, longitude) coordinate in the direction of the second coordinate.</p>
<ul>
<li>Syntax<ul>
<li><b>st_geodesic_bearing</b>(<i>y1, x1, y2, x2[, crs='EPSG:4326']</i>)</li>
<li><b>st_geodesic_bearing</b>(<i>geom1, geom2[, crs='EPSG:4326']</i>)</li>
<li><i>y1</i> → the y or latitude coordinate for the first point.</li>
<li><i>x1</i> → the x or longitude coordinate for the first point.</li>
<li><i>y2</i> → the y or latitude coordinate for the second point.</li>
<li><i>x2</i> → the x or longitude coordinate for the second point.</li>
<li><i>geom1</i> → the first point geometry.</li>
<li><i>geom2</i> → the second point geometry.</li>
<li><i>crs</i> → optional coordinate reference system of the y, x coordinates or geom1 and geom2. Default value is 'EPSG:4326' if not specified.</li>
</ul>
</li>
<li>Examples<ul>
<li><b>st_geodesic_bearing</b>(40.0124, -105.2713, 39.7407, -104.9880) → 141.131805</li>
<li><b>st_geodesic_bearing</b>(4867744, -11718747, 4828332, -11687210, 'EPSG:3857') → 141.1319</li>
<li><b>st_geodesic_bearing</b>(<b>make_point</b>(-105.2713, 40.0124), <b>make_point</b>(-104.9880, 39.7407)) → 141.131805</li>
<li><b>st_geodesic_bearing</b>(<b>make_point</b>(<b>make_point</b>(-11718747, 4867744), <b>make_point</b>(-11687210, 4828332), 'EPSG:3857') → 141.1319</li>
</ul>
</li>
</ul>
<p><b>st_geodesic_transform</b> geodesically transfrom a shape (point, line, polygon) using rotation, translation, and scaling.</p>
<ul>
<li>Syntax<ul>
<li><b>st_geodesic_transform</b>( <i>geom [, scale=1, rotate=0, distance=0, azimuth=0, unit='m', crs='EPSG:4326'</i>)</li>
<li><i>geom</i> → input geometry (point, line, polygon).</li>
<li><i>scale</i> → the scale factor. Default is 1.0.</li>
<li><i>rotate</i> → the rotation angle in degrees. Default is 0 degrees.</li>
<li><i>distance</i> → the translation distance. Default is 0.</li>
<li><i>azimuth</i> → the translation azimuth in degrees. Default is 0.</li>
<li><i>unit</i> → translation distance units.<ul>
<li>'cm' → centimeters</li>
<li>'m' → meters</li>
<li>'km' → kilometers</li>
<li>'in' → inches</li>
<li>'ft' → feet</li>
<li>'yard' → yards</li>
<li>'mi' → miles</li>
<li>'nm' → nautical miles</li>
</ul>
</li>
<li><i>crs</i> → optional coordinate reference system of the input geometry. Default value is 'EPSG:4326' if not specified.</li>
</ul>
</li>
<li>Example<ul>
<li><b>geom_to_wkt</b> ( <b>st_geodesic_transform</b>(make_line(make_point(2,4),make_point(3,5)), 1.0, 45, 1000, 90, 'km')) → returns 'LineString (10.80438811 4.44561039, 12.21595371 4.44309579)'</li>
</ul>
</li>
</ul>
<h2><a name="settings"></a>Settings</h2>
<p>The settings dialog box can be accessed from the Shape Tools menu <em>Vector->Shape Tools->Settings</em>. The following are the parameters that can be configured.</p>
<div style="text-align:center"><img src="doc/settings.jpg" alt="Settings"></div>
<ul>
<li><strong>Create Shapes default column names for input X,Y (Lat,Lon) geometry</strong> - All of the different shapes have a check box called <strong>Add input geometry fields to output table</strong>. When checked, the input point geometry will be added to fields in the output shape table. By default these fields are named <strong><em>geom_x</em></strong> and <strong><em>geom_y</em></strong>, but can be changed here. If the input layer has a field by the same name, then a number is appended to make it unique.</li>
<li><strong>Geodesic Line Settings</strong> - These settings are used when drawing geodesic and great circle lines.<ul>
<li><strong>Maximum segment length before creating a new segment</strong> - In order to draw a smooth curved line, multiple line segments are required. This defines how far to travel before a new line segment is created. This parameter is in kilometers. </li>
<li><strong>Maximum number of segments per line</strong> - This is the maximum number of line segments that will be created for any line even though the maximum segment length may be exceeded. This takes precedence.</li>
</ul>
</li>
<li><strong>Measure Tool Settings</strong> - These are settings for the <strong>Geodesic Measure Tool</strong>.<ul>
<li><strong>Azimuth Range</strong> - The azimuth is displayed from <strong>-180 to 180</strong> degrees or from <strong>0 to 360</strong> degrees.</li>
<li><strong>Points of the compass</strong> - The options are <strong>None</strong>, <strong>32 point</strong>, <strong>16 point</strong>, <strong>8 point</strong>, and <strong>4 point</strong>. If set to any option other than <strong>None</strong>, the measure tool dialog box will included additional compass cardinal headings.</li>
<li><strong>Rubber band color</strong> - Selects the rubber band line color used by the measure tool.</li>
<li><strong>Measurement layer color</strong> - Vector line color when a measurement layer is created from the <strong><em>Geodesic measure tool</em></strong> or from the <strong><em>Geodesic measurement layer</em></strong> tool.</li>
<li><strong>Measurement layer text</strong> - Color of the text when a measurement layer is created from the <strong><em>Geodesic measure tool</em></strong> or from the <strong><em>Geodesic measurement layer</em></strong> tool.</li>
<li><strong>Copy to clipboard significant digits</strong> - This is the number of significant decimal digits that are copied onto the clipboard when the user is using the <strong><em>Geodesic measure tool</em></strong> and presses on one of the copy to clipboard keys.</li>
<li><strong>Save to layer significant digits</strong> - This is the number of significant decimal digits that are used as the label when the user selects <strong><em>Save to Layer</em></strong> from the <strong><em>Geodesic measure tool</em></strong>.</li>
</ul>
</li>
<li><strong>Ellipsoid Used for Measurements</strong> - Selects the ellipsoid used for calculating the geodesic distances within Shape Tools. By default this should normally be <em>WGS 84</em><ul>
<li><strong>Ellipsoid group</strong> - Choose the default <em>WGS 84</em> setting or enable <em>System Ellipsoids</em> or <em>Historical Ellipsoids</em>.</li>
<li><strong>System Ellipsoids</strong> - This is enabled if <strong>Ellipsoid group</strong> is set to <em>System Ellipsoids</em>.</li>
<li><strong>Historical Ellipsoids</strong> - This is enabled if <strong>Ellipsoid group</strong> is set to <em>Historical Ellipsoids</em>. Additional historical ellipsoids can be selected.</li>
</ul>
</li>
</ul></body>