cubexpress 0.1.0__py3-none-any.whl

cubexpress/__init__.py

@@ -0,0 +1,18 @@
+from cubexpress.conversion import lonlat2rt
+from cubexpress.download import getcube, getGeoTIFF
+from cubexpress.geotyping import RasterTransform, Request, RequestSet
+
+# Export the functions
+__all__ = [
+    "lonlat2rt",
+    "RasterTransform",
+    "Request",
+    "RequestSet",
+    "getcube",
+    "getGeoTIFF",
+]
+
+# Dynamic version import
+import importlib.metadata
+
+__version__ = importlib.metadata.version("cubexpress")

cubexpress/conversion.py

@@ -0,0 +1,73 @@
+import utm
+
+from cubexpress.geotyping import RasterTransform
+
+# Define your GeotransformDict type if not already defined
+GeotransformDict = dict[str, float]
+
+
+def geo2utm(lon: float, lat: float) -> tuple[float, float, str]:
+    """
+    Converts latitude and longitude coordinates to UTM coordinates and returns the EPSG code.
+
+    Args:
+        lon (float): Longitude.
+        lat (float): Latitude.
+
+    Returns:
+        Tuple[float, float, str]: UTM coordinates (x, y) and the EPSG code.
+    """
+    x, y, zone, _ = utm.from_latlon(lat, lon)
+    epsg_code = f"326{zone:02d}" if lat >= 0 else f"327{zone:02d}"
+    return x, y, f"EPSG:{epsg_code}"
+
+
+def lonlat2rt(lon: float, lat: float, edge_size: int, scale: int) -> RasterTransform:
+    """
+    Generates a ``RasterTransform`` for a given point by converting geographic (lon, lat) coordinates
+    to UTM projection and building the necessary geotransform metadata.
+
+    This function:
+      1. Converts the input (lon, lat) to UTM coordinates using :func:`geo2utm`.
+      2. Defines the extent of the raster in UTM meters based on the specified ``edge_size`` (width/height in pixels)
+         and ``scale`` (meters per pixel).
+      3. Sets the Y-scale to be negative (``-scale``) because geospatial images typically consider the origin at
+         the top-left corner, resulting in a downward Y axis.
+
+    Args:
+        lon (float): The longitude coordinate.
+        lat (float): The latitude coordinate.
+        edge_size (int): Width and height of the output raster in pixels.
+        scale (int): Spatial resolution in meters per pixel.
+
+    Returns:
+        RasterTransform: A Pydantic model containing:
+         - ``crs``: The EPSG code in the form ``"EPSG:XYZ"``,
+         - ``geotransform``: A dictionary with the affine transform parameters,
+         - ``width`` and ``height``.
+
+    Example:
+        >>> import cubexpress
+        >>> rt = cubexpress.lonlat2rt(
+        ...     lon=-76.0,
+        ...     lat=40.0,
+        ...     edge_size=512,
+        ...     scale=30
+        ... )
+        >>> print(rt)
+    """
+    x, y, crs = geo2utm(lon, lat)
+    half_extent = (edge_size * scale) / 2
+
+    geotransform = GeotransformDict(
+        scaleX=scale,
+        shearX=0,
+        translateX=x - half_extent,
+        scaleY=-scale,  # Y-axis is inverted in geospatial images
+        shearY=0,
+        translateY=y + half_extent,
+    )
+
+    return RasterTransform(
+        crs=crs, geotransform=geotransform, width=edge_size, height=edge_size
+    )

cubexpress/download.py

