kuva-reader 0.1.0__py3-none-any.whl

kuva_reader/__init__.py

@@ -0,0 +1,44 @@
+"""
+Kuva Reader provides functionality for opening and accessing Kuva Space Earth
+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
+
+- **Open EO Products**: Load satellite images and corresponding metadata from
+  various data formats.
+- **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
+  analytical processes.
+
+## 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,
+  including labeled coordinates and metadata, which is useful for analysis and
+  visualization.
+"""
+
+__version__ = "0.1.0"
+
+from .reader.image import (
+    image_to_dtype_range,
+    image_to_original_range,
+    image_to_uint16_range,
+)
+from .reader.level0 import Level0Product
+from .reader.level1 import Level1ABProduct, Level1CProduct
+from .reader.level2 import Level2AProduct
+
+__all__ = [
+    "Level0Product",
+    "Level1ABProduct",
+    "Level1CProduct",
+    "Level2AProduct",
+    "image_to_dtype_range",
+    "image_to_original_range",
+    "image_to_uint16_range",
+]

kuva_reader/reader/image.py

@@ -0,0 +1,176 @@
+"""Utilities to process images related to product processing."""
+
+from typing import cast, overload
+
+import numpy as np
+import xarray
+
+# Helper type for image processing purposes. The same operations work both for EO
+# DataArrays and Numpy arrays.
+ImageArray_ = np.ndarray | xarray.DataArray
+
+
+@overload
+def image_to_dtype_range(
+    img: np.ndarray,
+    dtype: np.dtype,
+    offset: float | None = None,
+    scale: float | None = None,
+) -> tuple[xarray.DataArray, float, float]: ...
+
+
+@overload
+def image_to_dtype_range(
+    img: xarray.DataArray,
+    dtype: np.dtype,
+    offset: float | None = None,
+    scale: float | None = None,
+) -> tuple[xarray.DataArray, float, float]: ...
+
+
+def image_to_dtype_range(
+    img: ImageArray_,
+    dtype: np.dtype,
+    offset: float | None = None,
+    scale: float | None = None,
+) -> tuple[ImageArray_, float, float]:
+    """Normalize an image to the bounds of whatever numpy datatype. E.g. np.uint16
+    results in a np.uint16 image with values between entire range [0, 65535]
+
+    Parameters
+    ----------
+    img
+        Image to normalize
+    dtype
+        Target data type, only integer subtypes currently sensible and are supported
+    offset, optional
+        Offset if that was already precomputed. If not, it will be calculated from `arr`
+    scale, optional
+        Scale if that was already precomputed. If not, it will be calculated from `arr`
+
+    Returns
+    -------
+        The normalized image along casted to given data type, along with the offset and
+        scale used to normalize it
+
+    Raises
+    ------
+    ValueError
+        Unsupported data type
+    """
+    if np.issubdtype(dtype, np.integer):
+        type_info = np.iinfo(dtype)
+    else:
+        e_ = f"Unsupported dtype {dtype} for normalization"
+        raise ValueError(e_)
+
+    dtype_min = type_info.min
+    dtype_max = type_info.max
+
+    if offset is None or scale is None:
+        offset_ = cast(float, np.min(img))
+        scale_ = cast(float, np.max(img) - offset_)
+    else:
+        offset_ = offset
+        scale_ = scale
+
+    normed_to_0_1 = (img - offset_) / scale_
+
+    normalized_image = normed_to_0_1 * (dtype_max - dtype_min) + dtype_min
+    normalized_image = normalized_image.astype(dtype)
+
+    return normalized_image, offset_, scale_
+
+
+@overload
+def image_to_uint16_range(img: np.ndarray) -> tuple[np.ndarray, float, float]: ...
+
+
+@overload
+def image_to_uint16_range(
+    img: xarray.DataArray,
+) -> tuple[xarray.DataArray, float, float]: ...
+
+
+def image_to_uint16_range(img: ImageArray_) -> tuple[ImageArray_, float, float]:
+    """Normalise image to bounds of uint16, see above function for details
+
+    Parameters
+    ----------
+    img
+        Image to normalize
+
+    Returns
+    -------
+        The normalized image along casted to given data type, along with the offset and
+        scale used to normalize it
+    """
+    return image_to_dtype_range(img, np.dtype(np.uint16))
+
+
+@overload
+def image_to_original_range(
+    img: np.ndarray,
+    offset: float,
+    scale: float,
+    dtype: np.dtype | None = None,
+) -> xarray.DataArray: ...
+
+
+@overload
+def image_to_original_range(
+    img: xarray.DataArray,
+    offset: float,
+    scale: float,
+    dtype: np.dtype | None = None,
+) -> xarray.DataArray: ...
+
+
+def image_to_original_range(
+    img: ImageArray_,
+    offset: float,
+    scale: float,
+    dtype: np.dtype | None = None,
+) -> ImageArray_:
+    """Revert normalisation applied to an image. The image 'arr' must have the same
+    data type as the result from normalization, or it must be given separately
+
+    Parameters
+    ----------
+    arr
+        Image to revert back to original values
+    offset
+        Offset that was applied to the image
+    scale
+        Scale that was applied to the image
+    dtype, optional
+        The data type that the image was casted to during normalization, by default None
+        where the data type of `arr` will be assumed to be correct.
+
+    Returns
+    -------
+        Image that is back in original range of values before normalization
+
+    Raises
+    ------
+    ValueError
+        Unsupported data type
+    """
+    if not dtype:
+        dtype = img.dtype
+
+    # Check real bounds from numpy data types
+    if np.issubdtype(dtype, np.integer) and isinstance(dtype, np.dtype):
+        type_info = np.iinfo(dtype)
+    else:
+        e_ = f"Unsupported dtype {dtype} for normalization"
+        raise ValueError(e_)
+
+    dtype_min = type_info.min
+    dtype_max = type_info.max
+
+    # Reverse the normalization
+    denormed_to_0_1 = (img - dtype_min) / (dtype_max - dtype_min)
+    original_image = denormed_to_0_1 * scale + offset
+
+    return original_image

