geoai-py 0.26.0__tar.gz → 0.27.0__tar.gz

{geoai_py-0.26.0 → geoai_py-0.27.0}/.gitignore

@@ -32,6 +32,9 @@ docs/workshops/**/*.jpg
 docs/workshops/**/*.png
 docs/examples/data/
 docs/workshops/data/
+docs/examples/ndvi_regression_output/
+docs/examples/timm_regression_output/
+docs/examples/ndvi_model/
 *.pth
 
 # Distribution / packaging

{geoai_py-0.26.0 → geoai_py-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: geoai-py
-Version: 0.26.0
+Version: 0.27.0
 Summary: A Python package for using Artificial Intelligence (AI) with geospatial data
 Author-email: Qiusheng Wu <giswqs@gmail.com>
 License: MIT License
@@ -71,7 +71,7 @@ Dynamic: license-file
 [![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/geoai.svg)](https://anaconda.org/conda-forge/geoai)
 [![Conda Recipe](https://img.shields.io/badge/recipe-geoai-green.svg)](https://github.com/conda-forge/geoai-py-feedstock)
 [![image](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![image](https://img.shields.io/badge/YouTube-Tutorials-red)](https://tinyurl.com/GeoAI-Tutorials)
+[![image](https://img.shields.io/badge/YouTube-Tutorials-red)](https://www.youtube.com/playlist?list=PLAxJ4-o7ZoPcvENqwaPa_QwbbkZ5sctZE)
 [![QGIS](https://img.shields.io/badge/QGIS-plugin-orange.svg)](https://opengeoai.org/qgis_plugin)
 
 [![logo](https://raw.githubusercontent.com/opengeos/geoai/master/docs/assets/logo_rect.png)](https://github.com/opengeos/geoai/blob/master/docs/assets/logo.png)
@@ -91,7 +91,7 @@ The package provides five core capabilities:
 5. Interactive visualization through integration with [Leafmap](https://github.com/opengeos/leafmap/) and [MapLibre](https://github.com/eoda-dev/py-maplibregl).
 6. Seamless QGIS integration via a dedicated GeoAI plugin, enabling users to run AI-powered geospatial workflows directly within the QGIS desktop environment, without writing code.
 
-GeoAI addresses the growing demand for accessible AI tools in geospatial research by providing high-level APIs that abstract complex machine learning workflows while maintaining flexibility for advanced users. The package supports multiple data formats (GeoTIFF, JPEG2000,GeoJSON, Shapefile, GeoPackage) and includes automatic device management for GPU acceleration when available. With over 10 modules and extensive notebook examples, GeoAI serves as both a research tool and educational resource for the geospatial AI community.
+GeoAI addresses the growing demand for accessible AI tools in geospatial research by providing high-level APIs that abstract complex machine learning workflows while maintaining flexibility for advanced users. The package supports multiple data formats (GeoTIFF, JPEG2000, GeoJSON, Shapefile, GeoPackage) and includes automatic device management for GPU acceleration when available. With over 10 modules and extensive notebook examples, GeoAI serves as both a research tool and educational resource for the geospatial AI community.
 
 ## 📝 Statement of Need
 
@@ -130,7 +130,7 @@ If you find GeoAI useful in your research, please consider citing the following
 
 -   Integration with [PyTorch Segmentation Models](https://github.com/qubvel-org/segmentation_models.pytorch) for automatic feature extraction
 -   Specialized segmentation algorithms optimized for satellite and aerial imagery
--   Streamlined workflows for segmenting buildings, water bodies, wetlands,solar panels, etc.
+-   Streamlined workflows for segmenting buildings, water bodies, wetlands, solar panels, etc.
 -   Export capabilities to standard geospatial formats (GeoJSON, Shapefile, GeoPackage, GeoParquet)
 
 ### 🔍 Image Classification

{geoai_py-0.26.0 → geoai_py-0.27.0}/README.md

@@ -6,7 +6,7 @@
 [![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/geoai.svg)](https://anaconda.org/conda-forge/geoai)
 [![Conda Recipe](https://img.shields.io/badge/recipe-geoai-green.svg)](https://github.com/conda-forge/geoai-py-feedstock)
 [![image](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![image](https://img.shields.io/badge/YouTube-Tutorials-red)](https://tinyurl.com/GeoAI-Tutorials)
+[![image](https://img.shields.io/badge/YouTube-Tutorials-red)](https://www.youtube.com/playlist?list=PLAxJ4-o7ZoPcvENqwaPa_QwbbkZ5sctZE)
 [![QGIS](https://img.shields.io/badge/QGIS-plugin-orange.svg)](https://opengeoai.org/qgis_plugin)
 
 [![logo](https://raw.githubusercontent.com/opengeos/geoai/master/docs/assets/logo_rect.png)](https://github.com/opengeos/geoai/blob/master/docs/assets/logo.png)
@@ -26,7 +26,7 @@ The package provides five core capabilities:
 5. Interactive visualization through integration with [Leafmap](https://github.com/opengeos/leafmap/) and [MapLibre](https://github.com/eoda-dev/py-maplibregl).
 6. Seamless QGIS integration via a dedicated GeoAI plugin, enabling users to run AI-powered geospatial workflows directly within the QGIS desktop environment, without writing code.
 
-GeoAI addresses the growing demand for accessible AI tools in geospatial research by providing high-level APIs that abstract complex machine learning workflows while maintaining flexibility for advanced users. The package supports multiple data formats (GeoTIFF, JPEG2000,GeoJSON, Shapefile, GeoPackage) and includes automatic device management for GPU acceleration when available. With over 10 modules and extensive notebook examples, GeoAI serves as both a research tool and educational resource for the geospatial AI community.
+GeoAI addresses the growing demand for accessible AI tools in geospatial research by providing high-level APIs that abstract complex machine learning workflows while maintaining flexibility for advanced users. The package supports multiple data formats (GeoTIFF, JPEG2000, GeoJSON, Shapefile, GeoPackage) and includes automatic device management for GPU acceleration when available. With over 10 modules and extensive notebook examples, GeoAI serves as both a research tool and educational resource for the geospatial AI community.
 
 ## 📝 Statement of Need
 
@@ -65,7 +65,7 @@ If you find GeoAI useful in your research, please consider citing the following
 
 -   Integration with [PyTorch Segmentation Models](https://github.com/qubvel-org/segmentation_models.pytorch) for automatic feature extraction
 -   Specialized segmentation algorithms optimized for satellite and aerial imagery
--   Streamlined workflows for segmenting buildings, water bodies, wetlands,solar panels, etc.
+-   Streamlined workflows for segmenting buildings, water bodies, wetlands, solar panels, etc.
 -   Export capabilities to standard geospatial formats (GeoJSON, Shapefile, GeoPackage, GeoParquet)
 
 ### 🔍 Image Classification

{geoai_py-0.26.0 → geoai_py-0.27.0}/geoai/__init__.py

@@ -2,7 +2,7 @@
 
 __author__ = """Qiusheng Wu"""
 __email__ = "giswqs@gmail.com"
-__version__ = "0.26.0"
+__version__ = "0.27.0"
 
 
 import os
@@ -101,6 +101,12 @@ def set_proj_lib_path(verbose=False):
 
 from .dinov3 import DINOv3GeoProcessor, analyze_image_patches, create_similarity_map
 from .geoai import *
+from .utils import (
+    orthogonalize,
+    regularization,
+    hybrid_regularization,
+    adaptive_regularization,
+)
 
 from .timm_train import (
     get_timm_model,
@@ -122,6 +128,25 @@ from .timm_segment import (
     push_timm_model_to_hub,
 )
 
+from .timm_regress import (
+    PixelRegressionModel,
+    PixelRegressionDataset,
+    create_regression_tiles,
+    train_pixel_regressor,
+    predict_raster,
+    evaluate_regression,
+    plot_regression_comparison,
+    plot_scatter,
+    plot_training_history,
+    visualize_prediction,
+    plot_regression_results,
+    # Backward compatibility aliases
+    TimmRegressor,
+    RegressionDataset,
+    train_timm_regressor,
+    create_regression_patches,
+)
+
 # Import tools subpackage
 from . import tools
 
@@ -167,6 +192,7 @@ except ImportError:
 try:
     from .prithvi import (
         PrithviProcessor,
+        get_available_prithvi_models,
         load_prithvi_model,
         prithvi_inference,
     )

{geoai_py-0.26.0 → geoai_py-0.27.0}/geoai/auto.py

@@ -24,7 +24,6 @@ Example:
 import os
 from typing import Any, Dict, List, Optional, Tuple, Union
 
-import cv2
 import geopandas as gpd
 import numpy as np
 import rasterio
@@ -877,6 +876,8 @@ class AutoGeoModel:
         **kwargs: Any,
     ) -> Dict[str, Any]:
         """Run tiled inference for large images."""
+        import cv2  # Lazy import to avoid QGIS opencv conflicts
+
         if data.ndim == 3:
             _, height, width = data.shape
         else:
@@ -1872,6 +1873,7 @@ def show_segmentation(
         >>> result = geoai.auto.semantic_segmentation("aerial.tif", output_path="seg.tif")
         >>> fig = show_segmentation("aerial.tif", result["mask"])
     """
+    import cv2  # Lazy import to avoid QGIS opencv conflicts
     import matplotlib.pyplot as plt
 
     img, _ = _load_image_for_display(source)
@@ -1941,6 +1943,7 @@ def show_depth(
         >>> result = geoai.auto.depth_estimation("aerial.tif", output_path="depth.tif")
         >>> fig = show_depth("aerial.tif", result["depth"])
     """
+    import cv2  # Lazy import to avoid QGIS opencv conflicts
     import matplotlib.pyplot as plt
 
     img, _ = _load_image_for_display(source)

{geoai_py-0.26.0 → geoai_py-0.27.0}/geoai/change_detection.py

@@ -3,7 +3,6 @@
 import os
 from typing import Any, Dict, List, Optional, Tuple, Union
 
-import cv2
 import matplotlib.pyplot as plt
 import numpy as np
 import rasterio
@@ -736,6 +735,7 @@ class ChangeDetection:
         output_path="split_comparison.png",
     ):
         """Create a split comparison visualization showing before/after with change overlay."""
+        import cv2  # Lazy import to avoid QGIS opencv conflicts
 
         # Load data
         with rasterio.open(image1_path) as src:

{geoai_py-0.26.0 → geoai_py-0.27.0}/geoai/detectron2.py

@@ -6,7 +6,6 @@ import os
 import warnings
 from typing import Dict, List, Optional, Tuple, Union
 
-import cv2
 import numpy as np
 import rasterio
 import torch
@@ -135,6 +134,8 @@ def detectron2_segment(
     Returns:
         Dict containing segmentation results and output file paths
     """
+    import cv2  # Lazy import to avoid QGIS opencv conflicts
+
     check_detectron2()
 
     # Load the model
@@ -315,6 +316,8 @@ def visualize_detectron2_results(
     Returns:
         Visualization image as numpy array
     """
+    import cv2  # Lazy import to avoid QGIS opencv conflicts
+
     check_detectron2()
 
     # Load the image

{geoai_py-0.26.0 → geoai_py-0.27.0}/geoai/extract.py

@@ -6,7 +6,6 @@ import time
 from typing import Any, Dict, Generator, List, Optional, Tuple, Union
 
 # Third-Party Libraries
-import cv2
 import geopandas as gpd
 import matplotlib.pyplot as plt
 import numpy as np
@@ -440,6 +439,7 @@ class ObjectDetector:
         Returns:
             List of polygons as lists of (x, y) coordinates
         """
+        import cv2  # Lazy import to avoid QGIS opencv conflicts
 
         # Get parameters from kwargs or use instance defaults
         simplify_tolerance = kwargs.get("simplify_tolerance", self.simplify_tolerance)
@@ -637,6 +637,8 @@ class ObjectDetector:
         Returns:
             GeoDataFrame with objects
         """
+        import cv2  # Lazy import to avoid QGIS opencv conflicts
+
         # Use class defaults if parameters not provided
         simplify_tolerance = (
             simplify_tolerance
@@ -2165,6 +2167,7 @@ class ObjectDetector:
         Returns:
             GeoDataFrame with car detections and confidence values
         """
+        import cv2  # Lazy import to avoid QGIS opencv conflicts
 
         def _process_single_component(
             component_mask: np.ndarray,

{geoai_py-0.26.0 → geoai_py-0.27.0}/geoai/prithvi.py

@@ -28,6 +28,16 @@ NO_DATA_FLOAT = 0.0001
 OFFSET = 0
 PERCENTILE = 99.9
 
+# Available Prithvi models
+AVAILABLE_MODELS = [
+    "Prithvi-EO-2.0-tiny-TL",  # tiny transfer learning, embed_dim=192, depth=12, with coords
+    "Prithvi-EO-2.0-100M-TL",  # 100M transfer learning, embed_dim=768, depth=12, with coords
+    "Prithvi-EO-2.0-300M",  # 300M base model, embed_dim=1024, depth=24, no coords
+    "Prithvi-EO-2.0-300M-TL",  # 300M transfer learning, embed_dim=768, depth=12, with coords
+    "Prithvi-EO-2.0-600M",  # 600M base model, embed_dim=1280, depth=32, no coords
+    "Prithvi-EO-2.0-600M-TL",  # 600M transfer learning, embed_dim=1280, depth=32, with coords
+]
+
 
 def get_3d_sincos_pos_embed(embed_dim, grid_size, add_cls_token=False):
     """Create 3D sin/cos positional embeddings.
@@ -622,8 +632,22 @@ class PrithviMAE(nn.Module):
 class PrithviProcessor:
     """Prithvi EO 2.0 processor with GeoTIFF input/output support.
 
-    https://huggingface.co/ibm-nasa-geospatial/Prithvi-EO-2.0-300M-TL
-    https://github.com/NASA-IMPACT/Prithvi-EO-2.0
+    Supports multiple model variants:
+    - Prithvi-EO-2.0-tiny-TL (tiny transfer learning)
+    - Prithvi-EO-2.0-100M-TL (100M transfer learning)
+    - Prithvi-EO-2.0-300M (300M base model)
+    - Prithvi-EO-2.0-300M-TL (300M transfer learning)
+    - Prithvi-EO-2.0-600M (600M base model)
+    - Prithvi-EO-2.0-600M-TL (600M transfer learning)
+
+    References:
+        - tiny-TL: https://huggingface.co/ibm-nasa-geospatial/Prithvi-EO-2.0-tiny-TL
+        - 100M-TL: https://huggingface.co/ibm-nasa-geospatial/Prithvi-EO-2.0-100M-TL
+        - 300M: https://huggingface.co/ibm-nasa-geospatial/Prithvi-EO-2.0-300M
+        - 300M-TL: https://huggingface.co/ibm-nasa-geospatial/Prithvi-EO-2.0-300M-TL
+        - 600M: https://huggingface.co/ibm-nasa-geospatial/Prithvi-EO-2.0-600M
+        - 600M-TL: https://huggingface.co/ibm-nasa-geospatial/Prithvi-EO-2.0-600M-TL
+        - GitHub: https://github.com/NASA-IMPACT/Prithvi-EO-2.0
     """
 
     def __init__(
@@ -637,7 +661,14 @@ class PrithviProcessor:
         """Initialize Prithvi processor.
 
         Args:
-            model_name: Name of the Prithvi model to download from HuggingFace Hub
+            model_name: Name of the Prithvi model to download from HuggingFace Hub.
+                Options:
+                - "Prithvi-EO-2.0-tiny-TL" (tiny, 192 dim, 12 layers)
+                - "Prithvi-EO-2.0-100M-TL" (100M, 768 dim, 12 layers)
+                - "Prithvi-EO-2.0-300M" (base, 1024 dim, 24 layers)
+                - "Prithvi-EO-2.0-300M-TL" (default, 768 dim, 12 layers)
+                - "Prithvi-EO-2.0-600M" (base, 1280 dim, 32 layers)
+                - "Prithvi-EO-2.0-600M-TL" (1280 dim, 32 layers)
             config_path: Path to config file (optional, downloads if not provided)
             checkpoint_path: Path to checkpoint file (optional, downloads if not provided)
             device: Torch device to use
@@ -679,7 +710,13 @@ class PrithviProcessor:
         """Download Prithvi model from HuggingFace Hub.
 
         Args:
-            model_name: Name of the model
+            model_name: Name of the model. Options:
+                - "Prithvi-EO-2.0-tiny-TL"
+                - "Prithvi-EO-2.0-100M-TL"
+                - "Prithvi-EO-2.0-300M" (base model)
+                - "Prithvi-EO-2.0-300M-TL" (default)
+                - "Prithvi-EO-2.0-600M" (base model)
+                - "Prithvi-EO-2.0-600M-TL"
             cache_dir: Directory to cache files
 
         Returns:
@@ -1208,6 +1245,20 @@ class PrithviProcessor:
                 dest.write(image[i], i + 1)
 
 
+def get_available_prithvi_models() -> List[str]:
+    """Get list of available Prithvi model names.
+
+    Returns:
+        List of available model names
+
+    Example:
+        >>> models = get_available_prithvi_models()
+        >>> print(models)
+        ['Prithvi-EO-2.0-300M-TL', 'Prithvi-EO-2.0-600M-TL']
+    """
+    return AVAILABLE_MODELS.copy()
+
+
 def load_prithvi_model(
     model_name: str = "Prithvi-EO-2.0-300M-TL",
     device: Optional[str] = None,
@@ -1216,12 +1267,32 @@ def load_prithvi_model(
     """Load Prithvi model (convenience function).
 
     Args:
-        model_name: Name of the model
+        model_name: Name of the model. Options:
+            - "Prithvi-EO-2.0-tiny-TL"
+            - "Prithvi-EO-2.0-100M-TL"
+            - "Prithvi-EO-2.0-300M" (base)
+            - "Prithvi-EO-2.0-300M-TL" (default)
+            - "Prithvi-EO-2.0-600M" (base)
+            - "Prithvi-EO-2.0-600M-TL"
         device: Device to use ('cuda' or 'cpu')
         cache_dir: Cache directory
 
     Returns:
         PrithviProcessor instance
+
+    Example:
+        >>> # Load tiny-TL model
+        >>> processor = load_prithvi_model("Prithvi-EO-2.0-tiny-TL")
+        >>> # Load 100M-TL model
+        >>> processor = load_prithvi_model("Prithvi-EO-2.0-100M-TL")
+        >>> # Load 300M base model
+        >>> processor = load_prithvi_model("Prithvi-EO-2.0-300M")
+        >>> # Load 300M-TL model
+        >>> processor = load_prithvi_model("Prithvi-EO-2.0-300M-TL")
+        >>> # Load 600M base model
+        >>> processor = load_prithvi_model("Prithvi-EO-2.0-600M")
+        >>> # Load 600M-TL model
+        >>> processor = load_prithvi_model("Prithvi-EO-2.0-600M-TL")
     """
     if device is not None:
         device = torch.device(device)
@@ -1245,9 +1316,23 @@ def prithvi_inference(
     Args:
         file_paths: List of input GeoTIFF files
         output_dir: Output directory
-        model_name: Name of the model
+        model_name: Name of the model. Options:
+            - "Prithvi-EO-2.0-tiny-TL"
+            - "Prithvi-EO-2.0-100M-TL"
+            - "Prithvi-EO-2.0-300M" (base)
+            - "Prithvi-EO-2.0-300M-TL" (default)
+            - "Prithvi-EO-2.0-600M" (base)
+            - "Prithvi-EO-2.0-600M-TL"
         mask_ratio: Optional mask ratio
         device: Device to use
+
+    Example:
+        >>> # Use tiny-TL model
+        >>> prithvi_inference(
+        ...     file_paths=["img1.tif", "img2.tif", "img3.tif", "img4.tif"],
+        ...     model_name="Prithvi-EO-2.0-tiny-TL",
+        ...     output_dir="output_tiny"
+        ... )
     """
     processor = load_prithvi_model(model_name, device)
     processor.process_files(file_paths, output_dir, mask_ratio)

{geoai_py-0.26.0 → geoai_py-0.27.0}/geoai/sam.py

@@ -5,7 +5,6 @@ The SamGeo class provides an interface for segmenting geospatial data using the
 import os
 from typing import Any, Dict, List, Optional, Tuple, Union
 
-import cv2
 import numpy as np
 import torch
 from leafmap import array_to_image, blend_images
@@ -125,6 +124,7 @@ class SamGeo:
         Raises:
             ValueError: If the input source is not a valid path or numpy array.
         """
+        import cv2  # Lazy import to avoid QGIS opencv conflicts
 
         if isinstance(source, str):
             if source.startswith("http"):
@@ -399,6 +399,7 @@ class SamGeo:
         Raises:
             ValueError: If no masks are available and `save_masks()` cannot generate them.
         """
+        import cv2  # Lazy import to avoid QGIS opencv conflicts
         import matplotlib.pyplot as plt
 
         if self.batch:

{geoai_py-0.26.0 → geoai_py-0.27.0}/geoai/segment.py

@@ -4,7 +4,6 @@ import os
 from dataclasses import dataclass
 from typing import Any, Dict, List, Optional, Tuple, Union
 
-import cv2
 import geopandas as gpd
 import numpy as np
 import rasterio
@@ -174,6 +173,8 @@ class GroundedSAM:
         Returns:
             List[DetectionResult]: Filtered detection results.
         """
+        import cv2  # Lazy import to avoid QGIS opencv conflicts
+
         if not detections:
             return detections
 
@@ -235,6 +236,8 @@ class GroundedSAM:
 
     def _mask_to_polygon(self, mask: np.ndarray) -> List[List[int]]:
         """Convert mask to polygon coordinates."""
+        import cv2  # Lazy import to avoid QGIS opencv conflicts
+
         # Find contours in the binary mask
         contours, _ = cv2.findContours(
             mask.astype(np.uint8), cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE
@@ -255,6 +258,8 @@ class GroundedSAM:
         self, polygon: List[Tuple[int, int]], image_shape: Tuple[int, int]
     ) -> np.ndarray:
         """Convert polygon to mask."""
+        import cv2  # Lazy import to avoid QGIS opencv conflicts
+
         # Create an empty mask
         mask = np.zeros(image_shape, dtype=np.uint8)
 
@@ -279,6 +284,8 @@ class GroundedSAM:
         Returns:
             List[np.ndarray]: List of individual instance masks.
         """
+        import cv2  # Lazy import to avoid QGIS opencv conflicts
+
         # Find connected components
         num_labels, labels, stats, centroids = cv2.connectedComponentsWithStats(
             mask.astype(np.uint8), connectivity=8
@@ -320,6 +327,8 @@ class GroundedSAM:
         Returns:
             List[Dict]: List of polygon dictionaries with geometry and properties.
         """
+        import cv2  # Lazy import to avoid QGIS opencv conflicts
+
         polygons = []
 
         # Get individual instances