tessl/pypi-pyproj
Python interface to PROJ library for cartographic projections and coordinate transformations
—
Pending
crs.mddocs/
Coordinate Reference Systems
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.
Capabilities
CRS Creation
Create CRS objects from various input formats including EPSG codes, PROJ strings, WKT, and authority definitions.
class CRS:
def __init__(self, projparams: Any | None = None, **kwargs) -> None:
"""
Create a CRS object from various input types.
Args:
projparams: CRS definition (PROJ string, WKT, EPSG code, etc.)
**kwargs: Additional parameters for CRS creation
"""
@classmethod
def from_epsg(cls, code: str | int) -> "CRS":
"""
Create CRS from EPSG code.
Args:
code: EPSG code as string or integer
Returns:
CRS object for the specified EPSG code
Raises:
CRSError: If EPSG code is invalid or not found
"""
@classmethod
def from_authority(cls, auth_name: str, code: str | int) -> "CRS":
"""
Create CRS from authority name and code.
Args:
auth_name: Authority name (e.g., 'EPSG', 'ESRI', 'IAU_2015')
code: Authority code as string or integer
Returns:
CRS object from the specified authority and code
Raises:
CRSError: If authority or code is invalid
"""
@classmethod
def from_wkt(cls, in_wkt_string: str) -> "CRS":
"""
Create CRS from Well-Known Text string.
Args:
in_wkt_string: WKT string defining the CRS
Returns:
CRS object from WKT definition
Raises:
CRSError: If WKT string is malformed or invalid
"""
@classmethod
def from_proj4(cls, in_proj_string: str) -> "CRS":
"""
Create CRS from PROJ.4 string.
Args:
in_proj_string: PROJ.4 definition string
Returns:
CRS object from PROJ.4 definition
Raises:
CRSError: If PROJ string is invalid
"""
@classmethod
def from_string(cls, in_crs_string: str) -> "CRS":
"""
Create CRS from string representation (auto-detects format).
Args:
in_crs_string: CRS string in any supported format
Returns:
CRS object parsed from string
Raises:
CRSError: If string format cannot be determined or is invalid
"""
@classmethod
def from_user_input(cls, value: Any, **kwargs) -> "CRS":
"""
Create CRS from user input (most flexible input method).
Args:
value: CRS definition in any supported format or existing CRS object
**kwargs: Additional parameters
Returns:
CRS object from user input
Raises:
CRSError: If input cannot be converted to CRS
"""
@classmethod
def from_dict(cls, proj_dict: dict) -> "CRS":
"""
Create CRS from PROJ parameter dictionary.
Args:
proj_dict: Dictionary of PROJ parameters
Returns:
CRS object from parameter dictionary
Raises:
CRSError: If dictionary contains invalid parameters
"""
@classmethod
def from_json(cls, crs_json: str) -> "CRS":
"""
Create CRS from JSON string.
Args:
crs_json: JSON string representation of CRS
Returns:
CRS object from JSON definition
Raises:
CRSError: If JSON is malformed or invalid
"""
@classmethod
def from_json_dict(cls, crs_dict: dict) -> "CRS":
"""
Create CRS from JSON dictionary.
Args:
crs_dict: Dictionary containing JSON-style CRS definition
Returns:
CRS object from JSON dictionary
Raises:
CRSError: If dictionary structure is invalid
"""
@classmethod
def from_cf(cls, in_cf: dict, **kwargs) -> "CRS":
"""
Create CRS from Climate and Forecast (CF) conventions dictionary.
Args:
in_cf: CF conventions dictionary
**kwargs: Additional CF parameters
Returns:
CRS object from CF conventions
Raises:
CRSError: If CF dictionary is invalid or unsupported
"""CRS Conversion and Export
Convert CRS objects to various output formats for interoperability with other systems.
class CRS:
def to_string(self) -> str:
"""
Convert CRS to string representation.
Returns:
String representation of CRS (typically PROJ format)
"""
def to_dict(self) -> dict:
"""
Convert CRS to PROJ parameter dictionary.
Returns:
Dictionary of PROJ parameters
"""
def to_wkt(self, version: WktVersion = WktVersion.WKT2_2019, pretty: bool = False) -> str:
"""
Convert CRS to Well-Known Text format.
Args:
version: WKT version to use for output
pretty: Whether to format with indentation
Returns:
WKT string representation of CRS
"""
def to_proj4(self, version: ProjVersion = ProjVersion.PROJ_5) -> str:
"""
Convert CRS to PROJ.4 string format.
Args:
version: PROJ version for compatibility
Returns:
PROJ.4 string representation of CRS
"""
def to_json(self, pretty: bool = False, indentation: int = 2) -> str:
"""
Convert CRS to JSON string format.
Args:
pretty: Whether to format with indentation
indentation: Number of spaces for indentation
Returns:
JSON string representation of CRS
"""
def to_json_dict(self) -> dict:
"""
Convert CRS to JSON dictionary format.
Returns:
Dictionary containing JSON representation of CRS
"""
def to_cf(self, **kwargs) -> dict:
"""
Convert CRS to Climate and Forecast conventions dictionary.
Args:
**kwargs: CF conversion parameters
Returns:
Dictionary following CF conventions
Raises:
CRSError: If CRS cannot be represented in CF format
"""
def cs_to_cf(self) -> list[dict]:
"""
Convert coordinate system to CF conventions format.
Returns:
List of dictionaries representing coordinate system in CF format
"""CRS Comparison and Analysis
Compare CRS objects and analyze their properties and relationships.
class CRS:
def equals(self, other: Any, ignore_axis_order: bool = False) -> bool:
"""
Check if two CRS objects are equivalent.
Args:
other: Another CRS object or CRS-compatible input
ignore_axis_order: Whether to ignore axis order differences
Returns:
True if CRS objects are equivalent, False otherwise
"""
def is_exact_same(self, other: Any) -> bool:
"""
Check if two CRS objects are exactly the same.
Args:
other: Another CRS object
Returns:
True if CRS objects are identical, False otherwise
"""
def is_geographic(self) -> bool:
"""
Check if CRS is geographic (latitude/longitude).
Returns:
True if CRS is geographic, False otherwise
"""
def is_projected(self) -> bool:
"""
Check if CRS is projected (uses map projection).
Returns:
True if CRS is projected, False otherwise
"""
def is_vertical(self) -> bool:
"""
Check if CRS is vertical (height/depth).
Returns:
True if CRS is vertical, False otherwise
"""
def is_compound(self) -> bool:
"""
Check if CRS is compound (combines horizontal and vertical).
Returns:
True if CRS is compound, False otherwise
"""
def is_geocentric(self) -> bool:
"""
Check if CRS is geocentric (3D Cartesian).
Returns:
True if CRS is geocentric, False otherwise
"""
def is_bound(self) -> bool:
"""
Check if CRS is bound to another CRS.
Returns:
True if CRS is bound, False otherwise
"""CRS Properties and Metadata
Access detailed information about CRS properties, components, and associated objects.
class CRS:
@property
def name(self) -> str | None:
"""Get the name of the CRS."""
@property
def type_name(self) -> str:
"""Get the type name of the CRS."""
@property
def coordinate_system(self) -> CoordinateSystem:
"""Get the coordinate system of the CRS."""
@property
def coordinate_operation(self) -> CoordinateOperation | None:
"""Get the coordinate operation for derived CRS."""
@property
def datum(self) -> Datum | None:
"""Get the datum of the CRS."""
@property
def ellipsoid(self) -> Ellipsoid | None:
"""Get the ellipsoid of the CRS."""
@property
def prime_meridian(self) -> PrimeMeridian | None:
"""Get the prime meridian of the CRS."""
@property
def area_of_use(self) -> AreaOfUse | None:
"""Get the area of use for the CRS."""
@property
def remarks(self) -> str | None:
"""Get remarks about the CRS."""
@property
def scope(self) -> str | None:
"""Get the scope of the CRS."""
@property
def axis_info(self) -> list[Axis]:
"""Get information about CRS axes."""
@property
def geodetic_crs(self) -> "CRS" | None:
"""Get the geodetic CRS (for projected CRS)."""
@property
def source_crs(self) -> "CRS" | None:
"""Get the source CRS (for bound CRS)."""
@property
def target_crs(self) -> "CRS" | None:
"""Get the target CRS (for bound CRS)."""
def get_geod(self) -> Geod | None:
"""
Get associated Geod object for geodesic calculations.
Returns:
Geod object if CRS has associated ellipsoid, None otherwise
"""
def to_epsg(self, min_confidence: int = 70) -> int | None:
"""
Get EPSG code for CRS if available.
Args:
min_confidence: Minimum confidence level for authority match
Returns:
EPSG code as integer, or None if not found
"""
def to_authority(self, auth_name: str | None = None, min_confidence: int = 70) -> tuple[str, str] | None:
"""
Get authority name and code for CRS.
Args:
auth_name: Specific authority to search (None for any)
min_confidence: Minimum confidence level for match
Returns:
Tuple of (authority_name, code) or None if not found
"""
def list_authority(self, auth_name: str | None = None, min_confidence: int = 70) -> list[AuthorityMatchInfo]:
"""
List all matching authorities for the CRS.
Args:
auth_name: Authority name to filter by
min_confidence: Minimum confidence level for matches
Returns:
List of AuthorityMatchInfo objects with match details
"""
def utm_zone(self) -> str | None:
"""
Get UTM zone identifier for UTM CRS.
Returns:
UTM zone string (e.g., '33N') or None if not UTM
"""
def sub_crs_list(self) -> list["CRS"]:
"""
Get list of sub-CRS for compound CRS.
Returns:
List of CRS objects comprising this compound CRS
"""
def to_2d(self, name: str | None = None) -> "CRS":
"""
Convert CRS to 2D version.
Args:
name: Optional name for the new CRS
Returns:
2D version of the CRS
"""
def to_3d(self, name: str | None = None) -> "CRS":
"""
Convert CRS to 3D version.
Args:
name: Optional name for the new CRS
Returns:
3D version of the CRS
"""
def is_engineering(self) -> bool:
"""
Check if CRS is engineering.
Returns:
True if CRS is engineering, False otherwise
"""
def is_derived(self) -> bool:
"""
Check if CRS is derived from another CRS.
Returns:
True if CRS is derived, False otherwise
"""
def is_deprecated(self) -> bool:
"""
Check if CRS is deprecated.
Returns:
True if CRS is deprecated, False otherwise
"""
def get_non_deprecated(self) -> list["CRS"]:
"""
Get list of non-deprecated CRS alternatives.
Returns:
List of non-deprecated CRS alternatives
"""CRS Specialized Subclasses
Specialized CRS classes for specific coordinate system types with additional functionality.
class GeographicCRS(CRS):
"""Geographic coordinate reference system (latitude/longitude)."""
class ProjectedCRS(CRS):
"""Projected coordinate reference system (uses map projection)."""
class VerticalCRS(CRS):
"""Vertical coordinate reference system (height/depth)."""
class CompoundCRS(CRS):
"""Compound coordinate reference system (horizontal + vertical)."""
class BoundCRS(CRS):
"""Bound coordinate reference system (linked to another CRS)."""
class GeocentricCRS(CRS):
"""Geocentric coordinate reference system (3D Cartesian)."""
class DerivedGeographicCRS(CRS):
"""Geographic CRS derived from another geographic CRS."""Usage Examples
Creating CRS from Different Sources
from pyproj import CRS
# From EPSG code
wgs84 = CRS.from_epsg(4326)
utm_33n = CRS.from_epsg(32633)
# From PROJ string
mercator = CRS.from_proj4('+proj=merc +datum=WGS84 +no_defs')
# From WKT
wkt_string = '''GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563]],PRIMEM["Greenwich",0],UNIT["degree",0.0174532925199433]]'''
geographic = CRS.from_wkt(wkt_string)
# Auto-detect format
auto_crs = CRS.from_string('EPSG:4326')CRS Analysis and Comparison
from pyproj import CRS
crs1 = CRS.from_epsg(4326) # WGS84
crs2 = CRS.from_epsg(4269) # NAD83
# Check CRS properties
print(f"Is geographic: {crs1.is_geographic()}")
print(f"Is projected: {crs1.is_projected()}")
print(f"Name: {crs1.name}")
print(f"Area of use: {crs1.area_of_use}")
# Compare CRS objects
print(f"Are equal: {crs1.equals(crs2)}")
print(f"Are identical: {crs1.is_exact_same(crs2)}")
# Get associated geodesic object
geod = crs1.get_geod()
if geod:
print(f"Ellipsoid: {crs1.ellipsoid.name}")CRS Format Conversion
from pyproj import CRS, WktVersion
crs = CRS.from_epsg(4326)
# Convert to different formats
proj4_str = crs.to_proj4()
wkt_str = crs.to_wkt(version=WktVersion.WKT2_2019, pretty=True)
json_str = crs.to_json(pretty=True)
param_dict = crs.to_dict()
print(f"PROJ.4: {proj4_str}")
print(f"WKT: {wkt_str}")
print(f"Parameters: {param_dict}")Types
# Component classes
class CoordinateSystem:
"""Coordinate system component of CRS."""
name: str
axis_list: list[Axis]
class Datum:
"""Datum component of CRS."""
name: str
type_name: str
class Ellipsoid:
"""Ellipsoid component of CRS."""
name: str
semi_major_metre: float
semi_minor_metre: float
inverse_flattening: float
class PrimeMeridian:
"""Prime meridian component of CRS."""
name: str
longitude: float
unit_name: str
class CoordinateOperation:
"""Coordinate operation for derived CRS."""
name: str
method_name: str
params: list[dict]
class Axis:
"""Coordinate system axis information."""
name: str
abbrev: str
direction: str
unit_name: str
class AuthorityMatchInfo:
"""Information about CRS authority matches."""
auth_name: str
code: str
confidence: intInstall with Tessl CLI
npx tessl i tessl/pypi-pyproj