cubexpress 0.1.18__tar.gz → 0.1.32__tar.gz

{cubexpress-0.1.18 → cubexpress-0.1.32}/PKG-INFO

@@ -1,28 +1,28 @@
 Metadata-Version: 2.1
 Name: cubexpress
-Version: 0.1.18
+Version: 0.1.32
 Summary: Efficient processing of cubic Earth-observation (EO) data.
 Home-page: https://github.com/andesdatacube/cubexpress
 Keywords: earth-engine,sentinel-2,geospatial,eo,cube
 Author: Julio Contreras
 Author-email: contrerasnetk@gmail.com
-Requires-Python: >=3.9
+Requires-Python: >=3.10,<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
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Scientific/Engineering :: GIS
 Requires-Dist: earthengine-api (>=1.5.12)
-Requires-Dist: numpy (>=2.0.2)
-Requires-Dist: pandas (>=2.2.2)
+Requires-Dist: numpy (>=1.26.0,<2.1.0)
+Requires-Dist: pandas (>=2.0.0)
 Requires-Dist: pyarrow (>=14.0.0)
-Requires-Dist: pydantic (>=2.11.4)
+Requires-Dist: pydantic (>=2.0.0)
 Requires-Dist: pygeohash (>=1.2.0)
 Requires-Dist: pyproj (>=3.6.0)
 Requires-Dist: rasterio (>=1.3.9)
+Requires-Dist: tqdm (>=4.65.0)
 Requires-Dist: utm (>=0.7.0)
 Project-URL: Documentation, https://andesdatacube.github.io/cubexpress
 Project-URL: Repository, https://github.com/andesdatacube/cubexpress
@@ -53,12 +53,14 @@ Description-Content-Type: text/markdown
 </a>
 </p>
 