kuva_reader/reader/level0.py

@@ -0,0 +1,238 @@
+from pathlib import Path
+from typing import cast
+
+import numpy as np
+import rioxarray as rx
+import xarray
+from kuva_metadata import MetadataLevel0
+from pint import UnitRegistry
+
+from kuva_reader import image_to_dtype_range, image_to_original_range
+
+from .product_base import ProductBase
+
+
+class Level0Product(ProductBase[MetadataLevel0]):
+    """
+    Level 0 products contain the raw data acquired from the sensor. They
+    consist of one roughly georeferenced geotiff per camera and the associated
+    metadata. Changes to them are only performed at the metadata level to avoid
+    deteriorating them.
+
+    At this processing level frames are not aligned, a natural consequence of
+    satellite motion, and are therefore not very useful for any activity that
+    require working with more than one band simultaneously. In that case you
+    should look into using L1 products.
+
+    The data in the image files is lazy loaded to make things snappier for end
+    users but may lead to surprising behaviour if you are not aware of it
+
+
+    Parameters
+    ----------
+    image_path
+        Path to the folder containing the L0 product images
+    metadata, optional
+        Metadata if already read e.g. from a database. By default None, meaning
+        automatic fetching from metadata sidecar file
+    target_ureg, optional
+        Pint Unit Registry to swap to. This is only relevant when parsing data from a
+        JSON file, which by default uses the kuva-metadata ureg.
+    as_physical_unit
+        Whether to denormalize data from full data type range back to the physical
+        units stored with the data, by default False
+    target_dtype
+        Target data type to normalize data to. This will first denormalize the data
+        to its original range and then normalize to new data type range to keep a
+        scale and offset, by default None
+
+    Attributes
+    ----------
+    image_path: Path
+        Path to the folder containing the images.
+    metadata: MetadataLevel0
+        The metadata associated with the images
+    images: Dict[str, xarray.DataArray]
+        The arrays with the actual data. This have the rioxarray extension activated on
+        them so lots of GIS functionality are available on them. Imporantly, the GCPs
+        can be retrieved like so: `ds.rio.get_gcps()`
+    data_tags: Dict[str, Any]
+        Tags stored along with the data. These can be used e.g. to check the physical
+        units of pixels or normalisation factors.
+    """
+
+    def __init__(
+        self,
+        image_path: Path,
+        metadata: MetadataLevel0 | None = None,
+        target_ureg: UnitRegistry | None = None,
+        as_physical_unit: bool = False,
+        target_dtype: np.dtype | None = None,
+    ) -> None:
+        super().__init__(image_path, metadata, target_ureg)
+
+        self.images = {
+            camera: cast(
+                xarray.DataArray,
+                rx.open_rasterio(
+                    self.image_path / (cube.camera.name + ".tif"),
+                ),
+            )
+            for camera, cube in self.metadata.image.data_cubes.items()  # type: ignore
+        }
+
+        # Read tags for images and denormalize / renormalize if needed
+        self.data_tags = {camera: img.attrs for camera, img in self.images.items()}
+        if as_physical_unit or target_dtype:
+            for camera, img in self.images.items():
+                # Move from normalized full scale back to original data float values.
+                # pop() since values not true anymore after denormalization.
+                norm_img = image_to_original_range(
+                    img,
+                    self.data_tags[camera].pop("data_offset"),
+                    self.data_tags[camera].pop("data_scale"),
+                )
+                self.images[camera] = norm_img
+
+                if target_dtype:
+                    # For algorithm needs, cast and normalize to a specific dtype range
+                    # NOTE: This may remove data precision e.g. uint16 -> uint8
+                    norm_img, offset, scale = image_to_dtype_range(img, target_dtype)
+                    self.data_tags[camera]["data_offset"] = offset
+                    self.data_tags[camera]["data_scale"] = scale
+
+    def __getitem__(self, camera: str) -> xarray.DataArray:
+        """Return the datarray for the chosen camera."""
+        return self.images[camera]
+
+    def keys(self) -> list[str]:
+        """Easy access to the camera keys."""
+        return list(self.images.keys())
+
+    def _get_data_from_sidecar(
+        self, sidecar_path: Path, target_ureg: UnitRegistry | None = None
+    ) -> MetadataLevel0:
+        """Read product metadata from the sidecar file attached with the product
+
+        Parameters
+        ----------
+        sidecar_path
+            Path to sidecar JSON
+        target_ureg, optional
+            Unit registry to change to when validating JSON, by default None
+            (kuva-metadata ureg)
+
+        Returns
+        -------
+            The metadata object
+        """
+        with (sidecar_path).open("r") as fh:
+            if target_ureg is None:
+                metadata = MetadataLevel0.model_validate_json(
+                    fh.read(),
+                    context={
+                        "image_path": sidecar_path.parent,
+                    },
+                )
+            else:
+                # The Image subclass in MetadataLevel0 has an alignment graph that
+                # requires a specific context. Swapping UnitRegistries will also require
+                # serialization, requiring the extra graph path context parameter.
+                metadata = cast(
+                    MetadataLevel0,
+                    MetadataLevel0.model_validate_json_with_ureg(
+                        fh.read(),
+                        target_ureg,
+                        context={
+                            "image_path": sidecar_path.parent,
+                            "graph_json_file_name": f"{sidecar_path.stem}_graph.json",
+                        },
+                    ),
+                )
+
+        return metadata
+
+    def _calculate_band_offsets_and_frames(self, cube: str):
+        bands_info = self.metadata.image.data_cubes[cube].bands
+
+        band_n_frames = [band.n_frames for band in bands_info]
+        band_offsets = np.cumsum(band_n_frames)
+
+        # The first offset ie 0 is missing and the last is not an offset just the
+        # length. Fix it.
+        band_offsets = band_offsets[:-1].tolist()
+        band_offsets.insert(0, 0)
+        return band_offsets, band_n_frames
+
+    def calculate_frame_offset(self, cube: str, band_id: int, frame_idx: int) -> int:
+        """Find the offset at which a frame lives within a cube."""
+        band_offsets, _ = self._calculate_band_offsets_and_frames(cube)
+        frame_offset = band_offsets[band_id] + frame_idx
+
+        return frame_offset
+
+    def read_frame(self, cube: str, band_id: int, frame_idx: int) -> np.ndarray:
+        """Extract a specific frame from a cube and band."""
+        frame_offset = self.calculate_frame_offset(cube, band_id, frame_idx)
+        return self[cube][frame_offset, :, :].to_numpy()
+
+    def read_band(self, cube: str, band_id: int) -> np.ndarray:
+        """Extract a specific band from a cube"""
+        band_offsets, band_n_frames = self._calculate_band_offsets_and_frames(cube)
+
+        # Calculate the final frame offset for this band and frame
+        band_offset_ll = band_offsets[band_id]
+        band_offset_ul = band_offset_ll + band_n_frames[band_id]
+        return self[cube][band_offset_ll:band_offset_ul, :, :].to_numpy()
+
+    def read_data_units(self) -> np.ndarray:
+        """Read unit of product and validate they match between cameras"""
+        units = [tags.get("data_unit") for tags in self.data_tags.values()]
+        if all(product_unit == units[0] for product_unit in units):
+            return units[0]
+        else:
+            # TODO: We should try conversion though
+            e_ = "Cameras have different physical units stored to them."
+            raise ValueError(e_)
+
+    def get_bad_pixel_mask(self, camera: str | None = None) -> xarray.Dataset:
+        """Get the bad pixel mask associated to each camera of the L0 product
+
+        Returns
+        -------
+            The bad pixel masks of the cameras
+        """
+        if camera is None:
+            e_ = "The `camera` argument must be given for L0 product bad pixel masks."
+            raise ValueError(e_)
+        bad_pixel_filename = f"{camera}_per_frame_cloud_mask.tif"
+        return self._read_array(self.image_path / bad_pixel_filename)
+
+    def get_cloud_mask(self, camera: str | None = None) -> xarray.Dataset:
+        """Get the cloud mask associated to the product.
+
+        Returns
+        -------
+            The cloud mask
+        """
+        if camera is None:
+            e_ = "The `camera` argument must be given for L0 product cloud masks."
+            raise ValueError(e_)
+        bad_pixel_filename = f"{camera}_per_frame_cloud_mask.tif"
+        return self._read_array(self.image_path / bad_pixel_filename)
+
+
+def generate_level_0_metafile():
+    """Example function for reading a product and generating a metadata file from the
+    sidecar metadata objects.
+    """
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("image_path")
+    args = parser.parse_args()
+
+    image_path = Path(args.image_path)
+
+    product = Level0Product(image_path)
+    product.generate_metadata_file()

