0
# Projections
1
2
The Proj class provides the legacy PROJ.4 interface for cartographic projections, maintaining backward compatibility while offering direct projection operations. It inherits from Transformer and provides callable projection functionality with additional projection-specific methods.
3
4
## Capabilities
5
6
### Proj Creation
7
8
Create Proj objects for cartographic projections using various initialization methods and parameter formats.
9
10
```python { .api }
11
class Proj:
12
def __init__(
13
self,
14
projparams: Any | None = None,
15
preserve_units: bool = True,
16
**kwargs
17
) -> None:
18
"""
19
Create a Proj object for cartographic projections.
20
21
Args:
22
projparams: Projection parameters (PROJ string, dict, CRS object, etc.)
23
preserve_units: Preserve units from projection definition
24
**kwargs: Additional projection parameters (e.g., proj='utm', zone=33)
25
26
Raises:
27
CRSError: If projection parameters are invalid
28
ProjError: If projection cannot be created
29
"""
30
31
@property
32
def definition_string(self) -> str:
33
"""Get the definition string of the projection."""
34
35
@property
36
def srs(self) -> str:
37
"""Get the SRS (Spatial Reference System) string."""
38
39
@property
40
def crs(self) -> CRS:
41
"""Get the associated CRS object."""
42
43
@property
44
def is_latlong(self) -> bool:
45
"""Check if projection is geographic (latitude/longitude)."""
46
47
@property
48
def is_geocent(self) -> bool:
49
"""Check if projection is geocentric."""
50
51
@property
52
def has_inverse(self) -> bool:
53
"""Check if projection has inverse operation."""
54
```
55
56
### Direct Projection Operations
57
58
Perform forward and inverse projection transformations using the callable interface.
59
60
```python { .api }
61
class Proj:
62
def __call__(
63
self,
64
longitude,
65
latitude,
66
inverse: bool = False,
67
errcheck: bool = False,
68
radians: bool = False,
69
**kwargs
70
) -> tuple:
71
"""
72
Transform coordinates using projection (callable interface).
73
74
Args:
75
longitude: Longitude coordinate(s) or x coordinate(s) for inverse
76
latitude: Latitude coordinate(s) or y coordinate(s) for inverse
77
inverse: Perform inverse projection (projected -> geographic)
78
errcheck: Check for transformation errors
79
radians: Input/output coordinates in radians
80
**kwargs: Additional transformation parameters
81
82
Returns:
83
Tuple of transformed coordinates:
84
- Forward: (x, y) projected coordinates
85
- Inverse: (lon, lat) geographic coordinates
86
87
Raises:
88
ProjError: If projection transformation fails
89
"""
90
```
91
92
### Projection Analysis
93
94
Analyze projection properties including scale factors, convergence, and distortion characteristics.
95
96
```python { .api }
97
class Proj:
98
def get_factors(
99
self,
100
longitude: float,
101
latitude: float,
102
radians: bool = False,
103
errcheck: bool = False
104
) -> "Factors":
105
"""
106
Get projection factors at specified geographic location.
107
108
Args:
109
longitude: Longitude coordinate in degrees (or radians)
110
latitude: Latitude coordinate in degrees (or radians)
111
radians: Input coordinates are in radians
112
errcheck: Check for calculation errors
113
114
Returns:
115
Factors object containing projection distortion information
116
117
Raises:
118
ProjError: If factor calculation fails or point is outside projection domain
119
"""
120
121
def is_exact_same(self, other: "Proj") -> bool:
122
"""
123
Check if two Proj objects are exactly the same.
124
125
Args:
126
other: Another Proj object to compare
127
128
Returns:
129
True if projections are identical, False otherwise
130
"""
131
```
132
133
### Legacy Compatibility Methods
134
135
Methods for backward compatibility with older PROJ.4 workflows and coordinate system conversion.
136
137
```python { .api }
138
class Proj:
139
def to_latlong_def(self) -> str | None:
140
"""
141
Get latitude/longitude definition string.
142
143
Returns:
144
PROJ definition string for corresponding geographic CRS,
145
or None if projection doesn't have a clear geographic equivalent
146
147
Note:
148
Legacy method for PROJ.4 compatibility
149
"""
150
151
def to_latlong(self) -> "Proj":
152
"""
153
Create corresponding geographic (lat/long) projection.
154
155
Returns:
156
Proj object for geographic coordinates using same datum/ellipsoid
157
158
Raises:
159
ProjError: If geographic equivalent cannot be determined
160
"""
161
```
162
163
### Projection Factors Analysis
164
165
Detailed projection distortion analysis for cartographic quality assessment and scale calculations.
166
167
```python { .api }
168
class Factors:
169
"""Projection factors and distortion information at a specific point."""
170
171
@property
172
def meridional_scale(self) -> float:
173
"""Scale factor along meridian (north-south direction)."""
174
175
@property
176
def parallel_scale(self) -> float:
177
"""Scale factor along parallel (east-west direction)."""
178
179
@property
180
def areal_scale(self) -> float:
181
"""Areal (area) scale factor."""
182
183
@property
184
def angular_distortion(self) -> float:
185
"""Maximum angular distortion in radians."""
186
187
@property
188
def meridian_parallel_angle(self) -> float:
189
"""Angle between meridian and parallel in radians."""
190
191
@property
192
def meridian_convergence(self) -> float:
193
"""Meridian convergence angle in radians."""
194
195
@property
196
def tissot_semimajor(self) -> float:
197
"""Semi-major axis of Tissot indicatrix."""
198
199
@property
200
def tissot_semiminor(self) -> float:
201
"""Semi-minor axis of Tissot indicatrix."""
202
203
def __str__(self) -> str:
204
"""String representation of projection factors."""
205
```
206
207
## Usage Examples
208
209
### Basic Projection Operations
210
211
```python
212
from pyproj import Proj
213
214
# Create UTM Zone 33N projection
215
utm = Proj(proj='utm', zone=33, ellps='WGS84')
216
217
# Forward transformation: geographic -> projected
218
lon, lat = 10.0, 60.0
219
x, y = utm(lon, lat)
220
print(f"UTM coordinates: {x:.2f}, {y:.2f}")
221
222
# Inverse transformation: projected -> geographic
223
lon_back, lat_back = utm(x, y, inverse=True)
224
print(f"Geographic coordinates: {lon_back:.6f}, {lat_back:.6f}")
225
226
# Check projection properties
227
print(f"Is geographic: {utm.is_latlong}")
228
print(f"Has inverse: {utm.has_inverse}")
229
print(f"Definition: {utm.definition_string}")
230
```
231
232
### Working with Different Projections
233
234
```python
235
from pyproj import Proj
236
237
# Web Mercator projection
238
web_mercator = Proj(proj='merc', a=6378137, b=6378137)
239
240
# Albers Equal Area projection for continental mapping
241
albers = Proj(
242
proj='aea', # Albers Equal Area
243
lat_1=29.5, # First standard parallel
244
lat_2=45.5, # Second standard parallel
245
lat_0=37.5, # Latitude of origin
246
lon_0=-96, # Central meridian
247
x_0=0, # False easting
248
y_0=0, # False northing
249
ellps='GRS80' # Ellipsoid
250
)
251
252
# Lambert Conformal Conic for regional mapping
253
lambert = Proj(
254
proj='lcc',
255
lat_1=33,
256
lat_2=45,
257
lat_0=39,
258
lon_0=-96,
259
ellps='WGS84'
260
)
261
262
# Test point
263
lon, lat = -100.0, 40.0
264
265
# Project with different projections
266
web_merc_xy = web_mercator(lon, lat)
267
albers_xy = albers(lon, lat)
268
lambert_xy = lambert(lon, lat)
269
270
print(f"Web Mercator: {web_merc_xy}")
271
print(f"Albers: {albers_xy}")
272
print(f"Lambert: {lambert_xy}")
273
```
274
275
### Projection Factors and Distortion Analysis
276
277
```python
278
from pyproj import Proj
279
280
# Create projection for analysis
281
utm = Proj(proj='utm', zone=15, ellps='WGS84')
282
283
# Test point in central Texas
284
lon, lat = -99.0, 31.0
285
286
# Get projection factors
287
factors = utm.get_factors(lon, lat)
288
289
print("Projection Distortion Analysis:")
290
print(f"Meridional scale: {factors.meridional_scale:.6f}")
291
print(f"Parallel scale: {factors.parallel_scale:.6f}")
292
print(f"Areal scale: {factors.areal_scale:.6f}")
293
print(f"Angular distortion: {factors.angular_distortion:.6f} radians")
294
print(f"Meridian convergence: {factors.meridian_convergence:.6f} radians")
295
296
# Calculate distortion percentage
297
scale_distortion = abs(factors.meridional_scale - 1.0) * 100
298
area_distortion = abs(factors.areal_scale - 1.0) * 100
299
print(f"Scale distortion: {scale_distortion:.3f}%")
300
print(f"Area distortion: {area_distortion:.3f}%")
301
```
302
303
### Multiple Point Transformations
304
305
```python
306
from pyproj import Proj
307
import numpy as np
308
309
# State Plane projection (Texas Central)
310
texas_central = Proj(
311
proj='lcc',
312
lat_1=30.116666667,
313
lat_2=31.883333333,
314
lat_0=29.666666667,
315
lon_0=-100.333333333,
316
x_0=700000,
317
y_0=3000000,
318
ellps='GRS80'
319
)
320
321
# Multiple points across Texas
322
longitudes = np.array([-99.0, -100.0, -101.0, -98.5])
323
latitudes = np.array([31.0, 30.5, 31.5, 30.8])
324
325
# Transform all points
326
x_coords, y_coords = texas_central(longitudes, latitudes)
327
328
print("Projected coordinates:")
329
for i, (x, y) in enumerate(zip(x_coords, y_coords)):
330
print(f"Point {i+1}: {x:.2f}, {y:.2f}")
331
332
# Inverse transformation
333
lons_back, lats_back = texas_central(x_coords, y_coords, inverse=True)
334
335
print("Verification (should match input):")
336
for i, (lon, lat) in enumerate(zip(lons_back, lats_back)):
337
print(f"Point {i+1}: {lon:.6f}, {lat:.6f}")
338
```
339
340
### Working with Geographic Coordinates
341
342
```python
343
from pyproj import Proj
344
345
# Create projection
346
utm = Proj(proj='utm', zone=33, ellps='WGS84')
347
348
# Get corresponding geographic projection
349
geo_proj = utm.to_latlong()
350
351
print(f"Original projection: {utm.definition_string}")
352
print(f"Geographic projection: {geo_proj.definition_string}")
353
print(f"Geographic definition: {utm.to_latlong_def()}")
354
355
# Verify geographic properties
356
print(f"Is geographic: {geo_proj.is_latlong}")
357
print(f"Same ellipsoid: {utm.ellipsoid == geo_proj.ellipsoid}")
358
```
359
360
### Projection Parameter Dictionary
361
362
```python
363
from pyproj import Proj
364
365
# Create from parameter dictionary
366
params = {
367
'proj': 'stere', # Stereographic
368
'lat_0': 90, # North pole
369
'lat_ts': 70, # Standard parallel
370
'lon_0': -45, # Central meridian
371
'k_0': 0.994, # Scale factor
372
'x_0': 2000000, # False easting
373
'y_0': 2000000, # False northing
374
'ellps': 'WGS84'
375
}
376
377
polar_stereo = Proj(params)
378
379
# Test Arctic location
380
lon, lat = -45.0, 75.0 # Greenland
381
x, y = polar_stereo(lon, lat)
382
print(f"Polar stereographic: {x:.2f}, {y:.2f}")
383
384
# Access projection parameters
385
print(f"Definition: {polar_stereo.definition_string}")
386
print(f"Associated CRS: {polar_stereo.crs.name}")
387
```
388
389
### Error Handling and Validation
390
391
```python
392
from pyproj import Proj, ProjError
393
394
try:
395
# Valid projection
396
utm = Proj(proj='utm', zone=33, ellps='WGS84')
397
398
# Test point
399
lon, lat = 10.0, 60.0
400
x, y = utm(lon, lat, errcheck=True) # Enable error checking
401
402
# Point outside valid domain
403
invalid_lon, invalid_lat = 180.0, 85.0
404
try:
405
x_invalid, y_invalid = utm(invalid_lon, invalid_lat, errcheck=True)
406
except ProjError as e:
407
print(f"Projection error for invalid point: {e}")
408
409
# Test factors at edge of projection
410
factors = utm.get_factors(15.0, 60.0, errcheck=True) # Near zone edge
411
if factors.meridional_scale > 1.001:
412
print("High distortion warning")
413
414
except ProjError as e:
415
print(f"Projection creation failed: {e}")
416
```
417
418
## Types
419
420
```python { .api }
421
# Global constants from proj.py
422
pj_list: dict[str, str] # Dictionary of available PROJ operations
423
424
# Projection parameters for common ellipsoids (from geod.py)
425
pj_ellps: dict[str, dict[str, float]] # Ellipsoid parameter dictionary
426
427
# Common projection parameter keys
428
class ProjParams:
429
"""Common PROJ parameter names and values."""
430
431
# Projection types
432
PROJ_UTM = 'utm'
433
PROJ_MERCATOR = 'merc'
434
PROJ_LAMBERT_CONFORMAL_CONIC = 'lcc'
435
PROJ_ALBERS_EQUAL_AREA = 'aea'
436
PROJ_TRANSVERSE_MERCATOR = 'tmerc'
437
PROJ_STEREOGRAPHIC = 'stere'
438
PROJ_SINUSOIDAL = 'sinu'
439
PROJ_ROBINSON = 'robin'
440
441
# Common ellipsoids
442
ELLPS_WGS84 = 'WGS84'
443
ELLPS_GRS80 = 'GRS80'
444
ELLPS_NAD83 = 'GRS80'
445
ELLPS_NAD27 = 'clrk66'
446
447
# Parameter names
448
LAT_0 = 'lat_0' # Latitude of origin
449
LON_0 = 'lon_0' # Central meridian
450
LAT_1 = 'lat_1' # First standard parallel
451
LAT_2 = 'lat_2' # Second standard parallel
452
LAT_TS = 'lat_ts' # True scale latitude
453
K_0 = 'k_0' # Scale factor
454
X_0 = 'x_0' # False easting
455
Y_0 = 'y_0' # False northing
456
ZONE = 'zone' # UTM zone number
457
```