crskit API reference
Module: crskit
crskit 0.6.0 includes type annotations (_crskit.pyi and py.typed) for editor completion and mypy checking.
import crskit
Axis order
Coordinates follow the CRS's declared axis order. Geographic EPSG CRSs such as EPSG:4258 (ETRS89) and EPSG:4326 (WGS 84) put latitude first and longitude second. Crs.axes returns that order:
crskit.crs_from_epsg(4258).axes # [('Lat', 'North'), ('Lon', 'East')]
crskit.crs_from_epsg(25830).axes # [('E', 'East'), ('N', 'North')]
Swapped axes produce a different point rather than an error. If a seemingly valid point raises CoordinateOutsideDomainError, check axis order.
Module functions
| Function | Description |
|---|---|
init(epsg_database=None, data_directory=None) -> None |
Initializes the library with an EPSG database. See Initialization. |
is_initialized() -> bool |
True if an EPSG database is already initialized. |
epsg_version() -> str |
Open database's EPSG dataset version, such as '12.057'. |
crs_from_epsg(code: int) -> Crs |
CRS for EPSG code. Raises AuthorityCodeNotFoundError if absent. |
crs_from_wkt(wkt: str) -> Crs |
CRS described by WKT. Accepts OGC/ESRI WKT 1 and WKT 2, detecting grammar from text. Raises WktParseError on failure. |
compound_crs(horizontal: int, vertical: int) -> Crs |
Combines horizontal and vertical EPSG codes. Most combinations have no EPSG code (authority_code is None); names combine both parts, such as 'ETRS89 / UTM zone 30N + Alicante height'. |
transformation(source, target, *, select_operation=None, unknown_crs_policy=UnknownCrsPolicy.REJECT) -> Transformation |
Transforms CRS source to target. See transformation for the two keyword arguments. |
All except init and is_initialized raise CrsError before initialization.
transformation
transformation(source, target, *, select_operation=None, unknown_crs_policy=UnknownCrsPolicy.REJECT) -> Transformation
| Argument | Type | Description |
|---|---|---|
source |
Crs |
Source CRS. |
target |
Crs |
Target CRS. |
select_operation |
function or None |
Selects among multiple EPSG operations. Receives (source_name, target_name, operations), with operations a list of CoordinateOperation, returning an operation or its EPSG code (int). |
unknown_crs_policy |
UnknownCrsPolicy |
Behavior when a CRS is local or unknown. |
Without select_operation, multiple candidates make transformation raise TransformationNotFoundError. EPSG defines twelve ED50 (EPSG:4230) to ETRS89 (EPSG:4258) operations with differing accuracy and coverage. Select by area_of_use, as well as accuracy:
def peninsula(source_name, target_name, operations):
candidatas = [o for o in operations if "Spain - mainland" in o.area_of_use and not o.grid_files]
return min(candidatas, key=lambda o: o.accuracy)
ed50_a_etrs89 = crskit.transformation(crskit.crs_from_epsg(4230), crskit.crs_from_epsg(4258),
select_operation=peninsula)
transformation raises GridFileNotFoundError for a required grid missing from the grid folder, or TransformationNotFoundError if no operation exists.
Crs
Crs represents a CRS. Create Crs instances with crs_from_epsg, crs_from_wkt or compound_crs.
| Member | Type | Description |
|---|---|---|
name |
str |
CRS name, such as 'ETRS89 / UTM zone 30N'. |
authority |
str |
Code authority, such as 'EPSG'. |
authority_code |
int or None |
EPSG code, or None without a code. |
dimension |
int |
Coordinate count: 2 or 3. |
remarks |
str |
EPSG remarks about the CRS. |
axes |
list[tuple[str, str]] |
Axes in coordinate order, as (nombre, orientación) pairs. |
to_wkt(version=WktVersion.WKT1) -> str |
method | CRS WKT using the specified WktVersion. |
compare(other: Crs) -> int |
method | Structural similarity to other, from 0 to 100. 100 means equivalent CRSs. |
== |
operator | True for identical mathematical definitions (datum, prime meridian, projection, parameters and units). Ignores name, authority and axis order. |
Crs cannot be a dict key or set element: it has no __hash__.
Transformation
Transformation represents a transformation between CRSs. Create Transformation instances with transformation.
| Member | Type | Description |
|---|---|---|
name |
str |
Transformation name. |
authority |
str |
Operation code authority. |
authority_code |
str or None |
EPSG operation code, or None for non-EPSG transformations. |
area_of_use |
str |
Area of use. |
remarks |
str |
Remarks. |
source |
Crs |
Source CRS. |
target |
Crs |
Target CRS. |
source_dimension |
int |
Source point coordinate count. |
target_dimension |
int |
Transformed point coordinate count. |
is_identity |
bool |
True if coordinates remain unchanged. |
transform(point) -> list[float] |
method | Transforms a sequence of source_dimension numbers. Raises DimensionMismatchError for an incorrect count. |
transform_points(points) -> numpy.ndarray |
method | Transforms a NumPy array shaped (source_dimension,) or (n, source_dimension), returning (target_dimension,) or (n, target_dimension). One native library call handles all points. Requires NumPy. |
CoordinateOperation
CoordinateOperation represents an EPSG operation between CRSs. transformation passes a list to select_operation.
| Property | Type | Description |
|---|---|---|
code |
int |
EPSG operation code. |
name |
str |
Operation name. |
accuracy |
float or None |
Accuracy in meters, or None if unspecified. |
area_of_use |
str |
Area of use, such as 'Spain - mainland except northwest'. |
grid_files |
list[str] |
Required grids; empty if none. |
scope |
str or None |
EPSG operation purpose. |
remarks |
str or None |
Remarks. |
information_source |
str or None |
Publishing organization. |
WktVersion
WKT dialect written by Crs.to_wkt.
| Value | Dialect |
|---|---|
WKT1 |
OGC WKT 1 (OGC 01-009). Default. |
WKT1_ESRI |
ESRI WKT 1 without EPSG code, used by ArcGIS .prj. |
WKT1_ESRI_WITH_EPSG_CODE |
ESRI WKT 1 with EPSG code. |
WKT2_2015 |
ISO 19162:2015 WKT 2 (OGC 12-063r5). |
WKT2_2019 |
ISO 19162:2019 WKT 2 (OGC 18-010r7). |
UnknownCrsPolicy
Controls transformation when one CRS is local or unknown and the other is not.
| Value | Description |
|---|---|
REJECT |
Refuses transformation. Default. |
IDENTITY |
Returns unchanged coordinates, assuming the same reference frame and units. |
Exceptions
All derive from CrsError, itself derived from RuntimeError. except crskit.CrsError catches all.
| Exception | Raised when |
|---|---|
CrsError |
Uninitialized library, missing or unreadable EPSG database; base class for the others. |
AuthorityCodeNotFoundError |
EPSG code absent from the database. |
WktParseError |
Unparseable WKT. |
TransformationNotFoundError |
No operation exists, or multiple operations exist without select_operation. |
GridFileNotFoundError |
Missing grid. Properties: grid_file (name), searched_path, operation_code (EPSG code or None), operation_name, area_of_use and information_source. |
CoordinateOutsideDomainError |
Point outside grid or projection domain. |
DimensionMismatchError |
Point coordinate count differs from transformation requirements. |
UnsupportedFormatError |
Unsupported CRS type or operation method. |