geovista.transform#

Coordinate reference system (CRS) transformation functions.

Notes#

Added in version 0.3.0.

Functions#

transform_mesh(mesh, /, tgt_crs, *[, ...])

Transform the mesh from its source CRS to the target CRS.

transform_point(src_crs, tgt_crs, x, y[, z, trap])

Transform the spatial point from the source to the target CRS.

transform_points(src_crs, tgt_crs, xs, ys[, zs, trap])

Transform the spatial points from the source to the target CRS.

Module Contents#

geovista.transform.transform_mesh(mesh, /, tgt_crs, *, slice_connectivity=True, globe=None, zlevel=None, zscale=None, rtol=None, atol=None, inplace=False)[source]#

Transform the mesh from its source CRS to the target CRS.

Parameters:
meshPolyData

The mesh to be transformed from its source coordinate reference system (CRS) to the given tgt_crs.

tgt_crsCRSLike

The target coordinate reference system (CRS) of the transformation. May be anything accepted by pyproj.crs.CRS.from_user_input().

slice_connectivitybool, default=True

Slice the mesh prior to transformation in order to break mesh connectivity and create a seam in the mesh. Also see geovista.core.slice_mesh().

globeGlobe, optional

The globe to place the mesh on, at its render radius, which the mesh transformed records. Defaults to the globe the mesh records, else Globe().

zlevelint or ArrayLike, default=0

The z-axis level. Used in combination with the zscale to offset the render radius/vertical by a proportional amount e.g., render_radius * zlevel * zscale. In a planar CRS the offset is zlevel * zscale times the radius of the Earth in the units of that CRS, the same proportion as on the sphere. If zlevel is not a scalar, then it must broadcast to the shape (mesh.n_points,). For a point cloud, zlevel adds to the z-level each of its points already carries.

zscalefloat, optional

The proportional multiplier for z-axis zlevel. Defaults to the multiplier a point cloud carries, otherwise geovista.common.ZLEVEL_SCALE.

rtolfloat, optional

The relative tolerance for longitudes close to the ‘wrap meridian’ - see geovista.common.wrap() for more.

atolfloat, optional

The absolute tolerance for longitudes close to the ‘wrap meridian’ - see geovista.common.wrap() for more.

inplacebool, default=False

Update the mesh in-place. Can only perform an in-place operation when slice_connectivity=False.

Returns:
PolyData

The mesh transformed to the target coordinate reference system (CRS).

Notes

A point cloud keeps its z-levels from one transform to the next. On the sphere they are encoded in the radius of each point, and in a planar CRS they are carried in the geovista.common.GV_POINT_ZLEVEL point array. The cloud also carries the globe and zscale that encode them, so a value given here becomes its own.

A mesh with heights is placed by them, and takes no zlevel other than 0, nor a tgt_crs with an axis named “Ellipsoidal height”, as its heights are above mean sea level. On the sphere a point lies at a radius of s (R + V(h)), for the vertical mapping V of the globe. In any other CRS it lies at z = V(h), in the length unit of its axes, or where those are angular, at the angle V(h) subtends at R, in their angular unit.

A mesh already in the target CRS is not transformed, so no point moves and its globe is unchanged. Use geovista.core.resize() to change its globe.

Added in version 0.3.0.

geovista.transform.transform_point(src_crs, tgt_crs, x, y, z=None, *, trap=True)[source]#

Transform the spatial point from the source to the target CRS.

The point is missing when its x or y value is masked or NaN, and gives NaN in every component, without being transformed (positions spec §4.7). An infinite x or y value is refused.

Parameters:
src_crsCRSLike

The source Coordinate Reference System (CRS) of the provided x, y and z spatial point. May be anything accepted by pyproj.crs.CRS.from_user_input().

tgt_crsCRSLike

The target Coordinate Reference System (CRS) of the transform for the spatial point. May be anything accepted by pyproj.crs.CRS.from_user_input().

xArrayLike or pint.Quantity

The spatial point x-value, in canonical src_crs units, to be transformed from the src_crs to the tgt_crs. Must be a scalar or a single valued 1D array. A pint quantity, from any registry, carries its own units, and is read in those of the src_crs. Give y as a quantity too.

yArrayLike or pint.Quantity

The spatial point y-value, in canonical src_crs units, to be transformed from the src_crs to the tgt_crs. Must be a scalar or a single valued 1D array. A pint quantity, from any registry, carries its own units, and is read in those of the src_crs. Give x as a quantity too.

zArrayLike, optional

The spatial point z-value, in canonical src_crs units, to be transformed from the src_crs to the tgt_crs. Must be a scalar or a single valued 1D array.

trapbool, default=True

Raise an exception if an error occurs during CRS transformation of the spatial point. Otherwise, inf will be returned for the erroneous point.

Returns:
ndarray

The transformed spatial point in the canonical units of the target CRS. The shape of the result will be (3,).

Notes

Added in version 0.4.0.

geovista.transform.transform_points(src_crs, tgt_crs, xs, ys, zs=None, *, trap=True)[source]#

Transform the spatial points from the source to the target CRS.

A position is missing when its x or y value is masked or NaN, and gives a row of NaN, z included, without being transformed (positions spec §4.7). An infinite x or y value is refused.

Parameters:
src_crsCRSLike

The source Coordinate Reference System (CRS) of the provided xs, ys and zs spatial points. May be anything accepted by pyproj.crs.CRS.from_user_input().

tgt_crsCRSLike

The target Coordinate Reference System (CRS) of the transform for the spatial points. May be anything accepted by pyproj.crs.CRS.from_user_input().

xsArrayLike or pint.Quantity

The spatial points x-values, in canonical src_crs units, to be transformed from the src_crs to the tgt_crs. May be scalar, 1D or 2D. A pint quantity, from any registry, carries its own units, and is read in those of the src_crs. Give ys as a quantity too.

ysArrayLike or pint.Quantity

The spatial points y-values, in canonical src_crs units, to be transformed from the src_crs to the tgt_crs. May be scalar, 1D or 2D. A pint quantity, from any registry, carries its own units, and is read in those of the src_crs. Give xs as a quantity too.

zsArrayLike, optional

The spatial points z-values, in canonical src_crs units, to be transformed from the src_crs to the tgt_crs. May be scalar, 1D or 2D.

trapbool, default=True

Raise an exception if an error occurs during CRS transformation of the spatial points. Otherwise, inf will be returned for erroneous points.

Returns:
ndarray

The transformed spatial points in the canonical units of the target CRS. The shape of the result will either be (1, 3), (M, 3) or (M, N, 3) depending on whether the provided spatial points were scalar, 1D or 2D, respectively.

Notes

Added in version 0.4.0.