@@ -0,0 +1,347 @@
+import concurrent.futures
+import json
+import pathlib
+from concurrent.futures import ThreadPoolExecutor
+from copy import deepcopy
+from typing import Optional
+
+import ee
+import numpy as np
+import pandas as pd
+
+from cubexpress.geotyping import RequestSet
+
+
+def check_not_found_error(error_message: str) -> bool:
+    """
+    Checks if the error message indicates that the image was not found.
+
+    Args:
+        error_message (str): The error message to check.
+
+    Returns:
+        bool: True if the error message indicates "not found", False otherwise.
+
+    Example:
+        >>> check_not_found_error("Total request size must be less than or equal to...")
+        True
+    """
+    return (
+        "Total request size" in error_message
+        and "must be less than or equal to" in error_message
+    )
+
+
+def quadsplit_manifest(manifest: dict) -> list[dict]:
+    """
+    Splits a manifest into four smaller ones by dividing the grid dimensions.
+
+    Args:
+        manifest (dict): The original manifest to split.
+
+    Returns:
+        List[dict]: A list of four smaller manifests with updated grid transformations.
+
+    Example:
+        >>> manifest = {'grid': {'dimensions': {'width': 100, 'height': 100}, 'affineTransform': {'scaleX': 0.1, 'scaleY': 0.1, 'translateX': 0, 'translateY': 0}}}
+        >>> quadsplit_manifest(manifest)
+        [{'grid': {'dimensions': {'width': 50, 'height': 50}, 'affineTransform': {'scaleX': 0.1, 'scaleY': 0.1, 'translateX': 0, 'translateY': 0}}}, {'grid': {'dimensions': {'width': 50, 'height': 50}, 'affineTransform': {'scaleX': 0.1, 'scaleY': 0.1, 'translateX': 5.0, 'translateY': 0}}}, ...]
+    """
+    manifest_copy = deepcopy(manifest)
+    new_width = manifest["grid"]["dimensions"]["width"] // 2
+    new_height = manifest["grid"]["dimensions"]["height"] // 2
+    manifest_copy["grid"]["dimensions"]["width"] = new_width
+    manifest_copy["grid"]["dimensions"]["height"] = new_height
+
+    manifests = []
+    for idx in range(4):
+        new_manifest = deepcopy(manifest_copy)
+        res_x = manifest["grid"]["affineTransform"]["scaleX"]
+        res_y = manifest["grid"]["affineTransform"]["scaleY"]
+
+        add_x, add_y = (0, 0)
+        if idx == 1:
+            add_x = new_width * res_x
+        elif idx == 2:
+            add_y = new_height * res_y
+        elif idx == 3:
+            add_x = new_width * res_x
+            add_y = new_height * res_y
+
+        new_manifest["grid"]["affineTransform"]["translateX"] += add_x
+        new_manifest["grid"]["affineTransform"]["translateY"] += add_y
+
+        manifests.append(new_manifest)
+
+    return manifests
+
+
+def getGeoTIFFbatch(
+    manifest_dict: dict,
+    full_outname: pathlib.Path,
+    max_deep_level: Optional[int] = 5,
+    method: Optional[str] = "getPixels",
+) -> Optional[np.ndarray]:
+    """
+    Downloads a GeoTIFF image from Google Earth Engine using either the `getPixels` or `computePixels` method.
+    If the requested area exceeds the size limit, the image is recursively split into smaller tiles until the
+    download succeeds or the maximum recursion depth is reached.
+
+    Args:
+        manifest_dict (dict): A dictionary containing image metadata, including grid dimensions, affine transformations,
+                              and either an `assetId` or `expression` for the image source.
+        full_outname (pathlib.Path): The full path where the downloaded GeoTIFF file will be saved.
+        max_deep_level (Optional[int]): Maximum recursion depth for splitting large requests. Defaults to 5.
+        method (Optional[str]): Method for retrieving image data. Can be 'getPixels' for asset-based requests or
+                                'computePixels' for expressions. Defaults to 'getPixels'.
+
+    Returns:
+        Optional[pathlib.Path]: The path to the downloaded GeoTIFF file. Returns `None` if the download fails.
+
+    Raises:
+        ValueError: If the method is not 'getPixels' or 'computePixels', or if the image cannot be found.
+
+    Example:
+        >>> import ee
+        >>> import pathlib
+        >>> ee.Initialize()
+        >>> manifest_dict = {
+        ...     "assetId": "COPERNICUS/S2_HARMONIZED/20160816T153912_20160816T154443_T18TYN",
+        ...     "fileFormat": "GEO_TIFF",
+        ...     "bandIds": ["B4", "B3", "B2"],
+        ...     "grid": {
+        ...         "dimensions": {
+        ...             "width": 512,
+        ...             "height": 512
+        ...         },
+        ...         "affineTransform": {
+        ...             "scaleX": 10,
+        ...             "shearX": 0,
+        ...             "translateX": 725260.108545126,
+        ...             "scaleY": -10,
+        ...             "shearY": 0,
+        ...             "translateY": 4701550.38712196
+        ...         },
+        ...         "crsCode": "EPSG:32618"
+        ...     }
+        ... }
+
+        >>> getGeoTIFFbatch(manifest_dict pathlib.Path('output/sentinel_image.tif'))
+        PosixPath('output/sentinel_image.tif')
+    """
+
+    # Check if the maximum recursion depth has been reached
+    if max_deep_level == 0:
+        raise ValueError("Max recursion depth reached.")
+
+    try:
+        # Get the image bytes
+        if method == "getPixels":
+            image_bytes: bytes = ee.data.getPixels(manifest_dict)
+        elif method == "computePixels":
+            image_bytes: bytes = ee.data.computePixels(manifest_dict)
+        else:
+            raise ValueError("Method must be either 'getPixels' or 'computePixels'")
+
+        # Write the image bytes to a file
+        with open(full_outname, "wb") as src:
+            src.write(image_bytes)
+    except Exception as e:
+        # TODO: This is a workaround when the image is not found, as it is a message from the server
+        # it is not possible to check the type of the exception
+        if not check_not_found_error(str(e)):
+            raise ValueError(
+                f"Error downloading the GeoTIFF file from Earth Engine: {e}"
+            )
+
+        # Create the output directory if it doesn't exist
+        child_folder: pathlib.Path = full_outname.parent / full_outname.stem
+        pathlib.Path(child_folder).mkdir(parents=True, exist_ok=True)
+
+        # Split the manifest into four smaller manifests
+        manifest_dicts = quadsplit_manifest(manifest_dict)
+
+        for idx, manifest_dict_batch in enumerate(manifest_dicts):
+            # Recursively download the image
+            getGeoTIFFbatch(
+                full_outname=child_folder / ("%s__%02d.tif" % (full_outname.stem, idx)),
+                manifest_dict=manifest_dict_batch,
+                max_deep_level=max_deep_level - 1,
+                method=method,
+            )
+
+    return full_outname
+
+
+def getGeoTIFF(
+    manifest_dict: dict, full_outname: pathlib.Path, max_deep_level: Optional[int] = 5
+) -> Optional[np.ndarray]:
+    """
+    Retrieves an image from Earth Engine using the appropriate method based on the manifest type.
+
+    This function downloads a GeoTIFF image from Google Earth Engine (GEE). Depending on the content of
+    the provided manifest (`manifest_dict`), the function will either use the `getPixels` method (for
+    asset-based requests) or the `computePixels` method (for expressions). If the requested area exceeds
+    the size limit, the image will be recursively split into smaller tiles until the download succeeds or
+    the maximum recursion depth is reached.
+
+    Args:
+        manifest_dict (dict): A dictionary containing the image metadata. This should include either:
+            - `assetId`: The identifier of a GEE asset (e.g., satellite imagery).
+            - `expression`: A serialized string representing a GEE image expression (e.g., an image computation).
+            Additionally, the manifest should include grid information such as the image dimensions and affine transformations.
+
+        full_outname (pathlib.Path): The full path where the downloaded GeoTIFF file will be saved.
+
+        max_deep_level (Optional[int]): The maximum recursion depth for splitting large requests into smaller tiles if needed.
+            Defaults to 5.
+
+    Returns:
+        Optional[np.ndarray]: The downloaded image as a `numpy` array, or `None` if the download fails. It will
+            also return the full file path to the saved GeoTIFF image.
+
+    Raises:
+        ValueError: If the manifest does not contain either an `assetId` or `expression`, or if there is an error during download.
+
+    Example 1: Downloading an image using an `assetId`:
+        >>> import ee
+        >>> import pathlib
+        >>> ee.Initialize()
+        >>> manifest_dict = {
+        ...     "assetId": "COPERNICUS/S2_HARMONIZED/20160816T153912_20160816T154443_T18TYN",
+        ...     "fileFormat": "GEO_TIFF",
+        ...     "bandIds": ["B4", "B3", "B2"],
+        ...     "grid": {
+        ...         "dimensions": {"width": 512, "height": 512},
+        ...         "affineTransform": {
+        ...             "scaleX": 10,
+        ...             "shearX": 0,
+        ...             "translateX": 725260.108545126,
+        ...             "scaleY": -10,
+        ...             "shearY": 0,
+        ...             "translateY": 4701550.38712196
+        ...         },
+        ...         "crsCode": "EPSG:32618"
+        ...     }
+        ... }
+        >>> getGeoTIFF(manifest_dict, pathlib.Path('output/sentinel_image.tif'))
+        PosixPath('output/sentinel_image.tif')
+
+    Example 2: Downloading an image using an `expression`:
+        >>> image = ee.Image("COPERNICUS/S2_HARMONIZED/20160816T153912_20160816T154443_T18TYN") \
+        ...           .divide(10_000) \
+        ...           .select(["B4", "B3", "B2"])
+        >>> expression = image.serialize()
+        >>> manifest_dict = {
+        ...     "expression": expression,
+        ...     "fileFormat": "GEO_TIFF",
+        ...     "grid": {
+        ...         "dimensions": {"width": 512, "height": 512},
+        ...         "affineTransform": {
+        ...             "scaleX": 10,
+        ...             "shearX": 0,
+        ...             "translateX": 725260.108545126,
+        ...             "scaleY": -10,
+        ...             "shearY": 0,
+        ...             "translateY": 4701550.38712196
+        ...         },
+        ...         "crsCode": "EPSG:32618"
+        ...     }
+        ... }
+        >>> getGeoTIFF(manifest_dict, pathlib.Path('output/expression_image.tif'))
+        PosixPath('output/expression_image.tif')
+    """
+    if "assetId" in manifest_dict:
+        return getGeoTIFFbatch(
+            manifest_dict=manifest_dict,
+            full_outname=full_outname,
+            max_deep_level=max_deep_level,
+            method="getPixels",
+        )
+    elif "expression" in manifest_dict:
+        if isinstance(
+            manifest_dict["expression"], str
+        ):  # Decode only if the expression is still a string.
+            # From a string to a ee.Image object
+            manifest_dict["expression"] = ee.deserializer.decode(
+                json.loads(manifest_dict["expression"])
+            )
+
+        return getGeoTIFFbatch(
+            manifest_dict=manifest_dict,
+            full_outname=full_outname,
+            max_deep_level=max_deep_level,
+            method="computePixels",
+        )
+    else:
+        raise ValueError("Manifest does not contain 'assetId' or 'expression'")
+
+
+def getcube(
+    request: RequestSet,
+    output_path: str | pathlib.Path,
+    nworkers: Optional[int] = None,
+    max_deep_level: Optional[int] = 5,
+) -> list[pathlib.Path]:
+    """
+    Downloads multiple GeoTIFF images in parallel from Google Earth Engine (GEE) based on the provided request set.
+
+    Args:
+        request (RequestSet): A collection of image requests containing metadata and processing parameters.
+        output_path (Union[str, pathlib.Path]): Directory where the downloaded images will be saved.
+        nworkers (Optional[int], default=None): Number of parallel threads. If None, runs sequentially.
+        max_deep_level (Optional[int], default=5): Maximum recursion depth for image subdivision if exceeding GEE limits.
+
+    Returns:
+        List[pathlib.Path]: List of paths to the downloaded GeoTIFF files.
+
+    Example:
+        >>> import ee, cubexpress
+        >>> ee.Initialize()
+        >>> point = ee.Geometry.Point([-97.59, 33.37])
+        >>> collection = ee.ImageCollection("COPERNICUS/S2_SR_HARMONIZED") \
+        ...                 .filterBounds(point) \
+        ...                 .filterDate('2024-01-01', '2024-01-31')
+        >>> image_ids = collection.aggregate_array('system:id').getInfo()
+        >>> geotransform = cubexpress.lonlat2rt(lon=-97.59, lat=33.37, edge_size=128, scale=10)
+        >>> requests = [cubexpress.Request(id=f"s2_{i}", raster_transform=geotransform, bands=["B4", "B3", "B2"], image=ee.Image(img_id)) for i, img_id in enumerate(image_ids)]
+        >>> cube_requests = cubexpress.RequestSet(requestset=requests)
+        >>> cubexpress.getcube(request=cube_requests, nworkers=4, output_path="output", max_deep_level=5)
+        [PosixPath('output/s2_0.tif'), PosixPath('output/s2_1.tif'), ...]
+    """
+
+    # Check that _dataframe exists and is not empty
+    if request._dataframe is None or request._dataframe.empty:
+        raise ValueError(
+            "The request's _dataframe is None or empty. "
+            "There are no valid requests to process."
+        )
+    
+    # **Revalidate** the DataFrame structure, in case the user manipulated it.
+    request._validate_dataframe_schema()
+
+    # Get the table
+    table: pd.DataFrame = request._dataframe
+
+    # Create the output directory if it doesn't exist
+    output_path = pathlib.Path(output_path)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    results = []
+    with ThreadPoolExecutor(max_workers=nworkers) as executor:
+        futures = {
+            executor.submit(
+                getGeoTIFF, row.manifest, output_path / row.outname, max_deep_level
+            ): row
+            for _, row in table.iterrows()
+        }
+        for future in concurrent.futures.as_completed(futures):
+            try:
+                result = future.result()
+                if result:
+                    results.append(result)
+            except Exception as e:
+                # TODO add this into the log
+                print(f"Error processing {futures[future].outname}: {e}")
+
+    return results

