Geographic Utilities

/**
 * Geographic coordinate representation (longitude, latitude)
 * @param lng - Longitude in degrees (-180 to 180)
 * @param lat - Latitude in degrees (-90 to 90)
 */
class LngLat {
  lng: number;
  lat: number;
  
  constructor(lng: number, lat: number);
  
  /**
   * Convert from various input formats to LngLat instance
   * @param input - Coordinate input in various formats
   * @returns LngLat instance
   */
  static convert(input: LngLatLike): LngLat;
  
  /**
   * Wrap longitude to [-180, 180] range
   * @returns New LngLat with wrapped longitude
   */
  wrap(): LngLat;
  
  /**
   * Convert to [lng, lat] array
   * @returns Array containing longitude and latitude
   */
  toArray(): [number, number];
  
  /**
   * Convert to string representation
   * @returns String in format "LngLat(lng, lat)"
   */
  toString(): string;
  
  /**
   * Calculate distance to another point using Haversine formula
   * @param lnglat - Target coordinate
   * @returns Distance in meters
   */
  distanceTo(lnglat: LngLat): number;
  
  /**
   * Create bounding box around this point
   * @param radius - Radius in meters
   * @returns LngLatBounds containing the point with given radius
   */
  toBounds(radius: number): LngLatBounds;
}

type LngLatLike = 
  | LngLat 
  | [number, number] 
  | { lng: number; lat: number } 
  | { lon: number; lat: number };

import mapboxgl from 'mapbox-gl';

// Create LngLat instances
const nyc = new mapboxgl.LngLat(-74.006, 40.7128);
const london = new mapboxgl.LngLat(-0.1276, 51.5074);

// Convert from various formats
const fromArray = mapboxgl.LngLat.convert([-74.006, 40.7128]);
const fromObject = mapboxgl.LngLat.convert({ lng: -74.006, lat: 40.7128 });
const fromObjectAlt = mapboxgl.LngLat.convert({ lon: -74.006, lat: 40.7128 });

// Geographic calculations
const distance = nyc.distanceTo(london); // Distance in meters
console.log(`Distance from NYC to London: ${(distance / 1000).toFixed(0)} km`);

// Coordinate wrapping
const wrapped = new mapboxgl.LngLat(181, 40).wrap(); // lng becomes -179
console.log(`Wrapped coordinates: ${wrapped.lng}, ${wrapped.lat}`);

// Create bounds around a point
const nycBounds = nyc.toBounds(1000); // 1km radius
map.fitBounds(nycBounds);

// Array and string conversion
const coords = nyc.toArray(); // [-74.006, 40.7128]
const coordString = nyc.toString(); // "LngLat(-74.006, 40.7128)"

/**
 * Geographic bounding box representation
 * @param sw - Southwest corner coordinate
 * @param ne - Northeast corner coordinate
 */
class LngLatBounds {
  constructor(sw?: LngLatLike, ne?: LngLatLike);
  
  /**
   * Convert from various input formats to LngLatBounds instance
   * @param input - Bounds input in various formats
   * @returns LngLatBounds instance
   */
  static convert(input: LngLatBoundsLike): LngLatBounds;
  
  /**
   * Extend bounds to include a coordinate or another bounds
   * @param obj - Point or bounds to include
   * @returns Extended LngLatBounds instance
   */
  extend(obj: LngLatLike | LngLatBoundsLike): LngLatBounds;
  
  /**
   * Get the center point of the bounds
   * @returns Center coordinate as LngLat
   */
  getCenter(): LngLat;
  
  /**
   * Get the southwest corner
   * @returns Southwest coordinate as LngLat
   */
  getSouthWest(): LngLat;
  
  /**
   * Get the northeast corner
   * @returns Northeast coordinate as LngLat
   */
  getNorthEast(): LngLat;
  
  /**
   * Get the northwest corner
   * @returns Northwest coordinate as LngLat
   */
  getNorthWest(): LngLat;
  
  /**
   * Get the southeast corner
   * @returns Southeast coordinate as LngLat
   */
  getSouthEast(): LngLat;
  
  /**
   * Check if bounds contain a coordinate
   * @param lnglat - Coordinate to test
   * @returns True if coordinate is within bounds
   */
  contains(lnglat: LngLatLike): boolean;
  
  /**
   * Check if bounds are empty (no area)
   * @returns True if bounds are empty
   */
  isEmpty(): boolean;
  
