segment-geospatial 1.1.0__tar.gz → 1.2.0__tar.gz

{segment_geospatial-1.1.0 → segment_geospatial-1.2.0}/.github/workflows/draft-pdf.yml

@@ -14,7 +14,7 @@ jobs:
                   # This should be the path to the paper within your repo.
                   paper-path: paper/paper.md
             - name: Upload
-              uses: actions/upload-artifact@v5
+              uses: actions/upload-artifact@v6
               with:
                   name: paper
                   # This is the output path where Pandoc will write the compiled

{segment_geospatial-1.1.0 → segment_geospatial-1.2.0}/.pre-commit-config.yaml

@@ -12,7 +12,7 @@ repos:
             args: ["--maxkb=500"]
 
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.7.4
+      rev: v0.14.9
       hooks:
           - id: ruff
             types_or: [pyi, jupyter]

{segment_geospatial-1.1.0 → segment_geospatial-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: segment-geospatial
-Version: 1.1.0
+Version: 1.2.0
 Summary: Meta AI' Segment Anything Model (SAM) for Geospatial Data.
 Author-email: Qiusheng Wu <giswqs@gmail.com>
 License: MIT license
@@ -29,6 +29,7 @@ Requires-Dist: pyproj
 Requires-Dist: rasterio
 Requires-Dist: segment_anything
 Requires-Dist: shapely
+Requires-Dist: smoothify
 Requires-Dist: torch
 Requires-Dist: torchvision
 Requires-Dist: tqdm

segment_geospatial-1.2.0/docs/examples/sam3_tiled_segmentation.ipynb

@@ -0,0 +1,274 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Tiled Segmentation for Large GeoTIFF Images with SAM 3\n",
+    "\n",
+    "[![image](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/opengeos/segment-geospatial/blob/main/docs/examples/sam3_tiled_segmentation.ipynb)\n",
+    "\n",
+    "This notebook demonstrates how to use the sliding window (tiled) approach to segment large GeoTIFF images that would otherwise exceed GPU memory limits.\n",
+    "\n",
+    "## Overview\n",
+    "\n",
+    "When working with large satellite or aerial imagery, loading the entire image into GPU memory for SAM 3 inference is often not feasible. The `generate_masks_tiled()` method solves this by:\n",
+    "\n",
+    "1. **Dividing** the large image into smaller, overlapping tiles\n",
+    "2. **Processing** each tile independently with SAM 3\n",
+    "3. **Merging** the results back into a seamless output mask\n",
+    "4. **Preserving** georeferencing information from the original GeoTIFF\n",
+    "\n",
+    "## Key Parameters\n",
+    "\n",
+    "- **tile_size**: Size of each processing tile (default: 1024 pixels)\n",
+    "- **overlap**: Overlap between adjacent tiles (default: 128 pixels) - helps prevent edge artifacts\n",
+    "- **prompt**: Text description of objects to segment\n",
+    "- **min_size/max_size**: Filter objects by pixel area"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Installation\n",
+    "\n",
+    "Uncomment and run the following cell to install the required packages:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# %pip install \"segment-geospatial[samgeo3]\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Import Libraries"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "import leafmap\n",
+    "from samgeo import SamGeo3, common"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Download Sample Data\n",
+    "\n",
+    "We'll use a sample satellite image for this demonstration. You can replace this with your own large GeoTIFF."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Download a sample satellite image\n",
+    "url = \"https://huggingface.co/datasets/giswqs/geospatial/resolve/main/naip/naip_water_train.tif\"\n",
+    "image_path = \"naip_water_train.tif\"\n",
+    "\n",
+    "if not os.path.exists(image_path):\n",
+    "    common.download_file(url, image_path)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Check Raster Info\n",
+    "\n",
+    "Let's check the dimensions of our image to understand why tiling might be necessary."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "common.print_raster_info(image_path)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Initialize SamGeo3"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sam = SamGeo3(backend=\"meta\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Run Tiled Segmentation\n",
+    "\n",
+    "Now we'll use the `generate_masks_tiled()` method to process the image. This method:\n",
+    "\n",
+    "1. Reads the image tile by tile\n",
+    "2. Processes each tile with SAM3\n",
+    "3. Merges overlapping regions intelligently\n",
+    "4. Saves the result as a georeferenced GeoTIFF"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Output path for the mask\n",
+    "output_path = \"segmentation_mask.tif\"\n",
+    "\n",
+    "# Run tiled segmentation\n",
+    "sam.generate_masks_tiled(\n",
+    "    source=image_path,\n",
+    "    prompt=\"water\",  # Change prompt based on what you want to segment\n",
+    "    output=output_path,\n",
+    "    tile_size=1024,  # Size of each tile (adjust based on GPU memory)\n",
+    "    overlap=128,  # Overlap between tiles\n",
+    "    min_size=100,  # Minimum object size in pixels\n",
+    "    unique=False,  # Create binary mask (0 or 1)\n",
+    "    dtype=\"int32\",  # Data type for output\n",
+    "    verbose=True,  # Show progress\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Visualize Results"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "m = leafmap.Map()\n",
+    "m.add_raster(image_path, layer_name=\"Original Image\")\n",
+    "m.add_raster(\n",
+    "    output_path, nodata=0, opacity=0.8, cmap=\"Blues\", layer_name=\"Segmentation Mask\"\n",
+    ")\n",
+    "m"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Convert Mask to Vector\n",
+    "\n",
+    "You can convert the raster mask to vector format (GeoPackage, Shapefile, etc.) for further analysis in GIS software."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Convert mask to vector\n",
+    "vector_path = \"segmentation_mask.gpkg\"\n",
+    "common.raster_to_vector(output_path, vector_path)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Smooth Vector"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "smooth_vector_path = \"segmentation_mask_smooth.gpkg\"\n",
+    "gdf = common.smooth_vector(vector_path, smooth_vector_path)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "m.add_gdf(gdf, layer_name=\"Smoothed Vector\", info_mode=None)\n",
+    "m"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Tips for Processing Large Images\n",
+    "\n",
+    "1. **Tile Size**: Larger tiles capture more context but require more GPU memory. Start with 512 or 1024 and increase if you have sufficient GPU memory.\n",
+    "\n",
+    "2. **Overlap**: Higher overlap (e.g., 128-256) helps prevent artifacts at tile boundaries but increases processing time. Lower overlap (e.g., 64) is faster but may have more edge effects.\n",
+    "\n",
+    "3. **Memory Management**: The method automatically clears GPU memory after each tile. If you still encounter memory issues, try reducing the tile_size.\n",
+    "\n",
+    "4. **Data Type**: Use `int32` for images with many objects, `int16` for up to 65535 objects, or `int8` for up to 255 objects.\n",
+    "\n",
+    "5. **Filtering**: Use `min_size` and `max_size` to filter out noise (small objects) or irrelevant large regions."
+   ]
+  }
+ ],
+ "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.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

