Error Handling#

weitsicht uses a mix of:

Exceptions for invalid inputs and missing prerequisites
Result objects (ProjectionResult / MappingResult) for runtime outcomes like “no intersection”

This guide explains which is which, and how to handle them in user code.

Two kinds of failures#

1) Exceptions (you need to fix inputs / state)#

Exceptions are used when the function cannot even attempt the operation, when inputs are inconsistent, or when a core dependency (like coordinate transformation) fails:

NotGeoreferencedError: required pose/camera/georeference is missing
MapperMissingError: mapping is requested but no mapper is attached/passed
CRSInputError: inconsistent CRS arguments (e.g. providing both crs_s and transformer)
CoordinateTransformationError: a coordinate transformation could not be established or applied

CRSInputError is also a ValueError (multiple inheritance), so except ValueError will catch it as well.

2) ResultFailure (the operation ran but produced no/partial output)#

Most projection/mapping operations return a result object:

projection: ProjectionResult = ProjectionResultSuccess | ResultFailure
mapping: MappingResult = MappingResultSuccess | ResultFailure

Typical “runtime outcome” failures (no exception) include:

rays point in the wrong direction
intersections fall outside a raster/array extent
no intersection exists for a ray

In these cases you get ResultFailure(ok=False, error=..., issues=...) or a success result with a partial mask.

See Results, Masks, and Errors for the result fields and mask semantics.

Exception hierarchy (current)#

All package-specific exceptions inherit from WeitsichtError.

WeitsichtError
- CRSInputError (also ValueError)
  - CRSnoZaxisError
- CoordinateTransformationError
- NotGeoreferencedError
- MappingError
  - MapperMissingError
  - MappingBackendError

Notes:

CoordinateTransformationError is intentionally not wrapped into MappingError so you can catch it explicitly across the whole package.
MappingBackendError is raised by image map_* methods when the mapper backend throws an unexpected, non-weitsicht exception. The original exception is available via err.__cause__.

Recommended try/except patterns#

Catch only what you can handle (mapping)#

from weitsicht import (
    CoordinateTransformationError,
    CRSInputError,
    MapperMissingError,
    MappingBackendError,
    MappingError,
    NotGeoreferencedError,
)

try:
    mp = image.map_points([[200, 300], [50, 50]])
except CRSInputError:
    raise
except CoordinateTransformationError:
    raise
except (NotGeoreferencedError, MapperMissingError):
    raise
except MappingBackendError as err:
    # unexpected backend exception from the mapper class; the root cause is in err.__cause__
    raise

if not mp.ok:
    print("Mapping failed:", mp.error, "Issues:", mp.issues)
else:
    coords_valid = mp.coordinates[mp.mask]

Catch only what you can handle (projection)#

from weitsicht import CoordinateTransformationError, CRSInputError, NotGeoreferencedError

try:
    proj = image.project(points_3d, crs_s=points_crs)
except CRSInputError:
    # invalid CRS / transformer usage (e.g. crs_s and transformer both set)
    raise
except CoordinateTransformationError:
    # transformation could not be established or applied
    raise
except NotGeoreferencedError:
    raise

if not proj.ok:
    print("Projection failed:", proj.error, "Issues:", proj.issues)
else:
    pixels_valid = proj.pixels[proj.mask]

Working with ImageBatch#

ImageBatch methods return per-image results (dicts of MappingResult / ProjectionResult). They catch common per-image errors (for example NotGeoreferencedError, MapperMissingError, CRSInputError, MappingError) and convert them into ResultFailure with Issue.IMAGE_BATCH_ERROR so other images can still be processed.

Some exceptions (notably CoordinateTransformationError) may still propagate to the caller so you can handle transformation problems explicitly.