kuva_reader/reader/level1.py

@@ -0,0 +1,178 @@
+from pathlib import Path
+from typing import cast
+
+import rioxarray as rx
+from kuva_metadata import MetadataLevel1AB, MetadataLevel1C
+from pint import UnitRegistry
+from xarray import Dataset
+
+from .product_base import ProductBase
+
+
+class Level1ABProduct(ProductBase[MetadataLevel1AB]):
+    """
+    Level 1AB products combine multiple L0 products into a band aligned product.
+
+    Changes to them are only performed at the metadata level where results may be
+    cached for further use.
+
+    Parameters
+    ----------
+    image_path
+        Path to the folder containing the L1A or L1B product
+    metadata, optional
+        Metadata if already read e.g. from a database. By default None, meaning
+        automatic fetching from metadata sidecar file
+    target_ureg, optional
+        Pint Unit Registry to swap to. This is only relevant when parsing data from a
+        JSON file, which by default uses the kuva-metadata ureg.
+
+    Attributes
+    ----------
+    image_path: Path
+        Path to the folder containing the image.
+    metadata: MetadataLevel1AB
+        The metadata associated with the images
+    image: xarray.DataArray
+        The arrays with the actual data. This have the rioxarray extension activated on
+        them so lots of GIS functionality are available on them. For example, the GCPs
+        if any could be retrieved like so: `ds.rio.get_gcps()`
+    data_tags: dict
+        Tags saved along with the product. The tag "data_unit" shows what the unit of
+        the product actually is.
+    """
+
+    def __init__(
+        self,
+        image_path: Path,
+        metadata: MetadataLevel1AB | None = None,
+        target_ureg: UnitRegistry | None = None,
+    ) -> None:
+        super().__init__(image_path, metadata, target_ureg)
+
+        self.image = cast(
+            Dataset,
+            rx.open_rasterio(self.image_path / "L1B.tif"),
+        )
+        self.data_tags = self.image.attrs
+
+    def _get_data_from_sidecar(
+        self, sidecar_path: Path, target_ureg: UnitRegistry | None = None
+    ) -> MetadataLevel1AB:
+        """Read product metadata from the sidecar file attached with the product
+
+        Parameters
+        ----------
+        sidecar_path
+            Path to sidecar JSON
+        target_ureg, optional
+            Unit registry to change to when validating JSON, by default None
+            (kuva-metadata ureg)
+
+        Returns
+        -------
+            The metadata object
+        """
+        with (sidecar_path).open("r") as fh:
+            if target_ureg is None:
+                metadata = MetadataLevel1AB.model_validate_json(fh.read())
+            else:
+                metadata = cast(
+                    MetadataLevel1AB,
+                    MetadataLevel1AB.model_validate_json_with_ureg(
+                        fh.read(), target_ureg
+                    ),
+                )
+
+        return metadata
+
+
+class Level1CProduct(ProductBase[MetadataLevel1C]):
+    """
+    Level 1C products are georeferenced and orthorectified L1AB products.
+
+    Parameters
+    ----------
+    image_path
+        Path to the folder containing the L1C product
+    metadata, optional
+        Metadata if already read e.g. from a database. By default None, meaning
+        automatic fetching from metadata sidecar file
+    target_ureg, optional
+        Pint Unit Registry to swap to. This is only relevant when parsing data from a
+        JSON file, which by default uses the kuva-metadata ureg.
+
+    Attributes
+    ----------
+    image_path: Path
+        Path to the folder containing the image.
+    metadata: MetadataLevel1C
+        The metadata associated with the images
+    image: xarray.DataArray
+        The arrays with the actual data. This have the rioxarray extension activated on
+        them so lots of GIS functionality are available on them. For example, the GCPs
+        if any could be retrieved like so: `ds.rio.get_gcps()`
+    data_tags: dict
+        Tags saved along with the product. The tag "data_unit" shows what the unit of
+        the product actually is.
+    """
+
+    def __init__(
+        self,
+        image_path: Path,
+        metadata: MetadataLevel1C | None = None,
+        target_ureg: UnitRegistry | None = None,
+    ) -> None:
+        super().__init__(image_path, metadata, target_ureg)
+
+        self.image = cast(
+            Dataset,
+            rx.open_rasterio(self.image_path / "L1C.tif"),
+        )
+        self.data_tags = self.image.attrs
+
+    def _get_data_from_sidecar(
+        self, sidecar_path: Path, target_ureg: UnitRegistry | None = None
+    ) -> MetadataLevel1C:
+        """Read product metadata from the sidecar file attached with the product
+
+        Parameters
+        ----------
+        sidecar_path
+            Path to sidecar JSON
+        target_ureg, optional
+            Unit registry to change to when validating JSON, by default None
+            (kuva-metadata ureg)
+
+        Returns
+        -------
+            The metadata object
+        """
+        with (sidecar_path).open("r") as fh:
+            if target_ureg is None:
+                metadata = MetadataLevel1C.model_validate_json(fh.read())
+            else:
+                metadata = cast(
+                    MetadataLevel1C,
+                    MetadataLevel1C.model_validate_json_with_ureg(
+                        fh.read(), target_ureg
+                    ),
+                )
+
+        return metadata
+
+
+def generate_level_1_metafile():
+    """Example function for reading a product and generating a metadata file from the
+    sidecar metadata objects.
+    """
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("image_path")
+    args = parser.parse_args()
+
+    image_path = Path(args.image_path)
+
+    product = Level1ABProduct(image_path)
+    product.generate_metadata_file()

