ImageOrtho

For deeper information about the concept see: Ortho Photo

Class Methods

ImageOrtho.from_file(path[, crs, mapper])	Create an orthophoto image model from a raster file.
ImageOrtho.from_dict(param_dict[, mapper])	Create an ImageOrtho from a parameter dictionary.

Main API Methods

ImageOrtho.project(coordinates[, crs_s, ...])	Project 3D coordinates into orthophoto pixel coordinates.
ImageOrtho.map_center_point([mapper, ...])	Map the orthophoto center pixel to 3D coordinates via a mapper.
ImageOrtho.map_footprint([points_per_edge, ...])	Map the orthophoto footprint polygon to 3D coordinates via a mapper.
ImageOrtho.map_points(points_image[, ...])	Map orthophoto pixel coordinates to 3D coordinates via a mapper.

additional helpful Methods

ImageOrtho.from_dict(param_dict[, mapper])	Create an ImageOrtho from a parameter dictionary.
ImageOrtho.position_to_crs(crs_t[, transformer])	Return the orthophoto center position in the target CRS.

Properties

ImageOrtho.type	Return the image model type.
ImageOrtho.param_dict	Return image parameters as a dictionary.
ImageOrtho.mapper
ImageOrtho.is_geo_referenced	Return whether the image is geo-referenced.
ImageOrtho.position_wgs84
ImageOrtho.position_wgs84_geojson
ImageOrtho.crs	Return the image world CRS.
ImageOrtho.crs_wkt	Return images CRS as wkt string
ImageOrtho.crs_proj4	Return images CRS as proj4 string
ImageOrtho.width	Return width of image (column number)
ImageOrtho.height	Return height of image (row number)
ImageOrtho.shape	Return shape of image as tuple(width, height)

class weitsicht.ImageOrtho(width: float | int, height: float | int, geo_transform: Affine | None = None, resolution: float = 0.0, crs: CRS | None = None, mapper: MappingBase | None = None)

Bases: ImageBase

Orthophoto image model based on an affine geotransform.

This image type uses an affine transform to convert between image pixel coordinates and world coordinates on a plane (x/y). Heights can optionally be provided via a mapper.

Parameters:

• width (float | int)

• height (float | int)

• geo_transform (rasterio.Affine | None)

• resolution (float)

• crs (CRS | None)

• mapper (MappingBase | None)

__init__(width: float | int, height: float | int, geo_transform: Affine | None = None, resolution: float = 0.0, crs: CRS | None = None, mapper: MappingBase | None = None)

Initialize an orthophoto image model.

Parameters:

• width (float | int) – Image width in pixels.

• height (float | int) – Image height in pixels.

• geo_transform (rasterio.Affine | None) – Affine geotransform, defaults to None.

• resolution (float) – Pixel resolution in world units, defaults to 0.0. If 0.0 and a geotransform is provided, the mean scaling of the transform is used.

• crs (CRS | None) – World CRS of the orthophoto, defaults to None.

• mapper (MappingBase | None) – Mapping instance used for height queries, defaults to None.

classmethod from_file(path: Path | str, crs: CRS | None = None, mapper: MappingBase | None = None) → ImageOrtho

Create an orthophoto image model from a raster file.

Parameters:

• path (Path | str) – Path to the raster file.

• crs (CRS | None) – CRS which overrides the file CRS, defaults to None.

• mapper (MappingBase | None) – Mapping instance, defaults to None.

Returns:

Image model instance.

Return type:

ImageOrtho

Raises:

Exception – If rasterio cannot read the file or required metadata is unavailable.

property resolution: float

Return the pixel resolution in world units.

Returns:

Resolution value.

Return type:

float

property type

Return the image model type.

Returns:

Image type.

Return type:

ImageType

classmethod from_dict(param_dict: dict, mapper: MappingBase | None = None) → ImageOrtho

Create an ImageOrtho from a parameter dictionary.

Required keys are: - width - height

Optional keys are: - geo_transform (Affine as dict) - resolution - crs (WKT)

Parameters:

• param_dict (dict) – Dictionary with image parameters.

• mapper (MappingBase | None) – Mapping instance, defaults to None.

Returns:

Image model instance.

Return type:

ImageOrtho

Raises:

• KeyError – If required keys are missing.

• ValueError – If values are invalid.

• TypeError – If values have incompatible types.

• CRSInputError – If the CRS WKT string is invalid or unsupported.

property param_dict: dict

Return image parameters as a dictionary.

The returned dictionary is compatible with from_dict().

Returns:

Image parameters.

Return type:

dict

property center: tuple[float, float]

Return the image center in pixel coordinates.

Returns:

Center point (x, y) in pixel coordinates.

Return type:

tuple[float, float]

property is_geo_referenced: bool

Return whether the image is geo-referenced.

Returns:

True if a geotransform is set, otherwise False.

Return type:

bool

image_points_inside(point_image_coordinates: ArrayNx2) → MaskN_

Return whether image pixel coordinates are inside the raster bounds.

Parameters:

