transform

geodetic_engine.geodesy.transform(source_crs, target_crs, x, y=None, z=None, *, operation=None, allow_any_operation=False, coordinate_epoch=None)[source]

Transform points between two CRSs in one call.

A thin front for Transformation for the case where the transformation is used once. Resolved transformations are cached, so repeating the same call does not repeat the resolution. Prefer building a Transformation directly when transforming many separate batches.

Parameters:

  • source_crs (Any) – CRS the input coordinates are in.

  • target_crs (Any) – CRS to produce coordinates in.

  • x (Iterable[Iterable[float]] | Iterable[float] | float) – Either every point’s values in one go – a single point given flat such as (lon, lat), a list of tuples, or a 2D numpy array of shape (n_points, n_axes) – when y is omitted; or just the first axis’s values, matching pyproj.Transformer.transform()’s xx, yy, zz convention, when y is given.

  • y (Iterable[float] | float | None, default: None) – Second axis’s values: a scalar for one point, or a sequence for a batch. Omit to pass x as the whole set of points instead.

  • z (Iterable[float] | float | None, default: None) – Third axis’s values (for example a height), in the same shape as x and y. A lone scalar is broadcast against the other axes, so one height can be given once for many horizontal points rather than repeated.

  • operation (str | int | OperationCandidate | StatedOperation | CoordinateOperation | Sequence[str | int | OperationCandidate | StatedOperation | CoordinateOperation] | None, default: None) – EPSG coordinate operation to apply, for example "EPSG:15670", or an OperationCandidate from available_operations(). Or several, when a compound target CRS needs more than one pinned down – order does not matter, see Transformation. Or the operation itself, stated as an OSDU persistableReference payload, an ESRI GEOGTRAN, a pyproj.crs.CoordinateOperation or a parsed reference, which is then applied as given rather than looked up. Required whenever a datum change is involved, except where a bound CRS already names it.

  • allow_any_operation (bool, default: False) – Compatibility keyword with no effect on strict datum-operation selection or ballpark refusal.

  • coordinate_epoch (float | None, default: None) – Decimal year the coordinates were observed at, required when the selected operation reads time. A dynamic CRS alone does not require an epoch.

Return type:

TransformationResult

Returns:

The transformed coordinates and their provenance.

Raises:

AmbiguousOperationError – If no operation was given, the transformation involves an unbound datum change.

Example

>>> result = transform(
...     "EPSG:4258", "EPSG:25832", (10.75, 59.91),
...     operation="EPSG:16032",
... )
>>> result.operation.authority_code
'EPSG:16032'
>>> result.target_axes
('E', 'N')

Or as separate per-axis values:

>>> result = transform(
...     "EPSG:4258", "EPSG:25832", 10.75, 59.91, operation="EPSG:16032"
... )
>>> result.coordinates
((597868.38..., 6642681.51...),)