Area of Interest

class missiontools.AoI(lat_deg, lon_deg)[source]

Bases: object

Area of interest defined by a sampled point cloud.

All angles are in degrees at the user-facing interface; internally stored as radians. The lat_rad / lon_rad properties expose the radians representation for direct use with coverage analysis functions.

AoIs created via from_region(), from_shapefile(), from_geography(), or a set operation are geometry-backed — they store a Shapely geometry and generate their sample points lazily on first access. This means composing complex AoIs with set operations (|, &, -, ^) incurs no sampling cost until points are actually needed.

Parameters:

  • lat_deg (array-like) – Sample latitudes (deg), shape (M,).

  • lon_deg (array-like) – Sample longitudes (deg), shape (M,).

Parameters:

  • lat_deg (npt.ArrayLike)

  • lon_deg (npt.ArrayLike)

Notes

Directly constructed AoIs (AoI(lat, lon)) have no associated geometry and cannot participate in set operations.

Antimeridian caveat: set operations between a geometry from a Natural Earth shapefile that uses unwrapped longitudes (> 180°, e.g. Russia) and a from_region() box in [-180, 180] will not behave correctly because Shapely treats coordinates as Cartesian. For most geographies this is not an issue.

Examples

Direct construction from arrays:

import numpy as np
from missiontools import AoI

lat = np.linspace(-10, 10, 50)
lon = np.linspace(30, 60, 50)
aoi = AoI(lat, lon)

From a rectangular lat/lon band (lazy — no points generated yet):

aoi = AoI.from_region(lat_min_deg=-10, lat_max_deg=10,
                       lon_min_deg=30,  lon_max_deg=60)

From a Natural Earth geography:

aoi = AoI.from_geography('Australia')

Compound AoI via set operations:

conus = AoI.from_geography("US") - AoI.from_geography("US-AK") \
                                 - AoI.from_geography("US-HI")

can_arctic = AoI.from_geography("Canada") & AoI.from_region(lat_min_deg=66)
property lat: ndarray[tuple[Any, ...], dtype[float64]]

Sample latitudes (deg), shape (M,).

property lon: ndarray[tuple[Any, ...], dtype[float64]]

Sample longitudes (deg), shape (M,).

property lat_rad: ndarray[tuple[Any, ...], dtype[float64]]

Sample latitudes (rad), shape (M,) — for coverage functions.

property lon_rad: ndarray[tuple[Any, ...], dtype[float64]]

Sample longitudes (rad), shape (M,) — for coverage functions.

property geometry

Shapely geometry describing the AoI, or None if unavailable.

property shapefile_path: str | None

Path to the source shapefile, or None if not constructed from one.

classmethod from_region(lat_min_deg=None, lat_max_deg=None, lon_min_deg=None, lon_max_deg=None, *, point_density=100000.0)[source]

Sample an AoI from a rectangular lat/lon region.

Points are generated lazily on first access.

Parameters:

  • lat_min_deg (float | None, optional) – Southern boundary (deg). None extends to the South Pole.

  • lat_max_deg (float | None, optional) – Northern boundary (deg). None extends to the North Pole.

  • lon_min_deg (float | None, optional) – Western boundary (deg). Must be paired with lon_max_deg; None (together with lon_max_deg=None) includes all longitudes.

  • lon_max_deg (float | None, optional) – Eastern boundary (deg). May be less than lon_min_deg for anti-meridian-crossing regions.

  • point_density (float, optional) – Approximate area per sample point (km²). Defaults to 1×10⁵ km² (~100 000 km² per point).

Returns:

AoI – Geometry-backed, lazily sampled.

Parameters:

  • lat_min_deg (float | None)

  • lat_max_deg (float | None)

  • lon_min_deg (float | None)

  • lon_max_deg (float | None)

  • point_density (float)

Return type:

AoI

classmethod from_shapefile(path, *, feature_index=None, point_density=100000.0)[source]

Sample an AoI from an ESRI Shapefile polygon.

Stores the Shapely geometry; points are generated lazily on first access.

Parameters:

  • path (str) – Path to the .shp file.

  • feature_index (int | None, optional) – Index of the feature to sample. None (default) unions all features.

  • point_density (float, optional) – Approximate area per sample point (km²). Defaults to 1×10⁵ km².

Returns:

AoI – With geometry and shapefile_path populated.

Parameters:

  • path (str)

  • feature_index (int | None)

  • point_density (float)

Return type:

AoI

classmethod from_geography(geography, *, point_density=100000.0)[source]

Sample an AoI from a Natural Earth geography by name or code.

Stores the Shapely geometry; points are generated lazily on first access.

Parameters:

  • geography (str) – One of:

    • Country name: 'Canada' (case-insensitive)

    • 'Country/Subdivision': 'Canada/Quebec'

    • ISO 3166-1 alpha-2: 'CA'

    • ISO 3166-1 alpha-3: 'CAN'

    • ISO 3166-2: 'CA-QC'

  • point_density (float, optional) – Approximate area per sample point (km²). Defaults to 1×10⁵ km².

Returns:

AoI – With geometry populated.

Parameters:
Return type:

AoI