kuva-reader 0.1.3__py3-none-any.whl → 0.1.4__py3-none-any.whl

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/reader/level0.py

@@ -101,6 +101,17 @@ 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"""
+        return (
+            f"{self.__class__.__name__}("
+            f"len(self.images)={len(self.images)}, "
+            f"self.images[0].shape={self.images[0].shape}"
+            f"crs={self.images[0].rio.crs}, "
+            f"image_path='{self.image_path}"
+            ")"
+        )
+
     def __getitem__(self, camera: str) -> xarray.DataArray:
         """Return the datarray for the chosen camera."""
         return self.images[camera]
@@ -221,6 +232,15 @@ class Level0Product(ProductBase[MetadataLevel0]):
         bad_pixel_filename = f"{camera}_per_frame_cloud_mask.tif"
         return self._read_array(self.image_path / bad_pixel_filename)
 
+    def release_memory(self):
+        """Explicitely releases the memory of the `images` 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.images
+        self.images = None
 
 def generate_level_0_metafile():
     """Example function for reading a product and generating a metadata file from the

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,19 @@ 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"""
+        return (
+            f"{self.__class__.__name__}("
+            f"image.shape={self.image.shape}, "
+            f"image.crs={self.image.rio.crs}, "
+            f"wavelengths={self.wavelengths}"
+            f"image_path='{self.image_path})"
+        )
 
     def _get_data_from_sidecar(
         self, sidecar_path: Path, target_ureg: UnitRegistry | None = None
@@ -182,6 +204,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/reader/level2.py

@@ -52,6 +52,19 @@ 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"""
+        return (
+            f"{self.__class__.__name__}("
+            f"image.shape={self.image.shape}, "
+            f"image.crs={self.image.rio.crs}, "
+            f"wavelengths={self.wavelengths}"
+            f"image_path='{self.image_path})"
+        )
 
     def _get_data_from_sidecar(
         self, sidecar_path: Path, target_ureg: UnitRegistry | None = None
@@ -83,6 +96,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/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.4.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.1
+Name: kuva-reader
+Version: 0.1.4
+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
+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: 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.
+
+
+# Table of Contents
+
+- [Installation](#installation)
+- [Code](#code)
+  - [Minimal example](#minimal-example)
+  - [Processing levels](#processing-levels)
+  - [Special tags](#special-tags)
+- [Contributing](#contributing)
+- [Configuration](#configuration)
+- [Contact information](#contact-information)
+- [License](#license)
+
+# 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
+
+l1c_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](../CONTRIBUTING.md).
+
+Also, please follow our [Code of Conduct](../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](../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.4.dist-info/RECORD

@@ -0,0 +1,15 @@
+kuva_reader/__init__.py,sha256=qqsgtVNCkqXFuXOXf5v51ZT_Dcipj1ty0mGUw8fU3sU,1509
+kuva_reader/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kuva_reader/reader/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kuva_reader/reader/image.py,sha256=Ep54Tzila3hKF2I_u-54xnFUf8WqP2fiKAJnbyZxasA,4647
+kuva_reader/reader/level0.py,sha256=atehEeBnlHewRFaC0kuOGEwg7YaWnLaI9MR4OPiDveU,10233
+kuva_reader/reader/level1.py,sha256=iqTsetWpPZaiM9-CjeNdyXqJrODsKFPFqCyBGrlcNY0,7693
+kuva_reader/reader/level2.py,sha256=co6KOUI5PSPkGTqoKnZAxWFVsFRGOdE3PnQ5PDhmdnk,3969
+kuva_reader/reader/product_base.py,sha256=_O96DACi2bWEXhNJVuIU328RJ1y1gs7_rMyyEaMo4aA,4294
+kuva_reader/reader/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kuva_reader/reader/read.py,sha256=l2x-vlOLP8AUMzqSjHLaT7xt0YJtYUjiYWm6btV-rqo,1762
+kuva_reader/reader/utils.py,sha256=oZ1G43nm8lCxzfbdqBs0KhKaXWe_uf-78uBXWvmZigs,1566
+kuva_reader-0.1.4.dist-info/METADATA,sha256=YZzgW8DEPaLqKreWgz28uCguDBHpNpDQVXUOvGzFkMQ,4762
+kuva_reader-0.1.4.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+kuva_reader-0.1.4.dist-info/entry_points.txt,sha256=YJysY9EChfOb1W_IEht2oE5Z8Y9jA0J6-kofaPv-NdI,149
+kuva_reader-0.1.4.dist-info/RECORD,,

{kuva_reader-0.1.3.dist-info → kuva_reader-0.1.4.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.1.1
+Generator: poetry-core 1.9.0
 Root-Is-Purelib: true
 Tag: py3-none-any

kuva_reader-0.1.3.dist-info/METADATA

@@ -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)

kuva_reader-0.1.3.dist-info/RECORD

@@ -1,14 +0,0 @@
-kuva_reader/__init__.py,sha256=ZfbIywT9FhYS3hqEMVeg0U2E8F5B-be6KTfyzO9Sz2Q,1478
-kuva_reader/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kuva_reader/reader/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kuva_reader/reader/image.py,sha256=Ep54Tzila3hKF2I_u-54xnFUf8WqP2fiKAJnbyZxasA,4647
-kuva_reader/reader/level0.py,sha256=-5nuuxxwZDnn5Bw0--OFEiEiWz3HBFiCzOVAqczGA9k,9478
-kuva_reader/reader/level1.py,sha256=mN1uMMDHh8Mt6s20gCU1xH5OmcP8xM0OzfyN0VM9bL8,6487
-kuva_reader/reader/level2.py,sha256=k-vIvT84jvgyTBb_PmbaMMXY1wrl5v-MWqL7hV0tj1Q,3129
-kuva_reader/reader/product_base.py,sha256=_O96DACi2bWEXhNJVuIU328RJ1y1gs7_rMyyEaMo4aA,4294
-kuva_reader/reader/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kuva_reader/reader/utils.py,sha256=oZ1G43nm8lCxzfbdqBs0KhKaXWe_uf-78uBXWvmZigs,1566
-kuva_reader-0.1.3.dist-info/METADATA,sha256=Kf0jEWYkhSxeQEnav-mWLM9wbGXmzwro3gSxX_GHwRc,930
-kuva_reader-0.1.3.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
-kuva_reader-0.1.3.dist-info/entry_points.txt,sha256=YJysY9EChfOb1W_IEht2oE5Z8Y9jA0J6-kofaPv-NdI,149
-kuva_reader-0.1.3.dist-info/RECORD,,