0
# Coordinate Systems & Projections
1

2
Comprehensive coordinate transformation and projection system supporting multiple coordinate reference systems with built-in transformations between common projections.
3

4
## Capabilities
5

6
### Projection Class
7

8
Core projection definition class for defining coordinate reference systems.
9

10
```typescript { .api }
11
/**
12
 * Projection definition for coordinate reference systems
13
 * @param options - Projection configuration
14
 */
15
class Projection {
16
  constructor(options: ProjectionOptions);
17
  
18
  /** Get the projection code (e.g., 'EPSG:4326') */
19
  getCode(): string;
20
  /** Get the projection extent */
21
  getExtent(): Extent | null;
22
  /** Get the axis orientation */
23
  getAxisOrientation(): string;
24
  /** Get the units */
25
  getUnits(): Units;
26
  /** Get the meters per unit conversion factor */
27
  getMetersPerUnit(): number;
28
  /** Get the world extent */
29
  getWorldExtent(): Extent | null;
30
  /** Check if coordinates wrap around (e.g., longitude) */
31
  isGlobal(): boolean;
32
  /** Set the world extent */
33
  setWorldExtent(worldExtent: Extent): void;
34
  /** Set the extent */
35
  setExtent(extent: Extent): void;
36
  /** Set if the projection is global */
37
  setGlobal(global: boolean): void;
38
  /** Get point resolution at coordinate */
39
  getPointResolution(resolution: number, coordinate: Coordinate): number;
40
}
41

42
interface ProjectionOptions {
43
  /** Projection code (e.g., 'EPSG:4326') */
44
  code: string;
45
  /** Units of the projection */
46
  units?: Units;
47
  /** Projection extent */
48
  extent?: Extent;
49
  /** Axis orientation */
50
  axisOrientation?: string;
51
  /** Whether the projection is global */
52
  global?: boolean;
53
  /** Meters per unit conversion factor */
54
  metersPerUnit?: number;
55
  /** World extent */
56
  worldExtent?: Extent;
57
  /** Function to get point resolution */
58
  getPointResolution?: (resolution: number, coordinate: Coordinate) => number;
59
}
60
```
61

62
### Coordinate Transformation Functions
63

64
Core functions for transforming coordinates between different projection systems.
65

66
```typescript { .api }
67
/** Transform coordinates between projections */
68
function transform(coordinate: Coordinate, source: ProjectionLike, destination: ProjectionLike): Coordinate;
69

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

118
/** Get point resolution for projection */
119
function getPointResolution(projection: ProjectionLike, resolution: number, coordinate: Coordinate): number;
120
```
121

122
**Usage Examples:**
123

124
```typescript
125
import { transform, fromLonLat, toLonLat, get, addProjection } from 'ol/proj';
126
import Projection from 'ol/proj/Projection';
127

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

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

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

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

142
// Add custom projection
143
const customProj = new Projection({
144
  code: 'CUSTOM:1000',
145
  units: 'degrees',
146
  extent: [-180, -90, 180, 90],
147
  global: true
148
});
149
addProjection(customProj);
150
```
151

152
### Projection Units
153

154
Unit definitions and conversion factors for different measurement systems.
155

156
```typescript { .api }
157
/** Projection units enumeration */
158
enum Units {
159
  DEGREES = 'degrees',
160
  FEET = 'ft', 
161
  METERS = 'm',
162
  PIXELS = 'pixels',
163
  TILE_PIXELS = 'tile-pixels',
164
  USFEET = 'us-ft'
165
}
166

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

170
/** Get units from code string */
171
function fromCode(code: string): Units;
172
```
173

174
### Coordinate Utilities
175

176
Helper functions for working with coordinates.
177

178
```typescript { .api }
179
/** Add delta to coordinate */
180
function add(coordinate: Coordinate, delta: Coordinate): Coordinate;
181

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

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

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

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

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

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

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

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

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

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

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

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

218
/** Wrap X coordinate for global projections */
219
function wrapX(coordinate: Coordinate, projection: Projection): Coordinate;
220
```
221

222
**Usage Examples:**
223

224
```typescript
225
import { 
226
  add, distance, format, rotate, 
227
  createStringXY, toStringHDMS 
228
} from 'ol/coordinate';
229

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

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

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

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

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

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

252
### Common Projections
253

254
Pre-defined common coordinate reference systems.
255

256
```typescript { .api }
257
/** Web Mercator / Google Mercator (EPSG:3857) */
258
const EPSG3857: Projection;
259

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

263
/** Common projection codes */
264
const ProjectionCodes = {
265
  EPSG3857: 'EPSG:3857',
266
  EPSG4326: 'EPSG:4326',
267
  EPSG900913: 'EPSG:900913', // Legacy Google
268
} as const;
269
```
270

271
## Types
272

273
```typescript { .api }
274
type Coordinate = [number, number] | [number, number, number] | [number, number, number, number];
275
type ProjectionLike = Projection | string | undefined;
276
type TransformFunction = (coordinates: Coordinate[], coordinates2?: Coordinate[], stride?: number) => Coordinate[];
277
type CoordinateFormat = (coordinate?: Coordinate) => string;
278
```