0
# Coordinate Reference Systems
1
2
Coordinate Reference Systems (CRS) are fundamental to spatial data operations, defining how coordinates relate to real-world locations. PyProj provides comprehensive CRS management with support for multiple input formats and extensive metadata access.
3
4
## Capabilities
5
6
### CRS Creation
7
8
Create CRS objects from various input formats including EPSG codes, PROJ strings, WKT, and authority definitions.
9
10
```python { .api }
11
class CRS:
12
def __init__(self, projparams: Any | None = None, **kwargs) -> None:
13
"""
14
Create a CRS object from various input types.
15
16
Args:
17
projparams: CRS definition (PROJ string, WKT, EPSG code, etc.)
18
**kwargs: Additional parameters for CRS creation
19
"""
20
21
@classmethod
22
def from_epsg(cls, code: str | int) -> "CRS":
23
"""
24
Create CRS from EPSG code.
25
26
Args:
27
code: EPSG code as string or integer
28
29
Returns:
30
CRS object for the specified EPSG code
31
32
Raises:
33
CRSError: If EPSG code is invalid or not found
34
"""
35
36
@classmethod
37
def from_authority(cls, auth_name: str, code: str | int) -> "CRS":
38
"""
39
Create CRS from authority name and code.
40
41
Args:
42
auth_name: Authority name (e.g., 'EPSG', 'ESRI', 'IAU_2015')
43
code: Authority code as string or integer
44
45
Returns:
46
CRS object from the specified authority and code
47
48
Raises:
49
CRSError: If authority or code is invalid
50
"""
51
52
@classmethod
53
def from_wkt(cls, in_wkt_string: str) -> "CRS":
54
"""
55
Create CRS from Well-Known Text string.
56
57
Args:
58
in_wkt_string: WKT string defining the CRS
59
60
Returns:
61
CRS object from WKT definition
62
63
Raises:
64
CRSError: If WKT string is malformed or invalid
65
"""
66
67
@classmethod
68
def from_proj4(cls, in_proj_string: str) -> "CRS":
69
"""
70
Create CRS from PROJ.4 string.
71
72
Args:
73
in_proj_string: PROJ.4 definition string
74
75
Returns:
76
CRS object from PROJ.4 definition
77
78
Raises:
79
CRSError: If PROJ string is invalid
80
"""
81
82
@classmethod
83
def from_string(cls, in_crs_string: str) -> "CRS":
84
"""
85
Create CRS from string representation (auto-detects format).
86
87
Args:
88
in_crs_string: CRS string in any supported format
89
90
Returns:
91
CRS object parsed from string
92
93
Raises:
94
CRSError: If string format cannot be determined or is invalid
95
"""
96
97
@classmethod
98
def from_user_input(cls, value: Any, **kwargs) -> "CRS":
99
"""
100
Create CRS from user input (most flexible input method).
101
102
Args:
103
value: CRS definition in any supported format or existing CRS object
104
**kwargs: Additional parameters
105
106
Returns:
107
CRS object from user input
108
109
Raises:
110
CRSError: If input cannot be converted to CRS
111
"""
112
113
@classmethod
114
def from_dict(cls, proj_dict: dict) -> "CRS":
115
"""
116
Create CRS from PROJ parameter dictionary.
117
118
Args:
119
proj_dict: Dictionary of PROJ parameters
120
121
Returns:
122
CRS object from parameter dictionary
123
124
Raises:
125
CRSError: If dictionary contains invalid parameters
126
"""
127
128
@classmethod
129
def from_json(cls, crs_json: str) -> "CRS":
130
"""
131
Create CRS from JSON string.
132
133
Args:
134
crs_json: JSON string representation of CRS
135
136
Returns:
137
CRS object from JSON definition
138
139
Raises:
140
CRSError: If JSON is malformed or invalid
141
"""
142
143
@classmethod
144
def from_json_dict(cls, crs_dict: dict) -> "CRS":
145
"""
146
Create CRS from JSON dictionary.
147
148
Args:
149
crs_dict: Dictionary containing JSON-style CRS definition
150
151
Returns:
152
CRS object from JSON dictionary
153
154
Raises:
155
CRSError: If dictionary structure is invalid
156
"""
157
158
@classmethod
159
def from_cf(cls, in_cf: dict, **kwargs) -> "CRS":
160
"""
161
Create CRS from Climate and Forecast (CF) conventions dictionary.
162
163
Args:
164
in_cf: CF conventions dictionary
165
**kwargs: Additional CF parameters
166
167
Returns:
168
CRS object from CF conventions
169
170
Raises:
171
CRSError: If CF dictionary is invalid or unsupported
172
"""
173
```
174
175
### CRS Conversion and Export
176
177
Convert CRS objects to various output formats for interoperability with other systems.
178
179
```python { .api }
180
class CRS:
181
def to_string(self) -> str:
182
"""
183
Convert CRS to string representation.
184
185
Returns:
186
String representation of CRS (typically PROJ format)
187
"""
188
189
def to_dict(self) -> dict:
190
"""
191
Convert CRS to PROJ parameter dictionary.
192
193
Returns:
194
Dictionary of PROJ parameters
195
"""
196
197
def to_wkt(self, version: WktVersion = WktVersion.WKT2_2019, pretty: bool = False) -> str:
198
"""
199
Convert CRS to Well-Known Text format.
200
201
Args:
202
version: WKT version to use for output
203
pretty: Whether to format with indentation
204
205
Returns:
206
WKT string representation of CRS
207
"""
208
209
def to_proj4(self, version: ProjVersion = ProjVersion.PROJ_5) -> str:
210
"""
211
Convert CRS to PROJ.4 string format.
212
213
Args:
214
version: PROJ version for compatibility
215
216
Returns:
217
PROJ.4 string representation of CRS
218
"""
219
220
def to_json(self, pretty: bool = False, indentation: int = 2) -> str:
221
"""
222
Convert CRS to JSON string format.
223
224
Args:
225
pretty: Whether to format with indentation
226
indentation: Number of spaces for indentation
227
228
Returns:
229
JSON string representation of CRS
230
"""
231
232
def to_json_dict(self) -> dict:
233
"""
234
Convert CRS to JSON dictionary format.
235
236
Returns:
237
Dictionary containing JSON representation of CRS
238
"""
239
240
def to_cf(self, **kwargs) -> dict:
241
"""
242
Convert CRS to Climate and Forecast conventions dictionary.
243
244
Args:
245
**kwargs: CF conversion parameters
246
247
Returns:
248
Dictionary following CF conventions
249
250
Raises:
251
CRSError: If CRS cannot be represented in CF format
252
"""
253
254
def cs_to_cf(self) -> list[dict]:
255
"""
256
Convert coordinate system to CF conventions format.
257
258
Returns:
259
List of dictionaries representing coordinate system in CF format
260
"""
261
```
262
263
### CRS Comparison and Analysis
264
265
Compare CRS objects and analyze their properties and relationships.
266
267
```python { .api }
268
class CRS:
269
def equals(self, other: Any, ignore_axis_order: bool = False) -> bool:
270
"""
271
Check if two CRS objects are equivalent.
272
273
Args:
274
other: Another CRS object or CRS-compatible input
275
ignore_axis_order: Whether to ignore axis order differences
276
277
Returns:
278
True if CRS objects are equivalent, False otherwise
279
"""
280
281
def is_exact_same(self, other: Any) -> bool:
282
"""
283
Check if two CRS objects are exactly the same.
284
285
Args:
286
other: Another CRS object
287
288
Returns:
289
True if CRS objects are identical, False otherwise
290
"""
291
292
def is_geographic(self) -> bool:
293
"""
294
Check if CRS is geographic (latitude/longitude).
295
296
Returns:
297
True if CRS is geographic, False otherwise
298
"""
299
300
def is_projected(self) -> bool:
301
"""
302
Check if CRS is projected (uses map projection).
303
304
Returns:
305
True if CRS is projected, False otherwise
306
"""
307
308
def is_vertical(self) -> bool:
309
"""
310
Check if CRS is vertical (height/depth).
311
312
Returns:
313
True if CRS is vertical, False otherwise
314
"""
315
316
def is_compound(self) -> bool:
317
"""
318
Check if CRS is compound (combines horizontal and vertical).
319
320
Returns:
321
True if CRS is compound, False otherwise
322
"""
323
324
def is_geocentric(self) -> bool:
325
"""
326
Check if CRS is geocentric (3D Cartesian).
327
328
Returns:
329
True if CRS is geocentric, False otherwise
330
"""
331
332
def is_bound(self) -> bool:
333
"""
334
Check if CRS is bound to another CRS.
335
336
Returns:
337
True if CRS is bound, False otherwise
338
"""
339
```
340
341
### CRS Properties and Metadata
342
343
Access detailed information about CRS properties, components, and associated objects.
344
345
```python { .api }
346
class CRS:
347
@property
348
def name(self) -> str | None:
349
"""Get the name of the CRS."""
350
351
@property
352
def type_name(self) -> str:
353
"""Get the type name of the CRS."""
354
355
@property
356
def coordinate_system(self) -> CoordinateSystem:
357
"""Get the coordinate system of the CRS."""
358
359
@property
360
def coordinate_operation(self) -> CoordinateOperation | None:
361
"""Get the coordinate operation for derived CRS."""
362
363
@property
364
def datum(self) -> Datum | None:
365
"""Get the datum of the CRS."""
366
367
@property
368
def ellipsoid(self) -> Ellipsoid | None:
369
"""Get the ellipsoid of the CRS."""
370
371
@property
372
def prime_meridian(self) -> PrimeMeridian | None:
373
"""Get the prime meridian of the CRS."""
374
375
@property
376
def area_of_use(self) -> AreaOfUse | None:
377
"""Get the area of use for the CRS."""
378
379
@property
380
def remarks(self) -> str | None:
381
"""Get remarks about the CRS."""
382
383
@property
384
def scope(self) -> str | None:
385
"""Get the scope of the CRS."""
386
387
@property
388
def axis_info(self) -> list[Axis]:
389
"""Get information about CRS axes."""
390
391
@property
392
def geodetic_crs(self) -> "CRS" | None:
393
"""Get the geodetic CRS (for projected CRS)."""
394
395
@property
396
def source_crs(self) -> "CRS" | None:
397
"""Get the source CRS (for bound CRS)."""
398
399
@property
400
def target_crs(self) -> "CRS" | None:
401
"""Get the target CRS (for bound CRS)."""
402
403
def get_geod(self) -> Geod | None:
404
"""
405
Get associated Geod object for geodesic calculations.
406
407
Returns:
408
Geod object if CRS has associated ellipsoid, None otherwise
409
"""
410
411
def to_epsg(self, min_confidence: int = 70) -> int | None:
412
"""
413
Get EPSG code for CRS if available.
414
415
Args:
416
min_confidence: Minimum confidence level for authority match
417
418
Returns:
419
EPSG code as integer, or None if not found
420
"""
421
422
def to_authority(self, auth_name: str | None = None, min_confidence: int = 70) -> tuple[str, str] | None:
423
"""
424
Get authority name and code for CRS.
425
426
Args:
427
auth_name: Specific authority to search (None for any)
428
min_confidence: Minimum confidence level for match
429
430
Returns:
431
Tuple of (authority_name, code) or None if not found
432
"""
433
434
def list_authority(self, auth_name: str | None = None, min_confidence: int = 70) -> list[AuthorityMatchInfo]:
435
"""
436
List all matching authorities for the CRS.
437
438
Args:
439
auth_name: Authority name to filter by
440
min_confidence: Minimum confidence level for matches
441
442
Returns:
443
List of AuthorityMatchInfo objects with match details
444
"""
445
446
def utm_zone(self) -> str | None:
447
"""
448
Get UTM zone identifier for UTM CRS.
449
450
Returns:
451
UTM zone string (e.g., '33N') or None if not UTM
452
"""
453
454
def sub_crs_list(self) -> list["CRS"]:
455
"""
456
Get list of sub-CRS for compound CRS.
457
458
Returns:
459
List of CRS objects comprising this compound CRS
460
"""
461
462
def to_2d(self, name: str | None = None) -> "CRS":
463
"""
464
Convert CRS to 2D version.
465
466
Args:
467
name: Optional name for the new CRS
468
469
Returns:
470
2D version of the CRS
471
"""
472
473
def to_3d(self, name: str | None = None) -> "CRS":
474
"""
475
Convert CRS to 3D version.
476
477
Args:
478
name: Optional name for the new CRS
479
480
Returns:
481
3D version of the CRS
482
"""
483
484
def is_engineering(self) -> bool:
485
"""
486
Check if CRS is engineering.
487
488
Returns:
489
True if CRS is engineering, False otherwise
490
"""
491
492
def is_derived(self) -> bool:
493
"""
494
Check if CRS is derived from another CRS.
495
496
Returns:
497
True if CRS is derived, False otherwise
498
"""
499
500
def is_deprecated(self) -> bool:
501
"""
502
Check if CRS is deprecated.
503
504
Returns:
505
True if CRS is deprecated, False otherwise
506
"""
507
508
def get_non_deprecated(self) -> list["CRS"]:
509
"""
510
Get list of non-deprecated CRS alternatives.
511
512
Returns:
513
List of non-deprecated CRS alternatives
514
"""
515
```
516
517
### CRS Specialized Subclasses
518
519
Specialized CRS classes for specific coordinate system types with additional functionality.
520
521
```python { .api }
522
class GeographicCRS(CRS):
523
"""Geographic coordinate reference system (latitude/longitude)."""
524
525
class ProjectedCRS(CRS):
526
"""Projected coordinate reference system (uses map projection)."""
527
528
class VerticalCRS(CRS):
529
"""Vertical coordinate reference system (height/depth)."""
530
531
class CompoundCRS(CRS):
532
"""Compound coordinate reference system (horizontal + vertical)."""
533
534
class BoundCRS(CRS):
535
"""Bound coordinate reference system (linked to another CRS)."""
536
537
class GeocentricCRS(CRS):
538
"""Geocentric coordinate reference system (3D Cartesian)."""
539
540
class DerivedGeographicCRS(CRS):
541
"""Geographic CRS derived from another geographic CRS."""
542
```
543
544
## Usage Examples
545
546
### Creating CRS from Different Sources
547
548
```python
549
from pyproj import CRS
550
551
# From EPSG code
552
wgs84 = CRS.from_epsg(4326)
553
utm_33n = CRS.from_epsg(32633)
554
555
# From PROJ string
556
mercator = CRS.from_proj4('+proj=merc +datum=WGS84 +no_defs')
557
558
# From WKT
559
wkt_string = '''GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563]],PRIMEM["Greenwich",0],UNIT["degree",0.0174532925199433]]'''
560
geographic = CRS.from_wkt(wkt_string)
561
562
# Auto-detect format
563
auto_crs = CRS.from_string('EPSG:4326')
564
```
565
566
### CRS Analysis and Comparison
567
568
```python
569
from pyproj import CRS
570
571
crs1 = CRS.from_epsg(4326) # WGS84
572
crs2 = CRS.from_epsg(4269) # NAD83
573
574
# Check CRS properties
575
print(f"Is geographic: {crs1.is_geographic()}")
576
print(f"Is projected: {crs1.is_projected()}")
577
print(f"Name: {crs1.name}")
578
print(f"Area of use: {crs1.area_of_use}")
579
580
# Compare CRS objects
581
print(f"Are equal: {crs1.equals(crs2)}")
582
print(f"Are identical: {crs1.is_exact_same(crs2)}")
583
584
# Get associated geodesic object
585
geod = crs1.get_geod()
586
if geod:
587
print(f"Ellipsoid: {crs1.ellipsoid.name}")
588
```
589
590
### CRS Format Conversion
591
592
```python
593
from pyproj import CRS, WktVersion
594
595
crs = CRS.from_epsg(4326)
596
597
# Convert to different formats
598
proj4_str = crs.to_proj4()
599
wkt_str = crs.to_wkt(version=WktVersion.WKT2_2019, pretty=True)
600
json_str = crs.to_json(pretty=True)
601
param_dict = crs.to_dict()
602
603
print(f"PROJ.4: {proj4_str}")
604
print(f"WKT: {wkt_str}")
605
print(f"Parameters: {param_dict}")
606
```
607
608
## Types
609
610
```python { .api }
611
# Component classes
612
class CoordinateSystem:
613
"""Coordinate system component of CRS."""
614
name: str
615
axis_list: list[Axis]
616
617
class Datum:
618
"""Datum component of CRS."""
619
name: str
620
type_name: str
621
622
class Ellipsoid:
623
"""Ellipsoid component of CRS."""
624
name: str
625
semi_major_metre: float
626
semi_minor_metre: float
627
inverse_flattening: float
628
629
class PrimeMeridian:
630
"""Prime meridian component of CRS."""
631
name: str
632
longitude: float
633
unit_name: str
634
635
class CoordinateOperation:
636
"""Coordinate operation for derived CRS."""
637
name: str
638
method_name: str
639
params: list[dict]
640
641
class Axis:
642
"""Coordinate system axis information."""
643
name: str
644
abbrev: str
645
direction: str
646
unit_name: str
647
648
class AuthorityMatchInfo:
649
"""Information about CRS authority matches."""
650
auth_name: str
651
code: str
652
confidence: int
653
```