kuva-metadata 1.1.7__tar.gz

kuva_metadata-1.1.7/.gitignore

@@ -0,0 +1,134 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+*.ipynb
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Torch stuff
+lightning_logs/
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# VSCode
+.vscode
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# Direnv stuff
+.direnv/
+.envrc
+
+# Poetry
+# poetry.lock
+
+# Supervisord
+supervisord.log
+supervisord.pid
+
+# Debug folders
+_debug/
+
+# Kuva data
+*.tif
+*.tiff
+*.npy
+hyperfield*.json
+
+# Do not ignore Kuva files in the test_data directory
+!kuva-reader/tests/test_data/**

kuva_metadata-1.1.7/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: kuva-metadata
+Version: 1.1.7
+Summary: Definitions of Kuva Space product metadata
+Author-email: Guillem Ballesteros <guillem@kuvaspace.com>, Lennert Antson <lennert.antson@kuvaspace.com>, Arthur Vandenhoeke <arthur.vandenhoeke@kuvaspace.com>, Olli Eloranta <olli.eloranta@kuvaspace.com>
+License-Expression: MIT
+Requires-Python: <=3.13,>=3.10
+Requires-Dist: kuva-geometry<2.0.0,>=1.0.1
+Requires-Dist: networkx<4.0.0,>=3.4.2
+Requires-Dist: numpy-quaternion>=2022.4.4
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: pint<1.0.0,>=0.22
+Requires-Dist: pydantic<3.0.0,>=2.9.2
+Requires-Dist: rasterio<2,>=1.4.3
+Requires-Dist: shapely<3.0.0,>=2.0.6
+Requires-Dist: sympy<2.0.0,>=1.13.3
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/1d8b44f1-1999-4cfb-8744-32871056c253">
+    <img alt="kuva-space-logo" src="https://github.com/user-attachments/assets/d8f47cc8-1491-4d0c-a8cf-318ea7e0afdc" width="50%">
+  </picture>
+</div>
+
+# Kuva Metadata
+
+Images taken from a satellite are complicated beasts with lot of metadata associated
+to them. This repository contains the metadata definitions for the Hyperfield products. 
+This metadata along with the acquired GeoTIFF images form the Kuva Space products in its 
+various processing levels.
+
+With the metadata and images, we may process products to the 
+next processing levels, or do more precise processing than just with a GeoTIFF. 
+
+# Installation
+
+```bash
+pip install kuva-metadata
+``` 
+
+This package is also included when installing the `kuva-reader`.
+
+### Requirements
+
+`Python 3.10` to `3.13`, preferably within a virtual environment
+
+# Processing levels
+
+Currently there are metadata definitions for the following processing levels of Kuva products:
+
+- **L0**: Radiometrically corrected frames as TOA radiance
+- **L1AB**: Band-aligned product formed from multiple L0 products
+- **L1C**: Georeferences and orthorectified L1 product
+- **L2A**: Atmospherically corrected product as BOA reflectance
+
+# Architecture
+
+All the metadata are defined as Pydantic models, this has several advantages:
+
+- A very rich set of validations that are applied before data object construction
+- The ability to easily (de)serialize (from)to JSON
+
+# Contributing
+
+Please follow the guidelines in [CONTRIBUTING.md](https://github.com/KuvaSpace/kuva-data-processing/blob/main/CONTRIBUTING.md).
+
+Also, please follow our [Code of Conduct](https://github.com/KuvaSpace/kuva-data-processing/blob/main/CODE_OF_CONDUCT.md)
+while discussing in the issues and pull requests.
+
+# Contact information
+
+For questions or support, please open an issue. If you have been given a support contact, 
+feel free to send them an email explaining your issue.
+
+# License
+
+The `kuva-reader` project software is under the [MIT license](https://github.com/KuvaSpace/kuva-data-processing/blob/main/LICENSE.md).
+
+
+# Status of unit tests
+
+[![Unit tests for kuva-metadata](https://github.com/KuvaSpace/kuva-data-processing/actions/workflows/test-kuva-metadata.yml/badge.svg)](https://github.com/KuvaSpace/kuva-data-processing/actions/workflows/test-kuva-metadata.yml)

kuva_metadata-1.1.7/README.md

@@ -0,0 +1,65 @@
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/1d8b44f1-1999-4cfb-8744-32871056c253">
+    <img alt="kuva-space-logo" src="https://github.com/user-attachments/assets/d8f47cc8-1491-4d0c-a8cf-318ea7e0afdc" width="50%">
+  </picture>
+</div>
+
+# Kuva Metadata
+
+Images taken from a satellite are complicated beasts with lot of metadata associated
+to them. This repository contains the metadata definitions for the Hyperfield products. 
+This metadata along with the acquired GeoTIFF images form the Kuva Space products in its 
+various processing levels.
+
+With the metadata and images, we may process products to the 
+next processing levels, or do more precise processing than just with a GeoTIFF. 
+
+# Installation
+
+```bash
+pip install kuva-metadata
+``` 
+
+This package is also included when installing the `kuva-reader`.
+
+### Requirements
+
+`Python 3.10` to `3.13`, preferably within a virtual environment
+
+# Processing levels
+
+Currently there are metadata definitions for the following processing levels of Kuva products:
+
+- **L0**: Radiometrically corrected frames as TOA radiance
+- **L1AB**: Band-aligned product formed from multiple L0 products
+- **L1C**: Georeferences and orthorectified L1 product
+- **L2A**: Atmospherically corrected product as BOA reflectance
+
+# Architecture
+
+All the metadata are defined as Pydantic models, this has several advantages:
+
+- A very rich set of validations that are applied before data object construction
+- The ability to easily (de)serialize (from)to JSON
+
+# Contributing
+
+Please follow the guidelines in [CONTRIBUTING.md](https://github.com/KuvaSpace/kuva-data-processing/blob/main/CONTRIBUTING.md).
+
+Also, please follow our [Code of Conduct](https://github.com/KuvaSpace/kuva-data-processing/blob/main/CODE_OF_CONDUCT.md)
+while discussing in the issues and pull requests.
+
+# Contact information
+
+For questions or support, please open an issue. If you have been given a support contact, 
+feel free to send them an email explaining your issue.
+
+# License
+
+The `kuva-reader` project software is under the [MIT license](https://github.com/KuvaSpace/kuva-data-processing/blob/main/LICENSE.md).
+
+
+# Status of unit tests
+
+[![Unit tests for kuva-metadata](https://github.com/KuvaSpace/kuva-data-processing/actions/workflows/test-kuva-metadata.yml/badge.svg)](https://github.com/KuvaSpace/kuva-data-processing/actions/workflows/test-kuva-metadata.yml)

kuva_metadata-1.1.7/kuva_metadata/__init__.py

@@ -0,0 +1,25 @@
+"""
+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.
+"""
+
+__version__ = "1.1.2"
+
+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-1.1.7/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-1.1.7/kuva_metadata/geometry_utils.py

@@ -0,0 +1,189 @@
+"""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,
+    mode: str = "shapely",
+) -> list[shapely.Point] | np.ndarray:
+    """
+    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
+    mode, optional
+        Whether to return a list of shapely points or a numpy array, by default "shapely"
+
+    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 = ellipsoid.ray_Earth_intersection_new(sat_pos, rays)
+
+    match mode:
+        case "shapely":
+            intersection_points = [
+                shapely.Point(
+                    intersections[idx][0], intersections[idx][1], intersections[idx][2]
+                )
+                for idx in range(intersections.shape[0])
+            ]
+        case "array":
+            intersection_points = intersections
+        case _:
+            e_ = "The valid modes are 'shapely' and 'array'."
+            raise ValueError(e_)
+
+    return intersection_points
+
+
+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-1.1.7/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