0
# PyProj
1
2
PyProj is a Python interface to PROJ, providing cartographic projections and coordinate transformations. It enables precise coordinate reference system (CRS) operations, geodesic computations, and transformation between different spatial reference systems with high accuracy and comprehensive EPSG support.
3
4
## Package Information
5
6
- **Package Name**: pyproj
7
- **Language**: Python
8
- **Installation**: `pip install pyproj`
9
10
## Core Imports
11
12
```python
13
import pyproj
14
```
15
16
Common imports for working with coordinate systems and transformations:
17
18
```python
19
from pyproj import CRS, Transformer, Proj, Geod
20
from pyproj import transform, itransform
21
from pyproj import get_authorities, get_codes, get_units_map
22
from pyproj import show_versions
23
```
24
25
## Basic Usage
26
27
```python
28
from pyproj import CRS, Transformer
29
import pyproj
30
31
# Create coordinate reference systems
32
wgs84 = CRS('EPSG:4326') # WGS84 Geographic
33
utm_zone_33n = CRS('EPSG:32633') # UTM Zone 33N
34
35
# Create transformer for coordinate conversion
36
transformer = Transformer.from_crs(wgs84, utm_zone_33n, always_xy=True)
37
38
# Transform coordinates (longitude, latitude to easting, northing)
39
lon, lat = 10.0, 60.0
40
x, y = transformer.transform(lon, lat)
41
print(f"UTM coordinates: {x:.2f}, {y:.2f}")
42
43
# Transform multiple points
44
points = [(10.0, 60.0), (11.0, 61.0), (12.0, 62.0)]
45
transformed = list(transformer.itransform(points))
46
47
# Get projection information
48
print(f"Source CRS: {transformer.source_crs}")
49
print(f"Target CRS: {transformer.target_crs}")
50
```
51
52
## Architecture
53
54
PyProj is built around several key components that work together to provide comprehensive geospatial coordinate operations:
55
56
- **CRS**: Coordinate Reference System management with support for EPSG, PROJ4, WKT, and other formats
57
- **Transformer**: High-performance coordinate transformation between different CRS with operation chaining
58
- **Proj**: Legacy projection interface maintaining backward compatibility with PROJ.4 workflows
59
- **Geod**: Geodesic computations for great circle calculations, area, and distance measurements
60
- **Database**: PROJ database integration for authority codes, CRS definitions, and metadata queries
61
62
This architecture enables PyProj to serve as the foundational coordinate transformation library for the Python geospatial ecosystem, supporting libraries like GeoPandas, Cartopy, and GDAL/OGR.
63
64
## Capabilities
65
66
### Coordinate Reference Systems
67
68
Complete CRS management including creation from various formats, validation, comparison, and conversion between different CRS representations.
69
70
```python { .api }
71
class CRS:
72
def __init__(self, projparams: Any | None = None, **kwargs) -> None: ...
73
74
@classmethod
75
def from_epsg(cls, code: str | int) -> "CRS": ...
76
77
@classmethod
78
def from_wkt(cls, in_wkt_string: str) -> "CRS": ...
79
80
def to_string(self) -> str: ...
81
def equals(self, other: Any, ignore_axis_order: bool = False) -> bool: ...
82
```
83
84
[Coordinate Reference Systems](./crs.md)
85
86
### Coordinate Transformations
87
88
High-performance coordinate transformations between CRS with support for transformation pipelines, accuracy estimation, and batch processing.
89
90
```python { .api }
91
class Transformer:
92
@classmethod
93
def from_crs(cls, crs_from: Any, crs_to: Any, **kwargs) -> "Transformer": ...
94
95
def transform(self, xx, yy, zz=None, tt=None, **kwargs) -> tuple: ...
96
def itransform(self, points, **kwargs) -> Iterator: ...
97
def transform_bounds(self, left, bottom, right, top, **kwargs) -> tuple: ...
98
```
99
100
[Coordinate Transformations](./transformations.md)
101
102
### Geodesic Operations
103
104
Geodesic computations for great circle calculations including forward/inverse calculations, intermediate points, and area/perimeter measurements.
105
106
```python { .api }
107
class Geod:
108
def __init__(self, initstring: str | None = None, **kwargs) -> None: ...
109
110
def fwd(self, lons, lats, az, dist, **kwargs) -> tuple: ...
111
def inv(self, lons1, lats1, lons2, lats2, **kwargs) -> tuple: ...
112
def polygon_area_perimeter(self, lons, lats, **kwargs) -> tuple: ...
113
```
114
115
[Geodesic Operations](./geodesic.md)
116
117
### Projections
118
119
Legacy projection interface maintaining compatibility with PROJ.4 workflows and providing direct projection operations.
120
121
```python { .api }
122
class Proj:
123
def __init__(self, projparams: Any | None = None, preserve_units: bool = True, **kwargs) -> None: ...
124
125
def __call__(self, lon, lat, **kwargs) -> tuple: ...
126
def get_factors(self, longitude, latitude, **kwargs) -> "Factors": ...
127
```
128
129
[Projections](./projections.md)
130
131
### Database Operations
132
133
Access to PROJ database for querying coordinate reference systems, transformations, and spatial reference metadata.
134
135
```python { .api }
136
def get_authorities() -> list[str]: ...
137
def get_codes(auth_name: str, pj_type: PJType | str, allow_deprecated: bool = False) -> list[str]: ...
138
def query_crs_info(
139
auth_name: str | None = None,
140
pj_types: PJType | list[PJType] | None = None,
141
area_of_interest: AreaOfInterest | None = None,
142
contains: bool = False,
143
allow_deprecated: bool = False
144
) -> list[CRSInfo]: ...
145
def get_units_map(auth_name: str | None = None, category: str | None = None, allow_deprecated: bool = False) -> dict[str, Unit]: ...
146
```
147
148
[Database Operations](./database.md)
149
150
### Utility Functions
151
152
Utility functions for version information, data management, and package configuration.
153
154
```python { .api }
155
def show_versions() -> None: ...
156
def get_data_dir() -> str: ...
157
def set_network_enabled(enabled: bool) -> None: ...
158
159
# Global transformation functions
160
def transform(transformer, xx, yy, zz=None, tt=None, **kwargs) -> tuple: ...
161
def itransform(transformer, points, **kwargs) -> Iterator: ...
162
```
163
164
[Utility Functions](./utilities.md)
165
166
## Types
167
168
```python { .api }
169
# Enumerations
170
class WktVersion(Enum):
171
WKT2_2015 = "WKT2_2015"
172
WKT2_2015_SIMPLIFIED = "WKT2_2015_SIMPLIFIED"
173
WKT2_2019 = "WKT2_2019"
174
WKT2_2019_SIMPLIFIED = "WKT2_2019_SIMPLIFIED"
175
WKT1_GDAL = "WKT1_GDAL"
176
WKT1_ESRI = "WKT1_ESRI"
177
178
class ProjVersion(Enum):
179
PROJ_4 = 4
180
PROJ_5 = 5
181
182
class TransformDirection(Enum):
183
FORWARD = "FORWARD"
184
INVERSE = "INVERSE"
185
IDENT = "IDENT"
186
187
# Data structures
188
class AreaOfInterest:
189
west_lon_degree: float
190
south_lat_degree: float
191
east_lon_degree: float
192
north_lat_degree: float
193
194
class AreaOfUse:
195
west: float
196
south: float
197
east: float
198
north: float
199
name: str | None
200
201
class CRSInfo:
202
auth_name: str
203
code: str
204
name: str
205
type: str
206
deprecated: bool
207
area_of_use: AreaOfUse | None
208
projection_method_name: str | None
209
210
class Unit:
211
auth_name: str
212
code: str
213
name: str
214
category: str
215
conv_factor: float
216
proj_short_name: str | None
217
deprecated: bool
218
219
# Enumerations
220
class PJType(Enum):
221
"""Types of objects in PROJ database."""
222
CRS = "CRS"
223
PROJECTED_CRS = "PROJECTED_CRS"
224
GEOGRAPHIC_2D_CRS = "GEOGRAPHIC_2D_CRS"
225
GEOGRAPHIC_3D_CRS = "GEOGRAPHIC_3D_CRS"
226
VERTICAL_CRS = "VERTICAL_CRS"
227
COMPOUND_CRS = "COMPOUND_CRS"
228
GEOCENTRIC_CRS = "GEOCENTRIC_CRS"
229
ELLIPSOID = "ELLIPSOID"
230
DATUM = "DATUM"
231
PRIME_MERIDIAN = "PRIME_MERIDIAN"
232
233
# Exceptions
234
class ProjError(RuntimeError): ...
235
class CRSError(ProjError): ...
236
class GeodError(RuntimeError): ...
237
class DataDirError(RuntimeError): ...
238
```