geo-intersection-util/README.md

Point of intersection defined by its offset from the centerline and distance along the centerline

# geo-intersection-util

A lightweight TypeScript/JavaScript utility for calculating the perpendicular intersection of a point (e.g., a golf shot or geographic location) to a given centerline path. Supports distance and directional analysis (left/right/center) and works in both frontend and backend environments.

---

## ✨ Features

- Compute perpendicular intersection from a geographic point to a path
- Get distance (in meters) and side (left/right/center)
- Accepts centerline in "lng lat" string format
- Pure TypeScript with JS compatibility
- Lightweight, no external dependencies

## Installation

```bash
npm install geo-intersection-util
```

## 🚀 Quick Start

### TypeScript

```ts
import { Intersection } from "geo-intersection-util";

const center =
  "88.426709 22.579435, 88.430032 22.581458, 88.432886 22.582901, 88.437578 22.580801";
const point = "88.433217 22.581856";
const forward = "88.438367 22.580495";

const intersection = new Intersection();
const result = intersection.getInterSection(center, point, forward);

console.log(result);
```

### JavaScript

```js
const { Intersection } = require("geo-intersection-util");

const center =
  "88.426709 22.579435, 88.430032 22.581458, 88.432886 22.582901, 88.437578 22.580801";
const point = "88.433217 22.581856";
const forward = "88.438367 22.580495";

const intersection = new Intersection();
const result = intersection.getInterSection(center, point, forward);

console.log(result);
```

## 🧩 API Reference

getInterSection(centerLine: string, point: string, forwardPoint: string): IntersectionResult | undefined

Returns the intersection point on the centerline, the distance from the given point to the centerline (in meters), and the side relative to the centerline.

### Parameters

- `centerLine` (string): A comma-separated string of "lng lat" pairs representing the path.
- `point` (string): The shot or location point in "lng lat" format.
- `forwardPoint` (string): A "lng lat" point to help orient the centerline.


### Return
```
{
  intersectionLatLng: { lat: number; lng: number };
  distance: number; // in meters
  side: "left" | "right" | "center" | null;
}
```

### 📐 Units
- Distance is returned in meters.
- You can convert it to yards: ```yards = meters * 1.09361```


## 🧪 Example Use Case
# Perfect for:
- Golf shot dispersion analysis
- Road/path mapping
- Navigation systems
- GIS-based tools


## 📝 License

MIT © 2025 Mayank Anand

## 📬 Author & Support

**Mayank Anand**  
Email: [mayank.anand59@gmail.com](mailto:mayank.anand59@gmail.com)

### Contributing
💡 Have suggestions? I'm always open to feedback! Feel free to write to me or submit a request to improve accuracy or add new features.