dphelper/docs/markdown/coords.md

dphelper devtools for developers

# coords

Coordinate and geometry utilities for GPS, mapping, and calculations.

## Functions

| Function | Description | Example |
|----------|-------------|---------|
| `degreesToRadians` | Convert degrees to radians | `dphelper.coords.degreesToRadians(45)` |
| `latToMeters` | Convert latitude to meters | `dphelper.coords.latToMeters([40.68, -74.04])` |
| `toVector` | Convert coordinates to 3D vector | `dphelper.coords.toVector([lat, lon, alt])` |
| `convertToDecDegrees` | Convert DMS to decimal degrees | `dphelper.coords.convertToDecDegrees(39, 5, 59, 'N')` |
| `distance` | Calculate distance between two points (Haversine) | `dphelper.coords.distance([lat1, lon1], [lat2, lon2])` |
| `polarToCartesian` | Convert polar to Cartesian coordinates | `dphelper.coords.polarToCartesian(x, y, radius, angle)` |
| `mapDegreesToPixels` | Map degrees to pixel values | `dphelper.coords.mapDegreesToPixels(deg, min, max, minPx, maxPx, pad)` |

## Description

Coordinate manipulation toolkit:
- **Unit Conversion** - Degrees, radians, meters
- **Distance Calculation** - Haversine formula for GPS
- **Coordinate Systems** - Polar, Cartesian, 3D vectors
- **Mapping** - Degrees to pixels for maps

## Usage Examples

### Degree/Radian Conversion

```javascript
// Degrees to radians
console.log(dphelper.coords.degreesToRadians(0));    // 0
console.log(dphelper.coords.degreesToRadians(90));   // 1.57...
console.log(dphelper.coords.degreesToRadians(180));  // 3.14...
console.log(dphelper.coords.degreesToRadians(360));  // 6.28...
```

### Distance Calculation (GPS)

```javascript
// Distance between New York and Washington DC
const nyc = [40.7128, -74.0060];
const dc = [38.9072, -77.0369];

const dist = dphelper.coords.distance(nyc, dc);
console.log(dist);
// { km: 328.54, mi: 204.18, nMi: 177.4 }

// Calculate travel distance for logistics
const locations = [
  [40.7128, -74.0060],  // NYC
  [39.9526, -75.1652],  // Philadelphia
  [39.2894, -76.6152],  // Baltimore
  [38.9072, -77.0369]   // Washington DC
];

function calculateTotalDistance(points) {
  let total = 0;
  for (let i = 0; i < points.length - 1; i++) {
    const dist = dphelper.coords.distance(points[i], points[i + 1]);
    total += dist.km;
  }
  return total;
}
```

### Coordinate Conversion

```javascript
// Convert DMS to decimal degrees
// 39° 5' 59" N -> decimal
const dec = dphelper.coords.convertToDecDegrees(39, 5, 59, 'N');
console.log(dec); // 39.0997...

// With South/West (negative)
const south = dphelper.coords.convertToDecDegrees(33, 51, 30, 'S');
console.log(south); // -33.8583...
```

### 3D Vector from GPS

```javascript
// Convert GPS coordinates to 3D Earth-centered vector
const vector = dphelper.coords.toVector([40.7128, -74.0060, 0]);
console.log(vector);
// [x, y, z] in meters from Earth center
```

### Polar to Cartesian

```javascript
// Convert polar to Cartesian for graphics
const cart = dphelper.coords.polarToCartesian(100, 100, 50, 90);
console.log(cart);
// { x: 100, y: 150 }

// Create circular motion
for (let angle = 0; angle < 360; angle += 30) {
  const pos = dphelper.coords.polarToCartesian(200, 200, 80, angle);
  console.log(`Angle ${angle}:`, pos);
}
```

### Map Pixel Mapping

```javascript
// Map latitude to pixel for interactive maps
const pixel = dphelper.coords.mapDegreesToPixels(
  45,     // Current degree
  30,     // Min latitude
  60,      // Max latitude
  0,       // Min pixel
  500,     // Max pixel
  10       // Padding
);
```

## Details

- **Author:** Dario Passariello
- **Version:** 0.0.2
- **Creation Date:** 20210101
- **Last Modified:** 20260220
- **Environment:** Client-side only (browser)

---

*Automatically generated document*