cubexpress/geotyping.py

@@ -0,0 +1,488 @@
+from __future__ import annotations
+
+from concurrent.futures import ProcessPoolExecutor
+from typing import Any, Final, List, Set, TypeAlias
+
+import ee
+import pandas as pd
+from pydantic import BaseModel, field_validator, model_validator
+from pyproj import CRS, Transformer
+from typing_extensions import TypedDict
+
+# Type definitions
+NumberType: TypeAlias = int | float
+
+# Constants for required keys in the geotransform
+REQUIRED_KEYS: Final[Set[str]] = {
+    "scaleX",
+    "shearX",
+    "translateX",
+    "scaleY",
+    "shearY",
+    "translateY",
+}
+
+
+def get_transformer(source_crs_wkt: str) -> Transformer:
+    """Get cached transformer from source CRS to WGS84 (EPSG:4326)"""
+    target_crs = CRS.from_epsg(4326)
+    return Transformer.from_crs(
+        CRS.from_wkt(source_crs_wkt),
+        target_crs,
+        always_xy=True,  # Ensures consistent x,y order
+    )
+
+
+def rt2lonlat(raster: "RasterTransform") -> tuple[float, float]:
+    """
+    Calculate the geographic centroid in WGS84 with optimized performance.
+
+    Args:
+        raster: RasterTransform instance with geospatial metadata
+
+    Returns:
+        Tuple of (longitude, latitude) in WGS84 coordinates
+    """
+    # Calculate pixel coordinates of raster center
+    col_center = (raster.width - 1) / 2.0
+    row_center = (raster.height - 1) / 2.0
+
+    # Extract geotransform parameters as local variables for faster access
+    gt = raster.geotransform
+    tx = gt["translateX"]
+    sx = gt["scaleX"]
+    shx = gt["shearX"]
+    ty = gt["translateY"]
+    shy = gt["shearY"]
+    sy = gt["scaleY"]
+
+    # Apply affine transformation
+    x = tx + sx * col_center + shx * row_center
+    y = ty + shy * col_center + sy * row_center
+
+    # Check if transformation is needed
+    source_crs = CRS.from_user_input(raster.crs)
+    target_crs = CRS.from_epsg(4326)
+
+    if source_crs == target_crs:
+        return (x, y)
+
+    # Perform the transformation
+    transformer = get_transformer(source_crs.to_wkt())
+    lon, lat = transformer.transform(x, y)
+
+    return lon, lat, x, y
+
+
+class GeotransformDict(TypedDict):
+    """
+    Type definition for a geotransform dictionary containing spatial transformation parameters.
+
+    Attributes:
+        scaleX (NumberType): The scaling factor in the X direction.
+        shearX (NumberType): The shear factor in the X direction.
+        translateX (NumberType): The translation in the X direction.
+        scaleY (NumberType): The scaling factor in the Y direction.
+        shearY (NumberType): The shear factor in the Y direction.
+        translateY (NumberType): The translation in the Y direction.
+    """
+
+    scaleX: NumberType
+    shearX: NumberType
+    translateX: NumberType
+    scaleY: NumberType
+    shearY: NumberType
+    translateY: NumberType
+
+
+class RasterTransform(BaseModel):
+    """
+    Represents a single geospatial metadata entry with CRS and transformation information.
+
+    Attributes:
+        id (str): The unique identifier for the raster metadata.
+        crs (str): The Coordinate Reference System string (EPSG code or WKT).
+        geotransform (GeotransformDict): A dictionary containing spatial transformation parameters.
+        width (int): Raster width in pixels.
+        height (int): Raster height in pixels.
+
+    Example:
+        >>> metadata = RasterTransform(
+        ...     id="image1",
+        ...     crs="EPSG:4326",
+        ...     geotransform={
+        ...         'scaleX': 1.0, 'shearX': 0, 'translateX': 100.0,
+        ...         'scaleY': 1.0, 'shearY': 0, 'translateY': 200.0
+        ...     },
+        ...     width=1000,
+        ...     height=1000
+        ... )
+        RasterTransform(crs='EPSG:4326', width=1000, height=1000)
+    """
+
+    crs: str
+    geotransform: GeotransformDict
+    width: int
+    height: int
+
+    @model_validator(mode="before")
+    def validate_geotransform(cls, values):
+        """
+        Validates the geotransform dictionary to ensure it has the required keys
+        and that all values are numeric and non-zero where applicable.
+
+        Args:
+            values (dict): The input values being validated.
+
+        Returns:
+            dict: The validated values.
+
+        Raises:
+            ValueError: If validation fails for missing keys, invalid types, or zero scale values.
+        """
+        geotransform = values.get("geotransform")
+
+        if not isinstance(geotransform, dict):
+            raise ValueError(
+                f"Expected geotransform to be a dictionary, got {type(geotransform)}"
+            )
+
+        missing_keys = REQUIRED_KEYS - set(geotransform.keys())
+        if missing_keys:
+            raise ValueError(f"Missing required keys: {missing_keys}")
+
+        extra_keys = set(geotransform.keys()) - REQUIRED_KEYS
+        if extra_keys:
+            raise ValueError(f"Unexpected keys found: {extra_keys}")
+
+        for key in REQUIRED_KEYS:
+            if not isinstance(geotransform[key], (int, float)):
+                raise ValueError(f"Value for '{key}' must be numeric (int or float)")
+
+        if not (geotransform["scaleX"] and geotransform["scaleY"]):
+            raise ValueError("Scale values cannot be zero")
+
+        return values
+
+    @field_validator("width", "height")
+    @classmethod
+    def validate_positive(cls, value: int, field) -> int:
+        """
+        Validates that width and height are positive integers.
+
+        Args:
+            value (int): The value of width or height to validate.
+            field: The field being validated (width or height).
+
+        Returns:
+            int: The validated value.
+
+        Raises:
+            ValueError: If the value is not positive.
+        """
+        if value <= 0:
+            raise ValueError(
+                f"{field.field_name} must be positive and greater than zero, but got {value}"
+            )
+        return value
+
+    def __str__(self) -> str:
+        """
+        Provides a string representation of the RasterTransform instance with a table
+        format for the geotransform parameters.
+
+        Returns:
+            str: A formatted string showing the raster metadata and geotransform.
+        """
+        geotransform_data = {
+            "Parameter": [
+                "scaleX",
+                "shearX",
+                "translateX",
+                "scaleY",
+                "shearY",
+                "translateY",
+            ],
+            "Value": [
+                self.geotransform["scaleX"],
+                self.geotransform["shearX"],
+                self.geotransform["translateX"],
+                self.geotransform["scaleY"],
+                self.geotransform["shearY"],
+                self.geotransform["translateY"],
+            ],
+        }
+        geotransform_df = pd.DataFrame(geotransform_data)
+        return f"RasterTransform(crs={self.crs}, width={self.width}, height={self.height})\n\nGeotransform:\n{geotransform_df}"
+
+
+class Request(BaseModel):
+    id: str
+    raster_transform: RasterTransform
+    image: Any
+    bands: List[str]
+    _expression_key: str = None
+
+    @model_validator(mode="after")
+    def validate_image(self):
+
+        if isinstance(self.image, ee.Image):
+            self.image = self.image.serialize()
+            self._expression_key = "expression"
+        # to avoid reading serialization of an ee.Image as str in RequestSet
+        elif isinstance(self.image, str) and self.image.strip().startswith("{"):
+            self._expression_key = "expression"
+        else:
+            self.image = self.image
+            self._expression_key = "assetId"
+
+        return self
+
+
+class RequestSet(BaseModel):
+    """
+    Container for multiple RasterTransform instances with bulk validation capabilities.
+
+    Attributes:
+        rastertransformset (List[RasterTransform]): A list of RasterTransform metadata entries.
+
+    Example:
+        >>> metadatas = RasterTransformSet(rastertransformset=[metadata1, metadata2])
+        >>> df = metadatas.export_df()
+    """
+
+    requestset: List[Request]
+    _dataframe: pd.DataFrame | None = None
+
+
+
+    def create_manifests(self) -> pd.DataFrame:
+        """
+        Exports the raster metadata to a pandas DataFrame.
+
+        Returns:
+            pd.DataFrame: A DataFrame containing the metadata for all entries.
+
+        Example:
+            >>> df = raster_transform_set.export_df()
+            >>> print(df)
+        """
+        # Use ProcessPoolExecutor for CPU-bound tasks to convert raster transforms to lon/lat
+        with ProcessPoolExecutor(max_workers=None) as executor:
+            # Submit all tasks to the executor
+            futures = [
+                executor.submit(rt2lonlat, rt.raster_transform)
+                for rt in self.requestset
+            ]
+
+            # Collect results as they complete
+            points = [future.result() for future in futures]
+            lon, lat, x, y = zip(*points)
+
+        return pd.DataFrame(
+            [
+                {
+                    "id": meta.id,
+                    "lon": lon[index],
+                    "lat": lat[index],
+                    "x": x[index],
+                    "y": y[index],
+                    "crs": meta.raster_transform.crs,
+                    "width": meta.raster_transform.width,
+                    "height": meta.raster_transform.height,
+                    "geotransform": meta.raster_transform.geotransform,
+                    "scale_x": meta.raster_transform.geotransform["scaleX"],
+                    "scale_y": meta.raster_transform.geotransform["scaleY"],
+                    "manifest": {
+                        meta._expression_key: meta.image,
+                        "fileFormat": "GEO_TIFF",
+                        "bandIds": meta.bands,
+                        "grid": {
+                            "dimensions": {
+                                "width": meta.raster_transform.width,
+                                "height": meta.raster_transform.height,
+                            },
+                            "affineTransform": meta.raster_transform.geotransform,
+                            "crsCode": meta.raster_transform.crs,
+                        },
+                    },
+                    "outname": f"{meta.id}.tif",
+                }
+                for index, meta in enumerate(self.requestset)
+            ]
+        )
+
+
+    def _validate_dataframe_schema(self) -> None:
+        """
+        Checks that the `_dataframe` contains the required columns and that each column
+        has the expected data type. Also verifies that the `manifest` field has the
+        necessary minimum structure.
+        """
+
+        # A) Required columns and expected data types
+        required_columns = {
+            "id": str,
+            "lon": float,
+            "lat": float,
+            "x": float,
+            "y": float,
+            "crs": str,
+            "width": int,
+            "height": int,
+            "geotransform": dict,
+            "scale_x": (int, float),
+            "scale_y": (int, float),
+            "manifest": dict,
+            "outname": str,
+        }
+
+        df_cols = set(self._dataframe.columns)
+        required_cols = set(required_columns.keys())
+
+        # 1. Check for missing columns
+        missing_cols = required_cols - df_cols
+        if missing_cols:
+            raise ValueError(f"Missing required columns in dataframe: {missing_cols}")
+
+        # 2. (Optional) Check for extra columns
+        # extra_cols = df_cols - required_cols
+        # if extra_cols:
+        #     raise ValueError(f"Unexpected extra columns in dataframe: {extra_cols}")
+
+        # 3. Verify data types (basic check)
+        for col_name, expected_type in required_columns.items():
+            for i, value in enumerate(self._dataframe[col_name]):
+                if not isinstance(value, expected_type):
+                    # For cases like (int, float), you can check with isinstance(value, (int, float))
+                    # or directly use the tuple in `expected_type`
+                    if isinstance(expected_type, tuple):
+                        if not any(isinstance(value, t) for t in expected_type):
+                            raise ValueError(
+                                f"Column '{col_name}' has an invalid type in row {i}. "
+                                f"Expected one of {expected_type}, got {type(value)}"
+                            )
+                    else:
+                        raise ValueError(
+                            f"Column '{col_name}' has an invalid type in row {i}. "
+                            f"Expected {expected_type}, got {type(value)}"
+                        )
+
+        # B) Validation of the `manifest` column structure
+        #    - Must contain at least 'assetId' or 'expression'
+        #    - Must contain 'grid' with the minimum required sub-keys
+        #    - Example:
+        #         {
+        #           "fileFormat": "GEO_TIFF",
+        #           "bandIds": [...],
+        #           "grid": {
+        #              "dimensions": {"width": ..., "height": ...},
+        #              "affineTransform": {...},
+        #              "crsCode": ...
+        #           },
+        #           // Either "assetId" or "expression" must be here
+        #         }
+        for i, row in self._dataframe.iterrows():
+            manifest = row["manifest"]
+
+            # Main required keys
+            for key in ["fileFormat", "bandIds", "grid"]:
+                if key not in manifest:
+                    raise ValueError(
+                        f"Missing key '{key}' in 'manifest' for row index {i}"
+                    )
+
+            # At least one of 'assetId' or 'expression'
+            if not any(k in manifest for k in ["assetId", "expression"]):
+                raise ValueError(
+                    f"Manifest in row {i} does not contain 'assetId' or 'expression'"
+                )
+
+            # Basic validation of 'grid'
+            grid = manifest["grid"]
+            for subkey in ["dimensions", "affineTransform", "crsCode"]:
+                if subkey not in grid:
+                    raise ValueError(
+                        f"Missing key '{subkey}' in 'manifest.grid' for row index {i}"
+                    )
+
+            # Basic validation of 'dimensions'
+            dims = grid["dimensions"]
+            for dim_key in ["width", "height"]:
+                if dim_key not in dims:
+                    raise ValueError(
+                        f"Missing '{dim_key}' in 'manifest.grid.dimensions' for row {i}"
+                    )
+                if not isinstance(dims[dim_key], int) or dims[dim_key] <= 0:
+                    raise ValueError(
+                        f"'{dim_key}' in 'manifest.grid.dimensions' must be a positive integer. "
+                        f"Row {i} has value {dims[dim_key]}"
+                    )
+
+            # Basic validation of 'affineTransform'
+            aff = grid["affineTransform"]
+            for a_key in ["scaleX", "shearX", "translateX", "scaleY", "shearY", "translateY"]:
+                if a_key not in aff:
+                    raise ValueError(
+                        f"Missing '{a_key}' in 'manifest.grid.affineTransform' for row {i}"
+                    )
+                if not isinstance(aff[a_key], (int, float)):
+                    raise ValueError(
+                        f"Value for '{a_key}' in 'manifest.grid.affineTransform' must be numeric. "
+                        f"Row {i} has {type(aff[a_key])}."
+                    )
+
+
+
+    @model_validator(mode="after")
+    def validate_metadata(self) -> RequestSet:
+        """
+        Validates that all entries have consistent and valid CRS formats.
+
+        Returns:
+            RasterTransformSet: The validated instance.
+
+        Raises:
+            ValueError: If any CRS is invalid or inconsistent.
+        """
+        # 1. Pre-consistency validation (CRS, IDs, etc.)
+        crs_set: Set[str] = {meta.raster_transform.crs for meta in self.requestset}
+        validated_crs: Set[str] = set()
+
+        # Validate CRS formats
+        for crs in crs_set:
+            if crs not in validated_crs:
+                try:
+                    CRS.from_string(crs)
+                    validated_crs.add(crs)
+                except Exception as e:
+                    raise ValueError(f"Invalid CRS format: {crs}") from e
+
+        # Validate ids, they must be unique
+        ids = {meta.id for meta in self.requestset}
+        if len(ids) != len(self.requestset):
+            raise ValueError("All entries must have unique IDs")
+
+        # Upgrade same_coordinates to True if all coordinates are the same
+        # 2. We create the dataframe
+        self._dataframe = self.create_manifests()
+        
+        # 3. We validate the structure of the dataframe
+        self._validate_dataframe_schema()
+
+        return self
+    
+
+
+    def __repr__(self) -> str:
+        """
+        Provides a string representation of the metadata set including a table of all entries.
+
+        Returns:
+            str: A string representation of the entire RasterTransformSet.
+        """
+        num_entries = len(self.requestset)
+        return f"RasterTransformSet({num_entries} entries)"
+
+    def __str__(self):
+        return super().__repr__()