  /**
   * Convert to nested array format
   * @returns [[west, south], [east, north]]
   */
  toArray(): [[number, number], [number, number]];
  
  /**
   * Convert to string representation
   * @returns String representation of bounds
   */
  toString(): string;
}

type LngLatBoundsLike = 
  | LngLatBounds 
  | [LngLatLike, LngLatLike] 
  | [number, number, number, number];

import mapboxgl from 'mapbox-gl';

// Create bounds from corner coordinates
const manhattanBounds = new mapboxgl.LngLatBounds(
  [-74.047, 40.679], // Southwest corner
  [-73.906, 40.877]  // Northeast corner
);

// Create bounds from array
const boundsFromArray = mapboxgl.LngLatBounds.convert([
  [-74.047, 40.679], 
  [-73.906, 40.877]
]);

// Create bounds from flat array [west, south, east, north]
const boundsFromFlat = mapboxgl.LngLatBounds.convert(
  [-74.047, 40.679, -73.906, 40.877]
);

// Build bounds incrementally
const bounds = new mapboxgl.LngLatBounds();
bounds.extend([-74.006, 40.7128]); // NYC
bounds.extend([-73.935, 40.730]);  // Queens
bounds.extend([-73.991, 40.751]);  // Manhattan

// Fit map to bounds
map.fitBounds(bounds, { 
  padding: 50,
  duration: 2000
});

// Bounds operations
const center = bounds.getCenter();
const sw = bounds.getSouthWest();
const ne = bounds.getNorthEast();

console.log(`Bounds center: ${center.lng}, ${center.lat}`);
console.log(`Southwest: ${sw.lng}, ${sw.lat}`);
console.log(`Northeast: ${ne.lng}, ${ne.lat}`);

// Check if point is within bounds
const timesSquare = [-73.985, 40.758];
const containsPoint = bounds.contains(timesSquare);
console.log(`Times Square in bounds: ${containsPoint}`);

// Convert to different formats
const arrayFormat = bounds.toArray(); // [[west, south], [east, north]]
const stringFormat = bounds.toString();

/**
 * Mercator projection coordinate representation
 * @param x - X coordinate in Mercator space (0-1)
 * @param y - Y coordinate in Mercator space (0-1) 
 * @param z - Z coordinate for altitude
 */
class MercatorCoordinate {
  x: number;
  y: number;
  z?: number;
  
  constructor(x: number, y: number, z?: number);
  
  /**
   * Create MercatorCoordinate from geographic coordinates
   * @param lnglat - Geographic coordinates
   * @param altitude - Altitude in meters
   * @returns MercatorCoordinate instance
   */
  static fromLngLat(lnglat: LngLatLike, altitude?: number): MercatorCoordinate;
  
  /**
   * Convert to geographic coordinates
   * @returns Geographic coordinates as LngLat
   */
  toLngLat(): LngLat;
  
  /**
   * Get altitude from z coordinate
   * @returns Altitude in meters
   */
  toAltitude(): number;
  
  /**
   * Calculate distance to another Mercator coordinate
   * @param coord - Target coordinate
   * @returns Distance in Mercator units
   */
  distanceTo(coord: MercatorCoordinate): number;
}

import mapboxgl from 'mapbox-gl';

// Convert geographic to Mercator coordinates
const nyc = new mapboxgl.LngLat(-74.006, 40.7128);
const nycMercator = mapboxgl.MercatorCoordinate.fromLngLat(nyc);

console.log(`NYC Mercator: x=${nycMercator.x}, y=${nycMercator.y}`);

// Convert back to geographic
const nycGeo = nycMercator.toLngLat();
console.log(`NYC Geographic: ${nycGeo.lng}, ${nycGeo.lat}`);

// Work with altitude
const elevatedPoint = mapboxgl.MercatorCoordinate.fromLngLat(nyc, 100); // 100m altitude
const altitude = elevatedPoint.toAltitude();
console.log(`Altitude: ${altitude} meters`);

// Calculate distances in Mercator space
const london = new mapboxgl.LngLat(-0.1276, 51.5074);
const londonMercator = mapboxgl.MercatorCoordinate.fromLngLat(london);
const mercatorDistance = nycMercator.distanceTo(londonMercator);

/**
 * 2D point representation for screen coordinates
 * @param x - X coordinate
 * @param y - Y coordinate
 */