{segment_geospatial-1.1.0 → segment_geospatial-1.2.0}/mkdocs.yml

@@ -81,6 +81,7 @@ nav:
           - examples/sam3_point_prompts.ipynb
           - examples/sam3_point_prompts_batch.ipynb
           - examples/sam3_box_prompts.ipynb
+          - examples/sam3_tiled_segmentation.ipynb
     - Workshops:
           - workshops/purdue.ipynb
           - workshops/cn_workshop.ipynb

{segment_geospatial-1.1.0 → segment_geospatial-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "segment-geospatial"
-version = "1.1.0"
+version = "1.2.0"
 dynamic = [
     "dependencies",
 ]
@@ -111,7 +111,7 @@ dependencies = {file = ["requirements.txt"]}
 universal = true
 
 [tool.bumpversion]
-current_version = "1.1.0"
+current_version = "1.2.0"
 commit = true
 tag = true
 

{segment_geospatial-1.1.0 → segment_geospatial-1.2.0}/requirements.txt

@@ -10,6 +10,7 @@ pyproj
 rasterio
 segment_anything
 shapely
+smoothify
 torch
 torchvision
 tqdm

{segment_geospatial-1.1.0 → segment_geospatial-1.2.0}/samgeo/__init__.py

@@ -2,7 +2,7 @@
 
 __author__ = """Qiusheng Wu"""
 __email__ = "giswqs@gmail.com"
-__version__ = "1.1.0"
+__version__ = "1.2.0"
 
 
 from .samgeo import *  # noqa: F403

{segment_geospatial-1.1.0 → segment_geospatial-1.2.0}/samgeo/common.py

@@ -4,7 +4,7 @@ The source code is adapted from https://github.com/aliaksandr960/segment-anythin
 
 import os
 import tempfile
-from typing import Any, List, Optional, Tuple, Union
+from typing import Any, Dict, List, Optional, Tuple, Union
 
 import cv2
 import geopandas as gpd
@@ -4055,3 +4055,220 @@ def get_device() -> torch.device:
         return torch.device("mps")
     else:
         return torch.device("cpu")
+
+
+def get_raster_info(raster_path: str) -> Dict[str, Any]:
+    """Display basic information about a raster dataset.
+
+    Args:
+        raster_path (str): Path to the raster file
+
+    Returns:
+        dict: Dictionary containing the basic information about the raster
+    """
+    # Open the raster dataset
+    with rasterio.open(raster_path) as src:
+        # Get basic metadata
+        info = {
+            "driver": src.driver,
+            "width": src.width,
+            "height": src.height,
+            "count": src.count,
+            "dtype": src.dtypes[0],
+            "crs": src.crs.to_string() if src.crs else "No CRS defined",
+            "transform": src.transform,
+            "bounds": src.bounds,
+            "resolution": (src.transform[0], -src.transform[4]),
+            "nodata": src.nodata,
+        }
+
+        # Calculate statistics for each band
+        stats = []
+        for i in range(1, src.count + 1):
+            band = src.read(i, masked=True)
+            band_stats = {
+                "band": i,
+                "min": float(band.min()),
+                "max": float(band.max()),
+                "mean": float(band.mean()),
+                "std": float(band.std()),
+            }
+            stats.append(band_stats)
+
+        info["band_stats"] = stats
+
+    return info
+
+
+def get_raster_stats(raster_path: str, divide_by: float = 1.0) -> Dict[str, Any]:
+    """Calculate statistics for each band in a raster dataset.
+
+    This function computes min, max, mean, and standard deviation values
+    for each band in the provided raster, returning results in a dictionary
+    with lists for each statistic type.
+
+    Args:
+        raster_path (str): Path to the raster file
+        divide_by (float, optional): Value to divide pixel values by.
+            Defaults to 1.0, which keeps the original pixel values unchanged.
+
+    Returns:
+        dict: Dictionary containing lists of statistics with keys:
+            - 'min': List of minimum values for each band
+            - 'max': List of maximum values for each band
+            - 'mean': List of mean values for each band
+            - 'std': List of standard deviation values for each band
+    """
+    # Initialize the results dictionary with empty lists
+    stats = {"min": [], "max": [], "mean": [], "std": []}
+
+    # Open the raster dataset
+    with rasterio.open(raster_path) as src:
+        # Calculate statistics for each band
+        for i in range(1, src.count + 1):
+            band = src.read(i, masked=True)
+
+            # Append statistics for this band to each list
+            stats["min"].append(float(band.min()) / divide_by)
+            stats["max"].append(float(band.max()) / divide_by)
+            stats["mean"].append(float(band.mean()) / divide_by)
+            stats["std"].append(float(band.std()) / divide_by)
+
+    return stats
+
+
+def print_raster_info(
+    raster_path: str, show_preview: bool = True, figsize: Tuple[int, int] = (10, 8)
+) -> Optional[Dict[str, Any]]:
+    """Print formatted information about a raster dataset and optionally show a preview.
+
+    Args:
+        raster_path (str): Path to the raster file
+        show_preview (bool, optional): Whether to display a visual preview of the raster.
+            Defaults to True.
+        figsize (tuple, optional): Figure size as (width, height). Defaults to (10, 8).
+
+    Returns:
+        dict: Dictionary containing raster information if successful, None otherwise
+    """
+    import matplotlib.pyplot as plt
+    from rasterio.plot import show
+
+    try:
+        info = get_raster_info(raster_path)
+
+        # Print basic information
+        print(f"===== RASTER INFORMATION: {raster_path} =====")
+        print(f"Driver: {info['driver']}")
+        print(f"Dimensions: {info['width']} x {info['height']} pixels")
+        print(f"Number of bands: {info['count']}")
+        print(f"Data type: {info['dtype']}")
+        print(f"Coordinate Reference System: {info['crs']}")
+        print(f"Georeferenced Bounds: {info['bounds']}")
+        print(f"Pixel Resolution: {info['resolution'][0]}, {info['resolution'][1]}")
+        print(f"NoData Value: {info['nodata']}")
+
+        # Print band statistics
+        print("\n----- Band Statistics -----")
+        for band_stat in info["band_stats"]:
+            print(f"Band {band_stat['band']}:")
+            print(f"  Min: {band_stat['min']:.2f}")
+            print(f"  Max: {band_stat['max']:.2f}")
+            print(f"  Mean: {band_stat['mean']:.2f}")
+            print(f"  Std Dev: {band_stat['std']:.2f}")
+
+        # Show a preview if requested
+        if show_preview:
+            with rasterio.open(raster_path) as src:
+                # For multi-band images, show RGB composite or first band
+                if src.count >= 3:
+                    # Try to show RGB composite
+                    rgb = np.dstack([src.read(i) for i in range(1, 4)])
+                    plt.figure(figsize=figsize)
+                    plt.imshow(rgb)
+                    plt.title(f"RGB Preview: {raster_path}")
+                else:
+                    # Show first band for single-band images
+                    plt.figure(figsize=figsize)
+                    show(
+                        src.read(1),
+                        cmap="viridis",
+                        title=f"Band 1 Preview: {raster_path}",
+                    )
+                    plt.colorbar(label="Pixel Value")
+                plt.show()
+
+        return info
+
+    except Exception as e:
+        print(f"Error reading raster: {str(e)}")
+        return None
+
+
+def smooth_vector(
+    vector_data: Union[str, gpd.GeoDataFrame],
+    output_path: str = None,
+    segment_length: float = None,
+    smooth_iterations: int = 3,
+    num_cores: int = 0,
+    merge_collection: bool = True,
+    merge_field: str = None,
+    merge_multipolygons: bool = True,
+    preserve_area: bool = True,
+    area_tolerance: float = 0.01,
+    **kwargs: Any,
+) -> gpd.GeoDataFrame:
+    """Smooth a vector data using the smoothify library.
+    See https://github.com/DPIRD-DMA/Smoothify for more details.
+
+    Args:
+        vector_data: The vector data to smooth.
+        output_path: The path to save the smoothed vector data. If None, returns the smoothed vector data.
+        segment_length: Resolution of the original raster data in map units. If None (default), automatically
+            detects by finding the minimum segment length (from a data sample). Recommended to specify explicitly when known.
+        smooth_iterations: The number of iterations to smooth the vector data.
+        num_cores: Number of cores to use for parallel processing. If 0 (default), uses all available cores.
+        merge_collection: Whether to merge/dissolve adjacent geometries in collections before smoothing.
+        merge_field: Column name to use for dissolving geometries. Only valid when merge_collection=True.
+            If None, dissolves all geometries together. If specified, dissolves geometries grouped by the column values.
+        merge_multipolygons: Whether to merge adjacent polygons within MultiPolygons before smoothing
+        preserve_area: Whether to restore original area after smoothing via buffering (applies to Polygons only)
+        area_tolerance: Percentage of original area allowed as error (e.g., 0.01 = 0.01% error = 99.99% preservation).
+            Only affects Polygons when preserve_area=True
+
+    Returns:
+        gpd.GeoDataFrame: The smoothed vector data.
+
+    Examples:
+        >>> from samgeo import common
+        >>> gdf = common.read_vector("path/to/vector.geojson")
+        >>> smoothed_gdf = common.smooth_vector(gdf, smooth_iterations=3, output_path="path/to/smoothed_vector.geojson")
+        >>> smoothed_gdf.head()
+        >>> smoothed_gdf.explore()
+    """
+    import leafmap
+
+    try:
+        from smoothify import smoothify
+    except ImportError:
+        install_package("smoothify")
+        from smoothify import smoothify
+
+    if isinstance(vector_data, str):
+        vector_data = leafmap.read_vector(vector_data)
+
+    smoothed_vector_data = smoothify(
+        geom=vector_data,
+        segment_length=segment_length,
+        smooth_iterations=smooth_iterations,
+        num_cores=num_cores,
+        merge_collection=merge_collection,
+        merge_field=merge_field,
+        merge_multipolygons=merge_multipolygons,
+        preserve_area=preserve_area,
+        area_tolerance=area_tolerance,
+        **kwargs,
+    )
+    if output_path is not None:
+        smoothed_vector_data.to_file(output_path)
+    return smoothed_vector_data