0
# Coordinate Reference Systems
1
2
Comprehensive coordinate reference system support including EPSG codes, PROJ4 strings, WKT definitions, and CRS transformations. The CRS class provides a unified interface for working with different coordinate systems.
3
4
## Capabilities
5
6
### CRS Class
7
8
Central class for coordinate reference system representation and manipulation.
9
10
```python { .api }
11
class CRS:
12
"""Coordinate Reference System representation."""
13
14
def __init__(self, initialdata=None, **kwargs):
15
"""
16
Initialize CRS from various inputs.
17
18
Parameters:
19
- initialdata (str, int, dict, CRS): EPSG code, PROJ4 string, WKT, or CRS dict
20
- **kwargs: Additional CRS parameters
21
"""
22
23
# Properties
24
wkt: str # Well-Known Text representation
25
data: dict # CRS parameters as dictionary
26
to_proj4_dict: dict # PROJ4 parameters as dictionary
27
is_geographic: bool # True if geographic coordinate system
28
is_projected: bool # True if projected coordinate system
29
is_valid: bool # True if CRS is valid
30
linear_units: str # Linear units (e.g., 'metre')
31
linear_units_factor: tuple[str, float] # Units name and conversion factor
32
axis_info: list # Axis information
33
34
@classmethod
35
def from_epsg(cls, code):
36
"""
37
Create CRS from EPSG code.
38
39
Parameters:
40
- code (int): EPSG coordinate system code
41
42
Returns:
43
CRS: Coordinate reference system
44
"""
45
46
@classmethod
47
def from_proj4(cls, proj4):
48
"""
49
Create CRS from PROJ4 string.
50
51
Parameters:
52
- proj4 (str): PROJ4 coordinate system definition
53
54
Returns:
55
CRS: Coordinate reference system
56
"""
57
58
@classmethod
59
def from_wkt(cls, wkt):
60
"""
61
Create CRS from Well-Known Text.
62
63
Parameters:
64
- wkt (str): WKT coordinate system definition
65
66
Returns:
67
CRS: Coordinate reference system
68
"""
69
70
@classmethod
71
def from_user_input(cls, value):
72
"""
73
Create CRS from various user input formats.
74
75
Parameters:
76
- value (str, int, dict, CRS): Various CRS representations
77
78
Returns:
79
CRS: Coordinate reference system
80
"""
81
82
@classmethod
83
def from_string(cls, string):
84
"""
85
Create CRS from string representation.
86
87
Parameters:
88
- string (str): CRS string (PROJ4, WKT, or authority string)
89
90
Returns:
91
CRS: Coordinate reference system
92
"""
93
94
@classmethod
95
def from_dict(cls, proj_dict):
96
"""
97
Create CRS from PROJ4 dictionary.
98
99
Parameters:
100
- proj_dict (dict): PROJ4 parameters as dictionary
101
102
Returns:
103
CRS: Coordinate reference system
104
"""
105
106
def to_epsg(self):
107
"""
108
Get EPSG code if available.
109
110
Returns:
111
int or None: EPSG code
112
"""
113
114
def to_proj4(self):
115
"""
116
Convert to PROJ4 string representation.
117
118
Returns:
119
str: PROJ4 string
120
"""
121
122
def to_wkt(self, version='WKT2_2019', pretty=False):
123
"""
124
Convert to Well-Known Text representation.
125
126
Parameters:
127
- version (str): WKT version ('WKT1_GDAL', 'WKT2_2015', 'WKT2_2019')
128
- pretty (bool): Format for readability
129
130
Returns:
131
str: WKT string
132
"""
133
134
def to_dict(self):
135
"""
136
Convert to PROJ4 dictionary.
137
138
Returns:
139
dict: PROJ4 parameters
140
"""
141
142
def to_string(self):
143
"""
144
Convert to string representation.
145
146
Returns:
147
str: String representation
148
"""
149
150
def equals(self, other):
151
"""
152
Test equality with another CRS.
153
154
Parameters:
155
- other (CRS): CRS to compare
156
157
Returns:
158
bool: True if equivalent
159
"""
160
161
def is_exact_same(self, other):
162
"""
163
Test exact equivalence with another CRS.
164
165
Parameters:
166
- other (CRS): CRS to compare
167
168
Returns:
169
bool: True if exactly the same
170
"""
171
```
172
173
Usage examples:
174
175
```python
176
from rasterio.crs import CRS
177
178
# Create from EPSG code
179
crs_4326 = CRS.from_epsg(4326) # WGS84
180
crs_3857 = CRS.from_epsg(3857) # Web Mercator
181
182
# Create from PROJ4 string
183
crs_proj4 = CRS.from_proj4('+proj=utm +zone=33 +datum=WGS84 +units=m +no_defs')
184
185
# Create from WKT
186
wkt = '''GEOGCS["WGS 84",DATUM["WGS_1984",...]]'''
187
crs_wkt = CRS.from_wkt(wkt)
188
189
# Create from various inputs
190
crs_auto = CRS.from_user_input('EPSG:4326')
191
crs_auto = CRS.from_user_input(4326)
192
crs_auto = CRS.from_user_input('+proj=longlat +datum=WGS84')
193
194
# Convert between formats
195
epsg_code = crs_4326.to_epsg() # 4326
196
proj4_str = crs_4326.to_proj4() # '+proj=longlat +datum=WGS84 +no_defs'
197
wkt_str = crs_4326.to_wkt() # Well-Known Text representation
198
199
# Check properties
200
print(crs_4326.is_geographic) # True
201
print(crs_3857.is_projected) # True
202
print(crs_4326.linear_units) # 'degree'
203
print(crs_3857.linear_units) # 'metre'
204
205
# Compare CRS
206
print(crs_4326.equals(CRS.from_epsg(4326))) # True
207
```
208
209
### CRS Validation and Information
210
211
Utilities for working with CRS validity and metadata.
212
213
```python { .api }
214
def is_geographic_crs(crs):
215
"""
216
Test if CRS is geographic.
217
218
Parameters:
219
- crs (CRS): Coordinate reference system
220
221
Returns:
222
bool: True if geographic
223
"""
224
225
def is_projected_crs(crs):
226
"""
227
Test if CRS is projected.
228
229
Parameters:
230
- crs (CRS): Coordinate reference system
231
232
Returns:
233
bool: True if projected
234
"""
235
```
236
237
### Common CRS Patterns
238
239
Standard coordinate reference systems commonly used in geospatial applications:
240
241
```python
242
# Geographic coordinate systems
243
WGS84 = CRS.from_epsg(4326) # World Geodetic System 1984
244
NAD83 = CRS.from_epsg(4269) # North American Datum 1983
245
ETRS89 = CRS.from_epsg(4258) # European Terrestrial Reference System 1989
246
247
# Projected coordinate systems
248
WEB_MERCATOR = CRS.from_epsg(3857) # Web Mercator (Google Maps)
249
UTM_33N = CRS.from_epsg(32633) # UTM Zone 33N
250
ALBERS_USA = CRS.from_epsg(5070) # Albers Equal Area Conic (USA)
251
252
# Usage in dataset operations
253
with rasterio.open('input.tif') as src:
254
# Check dataset CRS
255
print(f"Dataset CRS: {src.crs}")
256
print(f"Is geographic: {src.crs.is_geographic}")
257
258
# Compare with target CRS
259
target_crs = CRS.from_epsg(3857)
260
needs_reprojection = not src.crs.equals(target_crs)
261
```
262
263
### CRS Error Handling
264
265
CRS operations can raise specific exceptions for invalid or incompatible coordinate systems:
266
267
```python { .api }
268
class CRSError(RasterioError):
269
"""Coordinate reference system related errors."""
270
```
271
272
Common error scenarios:
273
274
```python
275
from rasterio.errors import CRSError
276
277
try:
278
# Invalid EPSG code
279
invalid_crs = CRS.from_epsg(999999)
280
except CRSError as e:
281
print(f"Invalid EPSG code: {e}")
282
283
try:
284
# Invalid PROJ4 string
285
invalid_crs = CRS.from_proj4('+proj=invalid +datum=WGS84')
286
except CRSError as e:
287
print(f"Invalid PROJ4: {e}")
288
289
# Check validity before operations
290
crs = CRS.from_user_input(user_input)
291
if not crs.is_valid:
292
raise CRSError(f"Invalid CRS: {crs}")
293
```