Package pygeodesy :: Module simplify |
[frames] | no frames]

# Module simplify

Seven functions to simplify or linearize a path of `LatLon` points.

Each of the simplify functions is based on a different algorithm and produces different simplified results in (very) different run times for the same path of `LatLon` points.

Function simplify1 eliminates points based on edge lengths shorter than a given tolerance.

The functions simplifyRDP and simplifyRDPm use the original, respectively modified Ramer-Douglas-Peucker (RDP) algorithm, iteratively finding the point farthest from each path edge. The difference is that function simplifyRDP exhaustively searches the most distant point in each iteration, while modified simplifyRDPm stops at the first point exceeding the distance tolerance.

Function simplifyRW use the Reumann-Witkam method, sliding a "pipe" over each path edge, removing all subsequent points within, closer than the pipe radius up to the first point outside the pipe.

Functions simplifyVW and simplifyVWm are based on the original, respectively modified Visvalingam-Whyatt (VW) method using the area of the triangle formed by three neigboring points. Function simplifyVW removes only a single point per iteration, while modified simplifyVWm eliminates in each iteration all points with a triangular area not exceeding the tolerance.

Functions simplifyRDP, simplifyRDPm and simplifyRW provide keyword argument shortest to select the computation of the distance between a point and a path edge. If `True`, use the shortest distance to the path edge or path end points, if `False` use the perpendicular distance to the extended path edge line.

Keyword argument `radius` of all fuctions is set to the mean earth radius in meter. Other units can be choosen, provided that the radius and tolerance are always specified in the same units.

Use keyword argument `indices`=`True` in any function to return a list of simplified point indices instead of the simplified points. The first and last index are always the first and last original index.

Finally, any additional keyword arguments `options` to all functions are passed thru to function equirectangular_ to specify the distance approximation.

To process `NumPy` arrays containing rows of lat-, longitude and possibly other values, use class Numpy2LatLon to wrap the `NumPy` array into on-the-fly-LatLon points. Pass the Numpy2LatLon instance to any simplify function and the returned result will be a `NumPy` array containing the simplified subset, a partial copy of the original `NumPy` array. Use keyword argument `indices`=`True` to return a list of array row indices inlieu of the simplified array subset.

See:

- https://Bost.Ocks.org/mike/simplify
- https://WikiPedia.org/wiki/Ramer-Douglas-Peucker_algorithm
- https://hydra.Hull.ac.UK/resources/hull:8338
- https://psimpl.SourceForge.net/reumann-witkam.html
- https://www.CS.UBC.CA/cgi-bin/tr/1992/TR-92-07.pdf
- https://GitHub.com/FlorianWilhelm/gps_data_with_python
- https://www.BDCC.co.UK/Gmaps/GDouglasPeuker.js
- https://GitHub.com/mourner/simplify-js
- https://GitHub.com/OmarEstrella/simplify.py
- https://PyPI.org/project/rdp
- https://PyPI.org/project/visvalingam
- https://PyPI.org/project/simplification

Version: 20.02.22

Functions
simplify1(points, distance, radius=6371008.77141, indices=False, **options) Basic simplification of a path of `LatLon` points. |
simplifyRDP(points, distance, radius=6371008.77141, shortest=False, indices=False, **options) Ramer-Douglas-Peucker (RDP) simplification of a path of `LatLon` points. |
simplifyRDPm(points, distance, radius=6371008.77141, shortest=False, indices=False, **options) Modified Ramer-Douglas-Peucker (RDPm) simplification of a path of `LatLon` points. |
simplifyRW(points, pipe, radius=6371008.77141, shortest=False, indices=False, **options) Reumann-Witkam (RW) simplification of a path of `LatLon` points. |
simplifyVW(points, area, radius=6371008.77141, attr=None, indices=False, **options) Visvalingam-Whyatt (VW) simplification of a path of `LatLon` points. |
simplifyVWm(points, area, radius=6371008.77141, attr=None, indices=False, **options) Modified Visvalingam-Whyatt (VWm) simplification of a path of `LatLon` points. |

Variables
| __all__ = `_ALL_LAZY.simplify`

Function Details