kuva_reader/reader/level2.py

@@ -0,0 +1,100 @@
+from pathlib import Path
+from typing import cast
+
+import rioxarray as rx
+from kuva_metadata import MetadataLevel2A
+from pint import UnitRegistry
+from xarray import Dataset
+
+from .product_base import ProductBase
+
+
+class Level2AProduct(ProductBase[MetadataLevel2A]):
+    """
+    Level 2A products contain the atmospherically corrected BOA reflectance values.
+
+    Parameters
+    ----------
+    image_path
+        Path to the folder containing the L2A product
+    metadata, optional
+        Metadata if already read e.g. from a database. By default None, meaning
+        automatic fetching from metadata sidecar file
+    target_ureg, optional
+        Pint Unit Registry to swap to. This is only relevant when parsing data from a
+        JSON file, which by default uses the kuva-metadata ureg.
+
+    Attributes
+    ----------
+    image_path: Path
+        Path to the folder containing the image.
+    metadata: MetadataLevel2A
+        The metadata associated with the images
+    image: xarray.DataArray
+        The arrays with the actual data. This have the rioxarray extension activated on
+        them so lots of GIS functionality are available on them. For example, the GCPs
+        if any could be retrieved like so: `ds.rio.get_gcps()`
+    data_tags: dict
+        Tags saved along with the product. The tag "data_unit" shows what the unit of
+        the product actually is.
+    """
+
+    def __init__(
+        self,
+        image_path: Path,
+        metadata: MetadataLevel2A | None = None,
+        target_ureg: UnitRegistry | None = None,
+    ) -> None:
+        super().__init__(image_path, metadata, target_ureg)
+
+        self.image = cast(
+            Dataset,
+            rx.open_rasterio(self.image_path / "L2A.tif"),
+        )
+        self.data_tags = self.image.attrs
+
+    def _get_data_from_sidecar(
+        self, sidecar_path: Path, target_ureg: UnitRegistry | None = None
+    ) -> MetadataLevel2A:
+        """Read product metadata from the sidecar file attached with the product
+
+        Parameters
+        ----------
+        sidecar_path
+            Path to sidecar JSON
+        target_ureg, optional
+            Unit registry to change to when validating JSON, by default None
+            (kuva-metadata ureg)
+
+        Returns
+        -------
+            The metadata object
+        """
+        with (sidecar_path).open("r") as fh:
+            if target_ureg is None:
+                metadata = MetadataLevel2A.model_validate_json(fh.read())
+            else:
+                metadata = cast(
+                    MetadataLevel2A,
+                    MetadataLevel2A.model_validate_json_with_ureg(
+                        fh.read(), target_ureg
+                    ),
+                )
+
+        return metadata
+
+
+def generate_level_2_metafile():
+    """Example function for reading a product and generating a metadata file from the
+    sidecar metadata objects.
+    """
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("image_path")
+    args = parser.parse_args()
+
+    image_path = Path(args.image_path)
+
+    product = Level2AProduct(image_path)
+    product.generate_metadata_file()

