kuva-metadata 0.1.0__tar.gz

kuva_metadata-0.1.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.1
+Name: kuva-metadata
+Version: 0.1.0
+Summary: Definitions of Kuva Space product metadata
+License: MIT
+Author: Guillem Ballesteros
+Author-email: guillem@kuvaspace.com
+Requires-Python: >=3.10,<=3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: kuva-geometry
+Requires-Dist: networkx (>=3.4.2,<4.0.0)
+Requires-Dist: numpy (>=1.26.4,<2.0.0)
+Requires-Dist: numpy-quaternion (>=2022.4.4,<2023.0.0)
+Requires-Dist: pint (>=0.22,<0.23)
+Requires-Dist: pydantic (>=2.9.2,<3.0.0)
+Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
+Requires-Dist: pytz (>=2023.4,<2024.0)
+Requires-Dist: rasterio (>=1.4.1,<2.0.0)
+Requires-Dist: rich (>=13.9.3,<14.0.0)
+Requires-Dist: shapely (>=2.0.6,<3.0.0)
+Requires-Dist: sympy (>=1.13.3,<2.0.0)

kuva_metadata-0.1.0/kuva_metadata/__init__.py

@@ -0,0 +1,23 @@
+"""
+This library defines the metadata format used by the sidecar files that accompany
+the images produced by Hyperfield satellites.
+
+The core library used is pydantic which among other nice things allows us to
+(de)serialize (from)to JSON .
+
+If you are interested on reading from the Hyperfield metadata database into such
+objects then you want to look at the `hyperfield-db` project.
+"""
+
+from .sections_common import MetadataBase
+from .sections_l0 import MetadataLevel0
+from .sections_l1 import MetadataLevel1AB, MetadataLevel1C
+from .sections_l2 import MetadataLevel2A
+
+__all__ = [
+    "MetadataBase",
+    "MetadataLevel0",
+    "MetadataLevel1AB",
+    "MetadataLevel1C",
+    "MetadataLevel2A",
+]

kuva_metadata-0.1.0/kuva_metadata/custom_types.py

@@ -0,0 +1,36 @@
+"""Custom classes to store in Pydantic models"""
+
+import numpy as np
+from pydantic import BaseModel, ConfigDict
+from rasterio.crs import CRS
+from shapely import Point, Polygon, get_coordinates
+
+
+class CRSGeometry(BaseModel):
+    """
+    Store a `shapely.geometry` together with the relevant CRS.
+
+    Attributes
+    ----------
+    geom: Polygon
+        Shapely polygon with the geometry
+    crs_epsg: rasterio.crs.CRS
+        CRS over which the polygon is represented.
+    """
+
+    geom: Polygon | Point
+    crs_epsg: CRS
+    model_config = ConfigDict(
+        validate_assignment=True,
+        arbitrary_types_allowed=True,
+    )
+
+    @property
+    def numpy(self) -> np.ndarray:
+        """Turn the geometry into a numpy array of polygon coordinates.
+
+        Notes
+        -----
+        This loses the CRS information so make sure to keep track of it elsewhere
+        """
+        return get_coordinates(self.geom, include_z=True).squeeze()

kuva_metadata-0.1.0/kuva_metadata/geometry_utils.py

