shapelib.core package#

Core modules for shapelib.

This package contains: - geometries: BaseShapes, Polygons, Lines, Points, Empty - handlers: Local file format handlers - cloud: Cloud storage support (handlers, providers, writers) - ports: Interface definitions

Subpackages#

Submodules#

shapelib.core.transformations module#

Precise CRS transformations: bundled IBGE grids and best-only transformations.

Converting coordinates between datums needs a datum shift. For Brazil’s legacy datums — SAD69, SAD69(96), Córrego Alegre 1961 and 1970-72 — the official shift is IBGE’s correction grid. pyproj wheels ship no grids, and without them PROJ silently falls back to a formula that is metres off (SAD69 up to ~7.5 m) or, for Córrego Alegre 1961, which has no formula, to a “ballpark” transformation that ignores the datum shift altogether (~50 m off). Nothing signals the fallback, and coordinates that fail to transform become inf.

This module removes those silent paths:

  • register_bundled_grids adds the four IBGE grids shipped with shapelib (shapelib/data/proj) to PROJ’s search path, so the official shift is used offline;

  • transform_geometries transforms with the best transformation PROJ knows only (only_best), never a ballpark one, never a datum shift outside its area of use (PROJ would otherwise apply, say, Mexico’s NAD27 shift to a point in São Paulo), and checks every coordinate; when that cannot be done it raises DatumTransformationError instead of degrading;

  • datum_shift tells whether a CRS’s datum needs a shift to reach WGS 84, and how accurate that shift is, so data in a legacy datum can be flagged.

class shapelib.core.transformations.DatumShift(operation, accuracy)[source]#

Bases: object

A datum shift applied to reach WGS 84.

Variables:

  • operation (str) – The transformation used, as PROJ describes it.

  • accuracy (float | None) – Its published accuracy in metres, or None when none is published (e.g. TOWGS84 parameters taken from a .prj).

Parameters:

  • operation (str)

  • accuracy (float | None)

operation: str#
accuracy: float | None#
shapelib.core.transformations.register_bundled_grids()[source]#

Add the IBGE grids bundled with shapelib to PROJ’s search path.

Called when shapelib is imported, before any transformation. Idempotent.

Examples

>>> register_bundled_grids()
>>> str(BUNDLED_GRIDS_DIR) in pyproj.datadir.get_data_dir()
True
Return type:

None

shapelib.core.transformations.transform_geometries(geometries, source, target)[source]#

Transform geometries between CRSs with the best transformation known, or fail.

Before anything is transformed, the transformation is validated where the data lies (see _validate_where_the_data_lies): a datum shift is only accepted inside its area of use. Then every coordinate is transformed with errcheck, so a coordinate the best transformation cannot handle raises instead of silently becoming inf. Null and empty geometries are passed through; Z values are transformed when present.

Parameters:

  • geometries (ndarray) – Shapely geometries in source.

  • source (CRS) – The CRSs to transform from and to.

  • target (CRS) – The CRSs to transform from and to.

Returns:

The geometries in target.

Return type:

ndarray

Raises:

DatumTransformationError – If the best transformation cannot be used: it needs a grid that is not installed, there is no known transformation between the datums, or the only one known is not defined where the data lies.

Big-O

O(V) in the total number of vertices.

shapelib.core.transformations.datum_shift(crs, geometries)[source]#

The datum shift taking data in crs to WGS 84, or None if it needs none.

The transformation is validated where the data lies, as in transform_geometries. PROJ may use different transformations across a region (a grid covers one area and a formula another), so the shift is read at the data’s extreme vertices and in its middle, and the least accurate one found is returned.

Parameters:

  • crs (CRS) – The CRS of the data.

  • geometries (ndarray) – The data’s shapely geometries, in crs.

Returns:

The shift, or None when reaching WGS 84 applies no datum shift (WGS 84, SIRGAS 2000 and other modern datums).

Return type:

DatumShift | None

Raises:

DatumTransformationError – If the data cannot be transformed to WGS 84 with the best accuracy known.

Examples

>>> datum_shift(CRS.from_epsg(29193), geometries)  # SAD69 / UTM zone 23S
DatumShift(operation='... SAD69 to WGS 84 (15) ...', accuracy=2.0)