kuva_reader/reader/product_base.py

@@ -0,0 +1,129 @@
+from abc import ABCMeta, abstractmethod
+from pathlib import Path
+from typing import Generic, TypeVar, cast
+
+import rioxarray as rx
+from kuva_metadata.sections_common import MetadataBase
+from pint import UnitRegistry
+from pydantic import BaseModel
+from xarray import Dataset
+
+TMetadata = TypeVar("TMetadata", bound=BaseModel)
+
+
+class ProductBase(Generic[TMetadata], metaclass=ABCMeta):
+    """Base class for all Kuva product levels containing the image and all metadata
+
+    Parameters
+    ----------
+    image_path
+        Local path to the stored image
+    metadata, optional
+        Metadata if already read e.g. from a database. By default None, meaning
+        automatic fetching from metadata sidecar file
+    target_ureg, optional
+        Pint Unit Registry to swap to. This is only relevant when parsing data from a
+        JSON file, which by default uses the kuva-metadata ureg.
+
+    Raises
+    ------
+    ValueError
+        Providing Kuva image as something else than a folder
+    Exception
+        Any errors coming from the reading of the sidecar object
+    """
+
+    def __init__(
+        self,
+        image_path: Path,
+        metadata: MetadataBase | None = None,
+        target_ureg: UnitRegistry | None = None,
+    ):
+        self.image_path = Path(image_path)
+
+        if not self.image_path.exists():
+            e_ = f"Image path does not exist: {self.image_path}"
+            raise ValueError(e_)
+
+        if not self.image_path.is_dir():
+            e_ = "Kuva images are folders."
+            raise ValueError(e_)
+
+        if metadata is None:
+            sidecar_path = self.image_path / f"{self.image_path.name}.json"
+            try:
+                self.metadata = self._get_data_from_sidecar(sidecar_path, target_ureg)
+            except Exception as e:
+                e_ = f"Metadata could not be read from the sidecar: {sidecar_path}."
+                raise Exception(e_).with_traceback(e.__traceback__)
+        else:
+            self.metadata = metadata
+
+    @abstractmethod
+    def _get_data_from_sidecar(
+        self, sidecar_path: Path, target_ureg: UnitRegistry | None = None
+    ) -> TMetadata:
+        pass
+
+    @staticmethod
+    def _read_array(array_path: Path) -> Dataset:
+        if array_path.exists():
+            return cast(
+                Dataset,
+                rx.open_rasterio(array_path),
+            )
+        else:
+            e_ = f"Product does not contain the array to be read at '{array_path}'"
+            raise ValueError(e_)
+
+    def get_bad_pixel_mask(self, camera: str | None = None) -> Dataset:
+        """Get the bad pixel mask associated to the product.
+
+        Parameters
+        ----------
+        camera
+            The camera to fetch the mask for. Only valid for L0 products, and is ignored
+            in any other level.
+
+        Returns
+        -------
+            The bad pixel mask
+        """
+        if camera is not None:
+            e_ = "Parameter `camera` is not supported in this product level."
+            raise ValueError(e_)
+        return self._read_array(self.image_path / "bad_pixel_mask_aggregated.tif")
+
+    def get_cloud_mask(self, camera: str | None = None) -> Dataset:
+        """Get the cloud mask associated to the product.
+
+        Parameters
+        ----------
+        camera
+            The camera to fetch the mask for. Only valid for L0 products, and is ignored
+            in any other level.
+
+        Returns
+        -------
+            The cloud mask
+        """
+        if camera is not None:
+            e_ = "Parameter `camera` is not supported in this product level."
+            raise ValueError(e_)
+        return self._read_array(self.image_path / "cloud_mask.tif")
+
+    def generate_metadata_file(self) -> None:
+        """Write the sidecar files next to the product."""
+        metadata_file_name = self.image_path.name + ".json"
+        graph_json_file_name = self.image_path.name + "_graph.json"
+
+        with (self.image_path / metadata_file_name).open("w") as fh:
+            fh.write(
+                self.metadata.model_dump_json(
+                    indent=2,
+                    context={
+                        "image_path": self.image_path,
+                        "graph_json_file_name": graph_json_file_name,
+                    },
+                )
+            )

