Main API: geoPathReducer

Relevant source files

The following files were used as context for generating this wiki page:

• src/index.js
• src/distance.js
• src/perpendicular-distance.js
• README.md
• package.json

The geoPathReducer is the primary entry point for the geo-path-reducer library. Its purpose is to implement the Douglas-Peucker algorithm to simplify curves represented by a series of geographical points. By reducing the number of points in a path while maintaining its general shape within a specified tolerance (epsilon), the module helps optimize map data and spatial datasets.

Sources: README.md:1-5, src/index.js:3

Core Functionality: Douglas-Peucker Implementation

The geoPathReducer function serves as a recursive algorithm that simplifies a path by identifying points that deviate most significantly from a straight line between the path's start and end points.

Algorithmic Flow

1. Distance Evaluation: For a given set of points, the algorithm calculates the perpendicular distance of every intermediate point from the line segment connecting the first and last points.
2. Maximum Deviation: It identifies the point with the maximum distance (dmax).
3. Recursive Splitting:
   • If dmax exceeds the user-defined epsilon, the path is split into two parts at the index of the maximum distance point.
   • The algorithm then calls itself recursively on both the left and right segments.
4. Base Case: If dmax is less than or equal to epsilon, all intermediate points are discarded, and only the start and end points of that segment are returned.

Sources: src/index.js:5-23, README.md:27-31

Logic Diagram

The following diagram illustrates the decision logic within the geoPathReducer function.

Mathematical Components

The simplification process relies on two internal utility modules to perform spatial calculations: distance.js and perpendicular-distance.js.

1. Great-Circle Distance

The distance function calculates the distance between two geographical coordinates on the Earth's surface using the Haversine formula. It utilizes an Earth radius of 6371 kilometers.

Parameter	Type	Description
lat1	Number	Latitude of the first point
lon1	Number	Longitude of the first point
lat2	Number	Latitude of the second point
lon2	Number	Longitude of the second point

Sources: src/distance.js:1-16

2. Perpendicular Distance

The perpendicularDistance function calculates how far a point is from a line segment defined by a start and end point. It uses Heron's formula to find the area of the triangle formed by the three points and then derives the height (the perpendicular distance).

API Reference

geoPathReducer(points, epsilon)

This is the default export of the module.

Argument	Type	Description
points	Array<Object>	An array of objects containing lat and lng properties.
epsilon	Number	The maximum distance (tolerance) between the simplified curve and the original, in degrees.

Returns: A new array of simplified points with the same object structure ({ lat, lng }).

Sources: README.md:33-41, src/index.js:3

Implementation Example

import geoPathReducer from 'geo-path-reducer';

const points = [
  { lat: 37.7749, lng: -122.4194 },
  { lat: 37.7755, lng: -122.4182 },
  { lat: 37.7769, lng: -122.4159 },
];
const epsilon = 0.0001;
const result = geoPathReducer(points, epsilon);

Sources: README.md:15-25

Project Configuration

The project is structured as a modern ES module, as indicated by the "type": "module" field in package.json. It specifies src/index.js as the main entry point.

Key	Value
Name	geo-path-reducer
Main Entry	src/index.js
License	MIT
Dependencies	None (uses native Math functions)

Sources: package.json:1-13

Summary

The geoPathReducer API provides a robust implementation of path simplification for geographical data. By utilizing recursive splitting based on perpendicular distance and the Haversine formula for spherical distance, it effectively reduces the point count of paths while adhering to a strict spatial tolerance defined by the epsilon parameter.