Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The Geo Path Reducer project is an open-source JavaScript module designed to simplify spatial curves using the Douglas-Peucker algorithm. This guide outlines the technical structure and procedures for contributors to maintain and improve the codebase. The project emphasizes mathematical accuracy in geographic distance calculations and modular JavaScript development.
Sources: README.md:3-7, package.json:1-11
Development Environment and Standards
The project is structured as a modern ES module. Contributors should ensure their environment supports the following configuration:
- Module System: The project uses
type: "module"inpackage.json, requiring ECMAScript modules (ESM) syntax. - Dependencies: The project is designed to be lightweight with minimal external dependencies, as seen in the
package.json. - Testing: A test script is defined, though specific test frameworks are currently not pre-configured beyond the npm script placeholder.
Sources: package.json:7-11, src/index.js:1
Project Structure
| File | Purpose |
|---|---|
src/index.js | Entry point containing the Douglas-Peucker recursive logic. |
src/distance.js | Utility for calculating Great-Circle distance between coordinates. |
src/perpendicular-distance.js | Logic for calculating the offset of a point from a line segment. |
package.json | Project metadata, entry point definition, and scripts. |
Sources: package.json:5, src/index.js:1-3, src/perpendicular-distance.js:1
Core Algorithm Implementation
Contributors looking to modify the path reduction logic must understand the interaction between the recursive reducer and the mathematical utility functions.
Douglas-Peucker Flow
The main algorithm finds the point with the maximum perpendicular distance from a line formed by the start and end points of a path. If this distance exceeds the specified epsilon, the path is split and processed recursively.
The algorithm relies on the perpendicularDistance module to determine the significance of each point.
Sources: src/index.js:3-22
Mathematical Utilities
The project implements specific geographic calculations to ensure accuracy on the Earth's surface:
- Great-Circle Distance: Uses the Haversine formula with the Earth's radius set at 6371 kilometers to calculate the distance between two latitude/longitude pairs.
- Perpendicular Distance: Uses Heron's formula to calculate the area of a triangle formed by three points, then derives the height (perpendicular distance) relative to the segment base.
API Specifications
When contributing new features or bug fixes, ensure the public API remains consistent with the following interface:
geoPathReducer Function
| Parameter | Type | Description |
|---|---|---|
points | Array<Object> | List of objects with { lat, lng } properties. |
epsilon | Number | The threshold for simplification (in degrees/relative units). |
// Example of the expected data structure for points
const points = [
{ lat: 37.7749, lng: -122.4194 },
{ lat: 37.7755, lng: -122.4182 }
];
Sources: README.md:20-36, src/index.js:3
Submission Process
- Issue Reporting: Before making significant changes, contributors are encouraged to open an issue to discuss the proposed improvement or report a bug.
- Pull Requests:
- Ensure all code uses ESM
import/exportsyntax. - Maintain the existing naming conventions for coordinate properties (
latandlng). - Verify that any changes to
distance.jsmaintain the Great-Circle distance accuracy.
- Ensure all code uses ESM
Sources: README.md:43-45, src/distance.js:3, src/perpendicular-distance.js:6-8
Summary
Contributors to the Geo Path Reducer should focus on maintaining the mathematical integrity of the Douglas-Peucker implementation while adhering to the ESM architectural pattern. The system is designed to be a lightweight utility for spatial data simplification, relying on recursive path splitting and Haversine-based distance calculations.