kuva_reader/reader/utils.py

@@ -0,0 +1,51 @@
+import os
+from pathlib import Path
+
+import rasterio
+
+
+def db_conn_str():
+    "Prepare a connection string to connect to the DB"
+    test_db_params = {
+        "POSTGRES_USER": "postgres",
+        "POSTGRES_PASSWORD": "postgres",
+        "POSTGRES_HOST": "localhost",
+        "POSTGRES_DB": "hyperfield",
+        "POSTGRES_PORT": "5432",
+    }
+
+    def query_param(param):
+        return os.environ[param] if param in os.environ else test_db_params[param]
+
+    username = query_param("POSTGRES_USER")
+    password = query_param("POSTGRES_PASSWORD")
+    host = query_param("POSTGRES_HOST")
+    name = query_param("POSTGRES_DB")
+    port = query_param("POSTGRES_PORT")
+
+    conn_str = f"postgres://{username}:{password}@{host}:{port}/{name}?sslmode=disable"
+
+    return conn_str
+
+
+def retrieve_folder_product_id(image_path: Path, product_level: str) -> str:
+    tif_files = Path(image_path).glob("*.tif")
+
+    potential_ids = set()
+    for tif in tif_files:
+        ds = rasterio.open(tif)
+        tags = ds.tags()
+
+        if "_KUVA_PRODUCT_LEVEL" in tags and "_KUVA_PRODUCT_ID" in tags:
+            if tags["_KUVA_PRODUCT_LEVEL"] == product_level:
+                # This are files of interest
+                potential_ids.add(tags["_KUVA_PRODUCT_ID"])
+
+    if len(potential_ids) == 0:
+        raise ValueError(f"The folder contains no KUVA L{product_level} products.")
+    elif len(potential_ids) > 1:
+        raise ValueError(
+            f"The folder contains more than one KUVA L{product_level} product."
+        )
+    else:
+        return list(potential_ids)[0]

kuva_reader-0.1.0.dist-info/METADATA

@@ -0,0 +1,24 @@
+Metadata-Version: 2.1
+Name: kuva-reader
+Version: 0.1.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
+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.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+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=8tNS2ok8EdOWEURnFbWGGYGtLecBc3J9xAWHTO_IpQA,9474
+kuva_reader/reader/level1.py,sha256=bqEo6NlVSC2I6lrf9is6YgGsa_uNZMX21zXxtC6ewNc,5772
+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.0.dist-info/METADATA,sha256=Ru1joPFSJVhZ8dUKPYQv9D6VxT7LV0HD-36RuSBXT0c,930
+kuva_reader-0.1.0.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+kuva_reader-0.1.0.dist-info/entry_points.txt,sha256=YJysY9EChfOb1W_IEht2oE5Z8Y9jA0J6-kofaPv-NdI,149
+kuva_reader-0.1.0.dist-info/RECORD,,

kuva_reader-0.1.0.dist-info/WHEEL

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

kuva_reader-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+make-l0-meta=kuva_reader.reader.level0:generate_level_0_metafile
+make-l1-meta=kuva_reader.reader.level1:generate_level_1_metafile
+