cubexpress-0.1.0.dist-info/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025, AndesDataCube
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

cubexpress-0.1.0.dist-info/METADATA

@@ -0,0 +1,305 @@
+Metadata-Version: 2.1
+Name: cubexpress
+Version: 0.1.0
+Summary: A Python package for efficient processing of cubic earth observation (EO) data
+Home-page: https://github.com/andesdatacube/cubexpress/
+License: MIT
+Author: Julio Contreras
+Author-email: contrerasnetk@gmail.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: numpy (>=1.25.2)
+Requires-Dist: pandas (>=2.0.3)
+Requires-Dist: utm (>=0.8.0,<0.9.0)
+Project-URL: Documentation, https://andesdatacube.github.io/cubexpress/
+Project-URL: Repository, https://github.com/andesdatacube/cubexpress/
+Description-Content-Type: text/markdown
+
+<h1></h1>
+
+<p align="center">
+  <img src="./docs/logo_cubexpress.png" width="39%">
+</p>
+
+<p align="center">
+    <em>A Python package for efficient processing of cubic earth observation (EO) data</em> 🚀
+</p>
+
+<p align="center">
+<a href='https://pypi.python.org/pypi/cubexpress'>
+    <img src='https://img.shields.io/pypi/v/cubexpress.svg' alt='PyPI' />
+</a>
+<a href="https://opensource.org/licenses/MIT" target="_blank">
+    <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License">
+</a>
+<a href="https://github.com/psf/black" target="_blank">
+    <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Black">
+</a>
+<a href="https://pycqa.github.io/isort/" target="_blank">
+    <img src="https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336" alt="isort">
+</a>
+</p>
+
+---
+
+**GitHub**: [https://github.com/andesdatacube/cubexpress/](https://github.com/andesdatacube/cubexpress/) 🌐
+
+**PyPI**: [https://pypi.org/project/cubexpress/](https://pypi.org/project/cubexpress/) 🛠️
+
+---
+
+## **Overview**
+
+**CubeXpress** is a Python package designed to **simplify and accelerate** the process of working with Google Earth Engine (GEE) data cubes. With features like multi-threaded downloads, automatic subdivision of large requests, and direct pixel-level computations on GEE, **CubeXpress** helps you handle massive datasets with ease.
+
+## **Key Features**
+- **Fast Image and Collection Downloads**  
+  Retrieve single images or entire collections at once, taking advantage of multi-threaded requests.
+- **Automatic Tiling**  
+  Large images are split ("quadsplit") into smaller sub-tiles, preventing errors with GEE’s size limits.
+- **Direct Pixel Computations**  
+  Perform computations (e.g., band math) directly on GEE, then fetch results in a single step.
+- **Scalable & Efficient**  
+  Optimized memory usage and parallelism let you handle complex tasks in big data environments.
+
+## **Installation**
+Install the latest version from PyPI:
+
+```bash
+pip install cubexpress
+```
+
+> **Note**: You need a valid Google Earth Engine account and `earthengine-api` installed (`pip install earthengine-api`). Also run `ee.Initialize()` before using CubeXpress.
+
+---
+
+## **Basic Usage**
+
+### **Download a single `ee.Image`**
+
+```python
+import ee
+import cubexpress
+
+# Initialize Earth Engine
+ee.Initialize(project="your-project-id")
+
+# Create a raster transform
+geotransform = cubexpress.lonlat2rt(
+    lon=-76.5,
+    lat=-9.5,
+    edge_size=128,  # Width=Height=128 pixels
+    scale=90        # 90m resolution
+)
+
+# Define a single Request
+request = cubexpress.Request(
+    id="dem_test",
+    raster_transform=geotransform,
+    bands=["elevation"],
+    image="NASA/NASADEM_HGT/001" # Note: you can wrap with ee.Image("NASA/NASADEM_HGT/001").divide(10000) if needed
+
+# Build the RequestSet
+cube_requests = cubexpress.RequestSet(requestset=[request])
+
+# Download with multi-threading
+cubexpress.getcube(
+    request=cube_requests,
+    output_path="output_dem",
+    nworkers=4,
+    max_deep_level=5
+)
+```
+
+This will create a GeoTIFF named `dem_test.tif` in the `output_dem` folder, containing the elevation band.
+
+---
+
+
+### **Download pixel values from an ee.ImageCollection**
+
+You can fetch multiple images by constructing a `RequestSet` with several `Request` objects. For example, filter Sentinel-2 images near a point:
+
+```python
+import ee
+import cubexpress
+
+ee.Initialize(project="your-project-id")
+
+# Filter a Sentinel-2 collection
+point = ee.Geometry.Point([-97.59, 33.37])
+collection = ee.ImageCollection("COPERNICUS/S2_SR_HARMONIZED") \
+               .filterBounds(point) \
+               .filterDate('2024-01-01', '2024-01-31')
+
+# Extract image IDs
+image_ids = collection.aggregate_array('system:id').getInfo()
+
+# Set the geotransform
+geotransform = cubexpress.lonlat2rt(
+    lon=-97.59, 
+    lat=33.37, 
+    edge_size=512, 
+    scale=10
+)
+
+# Build multiple requests
+requests = [
+    cubexpress.Request(
+        id=f"s2test_{i}",
+        raster_transform=geotransform,
+        bands=["B4", "B3", "B2"],
+        image=image_id  # Note: you can wrap with ee.Image(image_id).divide(10000) if needed
+    )
+    for i, image_id in enumerate(image_ids)
+]
+
+# Create the RequestSet
+cube_requests = cubexpress.RequestSet(requestset=requests)
+
+# Download
+cubexpress.getcube(
+    request=cube_requests,
+    output_path="output_sentinel",
+    nworkers=4,
+    max_deep_level=5
+)
+```
+
+---
+
+### **Process and extract a pixel from an ee.Image**
+If you provide an `ee.Image` with custom calculations (e.g., `.divide(10000)`, `.normalizedDifference(...)`), CubeXpress can run those on GEE, then download the result. For large results, it automatically splits the image into sub-tiles.
+
+```python
+import ee
+import cubexpress
+
+ee.Initialize(project="your-project-id")
+
+# Example: NDVI from Sentinel-2
+image = ee.Image("COPERNICUS/S2_HARMONIZED/20170804T154911_20170804T155116_T18SUJ") \
+           .normalizedDifference(["B8", "B4"]) \
+           .rename("NDVI")
+
+geotransform = cubexpress.lonlat2rt(
+    lon=-76.59, 
+    lat=38.89, 
+    edge_size=256, 
+    scale=10
+)
+
+request = cubexpress.Request(
+    id="ndvi_test",
+    raster_transform=geotransform,
+    bands=["NDVI"],
+    image=image  # custom expression
+)
+
+cube_requests = cubexpress.RequestSet(requestset=[request])
+
+cubexpress.getcube(
+    request=cube_requests,
+    output_path="output_ndvi",
+    nworkers=2,
+    max_deep_level=5
+)
+```
+
+---
+
+## **Advanced Usage**
+
+### **Same Set of Sentinel-2 Images for Multiple Points**
+
+Below is a **advanced example** demonstrating how to work with **multiple points** and a **Sentinel-2** image collection in one script. We first create a global collection but then filter it on a point-by-point basis, extracting only the images that intersect each coordinate. Finally, we download them in parallel using **CubeXpress**.
+
+
+```python
+import ee
+import cubexpress
+
+# Initialize Earth Engine with your project
+ee.Initialize(project="your-project-id")
+
+# Define multiple points (longitude, latitude)
+points = [
+    (-97.64, 33.37),
+    (-97.59, 33.37)
+]
+
+# Start with a broad Sentinel-2 collection
+collection = (
+    ee.ImageCollection("COPERNICUS/S2_SR_HARMONIZED")
+    .filterDate("2024-01-01", "2024-01-31")
+)
+
+# Build a list of Request objects
+requestset = []
+for i, (lon, lat) in enumerate(points):
+    # Create a point geometry for the current coordinates
+    point_geom = ee.Geometry.Point([lon, lat])
+    collection_filtered = collection.filterBounds(point_geom)
+    
+    # Convert the filtered collection into a list of asset IDs
+    image_ids = collection_filtered.aggregate_array("system:id").getInfo()
+    
+    # Define a geotransform for this point
+    geotransform = cubexpress.lonlat2rt(
+        lon=lon,
+        lat=lat,
+        edge_size=512,  # Adjust the image size in pixels
+        scale=10        # 10m resolution for Sentinel-2
+    )
+    
+    # Create one Request per image found for this point
+    requestset.extend([
+        cubexpress.Request(
+            id=f"s2test_{i}_{idx}",
+            raster_transform=geotransform,
+            bands=["B4", "B3", "B2"],
+            image=image_id
+        )
+        for idx, image_id in enumerate(image_ids)
+    ])
+
+# Combine into a RequestSet
+cube_requests = cubexpress.RequestSet(requestset=requestset)
+
+# Download everything in parallel
+results = cubexpress.getcube(
+    request=cube_requests,
+    nworkers=4,
+    output_path="images_s2",
+    max_deep_level=5
+)
+
+print("Downloaded files:", results)
+```
+
+
+**How it works**:  
+
+1. **Points:** We define multiple coordinates in `points`.  
+2. **Global collection:** We retrieve a broad Sentinel-2 collection covering the desired date range.  
+3. **Per-point filter:** For each point, we call `.filterBounds(...)` to get only images intersecting that location.  
+4. **Geotransform:** We create a local geotransform (`edge_size`, `scale`) defining the spatial extent and resolution around each point.  
+5. **Requests:** Each point-image pair becomes a `Request`, stored in a single list.  
+6. **Parallel download:** With `cubexpress.getcube()`, all requests are fetched simultaneously, automatically splitting large outputs into sub-tiles if needed (up to `max_deep_level`).  
+
+
+
+## **License**
+This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).
+
+---
+
+<p align="center">
+  Built with 🌎 and ❤️ by the <strong>CubeXpress</strong> team
+</p>
+

cubexpress-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+cubexpress/__init__.py,sha256=1CF6kINn70mfS5HNzYyTf4UsOUPG0qzeetoJSDk0ALw,418
+cubexpress/conversion.py,sha256=h77re8AtdVV_Jy3ugZeQ-e2I8DHSKoghiq70MXkzBaQ,2506
+cubexpress/download.py,sha256=DX5DKPdKiuv1gHxs-5Q5ScZ06nvE-Pi1YGLSzQc2jrs,14315
+cubexpress/geotyping.py,sha256=5JgsOfRfwQf-iBh902wKQ1AxEKw1HgFL2brzwkxO0Pg,17152
+cubexpress-0.1.0.dist-info/LICENSE,sha256=XjoS-d76b7Cl-VgCWhQk83tNf2dNldKBN8SrImwGc2Q,1072
+cubexpress-0.1.0.dist-info/METADATA,sha256=XfBIfpFP1quHSNr60Dn6R8EEpdq02XJWCepwhl7j7U0,9327
+cubexpress-0.1.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+cubexpress-0.1.0.dist-info/RECORD,,

cubexpress-0.1.0.dist-info/WHEEL

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