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

# Module simplify

Simplify or linearize a path of `LatLon` points.

Each of the 4 simplify functions is based on a different algorithm and produces different, simplified results in (very) different run times for the same path:

- Function simplify1 eliminates points with edge lengths shorter than the given tolerance.
- Function simplifyRDP implements the Ramer-Douglas-Peucker (RDP) algorithm, iteratively finding the point farthest from each path edge. Original RDP exhaustively searches the most distant point in each iteration, modified RDP stops at the first point exceeding the distance tolerance.
- Function simplifyRW uses the Reumann-Witkam (RW) method, sliding a "pipe" over each path edge, removing all subsequent points within the pipe radius, up to the first point outside the pipe.
- Function simplifyVW provides the Visvalingam-Whyatt (VW) method using the area of the triangle formed by three neigboring points. Original VW removes only a single point per iteration, modified VW eliminates all points with a triangular area not exceeding the tolerance in each iteration.

Keyword argument shortest of functions simplifyRDP and simplifyRW specifies of the distance between a point and a path edge. If `True`, use the shortest distance to the path edge or edge points, otherwise use the perpendicular distance to the (extended) edge through both points.

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

Use keyword argument `indices=True` in any function to return a list of indices of simplified point instead of the simplified points with 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 pygeodesy.equirectangular4 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://www.ScienceDirect.com/science/article/pii/S0098300402000092
- 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: 24.12.02

Functions
simplify1(points, distance=0.001, radius=6371008.771415, indices=False, **options) Basic simplification of a path of `LatLon` points by eliminating any points closer together than the given distance tolerance. |
simplifyRDP(points, distance=0.001, radius=6371008.771415, shortest=False, indices=False, modified=False, **options) Ramer-Douglas-Peucker (RDP) simplification of a path of `LatLon` points by eliminating any points too close together or closer to an edge than the given distance tolerance. |
simplifyRW(points, pipe=0.001, radius=6371008.771415, shortest=False, indices=False, **options) Reumann-Witkam (RW) simplification of a path of `LatLon` points by eliminating any points too close together or within the given pipe tolerance along an edge. |
simplifyVW(points, area=0.001, radius=6371008.771415, indices=False, attr=None, modified=False, **options) Visvalingam-Whyatt (VW) simplification of a path of `LatLon` points by eliminating any points too close or with a triangular area not exceeding the given area tolerance squared. |

Variables
| __all__ = `_ALL_LAZY.simplify`

Function Details

### simplify1 (points, distance=0.001, radius=6371008.771415, indices=False, **options) |
Basic simplification of a path of `LatLon` points by eliminating any points closer together than the given distance tolerance. Arguments: `points` - Iterable with the path points (`LatLon`[]). `distance` - Tolerance (`meter`, same units as `radius`). `radius` - Mean earth radius (`meter`, conventionally). `indices` - If `True`, return `points` indices instead of the simplified points (`bool`). `options` - Optional keyword arguments passed thru to function pygeodesy.equirectangular4. Returns: Simplified points (`LatLon`[]) or `points` indices. Raises: `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function pygeodesy.equirectangular4. `ValueError` - Tolerance `distance` or `radius` too small.

### simplifyRDP (points, distance=0.001, radius=6371008.771415, shortest=False, indices=False, modified=False, **options) |
Ramer-Douglas-Peucker (RDP) simplification of a path of `LatLon` points by eliminating any points too close together or closer to an edge than the given distance tolerance. Arguments: `points` - Iterable with the path points (`LatLon`[]). `distance` - Tolerance (`meter`, same units as `radius`). `radius` - Mean earth radius (`meter`, conventionally). `shortest` - If `True`, use the shortest otherwise the perpendicular distance (`bool`). `indices` - If `True`, return `points` indices instead of the simplified points (`bool`). `modified` - If `True`, use the `modified RDP` method (`bool`), see the note. `options` - Optional keyword arguments passed thru to function pygeodesy.equirectangular4. Returns: Simplified points (`LatLon`[]) or `points` indices. Raises: `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function pygeodesy.equirectangular4. `ValueError` - Tolerance `distance` or `radius` too small. Note: The original `RDP` method exhaustively searches for the point with the largest distance (resulting in complexity O(n**2) with n is the number of points). The `modified` `RDP` method stops at the first point farther than the `distance` tolerance, significantly reducing the run time (but producing results different from the original `RDP` method).

### simplifyRW (points, pipe=0.001, radius=6371008.771415, shortest=False, indices=False, **options) |
Reumann-Witkam (RW) simplification of a path of `LatLon` points by eliminating any points too close together or within the given pipe tolerance along an edge. Arguments: `points` - Iterable with the path points (`LatLon`[]). `pipe` - Pipe radius, half-width (`meter`, same units as `radius`). `radius` - Mean earth radius (`meter`, conventionally). `shortest` - If `True`, use the shortest otherwise the perpendicular distance (`bool`). `indices` - If `True`, return `points` indices instead of the simplified points (`bool`). `options` - Optional keyword arguments passed thru to function pygeodesy.equirectangular4. Returns: Simplified points (`LatLon`[]) or `points` indices. Raises: `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function pygeodesy.equirectangular4. `ValueError` - Tolerance `pipe` or `radius` too small.

### simplifyVW (points, area=0.001, radius=6371008.771415, indices=False, attr=None, modified=False, **options) |
Visvalingam-Whyatt (VW) simplification of a path of `LatLon` points by eliminating any points too close or with a triangular area not exceeding the given area tolerance squared. Arguments: `points` - Iterable with the path points (`LatLon`[]). `area` - Tolerance (`meter`, same units as `radius`). `radius` - Mean earth radius (`meter`, conventionally). `indices` - If `True`, return `points` indices instead of the simplified points (`bool`). `attr` - Optional, `points` attribute to save the area value (`str`). `modified` - If `True`, use the `modified VW` method (`bool`), see the note. `options` - Optional keyword arguments passed thru to function pygeodesy.equirectangular4. Returns: Simplified points (`LatLon`[]) or `points` indices. Raises: `AttributeError` - An `attr` isinvalid for Numpy2 `points`. `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function pygeodesy.equirectangular4. `ValueError` - Tolerance `area` or `radius` too small. Note: The original `VW` method exhaustively searches for the point with the smallest triangular area (resulting in complexity O(n**2) with n the number of points). The `modified` `VW` 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).