geoai-py 0.4.2__tar.gz → 0.4.3__tar.gz

{geoai_py-0.4.2 → geoai_py-0.4.3}/.gitignore

@@ -14,6 +14,7 @@ docs/examples/*.md
 *.xml
 docs/examples/output/
 docs/examples/*.png
+docs/examples/data/
 *.pth
 
 # Distribution / packaging

{geoai_py-0.4.2 → geoai_py-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: geoai-py
-Version: 0.4.2
+Version: 0.4.3
 Summary: A Python package for using Artificial Intelligence (AI) with geospatial data
 Author-email: Qiusheng Wu <giswqs@gmail.com>
 License: MIT License

geoai_py-0.4.3/docs/examples/planetary_computer.ipynb

@@ -0,0 +1,338 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Download Data from Planetary Computer\n",
+    "\n",
+    "[![image](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/opengeos/geoai/blob/main/docs/examples/planetary_computer.ipynb)\n",
+    "\n",
+    "## Install package\n",
+    "To use the `geoai-py` package, ensure it is installed in your environment. Uncomment the command below if needed."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# %pip install geoai-py"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Import libraries"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import geoai"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Retrieve collections"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "collections = geoai.pc_collection_list()\n",
+    "collections"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Search NAIP imagery"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "items = geoai.pc_stac_search(\n",
+    "    collection=\"naip\",\n",
+    "    bbox=[-76.6657, 39.2648, -76.6478, 39.2724],  # Baltimore area\n",
+    "    time_range=\"2013-01-01/2014-12-31\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "items"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Visualize NAIP imagery"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.pc_item_asset_list(items[0])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.view_pc_item(item=items[0])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Download NAIP imagery"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "downloaded = geoai.pc_stac_download(\n",
+    "    items, output_dir=\"data\", assets=[\"image\", \"thumbnail\"]\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Search land cover data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "items = geoai.pc_stac_search(\n",
+    "    collection=\"chesapeake-lc-13\",\n",
+    "    bbox=[-76.6657, 39.2648, -76.6478, 39.2724],  # Baltimore area\n",
+    "    time_range=\"2013-01-01/2014-12-31\",\n",
+    "    max_items=10,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "items"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Visualize land cover data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.pc_item_asset_list(items[0])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.view_pc_item(item=items[0], colormap_name=\"tab10\", basemap=\"SATELLITE\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Download land cover data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.pc_stac_download(items[0], output_dir=\"data\", assets=[\"data\", \"rendered_preview\"])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ds = geoai.read_pc_item_asset(items[0], asset=\"data\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ds"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Search Landsat data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "items = geoai.pc_stac_search(\n",
+    "    collection=\"landsat-c2-l2\",\n",
+    "    bbox=[-76.6657, 39.2648, -76.6478, 39.2724],  # Baltimore area\n",
+    "    time_range=\"2024-10-27/2024-12-31\",\n",
+    "    query={\"eo:cloud_cover\": {\"lt\": 1}},\n",
+    "    max_items=10,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "items"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Visualize Landsat data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.pc_item_asset_list(items[0])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.view_pc_item(item=items[0], assets=[\"red\", \"green\", \"blue\"])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.view_pc_item(item=items[0], assets=[\"nir08\", \"red\", \"green\"])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.view_pc_item(\n",
+    "    item=items[0],\n",
+    "    expression=\"(nir08-red)/(nir08+red)\",\n",
+    "    rescale=\"-1,1\",\n",
+    "    colormap_name=\"greens\",\n",
+    "    name=\"NDVI Green\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Download Landsat data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.pc_stac_download(\n",
+    "    items[0], output_dir=\"data\", assets=[\"nir08\", \"red\", \"green\", \"blue\"]\n",
+    ")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "geo",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

{geoai_py-0.4.2 → geoai_py-0.4.3}/geoai/__init__.py

@@ -2,7 +2,7 @@
 
 __author__ = """Qiusheng Wu"""
 __email__ = "giswqs@gmail.com"
-__version__ = "0.4.2"
+__version__ = "0.4.3"
 
 
 import os

{geoai_py-0.4.2 → geoai_py-0.4.3}/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:
@@ -516,7 +517,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 +526,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 +867,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 +882,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,7 +899,7 @@ 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
@@ -911,31 +911,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
@@ -995,13 +977,11 @@ def pc_stac_download(
         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 +1018,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