class Point {
  x: number;
  y: number;
  
  constructor(x: number, y: number);
  
  /**
   * Create a copy of this point
   * @returns New Point instance
   */
  clone(): Point;
  
  /**
   * Add another point to this point
   * @param p - Point to add
   * @returns New Point with sum
   */
  add(p: Point): Point;
  
  /**
   * Subtract another point from this point
   * @param p - Point to subtract  
   * @returns New Point with difference
   */
  sub(p: Point): Point;
  
  /**
   * Multiply this point by a scalar
   * @param k - Scalar value
   * @returns New Point scaled by k
   */
  mult(k: number): Point;
  
  /**
   * Divide this point by a scalar
   * @param k - Scalar value
   * @returns New Point divided by k
   */
  div(k: number): Point;
  
  /**
   * Calculate distance to another point
   * @param p - Target point
   * @returns Distance between points
   */
  dist(p: Point): number;
}

type PointLike = Point | [number, number];

import mapboxgl from 'mapbox-gl';

// Create screen points
const screenPoint = new mapboxgl.Point(100, 200);
const mousePos = new mapboxgl.Point(event.clientX, event.clientY);

// Point operations
const offset = screenPoint.add(new mapboxgl.Point(50, -25));
const scaled = screenPoint.mult(2);
const distance = screenPoint.dist(mousePos);

// Convert between screen and geographic coordinates
map.on('click', (e) => {
  const screenPoint = e.point; // Point instance
  const geoCoord = e.lngLat;   // LngLat instance
  
  // Convert geographic to screen
  const projectedPoint = map.project(geoCoord);
  
  // Convert screen to geographic
  const unprojectedCoord = map.unproject(screenPoint);
  
  console.log(`Screen: ${screenPoint.x}, ${screenPoint.y}`);
  console.log(`Geographic: ${geoCoord.lng}, ${geoCoord.lat}`);
});

// Calculate distances between multiple points
function calculateRoute(waypoints: LngLatLike[]): { totalDistance: number; segments: number[] } {
  const points = waypoints.map(wp => mapboxgl.LngLat.convert(wp));
  const segments: number[] = [];
  let totalDistance = 0;
  
  for (let i = 0; i < points.length - 1; i++) {
    const segmentDistance = points[i].distanceTo(points[i + 1]);
    segments.push(segmentDistance);
    totalDistance += segmentDistance;
  }
  
  return { totalDistance, segments };
}

// Usage
const route = calculateRoute([
  [-74.006, 40.7128], // NYC
  [-73.935, 40.730],  // Queens  
  [-73.991, 40.751]   // Manhattan
]);
console.log(`Total route distance: ${(route.totalDistance / 1000).toFixed(2)} km`);

// Create bounds from multiple points
function createBoundsFromPoints(points: LngLatLike[]): LngLatBounds {
  const bounds = new mapboxgl.LngLatBounds();
  points.forEach(point => bounds.extend(point));
  return bounds;
}

// Find bounds intersection
function intersectBounds(bounds1: LngLatBounds, bounds2: LngLatBounds): LngLatBounds | null {
  const sw1 = bounds1.getSouthWest();
  const ne1 = bounds1.getNorthEast();
  const sw2 = bounds2.getSouthWest();
  const ne2 = bounds2.getNorthEast();
  
  const west = Math.max(sw1.lng, sw2.lng);
  const south = Math.max(sw1.lat, sw2.lat);
  const east = Math.min(ne1.lng, ne2.lng);
  const north = Math.min(ne1.lat, ne2.lat);
  
  if (west >= east || south >= north) {
    return null; // No intersection
  }
  
  return new mapboxgl.LngLatBounds([west, south], [east, north]);
}

// Geographic coordinate input types
type LngLatLike = 
  | LngLat 
  | [number, number] 
  | { lng: number; lat: number } 
  | { lon: number; lat: number };

type LngLatBoundsLike = 
  | LngLatBounds 
  | [LngLatLike, LngLatLike] 
  | [number, number, number, number];

// Screen coordinate input types  
type PointLike = Point | [number, number];

// Camera and view options that use geographic types
interface FitBoundsOptions {
  padding?: number | { top: number; bottom: number; left: number; right: number };
  linear?: boolean;
  easing?: (t: number) => number;
  offset?: PointLike;
  maxZoom?: number;
  duration?: number;
}