+
 ---
 
 **GitHub**: [https://github.com/andesdatacube/cubexpress/](https://github.com/andesdatacube/cubexpress/) 🌐
 
 **PyPI**: [https://pypi.org/project/cubexpress/](https://pypi.org/project/cubexpress/) 🛠️
 
+![Tests](https://github.com/andesdatacube/cubexpress/actions/workflows/tests.yml/badge.svg)
 ---
 
 ## **Overview**

{cubexpress-0.1.18 → cubexpress-0.1.32}/README.md

@@ -23,12 +23,14 @@
 </a>
 </p>
 
+
 ---
 
 **GitHub**: [https://github.com/andesdatacube/cubexpress/](https://github.com/andesdatacube/cubexpress/) 🌐
 
 **PyPI**: [https://pypi.org/project/cubexpress/](https://pypi.org/project/cubexpress/) 🛠️
 
+![Tests](https://github.com/andesdatacube/cubexpress/actions/workflows/tests.yml/badge.svg)
 ---
 
 ## **Overview**

cubexpress-0.1.32/cubexpress/__init__.py

@@ -0,0 +1,84 @@
+"""
+CubExpress - Efficient Earth Engine data download and processing.
+
+Main components:
+- lonlat2rt: Convert coordinates to raster transforms
+- s2_table: Query Sentinel-2 metadata with cloud scores
+- sensor_table: Query any sensor metadata (Landsat, S2)
+- table_to_requestset: Build request sets from metadata
+- get_cube: Download Earth Engine data cubes
+
+Format components:
+- Formats: Pre-configured export format presets
+- VisPresets: Visualization presets for common sensors
+- EEFileFormat: Available Earth Engine file formats
+- ExportFormat: Full format specification class
+- VisualizationOptions: Visualization parameters class
+
+Constants:
+- LANDSAT_COMMON_OPTIONAL: Set of properties common to all Landsat sensors
+- SENSORS: Dictionary of all supported sensor configurations
+"""
+
+from __future__ import annotations
+
+from cubexpress.animation import create_gif, create_gif_from_requests
+from cubexpress.cloud_utils import (
+    AGGREGATED_SENSORS,
+    LANDSAT_COMMON_OPTIONAL,
+    S2_BOA_BANDS,
+    S2_COMMON_OPTIONAL,
+    S2_TOA_BANDS,
+    SENSORS,
+    mss_table,
+    s2_table,
+    sensor_table,
+)
+from cubexpress.conversion import geo2utm, lonlat2rt
+from cubexpress.cube import get_cube, get_geotiff, get_numpy_cube
+from cubexpress.formats import EEFileFormat, ExportFormat, Formats, VisPresets, VisualizationOptions
+from cubexpress.geotyping import RasterTransform, Request, RequestSet
+from cubexpress.request import table_to_requestset
+from cubexpress.scene_geometry import clear_scene_cache, get_batch_scene_info, get_scene_info
+
+__all__ = [
+    # Core functions
+    "lonlat2rt",
+    "geo2utm",
+    "RasterTransform",
+    "Request",
+    "RequestSet",
+    "s2_table",
+    "mss_table",
+    "sensor_table",
+    "table_to_requestset",
+    "get_cube",
+    "get_geotiff",
+    "get_numpy_cube",
+    # Formats
+    "EEFileFormat",
+    "ExportFormat",
+    "Formats",
+    "VisualizationOptions",
+    "VisPresets",
+    # Animation
+    "create_gif",
+    "create_gif_from_requests",
+    # Constants
+    "AGGREGATED_SENSORS",
+    "LANDSAT_COMMON_OPTIONAL",
+    "S2_COMMON_OPTIONAL",
+    "S2_TOA_BANDS",
+    "S2_BOA_BANDS",
+    "SENSORS",
+    "get_batch_scene_info",
+    "get_scene_info",
+    "clear_scene_cache",
+]
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("cubexpress")
+except Exception:
+    __version__ = "0.0.0-dev"

cubexpress-0.1.32/cubexpress/animation.py

@@ -0,0 +1,177 @@
+"""Animation utilities for creating GIFs from image sequences."""
+
+from __future__ import annotations
+
+import pathlib
+from typing import Any
+
+
+def create_gif(
+    image_paths: list[pathlib.Path],
+    output_path: pathlib.Path,
+    duration: int = 500,
+    loop: int = 0,
+    background_color: tuple[int, int, int] = (0, 0, 0),
+) -> pathlib.Path:
+    """Create animated GIF from image sequence.
+
+    Args:
+        image_paths: List of PNG/JPEG image paths in order
+        output_path: Output GIF path
+        duration: Frame duration in milliseconds
+        loop: Number of loops (0 = infinite)
+        background_color: RGB tuple for background (replaces transparency)
+
+    Returns:
+        Path to created GIF
+    """
+    try:
+        from PIL import Image
+    except ImportError:
+        raise ImportError("Pillow required for GIF creation: pip install Pillow") from None
+
+    if not image_paths:
+        raise ValueError("No images provided for GIF creation")
+
+    # Load all frames and convert to RGB (no transparency issues)
+    frames = []
+    for path in image_paths:
+        img = Image.open(path)
+
+        # Handle transparency by compositing onto background
+        if img.mode == "RGBA":
+            background = Image.new("RGB", img.size, background_color)
+            background.paste(img, mask=img.split()[3])
+            img = background
+        elif img.mode != "RGB":
+            img = img.convert("RGB")
+
+        frames.append(img)
+
+    # Save as animated GIF
+    output_path = pathlib.Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Convert to palette mode for GIF
+    frames_p = []
+    for frame in frames:
+        frame_p = frame.quantize(colors=256, method=Image.Quantize.MEDIANCUT)
+        frames_p.append(frame_p)
+
+    frames_p[0].save(
+        output_path,
+        save_all=True,
+        append_images=frames_p[1:],
+        duration=duration,
+        loop=loop,
+        optimize=False,
+        disposal=2,
+    )
+
+    return output_path
+
+
+def create_gif_from_requests(
+    requests: Any,  # RequestSet or DataFrame
+    visualization: Any | None = None,
+    output_path: pathlib.Path | str = "animation.gif",
+    duration: int = 500,
+    background_color: tuple[int, int, int] = (0, 0, 0),
+    keep_frames: pathlib.Path | str | None = None,
+) -> pathlib.Path:
+    """Create animated GIF from RequestSet with FIXED geometry.
+
+    Uses getPixels/computePixels directly to ensure correct geometry
+    without distortion.
+
+    Args:
+        requests: RequestSet or DataFrame from table_to_requestset
+        visualization: VisualizationOptions (e.g., VisPresets.s2_truecolor())
+        output_path: Output GIF path
+        duration: Frame duration in ms
+        background_color: RGB tuple for background (replaces transparency)
+        keep_frames: If provided, save PNG frames to this folder
+
+    Returns:
+        Path to created GIF
+
+    Example:
+        >>> df = sensor_table("S2_TOA", lon=-0.3763, lat=39.4699, edge_size=256,
+        ...                   start="2024-01-01", end="2024-03-01", max_cloud=20)
+        >>> requests = table_to_requestset(df, mosaic=True)
+        >>> create_gif_from_requests(
+        ...     requests,
+        ...     visualization=VisPresets.s2_truecolor(),
+        ...     output_path="valencia_timelapse.gif",
+        ...     duration=300,
+        ... )
+    """
+    from cubexpress.downloader import download_manifest, temp_workspace
+    from cubexpress.formats import EEFileFormat, ExportFormat
+
+    output_path = pathlib.Path(output_path)
+
+    # Get dataframe
+    if hasattr(requests, "_dataframe"):
+        dataframe = requests._dataframe
+    else:
+        dataframe = requests
+
+    if dataframe.empty:
+        raise ValueError("Request set is empty")
+
+    n_frames = len(dataframe)
+
+    if visualization is None:
+        raise ValueError("visualization is required for GIF creation. " "Use VisPresets.s2_truecolor() or similar.")
+
+    png_format = ExportFormat(
+        file_format=EEFileFormat.PNG,
+        visualization=visualization,
+    )
+
+    # Determine frame folder
+    if keep_frames:
+        frame_dir = pathlib.Path(keep_frames)
+        frame_dir.mkdir(parents=True, exist_ok=True)
+        use_temp = False
+        tmp_context = None
+    else:
+        use_temp = True
+        tmp_context = temp_workspace(prefix="cubexpress_gif_")
+
+    try:
+        if use_temp:
+            frame_dir = tmp_context.__enter__()
+
+        frame_paths = []
+
+        print(f"⏳ Rendering {n_frames} frames...", end="", flush=True)
+
+        for i, (_, row) in enumerate(dataframe.iterrows()):
+            frame_path = frame_dir / f"frame_{i:04d}_{row.id}.png"
+
+            download_manifest(
+                ulist=row.manifest,
+                full_outname=frame_path,
+                export_format=png_format,
+            )
+            frame_paths.append(frame_path)
+
+        print(f"\r✅ Rendered {n_frames} frames")
+        print("⏳ Creating GIF...", end="", flush=True)
+
+        result = create_gif(
+            image_paths=frame_paths,
+            output_path=output_path,
+            duration=duration,
+            background_color=background_color,
+        )
+
+        print(f"\r✅ Created GIF: {output_path} ({n_frames} frames)")
+
+    finally:
+        if use_temp and tmp_context:
+            tmp_context.__exit__(None, None, None)
+
+    return result

cubexpress-0.1.32/cubexpress/cache.py

@@ -0,0 +1,73 @@
+"""Caching utilities for Earth Engine query results."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import pathlib
+
+from cubexpress.config import CACHE_DIR
+
+CACHE_DIR.mkdir(exist_ok=True, parents=True)
+
+
+def _cache_key(
+    lon: float,
+    lat: float,
+    edge_size: int | tuple[int, int],
+    scale: int,
+    collection: str,
+) -> pathlib.Path:
+    """
+    Generate a deterministic cache file path for query parameters.
+
+    Coordinates are rounded to 4 decimal places (~11m precision) to
+    ensure cache hits for equivalent locations.
+
+    Args:
+        lon: Longitude of center point
+        lat: Latitude of center point
+        edge_size: ROI size in pixels
+        scale: Pixel resolution in meters
+        collection: Earth Engine collection ID
+
+    Returns:
+        Path to hashed .parquet cache file
+    """
+    lon_r = round(lon, 4)
+    lat_r = round(lat, 4)
+
+    edge_tuple = (edge_size, edge_size) if isinstance(edge_size, int) else tuple(edge_size)
+
+    signature = [lon_r, lat_r, edge_tuple, scale, collection]
+
+    raw = json.dumps(signature, sort_keys=True).encode("utf-8")
+    digest = hashlib.md5(raw).hexdigest()
+
+    return CACHE_DIR / f"{digest}.parquet"
+
+
+def clear_cache() -> int:
+    """
+    Remove all cached query results.
+
+    Returns:
+        Number of files deleted
+    """
+    count = 0
+    for cache_file in CACHE_DIR.glob("*.parquet"):
+        cache_file.unlink()
+        count += 1
+    return count
+
+
+def get_cache_size() -> tuple[int, int]:
+    """
+    Calculate total cache size.
+
+    Returns:
+        Tuple of (file_count, total_bytes)
+    """
+    files = list(CACHE_DIR.glob("*.parquet"))
+    total_bytes = sum(f.stat().st_size for f in files)
+    return len(files), total_bytes