MappingRaster

For deeper information about the concept see: Raster Mapper

Class Methods

MappingRaster.from_dict(mapper_dict)

Create a MappingRaster instance from a configuration dictionary.

Main API Methods

MappingRaster.map_coordinates_from_rays(...)	Map coordinates by intersecting rays with the raster surface.
MappingRaster.map_heights_from_coordinates(...)	Sample heights for given coordinates using bilinear interpolation.

Methods Raster specific

This functions can be used to interact with the raster and coordinates

MappingRaster.pixel_to_coordinate(px_row, px_col)	Convert pixel indices to coordinates in raster CRS.
MappingRaster.pixel_valid(px_row, px_col)	Return whether pixel coordinates are within raster bounds.
MappingRaster.coordinate_on_raster(x_crs, y_crs)	Test if given coordinates in raster CRS are on the raster
MappingRaster.coordinate_to_pixel(x_crs, y_crs)	Get pixel position of coordinates
MappingRaster.get_coordinate_height(x_crs, y_crs)	Get raster value of coordinates in Raster CRS coordinates
MappingRaster.intersection_ray(...[, crs_s, ...])	Calculate the intersection of a single ray with the raster surface.
MappingRaster.load_window([limits_crs])	Load raster data into georef_array.

Properties

MappingRaster.type	Return the mapper type.
MappingRaster.backend	Return the active mapping backend.
MappingRaster.georef_mapper	Return the in-memory MappingGeorefArray backend.
MappingRaster.param_dict	Return the mapper configuration dictionary.
MappingRaster.crs	Return the CRS of the mapper (if set).
MappingRaster.crs_wkt	Return the CRS as WKT string, or None if not set.
MappingRaster.resolution	Return the raster resolution.
MappingRaster.transform	Return the affine geo-transform of the raster.
MappingRaster.width	Return raster width in pixels.
MappingRaster.height	Return raster height in pixels.

class weitsicht.MappingRaster(raster_path: Path | str, crs: CRS | None = None, force_no_crs: bool = False, preload_full_raster: bool = False, preload_window: None | tuple[float, float, float, float] = None, index_band: int | None = None)

Bases: MappingBase

Mapping backend using a geo-referenced raster for height sampling and ray intersections.

Parameters:

• raster_path (Path | str)

• crs (CRS | None)

• force_no_crs (bool)

• preload_full_raster (bool)

• preload_window (None | tuple[float, float, float, float])

• index_band (int | None)

__init__(raster_path: Path | str, crs: CRS | None = None, force_no_crs: bool = False, preload_full_raster: bool = False, preload_window: None | tuple[float, float, float, float] = None, index_band: int | None = None)

Create a raster-based mapper.

Provide a valid path for a raster which can be loaded via rasterio.

Parameters:

• raster_path (Path | str) – Path to a raster readable by rasterio.

• crs (CRS | None) – CRS overriding the raster’s internal CRS, defaults to None.

• force_no_crs (bool) – If True the CRS will be set to None regardless of raster metadata, defaults to False.

• preload_full_raster (bool) – If True preload the full raster into memory, defaults to False.

• preload_window (tuple[float, float, float, float] | None) – Optional window to preload as (xmin, ymin, xmax, ymax) in mapper CRS, defaults to None.

• index_band (int | None) – Band index to load (1-based). Mandatory if raster has more than one band, defaults to None.

Raises:

• ValueError – If input arguments are inconsistent or invalid.

• FileNotFoundError – If raster_path does not exist.

• CRSInputError – If CRS input is missing or invalid.

• CRSnoZaxisError – If the mapper CRS does not define a Z axis.

• MappingError – If the raster cannot be opened or is not geo-referenced.

property type

Return the mapper type.

Returns:

Mapper type.

Return type:

MappingType

property backend: MappingBase

Return the active mapping backend.

If a raster window (or the full raster) was preloaded via load_window() / preload_window / preload_full_raster, this returns the in-memory MappingGeorefArray backend. Otherwise, it returns self.

property georef_mapper: MappingGeorefArray

