Coordinate Systems & Projections

/**
 * Projection definition for coordinate reference systems
 * @param options - Projection configuration
 */
class Projection {
  constructor(options: ProjectionOptions);
  
  /** Get the projection code (e.g., 'EPSG:4326') */
  getCode(): string;
  /** Get the projection extent */
  getExtent(): Extent | null;
  /** Get the axis orientation */
  getAxisOrientation(): string;
  /** Get the units */
  getUnits(): Units;
  /** Get the meters per unit conversion factor */
  getMetersPerUnit(): number;
  /** Get the world extent */
  getWorldExtent(): Extent | null;
  /** Check if coordinates wrap around (e.g., longitude) */
  isGlobal(): boolean;
  /** Set the world extent */
  setWorldExtent(worldExtent: Extent): void;
  /** Set the extent */
  setExtent(extent: Extent): void;
  /** Set if the projection is global */
  setGlobal(global: boolean): void;
  /** Get point resolution at coordinate */
  getPointResolution(resolution: number, coordinate: Coordinate): number;
}

interface ProjectionOptions {
  /** Projection code (e.g., 'EPSG:4326') */
  code: string;
  /** Units of the projection */
  units?: Units;
  /** Projection extent */
  extent?: Extent;
  /** Axis orientation */
  axisOrientation?: string;
  /** Whether the projection is global */
  global?: boolean;
  /** Meters per unit conversion factor */
  metersPerUnit?: number;
  /** World extent */
  worldExtent?: Extent;
  /** Function to get point resolution */
  getPointResolution?: (resolution: number, coordinate: Coordinate) => number;
}

/** Transform coordinates between projections */
function transform(coordinate: Coordinate, source: ProjectionLike, destination: ProjectionLike): Coordinate;

/** Transform extent between projections */
function transformExtent(extent: Extent, source: ProjectionLike, destination: ProjectionLike): Extent;

/** Transform from WGS84 longitude/latitude to target projection */
function fromLonLat(coordinate: Coordinate, projection?: ProjectionLike): Coordinate;

/** Transform from target projection to WGS84 longitude/latitude */
function toLonLat(coordinate: Coordinate, projection?: ProjectionLike): Coordinate;

/** Get transformation function between projections */
function getTransform(source: ProjectionLike, destination: ProjectionLike): TransformFunction;

/** Get projection by code or object */
function get(projectionLike: ProjectionLike): Projection | null;

/** Add projection definition to registry */
function addProjection(projection: Projection): void;

/** Add coordinate transformation functions */
function addCoordinateTransforms(source: ProjectionLike, destination: ProjectionLike, forward: TransformFunction, inverse: TransformFunction): void;

/** Check if projections are equivalent */
function equivalent(projection1: ProjectionLike, projection2: ProjectionLike): boolean;

/** Create projection from EPSG code */
function fromEPSGCode(code: string): Promise<Projection>;

/** Use WGS84 geographic coordinates as default */
function useGeographic(): void;

/** Set user projection for simplified coordinate handling */
function setUserProjection(projection: ProjectionLike): void;

/** Get current user projection */
function getUserProjection(): Projection | null;

/** Transform from user coordinate system */
function fromUserCoordinate(coordinate: Coordinate): Coordinate;

/** Transform to user coordinate system */
function toUserCoordinate(coordinate: Coordinate): Coordinate;

/** Transform extent from user coordinate system */
function fromUserExtent(extent: Extent): Extent;

/** Transform extent to user coordinate system */
function toUserExtent(extent: Extent): Extent;

/** Get point resolution for projection */
function getPointResolution(projection: ProjectionLike, resolution: number, coordinate: Coordinate): number;

import { transform, fromLonLat, toLonLat, get, addProjection } from 'ol/proj';
import Projection from 'ol/proj/Projection';

// Transform coordinates between projections
const lonLatCoord = [-74.006, 40.7128]; // New York
const webMercatorCoord = fromLonLat(lonLatCoord);

// Transform back to longitude/latitude
const backToLonLat = toLonLat(webMercatorCoord);

