geoai-py 0.4.2__py2.py3-none-any.whl → 0.5.0__py2.py3-none-any.whl

geoai/download.py

@@ -10,8 +10,9 @@ import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
 import planetary_computer as pc
+import pystac
 import requests
-import rioxarray
+import rioxarray as rxr
 import xarray as xr
 from pystac_client import Client
 from shapely.geometry import box
@@ -121,7 +122,7 @@ def download_naip(
                 #
             else:
                 # Fallback to direct rioxarray opening (less common case)
-                data = rioxarray.open_rasterio(rgb_asset.href)
+                data = rxr.open_rasterio(rgb_asset.href)
                 data.rio.to_raster(output_path)
 
             downloaded_files.append(output_path)
@@ -129,7 +130,7 @@ def download_naip(
 
             # Optional: Display a preview (uncomment if needed)
             if preview:
-                data = rioxarray.open_rasterio(output_path)
+                data = rxr.open_rasterio(output_path)
                 preview_raster(data)
 
         except Exception as e:
@@ -206,98 +207,130 @@ def json_serializable(obj: Any) -> Any:
         return obj
 
 
+def get_overture_latest_release(patch=True) -> str:
+    """
+    Retrieves the value of the 'latest' key from the Overture Maps release JSON file.
+
+    Args:
+        patch (bool): If True, returns the full version string (e.g., "2025-02-19.0").
+
+    Returns:
+        str: The value of the 'latest' key from the releases.json file.
+
+    Raises:
+        requests.RequestException: If there's an issue with the HTTP request.
+        KeyError: If the 'latest' key is not found in the JSON data.
+        json.JSONDecodeError: If the response cannot be parsed as JSON.
+    """
+    url = "https://labs.overturemaps.org/data/releases.json"
+
+    try:
+        response = requests.get(url)
+        response.raise_for_status()  # Raise an exception for HTTP errors
+
+        data = response.json()
+        if patch:
+            latest_release = data.get("latest")
+        else:
+            latest_release = data.get("latest").split(".")[
+                0
+            ]  # Extract the version number
+
+        if latest_release is None:
+            raise KeyError("The 'latest' key was not found in the releases.json file")
+
+        return latest_release
+
+    except requests.RequestException as e:
+        print(f"Error making the request: {e}")
+        raise
+    except json.JSONDecodeError as e:
+        print(f"Error parsing JSON response: {e}")
+        raise
+    except KeyError as e:
+        print(f"Key error: {e}")
+        raise
+
+
+def get_all_overture_types():
+    """Get a list of all available Overture Maps data types.
+
+    Returns:
+        list: List of available Overture Maps data types.
+    """
+    from overturemaps import core
+
+    return core.get_all_overture_types()
+
+
 def download_overture_buildings(
     bbox: Tuple[float, float, float, float],
-    output_file: str,
-    output_format: str = "geojson",
-    data_type: str = "building",
-    verbose: bool = True,
+    output: str,
+    overture_type: str = "building",
+    **kwargs: Any,
 ) -> str:
     """Download building data from Overture Maps for a given bounding box using the overturemaps CLI tool.
 
     Args:
         bbox: Bounding box in the format (min_lon, min_lat, max_lon, max_lat) in WGS84 coordinates.
-        output_file: Path to save the output file.
-        output_format: Format to save the output, one of "geojson", "geojsonseq", or "geoparquet".
-        data_type: The Overture Maps data type to download (building, place, etc.).
-        verbose: Whether to print verbose output.
+        output: Path to save the output file.
+        overture_type: The Overture Maps data type to download (building, place, etc.).
 
     Returns:
         Path to the output file.
     """
-    # Create output directory if needed
-    output_dir = os.path.dirname(output_file)
-    if output_dir and not os.path.exists(output_dir):
-        os.makedirs(output_dir, exist_ok=True)
-
-    # Format the bounding box string for the command
-    west, south, east, north = bbox
-    bbox_str = f"{west},{south},{east},{north}"
-
-    # Build the command
-    cmd = [
-        "overturemaps",
-        "download",
-        "--bbox",
-        bbox_str,
-        "-f",
-        output_format,
-        "--type",
-        data_type,
-        "--output",
-        output_file,
-    ]
-
-    if verbose:
-        logger.info(f"Running command: {' '.join(cmd)}")
-        logger.info("Downloading %s data for area: %s", data_type, bbox_str)
+
+    return get_overture_data(
+        overture_type=overture_type, bbox=bbox, output=output, **kwargs
+    )
+
+
+def get_overture_data(
+    overture_type: str,
+    bbox: Tuple[float, float, float, float] = None,
+    columns: List[str] = None,
+    output: str = None,
+    **kwargs: Any,
+) -> "gpd.GeoDataFrame":
+    """Fetches overture data and returns it as a GeoDataFrame.
+
+    Args:
+        overture_type (str): The type of overture data to fetch.It can be one of the following:
+            address|building|building_part|division|division_area|division_boundary|place|
+            segment|connector|infrastructure|land|land_cover|land_use|water
+        bbox (Tuple[float, float, float, float], optional): The bounding box to
+            filter the data. Defaults to None.
+        columns (List[str], optional): The columns to include in the output.
+            Defaults to None.
+        output (str, optional): The file path to save the output GeoDataFrame.
+            Defaults to None.
+
+    Returns:
+        gpd.GeoDataFrame: The fetched overture data as a GeoDataFrame.
+
+    Raises:
+        ImportError: If the overture package is not installed.
+    """
 
     try:
-        # Run the command
-        result = subprocess.run(
-            cmd,
-            check=True,
-            stdout=subprocess.PIPE if not verbose else None,
-            stderr=subprocess.PIPE,
-            text=True,
-        )
+        from overturemaps import core
+    except ImportError:
+        raise ImportError("The overturemaps package is required to use this function")
 
-        # Check if the file was created
-        if os.path.exists(output_file):
-            file_size = os.path.getsize(output_file) / (1024 * 1024)  # Size in MB
-            logger.info(
-                f"Successfully downloaded data to {output_file} ({file_size:.2f} MB)"
-            )
+    gdf = core.geodataframe(overture_type, bbox=bbox)
+    if columns is not None:
+        gdf = gdf[columns]
 
-            # Optionally show some stats about the downloaded data
-            if output_format == "geojson" and os.path.getsize(output_file) > 0:
-                try:
-                    gdf = gpd.read_file(output_file)
-                    logger.info(f"Downloaded {len(gdf)} features")
-
-                    if len(gdf) > 0 and verbose:
-                        # Show a sample of the attribute names
-                        attrs = list(gdf.columns)
-                        attrs.remove("geometry")
-                        logger.info(f"Available attributes: {', '.join(attrs[:10])}...")
-                except Exception as e:
-                    logger.warning(f"Could not read the GeoJSON file: {str(e)}")
+    gdf.crs = "EPSG:4326"
 
-            return output_file
-        else:
-            logger.error(f"Command completed but file {output_file} was not created")
-            if result.stderr:
-                logger.error(f"Command error output: {result.stderr}")
-            return None
-
-    except subprocess.CalledProcessError as e:
-        logger.error(f"Error running overturemaps command: {str(e)}")
-        if e.stderr:
-            logger.error(f"Command error output: {e.stderr}")
-        raise RuntimeError(f"Failed to download Overture Maps data: {str(e)}")
-    except Exception as e:
-        logger.error(f"Unexpected error: {str(e)}")
-        raise
+    out_dir = os.path.dirname(os.path.abspath(output))
+    if not os.path.exists(out_dir):
+        os.makedirs(out_dir, exist_ok=True)
+
+    if output is not None:
+        gdf.to_file(output, **kwargs)
+
+    return gdf
 
 
 def convert_vector_format(
@@ -360,18 +393,23 @@ def convert_vector_format(
         raise
 
 
-def extract_building_stats(geojson_file: str) -> Dict[str, Any]:
+def extract_building_stats(data: str) -> Dict[str, Any]:
     """Extract statistics from the building data.
 
     Args:
-        geojson_file: Path to the GeoJSON file.
+        data: Path to the GeoJSON file or GeoDataFrame containing building data.
 
     Returns:
         Dictionary with statistics.
     """
     try:
         # Read the GeoJSON file
-        gdf = gpd.read_file(geojson_file)
+
+        if isinstance(data, gpd.GeoDataFrame):
+            gdf = data
+        else:
+
+            gdf = gpd.read_file(data)
 
         # Calculate statistics
         bbox = gdf.total_bounds.tolist()
@@ -516,7 +554,7 @@ def download_pc_stac_item(
                     )
                 # Still need to open the file to get the data for merging
                 if merge_bands:
-                    band_data = rioxarray.open_rasterio(file_path)
+                    band_data = rxr.open_rasterio(file_path)
                     band_data_arrays.append((band, band_data))
                     band_names.append(band)
                 result[band] = file_path
@@ -525,7 +563,7 @@ def download_pc_stac_item(
         if show_progress and not isinstance(progress_iter, list):
             progress_iter.set_description(f"Downloading {band}")
 
-        band_data = rioxarray.open_rasterio(band_url)
+        band_data = rxr.open_rasterio(band_url)
 
         # Store the data array for potential merging later
         if merge_bands:
@@ -866,10 +904,9 @@ def pc_stac_search(
 def pc_stac_download(
     items,
     output_dir=".",
-    asset_keys=None,
+    assets=None,
     max_workers=4,
     skip_existing=True,
-    sign_urls=True,
 ):
     """
     Download assets from STAC items retrieved from the Planetary Computer.
@@ -882,7 +919,7 @@ def pc_stac_download(
         items (list or pystac.Item): STAC Item object or list of STAC Item objects.
         output_dir (str, optional): Directory where assets will be saved.
             Defaults to current directory.
-        asset_keys (list, optional): List of asset keys to download. If None,
+        assets (list, optional): List of asset keys to download. If None,
             downloads all available assets. Defaults to None.
         max_workers (int, optional): Maximum number of concurrent download threads.
             Defaults to 4.
@@ -899,11 +936,11 @@ def pc_stac_download(
         TypeError: If items is not a STAC Item or list of STAC Items.
         IOError: If there's an error writing the downloaded assets to disk.
     """
-    import pystac
+
     from concurrent.futures import ThreadPoolExecutor, as_completed
 
     # Handle single item case
-    if isinstance(items, pystac.Item):
+    if isinstance(items, pystac.Item) or isinstance(items, str):
         items = [items]
     elif not isinstance(items, list):
         raise TypeError("items must be a STAC Item or list of STAC Items")
@@ -911,31 +948,13 @@ def pc_stac_download(
     # Create output directory if it doesn't exist
     os.makedirs(output_dir, exist_ok=True)
 
-    # Function to sign URLs if needed
-    def get_signed_url(href):
-        if not sign_urls:
-            return href
-
-        # Planetary Computer typically requires signing URLs for accessing data
-        # Check if the URL is from Microsoft Planetary Computer
-        if "planetarycomputer" in href:
-            try:
-                sign_url = "https://planetarycomputer.microsoft.com/api/sas/v1/sign"
-                response = requests.get(sign_url, params={"href": href})
-                response.raise_for_status()
-                return response.json().get("href", href)
-            except Exception as e:
-                print(f"Warning: Failed to sign URL {href}: {str(e)}")
-                return href
-        return href
-
     # Function to download a single asset
     def download_asset(item, asset_key, asset):
+        item = pc.sign(item)
         item_id = item.id
 
         # Get the asset URL and sign it if needed
-        asset_url = get_signed_url(asset.href)
-
+        asset_url = item.assets[asset_key].href
         # Determine output filename
         if asset.media_type:
             # Use appropriate file extension based on media type
@@ -991,17 +1010,17 @@ def pc_stac_download(
 
     for item in items:
         item_assets = {}
+        if isinstance(item, str):
+            item = pystac.Item.from_file(item)
         item_id = item.id
         print(f"Processing STAC item: {item_id}")
 
         # Determine which assets to download
-        if asset_keys:
-            assets_to_download = {
-                k: v for k, v in item.assets.items() if k in asset_keys
-            }
+        if assets:
+            assets_to_download = {k: v for k, v in item.assets.items() if k in assets}
             if not assets_to_download:
                 print(
-                    f"Warning: None of the specified asset keys {asset_keys} found in item {item_id}"
+                    f"Warning: None of the specified asset keys {assets} found in item {item_id}"
                 )
                 print(f"Available asset keys: {list(item.assets.keys())}")
                 continue
@@ -1038,3 +1057,127 @@ def pc_stac_download(
     print(f"\nDownloaded {total_assets} assets for {len(results)} items")
 
     return results
+
+
+def pc_item_asset_list(item):
+    """
+    Retrieve the list of asset keys from a STAC item in the Planetary Computer catalog.
+
+    Args:
+        item (str): The URL of the STAC item.
+
+    Returns:
+        list: A list of asset keys available in the signed STAC item.
+    """
+    if isinstance(item, str):
+        item = pystac.Item.from_file(item)
+
+    if not isinstance(item, pystac.Item):
+        raise ValueError("item_url must be a string (URL) or a pystac.Item object")
+
+    return list(item.assets.keys())
+
+
+def read_pc_item_asset(item, asset, output=None, as_cog=True, **kwargs):
+    """
+    Read a specific asset from a STAC item in the Planetary Computer catalog.
+
+    Args:
+        item (str): The URL of the STAC item.
+        asset (str): The key of the asset to read.
+        output (str, optional): If specified, the path to save the asset as a raster file.
+        as_cog (bool, optional): If True, save the asset as a Cloud Optimized GeoTIFF (COG).
+
+    Returns:
+        xarray.DataArray: The data array for the specified asset.
+    """
+    if isinstance(item, str):
+        item = pystac.Item.from_file(item)
+
+    if not isinstance(item, pystac.Item):
+        raise ValueError("item must be a string (URL) or a pystac.Item object")
+
+    signed_item = pc.sign(item)
+
+    if asset not in signed_item.assets:
+        raise ValueError(
+            f"Asset '{asset}' not found in item '{item.id}'. It has available assets: {list(signed_item.assets.keys())}"
+        )
+
+    asset_url = signed_item.assets[asset].href
+    ds = rxr.open_rasterio(asset_url)
+
+    if as_cog:
+        kwargs["driver"] = "COG"  # Ensure the output is a Cloud Optimized GeoTIFF
+
+    if output:
+        print(f"Saving asset '{asset}' to {output}...")
+        ds.rio.to_raster(output, **kwargs)
+        print(f"Asset '{asset}' saved successfully.")
+    return ds
+
+
+def view_pc_item(
+    url=None,
+    collection=None,
+    item=None,
+    assets=None,
+    bands=None,
+    titiler_endpoint=None,
+    name="STAC Item",
+    attribution="Planetary Computer",
+    opacity=1.0,
+    shown=True,
+    fit_bounds=True,
+    layer_index=None,
+    backend="folium",
+    basemap=None,
+    map_args=None,
+    **kwargs,
+):
+
+    if backend == "folium":
+        import leafmap.foliumap as leafmap
+
+    elif backend == "ipyleaflet":
+        import leafmap.leafmap as leafmap
+
+    else:
+        raise ValueError(
+            f"Unsupported backend: {backend}. Supported backends are 'folium' and 'ipyleaflet'."
+        )
+
+    if map_args is None:
+        map_args = {}
+
+    if "draw_control" not in map_args:
+        map_args["draw_control"] = False
+
+    if url is not None:
+
+        item = pystac.Item.from_file(url)
+
+    if isinstance(item, pystac.Item):
+        collection = item.collection_id
+        if assets is None:
+            assets = [list(item.assets.keys())[0]]
+        item = item.id
+
+    m = leafmap.Map(**map_args)
+    if basemap is not None:
+        m.add_basemap(basemap)
+    m.add_stac_layer(
+        collection=collection,
+        item=item,
+        assets=assets,
+        bands=bands,
+        titiler_endpoint=titiler_endpoint,
+        name=name,
+        attribution=attribution,
+        opacity=opacity,
+        shown=shown,
+        fit_bounds=fit_bounds,
+        layer_index=layer_index,
+        **kwargs,
+    )
+    return m