Return the in-memory MappingGeorefArray backend.

Raises:

MappingError – If no in-memory window/full raster was loaded.

classmethod from_dict(mapper_dict: Mapping[str, Any]) → MappingRaster

Create a MappingRaster instance from a configuration dictionary.

Required keys: - raster_filepath: file path to the raster - crs: CRS WKT string (or None to force no CRS)

Optional keys: - band: band index (1-based), defaults to None - preload_window: preload window in mapper CRS as (xmin, ymin, xmax, ymax), defaults to None - preload_full: preload full raster, defaults to False

Parameters:

mapper_dict (Mapping[str, Any]) – Mapper configuration dictionary (typically created via mapper.param_dict).

Returns:

Instantiated mapper.

Return type:

MappingRaster

Raises:

• KeyError – If a required dictionary key is missing.

• FileNotFoundError – If the raster file does not exist.

• ValueError – If configuration values are invalid.

• CRSInputError – If the CRS WKT string is invalid.

• CRSnoZaxisError – If the mapper CRS does not define a Z axis.

• MappingError – If the raster cannot be opened or is not geo-referenced.

property param_dict

Return the mapper configuration dictionary.

Returns:

Mapper configuration dictionary.

Return type:

dict[str, Any]

property resolution

Return the raster resolution.

Returns:

Mean raster resolution in CRS units.

Return type:

float

property transform: Affine

Return the affine geo-transform of the raster.

Returns:

Affine geo-transform.

Return type:

Affine

property width

Return raster width in pixels.

property height

Return raster height in pixels.

load_window(limits_crs: tuple[float, float, float, float] | None = None) → MappingGeorefArray

Load raster data into georef_array.

Parameters:

limits_crs (tuple[float, float, float, float] | None) – Optional window limits as (xmin, ymin, xmax, ymax) in mapper CRS, defaults to None (loads full raster).

Raises:

MappingError – If the provided window is not fully inside the raster extent.

Return type:

MappingGeorefArray

pixel_to_coordinate(px_row: float, px_col: float) → tuple

Convert pixel indices to coordinates in raster CRS.

Parameters:

• px_row (float) – Pixel row coordinate

• px_col (float) – Pixel column coordinate

Returns:

(x, y) coordinate in raster CRS.

Return type:

tuple[float, float]

pixel_valid(px_row: float, px_col: float) → bool

Return whether pixel coordinates are within raster bounds.

Parameters:

• px_row (float) – Pixel row coordinate

• px_col (float) – Pixel column coordinate

Returns:

True if valid.

Return type:

bool

pixel_valid_mat(px_row: ArrayN_, px_col: ArrayN_) → MaskN_

Vectorized validity check for pixel coordinates.

Parameters:

• px_row (ArrayN_) – Array with Pixel row coordinate

• px_col (ArrayN_) – Array with Pixel column coordinate

Returns:

Boolean mask for valid pixels.

Return type:

MaskN_

coordinate_on_raster(x_crs: float, y_crs: float) → bool

Test if given coordinates in raster CRS are on the raster

Parameters:

• x_crs (float) – X coordinate

• y_crs (float) – Y coordinate

Returns:

True if on the raster.

Return type:

bool

coordinate_to_pixel(x_crs: float, y_crs: float) → tuple[float, float]

Get pixel position of coordinates

Parameters:

• x_crs (float) – X coordinate

• y_crs (float) – Y coordinate

Returns:

(row, col) pixel coordinates as floats.

Return type:

tuple[float, float]

coordinate_to_pixel_mat(x: ArrayN_, y: ArrayN_) → tuple[ArrayN_, ArrayN_]

Get pixel position of coordinates.

This is pure affine transformation, it will not check if the pixel are valid

Parameters:

• x (ArrayN_) – Array of X coordinate

• y (ArrayN_) – Array of Y coordinate

Returns:

(row, col) pixel coordinates.

Return type:

tuple[ArrayN_, ArrayN_]

get_coordinate_height(x_crs: float, y_crs: float) → float | None