// Direct transformation between projections
const utmCoord = transform(lonLatCoord, 'EPSG:4326', 'EPSG:32633');

// Get projection information
const wgs84 = get('EPSG:4326');
const webMercator = get('EPSG:3857');

// Add custom projection
const customProj = new Projection({
  code: 'CUSTOM:1000',
  units: 'degrees',
  extent: [-180, -90, 180, 90],
  global: true
});
addProjection(customProj);

/** Projection units enumeration */
enum Units {
  DEGREES = 'degrees',
  FEET = 'ft', 
  METERS = 'm',
  PIXELS = 'pixels',
  TILE_PIXELS = 'tile-pixels',
  USFEET = 'us-ft'
}

/** Conversion factors to meters */
const METERS_PER_UNIT: Record<Units, number>;

/** Get units from code string */
function fromCode(code: string): Units;

/** Add delta to coordinate */
function add(coordinate: Coordinate, delta: Coordinate): Coordinate;

/** Calculate distance between coordinates */
function distance(coord1: Coordinate, coord2: Coordinate): number;

/** Calculate squared distance between coordinates */
function squaredDistance(coord1: Coordinate, coord2: Coordinate): number;

/** Test coordinate equality */
function equals(coord1: Coordinate, coord2: Coordinate): boolean;

/** Format coordinate using formatter function */
function format(coordinate: Coordinate, template: string, fractionDigits?: number): string;

/** Rotate coordinate around origin */
function rotate(coordinate: Coordinate, angle: number): Coordinate;

/** Scale coordinate by factor */
function scale(coordinate: Coordinate, scale: number): Coordinate;

/** Create coordinate string formatter */
function createStringXY(fractionDigits?: number): CoordinateFormat;

/** Convert degrees to HDMS (Hours, Degrees, Minutes, Seconds) string */
function degreesToStringHDMS(degrees: number): string;

/** Format coordinate as HDMS string */
function toStringHDMS(coordinate?: Coordinate): string;

/** Format coordinate as XY string */
function toStringXY(coordinate?: Coordinate, fractionDigits?: number): string;

/** Find closest point on circle */
function closestOnCircle(coordinate: Coordinate, circle: Circle): Coordinate;

/** Find closest point on line segment */
function closestOnSegment(coordinate: Coordinate, segment: Coordinate[]): Coordinate;

/** Wrap X coordinate for global projections */
function wrapX(coordinate: Coordinate, projection: Projection): Coordinate;

import { 
  add, distance, format, rotate, 
  createStringXY, toStringHDMS 
} from 'ol/coordinate';

// Basic coordinate operations
const coord1 = [100, 200];
const coord2 = [150, 250];

// Add offset to coordinate
const offset = add(coord1, [10, 15]); // [110, 215]

// Calculate distance
const dist = distance(coord1, coord2); // ~70.7

// Rotate coordinate around origin
const rotated = rotate(coord1, Math.PI / 4); // 45 degree rotation

// Format coordinates
const formatter = createStringXY(2);
const formatted = formatter(coord1); // "100.00, 200.00"

// Format as degrees, minutes, seconds
const lonLat = [-74.006, 40.7128];
const hdms = toStringHDMS(lonLat); // "74° 00′ 22″ W 40° 42′ 46″ N"

/** Web Mercator / Google Mercator (EPSG:3857) */
const EPSG3857: Projection;

/** WGS84 Geographic (EPSG:4326) */  
const EPSG4326: Projection;

/** Common projection codes */
const ProjectionCodes = {
  EPSG3857: 'EPSG:3857',
  EPSG4326: 'EPSG:4326',
  EPSG900913: 'EPSG:900913', // Legacy Google
} as const;

type Coordinate = [number, number] | [number, number, number] | [number, number, number, number];
type ProjectionLike = Projection | string | undefined;
type TransformFunction = (coordinates: Coordinate[], coordinates2?: Coordinate[], stride?: number) => Coordinate[];
type CoordinateFormat = (coordinate?: Coordinate) => string;