### simplify1(points, distance, radius=6371008.77141, indices=False, **options) |
Basic simplification of a path of `LatLon` points. Eliminates any points closer together than the given distance tolerance. Parameters: `points` - Path points (`LatLon`[]). `distance` - Tolerance (`meter`, same units as `radius`). `radius` - Mean earth radius (`meter`). `indices` - Optionally return the simplified point indices instead of the simplified points (`bool`). `options` - Optional keyword arguments passed thru to function equirectangular_. Returns: Simplified points (`LatLon`[]). Raises: `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function equirectangular_. `ValueError` - Tolerance `distance` or `radius` too small.

### simplifyRDP(points, distance, radius=6371008.77141, shortest=False, indices=False, **options) |
Ramer-Douglas-Peucker (RDP) simplification of a path of `LatLon` points. Eliminates any points too close together or closer to an edge than the given distance tolerance. This `RDP` method exhaustively searches for the point with the largest distance, resulting in worst-case complexity O(n**2) where n is the number of points. Parameters: `points` - Path points (`LatLon`[]). `distance` - Tolerance (`meter`, same units as `radius`). `radius` - Mean earth radius (`meter`). `shortest` - Optional, shortest or perpendicular distance (`bool`). `indices` - Optionally return the simplified point indices instead of the simplified points (`bool`). `options` - Optional keyword arguments passed thru to function equirectangular_. Returns: Simplified points (`LatLon`[]). Raises: `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function equirectangular_. `ValueError` - Tolerance `distance` or `radius` too small.

### simplifyRDPm(points, distance, radius=6371008.77141, shortest=False, indices=False, **options) |
Modified Ramer-Douglas-Peucker (RDPm) simplification of a path of `LatLon` points. Eliminates any points too close together or closer to an edge than the given distance tolerance. This `RDPm` method stops at the first point farther than the given distance tolerance, significantly reducing the run time (but producing results different from the original `RDP` method). Parameters: `points` - Path points (`LatLon`[]). `distance` - Tolerance (`meter`, same units as `radius`). `radius` - Mean earth radius (`meter`). `shortest` - Optional, shortest or perpendicular distance (`bool`). `indices` - Optionally return the simplified point indices instead of the simplified points (`bool`). `options` - Optional keyword arguments passed thru to function equirectangular_. Returns: Simplified points (`LatLon`[]). Raises: `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function equirectangular_. `ValueError` - Tolerance `distance` or `radius` too small.

### simplifyRW(points, pipe, radius=6371008.77141, shortest=False, indices=False, **options) |
Reumann-Witkam (RW) simplification of a path of `LatLon` points. Eliminates any points too close together or within the given pipe tolerance along an edge. Parameters: `points` - Path points (`LatLon`[]). `pipe` - Half pipe width (`meter`, same units as `radius`). `radius` - Mean earth radius (`meter`). `shortest` - Optional, shortest or perpendicular distance (`bool`). `indices` - Optionally return the simplified point indices instead of the simplified points (`bool`). `options` - Optional keyword arguments passed thru to function equirectangular_. Returns: Simplified points (`LatLon`[]). Raises: `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function equirectangular_. `ValueError` - Tolerance `pipe` or `radius` too small.

### simplifyVW(points, area, radius=6371008.77141, attr=None, indices=False, **options) |
Visvalingam-Whyatt (VW) simplification of a path of `LatLon` points. Eliminates any points too close together or with a triangular area not exceeding the given area tolerance (squared). This `VW` method exhaustively searches for the single point with the smallest triangular area, resulting in worst-case complexity O(n**2) where n is the number of points. Parameters: `points` - Path points (`LatLon`[]). `area` - Tolerance (`meter`, same units as `radius`). `radius` - Mean earth radius (`meter`). `attr` - Optional, points attribute save area value (`str`). `indices` - Optionally return the simplified point indices instead of the simplified points (`bool`). `options` - Optional keyword arguments passed thru to function equirectangular_. Returns: Simplified points (`LatLon`[]). Raises: `AttributeError` - If an `attr` is specified for Numpy2 `points`. `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function equirectangular_. `ValueError` - Tolerance `area` or `radius` too small.

### simplifyVWm(points, area, radius=6371008.77141, attr=None, indices=False, **options) |
Modified Visvalingam-Whyatt (VWm) simplification of a path of `LatLon` points. Eliminates any points too close together or with a triangular area not exceeding the given area tolerance (squared). This `VWm` method removes all points with a triangular area below the tolerance in each iteration, significantly reducing the run time (but producing results different from the original `VW` method). Parameters: `points` - Path points (`LatLon`[]). `area` - Tolerance (`meter`, same units as `radius`). `radius` - Mean earth radius (`meter`). `attr` - Optional attribute to save the area value (`str`). `indices` - Optionally return the simplified point indices instead of the simplified points (`bool`). `options` - Optional keyword arguments passed thru to function equirectangular_. Returns: Simplified points (`LatLon`[]). Raises: `AttributeError` - If an `attr` is specified for Numpy2 `points`. `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function equirectangular_. `ValueError` - Tolerance `area` or `radius` too small.