Get raster value of coordinates in Raster CRS coordinates

Parameters:

• x_crs (float) – X coordinate

• y_crs (float) – Y coordinate

Returns:

Raster value or 0.0 if no-data / invalid.

Return type:

float

intersection_ray(ray_vector_crs_s: Vector3D, ray_start_crs_s: Vector3D, crs_s: CRS | None = None, transformer: CoordinateTransformer | None = None, max_iter: int = 20) → tuple[Vector3D, bool, bool, bool, Vector3D]

Calculate the intersection of a single ray with the raster surface.

The algorithm iteratively adjusts the intersection plane using heights sampled from the raster.

Parameters:

• ray_vector_crs_s (Vector3D) – Ray direction vector (3,).

• ray_start_crs_s (Vector3D) – Ray start point (3,).

• crs_s (CRS | None) – CRS of the ray input, defaults to None.

• transformer (CoordinateTransformer | None) – Coordinate transformer to mapper CRS, defaults to None.

• max_iter (int) – Maximum number of iterations, defaults to 20.

Returns:

Tuple (intersection_coordinates, is_invalid, is_outside_raster, Nodata height, normal in crs_s).

Return type:

tuple[Vector3D, bool, bool, Vector3D]

Raises:

• CRSInputError – If both crs_s and transformer are provided.

• CoordinateTransformationError – If coordinate transformation fails.

map_coordinates_from_rays(ray_vectors_crs_s: ArrayNx3, ray_start_crs_s: ArrayNx3, crs_s: CRS | None = None, transformer: CoordinateTransformer | None = None) → MappingResultSuccess | ResultFailure[Issue]

Map coordinates by intersecting rays with the raster surface.

Parameters:

• ray_vectors_crs_s (ArrayNx3) – Ray direction vectors (N×3).

• ray_start_crs_s (ArrayNx3) – Ray start points (N×3), same shape as ray_vectors_crs_s.

• crs_s (CRS | None) – CRS of the input rays, defaults to None.

• transformer (CoordinateTransformer | None) – Coordinate transformer to mapper CRS, defaults to None.

Returns:

Mapping result containing intersection coordinates and a validity mask.

Return type:

MappingResult

Raises:

• ValueError – If input arrays have incompatible shapes.

• CRSInputError – If both crs_s and transformer are provided.

• CoordinateTransformationError – If coordinate transformation fails.

map_heights_from_coordinates_sampling(coordinates_crs_s: ArrayNx3 | ArrayNx2, crs_s: CRS | None = None, transformer: CoordinateTransformer | None = None) → MappingResultSuccess | ResultFailure[Issue]

Sample heights using rasterio’s point sampling (no interpolation).

Parameters:

• coordinates_crs_s (ArrayNx3 | ArrayNx2) – Coordinates to sample (N×2 or N×3).

• crs_s (CRS | None) – CRS of the input coordinates, defaults to None.

• transformer (CoordinateTransformer | None) – Coordinate transformer to mapper CRS, defaults to None.

Returns:

Mapping result containing sampled coordinates and a validity mask.

Return type:

MappingResult

Raises:

• CRSInputError – If both crs_s and transformer are provided.

• CoordinateTransformationError – If coordinate transformation fails.

map_heights_from_coordinates(coordinates_crs_s: ArrayNx3 | ArrayNx2, crs_s: CRS | None = None, transformer: CoordinateTransformer | None = None) → MappingResultSuccess | ResultFailure[Issue]

Sample heights for given coordinates using bilinear interpolation.

Parameters:

• coordinates_crs_s (ArrayNx3 | ArrayNx2) – Coordinates to sample (N×2 or N×3).

• crs_s (CRS | None) – CRS of the input coordinates, defaults to None.

• transformer (CoordinateTransformer | None) – Coordinate transformer to mapper CRS, defaults to None.

Returns:

Mapping result containing sampled coordinates and a validity mask.

Return type:

MappingResult

Raises:

• CRSInputError – If both crs_s and transformer are provided.

• CoordinateTransformationError – If coordinate transformation fails.