kuva-reader 0.1.3__tar.gz → 1.0.0__tar.gz

kuva_reader-1.0.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.1
+Name: kuva-reader
+Version: 1.0.0
+Summary: Manipulate the Kuva Space image and metadata formats
+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
+Requires-Dist: kuva-geometry @ file:///home/olli/projects/kuva-repos/kuva-data-processing/kuva-geometry
+Requires-Dist: kuva-metadata @ file:///home/olli/projects/kuva-repos/kuva-data-processing/kuva-metadata
+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: rasterio (>=1.4.1,<2.0.0)
+Requires-Dist: rioxarray (>=0.12.4,<0.13.0)
+Requires-Dist: xarray (>=2022.12.0,<2023.0.0)
+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>
+
+# Reader for Kuva Space images
+
+The reader project allows the reading of Kuva Space products from any part of its processing chain.
+
+The Kuva Space images are in GeoTIFF format. The products consist of an image or multiple 
+images along with its metadata to give all the necessary information to use the products. 
+The metadata lives either in a Kuva Space database, or alternatively in a sidecar JSON file. 
+
+This library allows the reading of the image GeoTIFFs into `xarray.Dataset` objects that 
+allow convenient raster manipulations, along with their `kuva-metadata` metadata objects.
+
+# Installation
+
+```bash
+pip install kuva-reader
+``` 
+
+### Requirements
+
+`Python 3.10` to `3.13`, preferably within a virtual environment
+
+# Code
+
+## Minimal example
+
+This is a minimal example that allows you to read and print the image shape of a L1 product. \
+The result product is in this case an L1C product (as seen from the folder name).
+The loaded product is stored in a `rioxarray` object, which contains extensive GIS functionalities [(examples for usage)](https://corteva.github.io/rioxarray/stable/examples/examples.html).
+
+```python
+from kuva_reader import read_product
+
+l2a_product = read_product("my_data_folder/hyperfield1a_L2A_20250105T092548")
+print(product)  # Will show some main information such as image shape and CRS
+```
+
+This assumes a mostly untouched folder after distributing. Otherwise, you may need to
+read the product manually based on the product processing level:
+
+```python
+from kuva_reader import Level2AProduct
+
+l2a_product = Level2AProduct("your/l2a/folder")
+```
+
+The actual raster image is stored and can be analysed in `product.image`, while metadata
+information of the product is in `product.metadata`. 
+
+## Processing levels
+
+Currently the reader supports the following processing levels for 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
+
+## Special tags
+
+All images generated by Kuva Space should have the following special tags added to the
+geotiff metadata.
+- `_KUVA_PRODUCT_LEVEL`: A string, e.g, `"0"` describing the level of the product.
+- `_KUVA_PRODUCT_ID`: The id on the database for the product associated with the geotiff.
+
+This makes it very easy to pinpoint what product we are dealing with and works around
+the issue that our images are not a monolithic entity but rather just folders that can
+be messed with.
+
+# 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-reader](https://github.com/KuvaSpace/kuva-data-processing/actions/workflows/test-kuva-reader.yml/badge.svg)](https://github.com/KuvaSpace/kuva-data-processing/actions/workflows/test-kuva-reader.yml)
+

kuva_reader-1.0.0/README.md

@@ -0,0 +1,94 @@
+<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>
+
+# Reader for Kuva Space images
+
+The reader project allows the reading of Kuva Space products from any part of its processing chain.
+
+The Kuva Space images are in GeoTIFF format. The products consist of an image or multiple 
+images along with its metadata to give all the necessary information to use the products. 
+The metadata lives either in a Kuva Space database, or alternatively in a sidecar JSON file. 
+
+This library allows the reading of the image GeoTIFFs into `xarray.Dataset` objects that 
+allow convenient raster manipulations, along with their `kuva-metadata` metadata objects.
+
+# Installation
+
+```bash
+pip install kuva-reader
+``` 
+
+### Requirements
+
+`Python 3.10` to `3.13`, preferably within a virtual environment
+
+# Code
+
+## Minimal example
+
+This is a minimal example that allows you to read and print the image shape of a L1 product. \
+The result product is in this case an L1C product (as seen from the folder name).
+The loaded product is stored in a `rioxarray` object, which contains extensive GIS functionalities [(examples for usage)](https://corteva.github.io/rioxarray/stable/examples/examples.html).
+
+```python
+from kuva_reader import read_product
+
+l2a_product = read_product("my_data_folder/hyperfield1a_L2A_20250105T092548")
+print(product)  # Will show some main information such as image shape and CRS
+```
+
+This assumes a mostly untouched folder after distributing. Otherwise, you may need to
+read the product manually based on the product processing level:
+
+```python
+from kuva_reader import Level2AProduct
+
+l2a_product = Level2AProduct("your/l2a/folder")
+```
+
+The actual raster image is stored and can be analysed in `product.image`, while metadata
+information of the product is in `product.metadata`. 
+
+## Processing levels
+
+Currently the reader supports the following processing levels for 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
+
+## Special tags
+
+All images generated by Kuva Space should have the following special tags added to the
+geotiff metadata.
+- `_KUVA_PRODUCT_LEVEL`: A string, e.g, `"0"` describing the level of the product.
+- `_KUVA_PRODUCT_ID`: The id on the database for the product associated with the geotiff.
+
+This makes it very easy to pinpoint what product we are dealing with and works around
+the issue that our images are not a monolithic entity but rather just folders that can
+be messed with.
+
+# 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-reader](https://github.com/KuvaSpace/kuva-data-processing/actions/workflows/test-kuva-reader.yml/badge.svg)](https://github.com/KuvaSpace/kuva-data-processing/actions/workflows/test-kuva-reader.yml)

{kuva_reader-0.1.3 → kuva_reader-1.0.0}/kuva_reader/__init__.py

@@ -4,20 +4,20 @@ Observation (EO) products.  The module handles the reading and parsing of image
 data, as well as extracting and structuring the associated metadata to
 facilitate further analysis or visualization.
 
-## Key Features
+Key Features
 
-- **Open EO Products**: Load satellite images and corresponding metadata from
-  various data formats.
-- **Access Metadata**: Retrieve information such as acquisition time, satellite
+- Open EO Products: Load satellite images and corresponding metadata from
+  various dataformats.
+- Access Metadata: Retrieve information such as acquisition time, satellite
   name, sensor type, geospatial coordinates, and any custom metadata embedded
   within the product.
-- **Image Handling**: Manage the loading  of image data for efficient use in
+- Image Handling: Manage the loading  of image data for efficient use in
   analytical processes.
 
-## Dependencies
-- **kuva-metadata**: A specialized library that handles the extraction and
+Dependencies
+- kuva-metadata: A specialized library that handles the extraction and
   parsing of metadata associated with Kuva Space products.
-- **xarray**: Used for loading image data as arrays with extra functionality,
+- xarray: Used for loading image data as arrays with extra functionality,
   including labeled coordinates and metadata, which is useful for analysis and
   visualization.
 """
@@ -32,6 +32,7 @@ from .reader.image import (
 from .reader.level0 import Level0Product
 from .reader.level1 import Level1ABProduct, Level1CProduct
 from .reader.level2 import Level2AProduct
+from .reader.read import read_product
 
 __all__ = [
     "Level0Product",
@@ -41,4 +42,5 @@ __all__ = [
     "image_to_dtype_range",
     "image_to_original_range",
     "image_to_uint16_range",
+    "read_product",
 ]

{kuva_reader-0.1.3 → kuva_reader-1.0.0}/kuva_reader/reader/level0.py

@@ -101,6 +101,18 @@ class Level0Product(ProductBase[MetadataLevel0]):
                     self.data_tags[camera]["data_offset"] = offset
                     self.data_tags[camera]["data_scale"] = scale
 
+    def __repr__(self):
+        """Pretty printing of the object with the most important info"""
+        if self.images is not None and len(self.images):
+            return (
+                f"{self.__class__.__name__}"
+                f"with {len(self.images)} frames of shape {self.images[0].shape} "
+                f"and CRS '{self.images[0].rio.crs}'. "
+                f"Loaded from: '{self.image_path}'."
+            )
+        else:
+            return f"{self.__class__.__name__} loaded from '{self.image_path}'."
+
     def __getitem__(self, camera: str) -> xarray.DataArray:
         """Return the datarray for the chosen camera."""
         return self.images[camera]

{kuva_reader-0.1.3 → kuva_reader-1.0.0}/kuva_reader/reader/level1.py

@@ -91,7 +91,6 @@ class Level1ABProduct(ProductBase[MetadataLevel1AB]):
         self, camera: str | None = None, per_band: bool = False
     ) -> xarray.Dataset:
         """Get the bad pixel mask associated to each camera of the L0 product
-
         Returns
         -------
             The bad pixel masks of the cameras
@@ -107,6 +106,16 @@ class Level1ABProduct(ProductBase[MetadataLevel1AB]):
 
         return self._read_array(self.image_path / bad_pixel_filename)
 
+    def release_memory(self):
+        """Explicitely releases the memory of the `image` variable.
+
+        NOTE: this function is implemented because of a memory leak inside the Rioxarray
+        library that doesn't release memory properly. Only use it when the image data is
+        not needed anymore.
+        """
+        del self.image
+        self.image = None
+
 
 class Level1CProduct(ProductBase[MetadataLevel1C]):
     """
@@ -151,6 +160,20 @@ class Level1CProduct(ProductBase[MetadataLevel1C]):
             rx.open_rasterio(self.image_path / "L1C.tif"),
         )
         self.data_tags = self.image.attrs
+        self.wavelengths = [
+            b.wavelength.to("nm").magnitude for b in self.metadata.image.bands
+        ]
+
+    def __repr__(self):
+        """Pretty printing of the object with the most important info"""
+        if self.image is not None:
+            return (
+                f"{self.__class__.__name__} with shape {self.image.shape} "
+                f"and wavelengths {self.wavelengths} (CRS: '{self.image.rio.crs}'). "
+                f"Loaded from: '{self.image_path}'."
+            )
+        else:
+            return f"{self.__class__.__name__} loaded from '{self.image_path}'"
 
     def _get_data_from_sidecar(
         self, sidecar_path: Path, target_ureg: UnitRegistry | None = None
@@ -182,6 +205,16 @@ class Level1CProduct(ProductBase[MetadataLevel1C]):
 
         return metadata
 
+    def release_memory(self):
+        """Explicitely releases the memory of the `image` variable.
+
+        NOTE: this function is implemented because of a memory leak inside the Rioxarray
+        library that doesn't release memory properly. Only use it when the image data is
+        not needed anymore.
+        """
+        del self.image
+        self.image = None
+
 
 def generate_level_1_metafile():
     """Example function for reading a product and generating a metadata file from the

{kuva_reader-0.1.3 → kuva_reader-1.0.0}/kuva_reader/reader/level2.py

@@ -52,6 +52,20 @@ class Level2AProduct(ProductBase[MetadataLevel2A]):
             rx.open_rasterio(self.image_path / "L2A.tif"),
         )
         self.data_tags = self.image.attrs
+        self.wavelengths = [
+            b.wavelength.to("nm").magnitude for b in self.metadata.image.bands
+        ]
+
+    def __repr__(self):
+        """Pretty printing of the object with the most important info"""
+        if self.image is not None:
+            return (
+                f"{self.__class__.__name__} with shape {self.image.shape} "
+                f"and wavelengths {self.wavelengths} (CRS: '{self.image.rio.crs}'). "
+                f"Loaded from: '{self.image_path}'."
+            )
+        else:
+            return f"{self.__class__.__name__} loaded from '{self.image_path}'"
 
     def _get_data_from_sidecar(
         self, sidecar_path: Path, target_ureg: UnitRegistry | None = None
@@ -83,6 +97,16 @@ class Level2AProduct(ProductBase[MetadataLevel2A]):
 
         return metadata
 
+    def release_memory(self):
+        """Explicitely releases the memory of the `image` variable.
+
+        NOTE: this function is implemented because of a memory leak inside the Rioxarray
+        library that doesn't release memory properly. Only use it when the image data is
+        not needed anymore.
+        """
+        del self.image
+        self.image = None
+
 
 def generate_level_2_metafile():
     """Example function for reading a product and generating a metadata file from the

kuva_reader-1.0.0/kuva_reader/reader/read.py

@@ -0,0 +1,55 @@
+from pathlib import Path
+
+from kuva_reader import Level0Product, Level1ABProduct, Level1CProduct, Level2AProduct
+
+
+def read_product(
+    product_path: Path,
+) -> Level0Product | Level1ABProduct | Level1CProduct | Level2AProduct:
+    """Helper function for reading any product level based on folder name or TIF name.
+
+    Parameters
+    ----------
+    product_path
+        Path to the product to load
+
+    Returns
+    -------
+        The product of the correct processing level
+
+    Raises
+    ------
+    ValueError
+        Folder not existing or files are renamed so that processing level isn't visible
+    """
+
+    product_map = {
+        "L0": Level0Product,
+        "L1AB": Level1ABProduct,
+        "L1C": Level1CProduct,
+        "L2A": Level2AProduct,
+    }
+
+    product_path = Path(product_path)  # Might be a string, typing not enforced
+    if not product_path.is_dir():
+        e_ = f"Given product path is not a folder: '{product_path}'"
+        raise ValueError(e_)
+
+    # First check if top level filepath matches
+    for product_level, product_class in product_map.items():
+        if product_level in product_path.name:
+            return product_class(product_path)
+
+    # In case folder is renamed, check if tif file product level matches.
+    # Folder should contain one 'LXX.tif' file.
+    for tif_path in product_path.glob("L*.tif"):
+        if tif_path.stem in product_map:
+            return product_map[tif_path.stem](product_path)
+
+    # Folder and filenames don't match expected format
+    e_ = (
+        f"Product folder '{product_path}' does not contain the processing level "
+        "information. Check that you have a correct folder or consider using the "
+        "correct reader (L0, L1AB, L1C, L2A)."
+    )
+    raise ValueError(e_)

{kuva_reader-0.1.3 → kuva_reader-1.0.0}/pyproject.toml

@@ -4,9 +4,10 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "kuva-reader"
-version = "0.1.3"
+version = "1.0.0"
 description = "Manipulate the Kuva Space image and metadata formats"
 authors = ["Guillem Ballesteros <guillem@kuvaspace.com>" , "Lennert Antson <lennert.antson@kuvaspace.com>", "Arthur Vandenhoeke <arthur.vandenhoeke@kuvaspace.com>", "Olli Eloranta <olli.eloranta@kuvaspace.com>"]
+readme = "README.md"
 license = "MIT"
 
 [tool.ruff]
@@ -25,23 +26,21 @@ make-l1-meta = "kuva_reader.reader.level1:generate_level_1_metafile"
 python = ">=3.10,<=3.13"
 numpy = "^1.26.4"
 numpy-quaternion = "^2022.4.4"
-dask = "^2023.12.1"
 pint = "^0.22"
-psycopg = "^3.2.3"
 rasterio = "^1.4.1"
 xarray = "^2022.12.0"
 rioxarray = "^0.12.4"
-kuva-geometry = "*"
-kuva-metadata = "*"
+# kuva-geometry = "*"
+# kuva-metadata = "*"
 
 # Temporarily can replace pypi version with relative dep if doing local development
-# [tool.poetry.dependencies.kuva-geometry]
-# path = "../kuva-geometry"
-# develop = true
+[tool.poetry.dependencies.kuva-geometry]
+path = "../kuva-geometry"
+develop = true
 
-# [tool.poetry.dependencies.kuva-metadata]
-# path = "../kuva-metadata"
-# develop = true
+[tool.poetry.dependencies.kuva-metadata]
+path = "../kuva-metadata"
+develop = true
 
 
 [tool.ruff.lint]

kuva_reader-0.1.3/PKG-INFO

@@ -1,24 +0,0 @@
-Metadata-Version: 2.3
-Name: kuva-reader
-Version: 0.1.3
-Summary: Manipulate the Kuva Space image and metadata formats
-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: dask (>=2023.12.1,<2024.0.0)
-Requires-Dist: kuva-geometry
-Requires-Dist: kuva-metadata
-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: psycopg (>=3.2.3,<4.0.0)
-Requires-Dist: rasterio (>=1.4.1,<2.0.0)
-Requires-Dist: rioxarray (>=0.12.4,<0.13.0)
-Requires-Dist: xarray (>=2022.12.0,<2023.0.0)