`CoordinateTransformer`#

Class Methods

`CoordinateTransformer.from_pipeline`(...)	Create a transformer from a PROJ pipeline definition.
`CoordinateTransformer.from_crs`(crs_s, crs_t)	Create a coordinate transformer from source CRS to target CRS.

Methods

`CoordinateTransformer.is_3d`(coo)	Return whether the coordinate array has a Z component.
`CoordinateTransformer.transform`(coordinates)	Transform coordinates using the configured transformer chain.

Properties

`CoordinateTransformer.source_crs`	Return the source CRS of the transformer chain.
`CoordinateTransformer.target_crs`	Return the target CRS of the transformer chain.

class weitsicht.CoordinateTransformer(transformer: Transformer)[source]#

class weitsicht.CoordinateTransformer(transformer: list[Transformer])

Bases: object

Class to handle transformations of coordinates. Basically a little pyproj wrapper with basic functions needed in the package.

Parameters:: transformer (Transformer | list[Transformer])

__init__(transformer: Transformer)[source]#

__init__(transformer: list[Transformer])

Create a transformer wrapper.

Parameters:: transformer (Transformer | list[Transformer]) – A single pyproj transformer or a chain of transformers.

property source_crs: CRS | None#: Return the source CRS of the transformer chain.

property target_crs: CRS | None#: Return the target CRS of the transformer chain.

classmethod from_pipeline(proj_pipeline: str)[source]#

Create a transformer from a PROJ pipeline definition.

Parameters:: proj_pipeline (str) – PROJ pipeline string.
Returns:: Transformer instance.
Return type:: CoordinateTransformer
Raises:: CoordinateTransformationError – If the pipeline cannot be established.

classmethod from_crs(crs_s: CRS | None, crs_t: CRS | None) → CoordinateTransformer | None[source]#

Create a coordinate transformer from source CRS to target CRS.

If both CRSs are None or equal, this returns None (no transformation required).

Parameters:

crs_s (CRS | None) – Source CRS, or None.
crs_t (CRS | None) – Target CRS, or None.

Returns:

Coordinate transformer or None if no transformation is required.

Return type:

CoordinateTransformer | None

Raises:

ValueError – If only one CRS is None.
CoordinateTransformationError – If establishing a transformation fails.

static is_3d(coo: ArrayNx2 | ArrayNx3)[source]#

Return whether the coordinate array has a Z component.

Parameters:: coo (ArrayNx2 | ArrayNx3) – Coordinate array.
Returns:: True if the input has shape N×3.
Return type:: bool

transform(coordinates: ArrayNx3 | ArrayNx2, direction: str = 'forward') → ArrayNx3 | ArrayNx2[source]#

Transform coordinates using the configured transformer chain.

Parameters:

coordinates (ArrayNx3 | ArrayNx2) – Coordinates to transform as N×2 (2D) or N×3 (3D).
direction (str) – Transform direction (forward, inverse, identity), defaults to forward.

Returns:

Transformed coordinates with the same dimensionality as input.

Return type:

ArrayNx3 | ArrayNx2

Raises:

CoordinateTransformationError – If input dimensions are invalid or a transformation fails.

transform_vector(coordinates_start: ArrayNx3, vector: ArrayNx3, direction: str = 'forward') → ArrayNx3[source]#

Transform direction vectors using the configured transformer chain.

Vectors can not be transformed directly through most CRS transformations, therefore this helper transforms two points per vector and derives the resulting direction: start and start + unit(vector) * 10 (i.e. 10 units along the provided vector direction).

Parameters:

coordinates_start (ArrayNx3) – Start coordinates (N×3).
vector (ArrayNx3) – Direction vectors in the source CRS (N×3 or single 3-vector).
direction (str) – Transform direction (forward, inverse, identity), defaults to forward.

Returns:

Unit direction vectors in the target CRS (N×3).

Return type:

ArrayNx3

Raises:

ValueError – If input shapes are incompatible or vectors have zero length.
CoordinateTransformationError – If transforming coordinates fails.

transform_rotation_matrix(coordinates_start: ArrayNx3, rotation_matrix: ndarray, direction: str = 'forward', orthonormalize: bool = True) → ndarray[source]#

Transform rotation matrices between CRSs by transforming their basis axes.

The rotation matrix convention in weitsicht is:

v_world = R @ v_local

i.e. the columns of R are the local basis axes expressed in the world CRS.

This helper transforms those three axes using transform_vector() evaluated at coordinates_start and re-assembles a rotation matrix in the target CRS.

Since many CRS transformations are not strictly rigid, the transformed axes may not be perfectly orthogonal. If orthonormalize is True, the result is projected onto SO(3) via an SVD-based orthonormalization, enforcing det(R)=+1.

Parameters:

coordinates_start (ArrayNx3) – Start coordinates (N×3) where the rotation is defined.
rotation_matrix (numpy.ndarray) – Rotation matrix (3×3) or stacked (N×3×3).
direction (str) – Transform direction (forward, inverse), defaults to forward.
orthonormalize (bool) – Re-orthonormalize the transformed axes, defaults to True.

Returns:

Transformed rotation matrix (3×3) or stacked (N×3×3).

Return type:

numpy.ndarray

Raises:

ValueError – If input shapes are incompatible.

CoordinateTransformer#

`CoordinateTransformer`#