ImagePerspective

Main API Methods

ImagePerspective.pixel_to_ray_vector(pixel_pos)	Calculate world ray direction vectors for image pixels.
ImagePerspective.project(coordinates[, ...])	Project 3D coordinates into image pixel coordinates.
ImagePerspective.map_center_point([mapper, ...])	Map the image center pixel (principal point) to 3D coordinates.
ImagePerspective.map_footprint([...])	Map the image footprint polygon to 3D coordinates.
ImagePerspective.map_points(points_image[, ...])	Map image pixel coordinates to 3D coordinates via a mapper.

additional helpful Methods

ImagePerspective.from_dict(param_dict[, mapper])	Create an ImagePerspective from a parameter dictionary.
ImagePerspective.position_to_crs(crs_t)	Return the camera position in the target CRS.

Properties

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

class weitsicht.ImagePerspective(width: float | int, height: float | int, camera: CameraBasePerspective | None, crs: CRS | None = None, position: Vector3D | None = None, orientation: Rotation | None = None, mapper: MappingBase | None = None)

Bases: ImageBase

Perspective image model.

The image is geo-referenced if position, orientation, camera and CRS are specified. The camera model implementation should support resampled images (i.e. account for calibration size vs. current image size).

Parameters:

• width (float | int)

• height (float | int)

• camera (CameraBasePerspective | None)

• crs (CRS | None)

• position (Vector3D | None)

• orientation (Rotation | None)

• mapper (MappingBase | None)

__init__(width: float | int, height: float | int, camera: CameraBasePerspective | None, crs: CRS | None = None, position: Vector3D | None = None, orientation: Rotation | None = None, mapper: MappingBase | None = None)

Initialize a perspective image model.

Parameters:

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

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

• camera (CameraBasePerspective | None) – Camera model used for projection/distortion, may be None for non-geo-referenced instances.

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

• position (Vector3D | None) – Camera position in world CRS, defaults to None.

• orientation (Rotation | None) – Camera orientation, defaults to None.

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

property type: ImageType

Return the image model type.

Returns:

Image type.

Return type:

ImageType

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

Create an ImagePerspective from a parameter dictionary.

Required keys are: - width - height

Optional keys are: - position (3D) - orientation_matrix (3x3) - crs (WKT) - camera (camera param_dict)

Parameters:

• param_dict (dict) – Dictionary with image parameters.

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

Returns:

Image model instance.

Return type:

ImagePerspective

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 is_geo_referenced: bool

Return whether the image is geo-referenced.

Returns:

True if position, orientation and camera are set, otherwise False.

Return type:

bool

property camera

Return the camera model used by this image.

Returns:

Camera model instance or None.

Return type:

CameraBasePerspective | None

property center: tuple[float, float]

Return the image center used for mapping/projection.

For perspective images this is the principal point as defined by the camera model.

Returns:

Center point (x, y) in image pixel coordinates.

Return type:

tuple[float, float]

Raises:

NotGeoreferencedError – If no camera model is specified.

image_points_inside(point_image_coordinates: ArrayNx2) → MaskN_

Return whether undistorted image points are valid for this camera model.

Within the camera class the distortion border is generated during initialization and is used to determine where distortion/undistortion is valid.

Parameters:

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

Returns:

Boolean mask of shape (N,).

Return type:

MaskN_

Raises:

NotGeoreferencedError – If no camera model is specified.

position_to_crs(crs_t: CRS) → Vector3D | None

Return the camera position in the target CRS.

Parameters:

crs_t (CRS) – Target CRS.

Returns:

Position in crs_t or None if unavailable.

Return type:

Vector3D | None

Raises:

CoordinateTransformationError – If coordinate transformation fails.

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

Project 3D coordinates into image pixel coordinates.

The projection is first computed in undistorted image coordinates. If to_distorted is True, only pixels within the camera model’s valid undistortion border are distorted; invalid pixels remain undistorted and are marked in the returned mask.

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.

• to_distorted (bool) – Whether to return distorted image coordinates, defaults to True.

Returns:

Projection result.

Return type:

ProjectionResult

Raises:

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

• CRSInputError – If both crs_s and transformer are provided.

• CoordinateTransformationError – If coordinate transformation fails.

pixel_to_ray_vector(pixel_pos: ArrayNx2, is_undistorted: bool = False) → ArrayNx3

Calculate world ray direction vectors for image pixels.

Parameters:

• pixel_pos (ArrayNx2) – Image pixel coordinates (pixel CRS).

• is_undistorted (bool) – Whether input pixels are already undistorted, defaults to False.

Returns:

Unit direction vectors in world CRS.

Return type:

ArrayNx3

Raises:

NotGeoreferencedError – If the image is not geo-referenced.

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

Map the image center pixel (principal point) to 3D coordinates.

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.

• MappingBackendError – If the mapping backend fails unexpectedly.

• 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 image footprint polygon to 3D coordinates.

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.

• MappingBackendError – If the mapping backend fails unexpectedly.

• 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, is_undistorted: bool = False) → MappingResultSuccess | ResultFailure[Issue]

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

It is also possible to pass undistorted pixels. This can be useful if you already computed undistorted pixel coordinates from the original distorted image content.

Parameters:

• points_image (ArrayNx2 | ArrayNx3 | list[list[float]] | list[list[int]] | list[float] | list[int]) – Pixel coordinates (distorted or undistorted).

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

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

• is_undistorted (bool) – Whether input pixels are already undistorted, defaults to False.

Returns:

Mapping result.

Return type:

MappingResult

Raises:

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

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

• MappingBackendError – If the mapping backend fails unexpectedly.

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

_estimate_gsd_for_mapped_points(pixels: ArrayNx2, ray_vectors: ArrayNx3, coordinates: ArrayNx3, normals: ArrayNx3, mask: MaskN_, is_undistorted: bool, *, pixel_step: float = 1.0) → tuple[float | None, ArrayN_]

Estimate GSD for mapped points.

Computes per-point GSD from the distance to each mapped 3D point and the angular separation of neighbouring pixel rays (no additional mapper calls).

Surface normals (in the same CRS as the mapped coordinates) are used to correct for oblique viewing angles. If normals are valid, neighbouring pixel rays are intersected with the local tangent plane at the mapped point. As a fallback, the range-sphere chord estimate is scaled by 1 / cos(incidence) where incidence is the angle between the viewing direction and the surface normal.

Parameters:

• pixels (ArrayNx2)

• ray_vectors (ArrayNx3)

• coordinates (ArrayNx3)

• normals (ArrayNx3)

• mask (MaskN_)

• is_undistorted (bool)

• pixel_step (float)

Return type:

tuple[float | None, ArrayN_]