point_image_coordinates (ArrayNx2) – Image pixel coordinates (image CRS).

Returns:

Boolean mask of shape (N,).

Return type:

MaskN_

Raises:

• ValueError – If the input cannot be converted to an (N, 2) array.

• TypeError – If the input has incompatible types.

position_to_crs(crs_t: CRS, transformer: CoordinateTransformer | None = None) → Vector3D | None

Return the orthophoto center position in the target CRS.

If a mapper is available, the Z value is obtained by mapping the center point.

Parameters:

• crs_t (CRS) – Target CRS.

• transformer (CoordinateTransformer | None) – Optional coordinate transformer, defaults to None.

Returns:

Center position in crs_t or None if unavailable.

Return type:

Vector3D | None

Raises:

• CRSInputError – If CRS/transformer input is invalid.

• CoordinateTransformationError – If coordinate transformation fails.

project(coordinates: ArrayNx3 | ArrayNx2, crs_s: CRS | None = None, transformer: CoordinateTransformer | None = None) → ProjectionResultSuccess | ResultFailure[Issue]

Project 3D coordinates into orthophoto pixel coordinates.

Once the coordinates from the coordinates crs (crs_s) are transformed to the mapper crs, then onlyx/y coordinates are used for the affine transform; z is ignored.

The reason of the tranformatoin from crs_s to mapper crs is why also here for orthophoto, 3D coordiantes must be used as input.

Parameters:

• coordinates (ArrayNx3) – 3D coordinates to project.

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

• transformer (CoordinateTransformer | None) – Optional coordinate transformer, defaults to None.

Returns:

Projection result.

Return type:

ProjectionResult

Raises:

• ValueError – If CRS/transformer inputs are inconsistent.

• NotGeoreferencedError – If the image is not geo-referenced.

• CRSInputError – If CRS/transformer input is invalid.

• CoordinateTransformationError – If coordinate transformation fails.

map_center_point(mapper: MappingBase | None = None, transformer: CoordinateTransformer | None = None) → MappingResultSuccess | ResultFailure[Issue]

Map the orthophoto center pixel to 3D coordinates via a mapper.

Parameters:

• mapper (MappingBase | None) – Mapper to use, defaults to None (uses mapper).

• transformer (CoordinateTransformer | None) – Optional coordinate transformer, defaults to None.

Returns:

Mapping result.

Return type:

MappingResult

Raises:

• NotGeoreferencedError – If the image is not geo-referenced.

• MapperMissingError – If no mapper is available.

• CRSInputError – If the mapper rejects CRS/transformer input.

• CoordinateTransformationError – If coordinate transformation fails.

• WeitsichtError – Base class for all weitsicht exceptions. Catch this to handle any weitsicht error; catch specific subclasses first if you need to distinguish causes.

map_footprint(points_per_edge: int = 0, mapper: MappingBase | None = None, transformer: CoordinateTransformer | None = None) → MappingResultSuccess | ResultFailure[Issue]

Map the orthophoto footprint polygon to 3D coordinates via a mapper.

Parameters:

• points_per_edge (int) – Number of points inserted between corners, defaults to 0. Values < 1 map only the corner points.

• mapper (MappingBase | None) – Mapper to use, defaults to None (uses mapper).

• transformer (CoordinateTransformer | None) – Optional coordinate transformer, defaults to None.

Returns:

Mapping result.

Return type:

MappingResult

Raises:

• NotGeoreferencedError – If the image is not geo-referenced.

• MapperMissingError – If no mapper is available.

• CRSInputError – If the mapper rejects CRS/transformer input.

• CoordinateTransformationError – If coordinate transformation fails.

• WeitsichtError – Base class for all weitsicht exceptions. Catch this to handle any weitsicht error; catch specific subclasses first if you need to distinguish causes.

map_points(points_image: ArrayNx2 | ArrayNx3 | list[list[float]] | list[list[int]] | list[float] | list[int], mapper: MappingBase | None = None, transformer: CoordinateTransformer | None = None) → MappingResultSuccess | ResultFailure[Issue]

Map orthophoto pixel coordinates to 3D coordinates via a mapper.

Parameters:

• points_image (ArrayNx2 | ArrayNx3 | list[list[float]] | list[list[int]] | list[float] | list[int]) – Pixel coordinates (image CRS).

• mapper (MappingBase | None) – Mapper to use, defaults to None (uses mapper).

• transformer (CoordinateTransformer | None) – Optional coordinate transformer, defaults to None.

Returns:

Mapping result.

Return type:

MappingResult

Raises:

• ValueError – If points_image cannot be parsed as an array of 2D points.

• TypeError – If points_image has incompatible types.

• NotGeoreferencedError – If the image is not geo-referenced.

• MapperMissingError – If no mapper is available.

• CRSInputError – If the mapper rejects CRS/transformer input.

• CoordinateTransformationError – If coordinate transformation fails.

• WeitsichtError – Base class for all weitsicht exceptions. Catch this to handle any weitsicht error; catch specific subclasses first if you need to distinguish causes.