@@ -0,0 +1,173 @@
+"""Geometry utilities to find the footprint associated with an in orbit camera"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+import quaternion
+import shapely
+from kuva_geometry import ellipsoid, geometry
+
+if TYPE_CHECKING:
+    from .sections_l0 import Camera, Frame
+
+
+def get_sensor_corner_rays(
+    camera: Camera,
+    position: np.ndarray,
+    orientation: quaternion.quaternion,
+    use_negative_sensor_plane: bool = False,
+):
+    """Get the rays emanating from a camera associated with the corners of the sensor
+
+    Parameters
+    ----------
+    camera
+        Camera intrinsic parameters
+    position
+        The position of the satellite in ECEF coordinates expressed in meters (3 values)
+    orientation
+        Quaternion describing the orientation of the satellite wrt ECEF
+    use_negative_sensor_plane, optional
+        Whether to use the negative sensor plane to calculate the rays, by default False
+
+    Returns
+    -------
+        The vectors that join the back nodal point to the sensor corners.
+    """
+    ray_origin, rays = geometry.get_sensor_corner_rays(
+        np.array(position),
+        orientation,
+        camera.focal_distance.to("meters").magnitude,
+        camera.width.to("meters").magnitude,
+        camera.height.to("meters").magnitude,
+        use_negative_sensor_plane,
+    )
+
+    return ray_origin, rays
+
+
+def get_sensor_rays(
+    sensor_coords: np.ndarray,
+    camera: Camera,
+    position: np.ndarray,
+    orientation: quaternion.quaternion,
+) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Produce an array with the ray vectors for a collections of sensor coords.
+
+    Sensor coords are measured from the center of the sensor and are valid within
+    [-0.5, 0.5]^2.
+
+    Parameters
+    ----------
+    sensor_coords
+        A rank-2 tensor of dimension (n_sensor_coords, 2)
+    camera
+        Camera intrinsic parameters
+    position
+        The position of the satellite in ECEF coordinates expressed in meters (3 values)
+    orientation
+        Quaternion describing the orientation of the satellite wrt ECEF
+
+    Returns
+    -------
+    The position from which the rays emanate, i.e. the camera position and rank 2 tensor
+    of dimensions (n_sensor_coords, 3) describing the direction vector of the rays.
+    """
+    rays = geometry.get_sensor_rays(
+        sensor_coords,
+        position,
+        orientation,
+        camera.focal_distance.to("meters").magnitude,
+        camera.width.to("meters").magnitude,
+        camera.height.to("meters").magnitude,
+        use_negative_sensor_plane=True,
+    )
+
+    return position, rays
+
+
+def frame_ray_Earth_intersections(
+    sensor_coords: np.ndarray, frame: Frame, camera: Camera
+) -> list[shapely.Point]:
+    """
+    Return the intersecton of camera ray with the WGS84 ellipsoid.
+
+    Parameters
+    ----------
+    sensor_coords
+        The coordinates of the ray we are interested on. Within sensor coords range
+        between +- 0.5 on both axis.
+    frame
+        Information about how the frame was taken. Namely camera orientation and
+        position.
+    camera
+        The camera parameters
+
+    Returns
+    -------
+        Intersection of camera rays on the Earth
+    """
+    sat_pos, sat_ecef_orientation = frame.position.numpy, frame.sat_ecef_orientation
+
+    # Make sure the order is correct, i.e. begin from the right-hand side!
+    # The process is the same as for how we calculate homographies.
+    orientation = sat_ecef_orientation * camera.sensor_wrt_sat_axis_quaternion
+
+    _, rays = get_sensor_rays(sensor_coords, camera, sat_pos, orientation)
+
+    rays = rays / np.sqrt((rays**2).sum(axis=1))[:, None]
+
+    intersections = [
+        shapely.Point(*ellipsoid.ray_Earth_intersection(sat_pos, rays[idx]))
+        for idx in range(rays.shape[0])
+    ]
+
+    return intersections
+
+
+def frame_footprint(
+    frame: Frame,
+    camera: Camera,
+    use_negative_sensor_plane: bool = False,
+) -> shapely.Polygon:
+    """Find the footprint on the ground associated with the corners rays of a camera
+
+    Parameters
+    ----------
+    frame
+        Information about how the frame was taken. Namely camera orientation and
+        position.
+    camera
+        The camera parameters
+    use_negative_sensor_plane, optional
+        Whether to use the negative sensor plane to calculate the rays, by default False
+
+    Returns
+    -------
+        The footprint on the ground as a polygon
+    """
+    sat_pos, sat_ecef_orientation = frame.position.numpy, frame.sat_ecef_orientation
+
+    orientation = sat_ecef_orientation * camera.sensor_wrt_sat_axis_quaternion
+
+    _, sensor_corners_ray = get_sensor_corner_rays(
+        camera, sat_pos, orientation, use_negative_sensor_plane
+    )
+
+    sensor_corners_ray = (
+        sensor_corners_ray / np.sqrt((sensor_corners_ray**2).sum(axis=1))[:, None]
+    )
+
+    footprint = [
+        ellipsoid.ray_Earth_intersection(sat_pos, sensor_corners_ray[idx])
+        for idx in range(sensor_corners_ray.shape[0])
+    ]
+
+    # Polygons are ordered X,Y despite the CRS being lat, long i.e. x,y. If you
+    # leave the points in the order they come in the 4326 CRS things will break.
+    footprint = shapely.Polygon(footprint)
+
+    return footprint

kuva_metadata-0.1.0/kuva_metadata/helper_types.py

@@ -0,0 +1,13 @@
+"""Additional type aliases"""
+
+import numpy as np
+from pint import Quantity
+from quaternion import quaternion
+from shapely import Polygon
+
+# All this types with lists would be better expressed with tuples but pydantic
+# reads the json as lists so we have a type to match.
+Quantity_ = Quantity | list[float | str]
+quaternion_ = quaternion | list[float]
+array_3x3_ = np.ndarray | list[list[float]]
+Polygon_ = Polygon | str

kuva_metadata-0.1.0/kuva_metadata/sections_common.py

