`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)

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)

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[source]#

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:

FileNotFoundError – If path does not exist.
rasterio.errors.RasterioIOError – If the raster cannot be opened/read.
pyproj.exceptions.CRSError – If the dataset CRS cannot be parsed/converted.

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[source]#

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_[source]#

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[source]#

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][source]#

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][source]#

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][source]#

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 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.

ImageOrtho#

`ImageOrtho`#