@@ -0,0 +1,194 @@
+import typing
+from datetime import datetime
+from pathlib import Path
+from typing import cast
+
+import pytz
+from pint import Quantity, UnitRegistry
+from pydantic import (
+    UUID4,
+    BaseModel,
+    ConfigDict,
+    field_serializer,
+    field_validator,
+)
+from rasterio.rpc import RPC
+
+from kuva_metadata.serializers import serialize_RPCs
+from kuva_metadata.validators import check_is_utc_datetime, parse_rpcs, parse_timestamp
+
+_T = typing.TypeVar("_T")
+
+
+class Header(BaseModel):
+    """Header for the metadata files
+
+    Attributes
+    ----------
+    version
+        Version of the library used to create the file.
+    author
+        The author of the file.
+    creation_date
+        Creation date for the metadata file.
+    """
+
+    version: str
+    author: str
+    creation_date: datetime = datetime.now(tz=pytz.utc)
+
+    _parse_timestamp = field_validator("creation_date", mode="before")(parse_timestamp)
+    _check_tz = field_validator("creation_date")(check_is_utc_datetime)
+    model_config = ConfigDict(validate_assignment=True)
+
+
+class Satellite(BaseModel):
+    """Specifies the information relating to the satellite from which the file images
+    where acquired.
+
+    Attributes
+    ----------
+    name
+        Short name of the satellite.
+    cospar_id
+        International designator assigned to the satellite after launch.
+    launch_date
+        When the satellite was launched
+    """
+
+    name: str
+    cospar_id: str
+    launch_date: datetime
+
+    _parse_timestamp = field_validator("launch_date", mode="before")(parse_timestamp)
+    _check_tz = field_validator("launch_date")(check_is_utc_datetime)
+    model_config = ConfigDict(validate_assignment=True)
+
+
+class Radiometry(BaseModel):
+    """Information required for TOA calculations and physical units
+
+    Attributes
+    ----------
+    lut_file
+        A lookup table stored together with the image file that associates raw image
+        values to a radiance for different wavelengths and integration times. Stored as
+        a numpy `npy` file.
+    sun_spectrum_file
+        Sun spectrum radiance of each band. Required for top of atmosphere calculation.
+    """
+
+    lut_file: Path
+    sun_spectrum_file: Path
+
+
+class RPCoefficients(BaseModel):
+    """Rational polynomial function coefficients for orthorectification.
+
+    A rational polynomial functions is simply a function which is the ratio of two
+    polynomials. In our case we have two functions that are R^3 -> R^2 and map world
+    coordinates to pixel space. The first function maps the x coordinates and the
+    second the y coordinates.
+
+    Attributes
+    ----------
+    rpcs
+        Rational polynomial function coefficients for orthorectification
+    """
+
+    rpcs: RPC
+
+    _parse_rpcs = field_validator("rpcs", mode="before")(parse_rpcs)
+
+    @field_serializer("rpcs")
+    def _serialize_RPCs(self, rpcs: RPC):
+        return serialize_RPCs(rpcs)
+
+    model_config = ConfigDict(validate_assignment=True, arbitrary_types_allowed=True)
+
+
+class BaseModelWithUnits(BaseModel, typing.Generic[_T]):
+    """Allows an pint unit registry to be plugged in one of the classes using units"""
+
+    @classmethod
+    def model_validate_json_with_ureg(
+        cls, json_data: str, new_ureg: UnitRegistry, **val_kwargs
+    ) -> _T:
+        """Will create a model from JSON data. However, the data will be copied so that
+        each Quantity in all submodels is recursively converted to a new given
+        UnitRegistry. If data is read from a JSON file without this method, it will be
+        attached to the kuva-metadata default UnitRegistry.
+
+        Parameters
+        ----------
+        json_data
+            Model data to validate
+        new_ureg
+            Pint UnitRegistry to swap to
+
+        Returns
+        -------
+            The validated model instance
+        """
+        model_instance = cls.model_validate_json(json_data, **val_kwargs)
+        swapped_instance = cast(
+            _T, swap_ureg_in_instance(model_instance, new_ureg, **val_kwargs)
+        )
+
+        return swapped_instance
+
+
+class MetadataBase(BaseModelWithUnits):
+    """Base class for all product levels' metadata
+
+    Attributes
+    ----------
+    id
+        Metadata ID for identifying metadata from DB
+    header
+        Metadata file header
+    satellite
+        Satellite the metadata's product has been created for
+    image
+        Image that the metadata is associated to
+    """
+
+    id: UUID4
+    header: Header
+    satellite: Satellite
+
+
+def swap_ureg_in_instance(obj: BaseModel, new_ureg: UnitRegistry, **val_kwargs):
+    """Swaps Pint UnitRegistry recursively within a pydantic model.
+
+    Parameters
+    ----------
+    obj
+        Instance of a model
+    new_ureg
+        Pint UnitRegistry to swap to
+    val_kwargs
+        Keyword arguments that are required in model validation, e.g. a pydantic context
+
+    Returns
+    -------
+        The validated model instance which now has the new UnitRegistry in its or its
+        child objects' Quantities
+    """
+
+    def _replace_ureg(value):
+        """Helper recursion function to correctly go through the different attributes"""
+        if isinstance(value, Quantity):
+            return new_ureg.Quantity(value.magnitude, value.units)
+        elif isinstance(value, BaseModel):
+            return swap_ureg_in_instance(value, new_ureg, **val_kwargs)
+        elif isinstance(value, (list, tuple, set)):
+            return type(value)(_replace_ureg(v) for v in value)
+        elif isinstance(value, dict):
+            return {k: _replace_ureg(v) for k, v in value.items()}
+        else:
+            return value
+
+    field_values = obj.model_dump(**val_kwargs)
+    updated_field_values = _replace_ureg(field_values)
+    return obj.__class__.model_validate(updated_field_values, **val_kwargs)