DOCSEARCHbyAlgolia
Submit Docs

segment-geospatial (SamGeo)

repository·main·Indexed 26 days ago

https://github.com/opengeos/segment-geospatial

A Python package for geospatial data segmentation using Meta AI's Segment Anything Model (SAM). It supports SAM v1, SAM 2, SAM 3, FastSAM, HQ-SAM, and LangSAM. Features include text-prompted masking, object segmentation, timeseries analysis, and a REST API. The library provides a command-line interface (cli-anything-samgeo) and integrates with desktop GIS platforms via a QGIS plugin and an ArcGIS Pro toolbox.

Tokens
36.9K
Snippets
166
Records
237
Agent score
88%

What's inside segment-geospatial

  1. Overview of segment-geospatial (samgeo)

    main
    segment-geospatial (also referred to as samgeo) is a Python package designed for segmenting geospatial data using Meta AI's Segment Anything Model (SAM) family. It provides geospatial-aware I/O (supporting formats like GeoTIFF and GeoPackage) and wraps several models including SAM v1, SAM 2, SAM 3, FastSAM, HQ-SAM, and LangSAM.

  2. Overview of SamGeo (segment-geospatial)

    main

    SamGeo (segment-geospatial) is an open-source Python package designed to simplify geospatial data segmentation using the Segment Anything Model (SAM). It provides a low-code and no-code solution for segmenting remote sensing imagery without requiring users to train deep learning models.

    Key capabilities include:

    • Automated Segmentation: Run segmentation processes automatically on imagery.
    • Interactive GUI: Perform segmentation interactively via a graphical user interface.
    • Text Prompting: Use text prompts (built upon Grounding DINO) to drive segmentation.
    • Data Export: Export results in various formats, including vector and raster data.
    • Imagery Management: Download remote sensing imagery and visualize segmentation results interactively within Jupyter environments.

    The package integrates with several popular libraries, including leafmap, ipywidgets, rasterio, geopandas, and segment-anything-py.

  3. SamGeo Features Overview

    main

    SamGeo provides a suite of tools for geospatial segmentation using the Segment Anything Model (SAM) and HQ-SAM:

    • Data Handling: Download map tiles from TMS servers to GeoTIFF; save results as GeoPackage, Shapefile, or GeoJSON.
    • Segmentation: Support for SAM, HQ-SAM, SAM 2, SAM 3, and Fast SAM; segment remote sensing imagery using text prompts.
    • Interactivity: Create foreground/background markers interactively or load them from vector datasets.
    • Advanced Analysis: Segment objects from timeseries imagery; feature edge reconstruction (FER).
    • Deployment: REST API for serving segmentation over HTTP.

  5. Install SamGeo using pixi (Recommended)

    main

    For the most reliable installation, especially on Windows or when using complex dependencies like PyTorch/CUDA and SAM 3, use pixi. This avoids common numpy version conflicts and provides faster dependency resolution.

    1. Install pixi:
      • Linux/macOS: curl -fsSL https://pixi.sh/install.sh | sh
      • Windows (PowerShell): powershell -ExecutionPolicy Bypass -c "irm -useb https://pixi.sh/install.ps1 | iex"
    2. Initialize a project: pixi init geo cd geo
    3. Configure pixi.toml (refer to project documentation for GPU/CPU specific configurations).
    4. Install dependencies: pixi install
    5. Run Jupyter Lab: pixi run jupyter lab
    # Install pixi (Linux/macOS)
curl -fsSL https://pixi.sh/install.sh | sh

# Or on Windows (PowerShell)
powershell -ExecutionPolicy Bypass -c "irm -useb https://pixi.sh/install.ps1 | iex"

# Create a new pixi project
pixi init geo
cd geo

# Edit pixi.toml with your configuration (see docs for GPU/CPU examples)
# Then install
pixi install

# Start Jupyter Lab
pixi run jupyter lab

  6. Check the CRS of a GeoTIFF

    main

    You can verify the Coordinate Reference System (CRS) of your input GeoTIFF files using either the GDAL command-line tool or the rasterio Python library. This is useful for ensuring your input data has correct metadata before starting the segmentation process.

    # Using GDAL
gdalinfo your_file.tif
    # Using Python with rasterio
import rasterio
with rasterio.open("your_file.tif") as src:
    print(f"CRS: {src.crs}")

  7. Install segment-geospatial REST API dependencies

    main

    To use the built-in FastAPI-powered REST API, install the package with the api extra. You can also combine it with specific SAM model backends like samgeo3.

    # Install API dependencies
pip install "segment-geospatial[api]"

# Install API dependencies with samgeo3 backend
pip install "segment-geospatial[api,samgeo3]"
    pip install "segment-geospatial[api]"

  9. Install the SamGeo QGIS Plugin

    main

    You can install the plugin using an automated script or by manually placing the repository in your QGIS plugins directory.

    Option A: Using the install script

    Clone the repository and run the provided installation script within your active geo conda environment.

    Option B: Manual installation

    1. Locate your QGIS plugins directory based on your OS:
      • Linux: ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins
      • macOS: ~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins
      • Windows: %APPDATA%\QGIS\QGIS3\profiles\default\python\plugins
    2. Copy or symlink the qgis-samgeo-plugin folder to that directory and rename it to samgeo_plugin.
    3. Restart QGIS and enable the plugin via Plugins > Manage and Install Plugins.
    # Option A: Scripted installation
git clone https://github.com/opengeos/qgis-samgeo-plugin.git
cd qgis-samgeo-plugin
conda activate geo

# Linux/macOS
python install_plugin.py

# Or using shell script
chmod +x install_plugin.sh
./install_plugin.sh

# Option B: Manual symlink example (Linux)
ln -s /path/to/qgis-samgeo-plugin ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/samgeo_plugin

  10. Pull Request requirements

    main

    Ensure your Pull Request meets these criteria before submission:

    • Tests: Must include unit tests for any new functionality.
    • Documentation: If adding functionality, update the documentation. New functions should include a docstring, and the feature should be listed in README.md.
    • Python Compatibility: The code must work for Python 3.8, 3.9, 3.10, and 3.11. Ensure tests pass for all these versions (using tox).

  11. Request access and download SAM 3 or SAM 3.1

    main

    SAM 3 and SAM 3.1 require manual access requests on Hugging Face:

    Once access is granted, authenticate and download the models using Pixi:

    1. Authenticate:
      pixi run hf auth login
    2. Download SAM 3:
      pixi run hf download facebook/sam3
    3. Download SAM 3.1:
      pixi run hf download facebook/sam3.1

    Warning: SAM 3/3.1 require an NVIDIA GPU with CUDA. On CPU-only systems, you will encounter the error: Failed to load model: Torch not compiled with CUDA enabled.

    pixi run hf auth login
pixi run hf download facebook/sam3

  12. Enable cli-anything-samgeo for Claude Code

    main

    You can enable Claude Code to automatically discover and use the CLI using the provided SKILL.md file.

    Option 1: Update CLAUDE.md Append a reference to the skill file in your CLAUDE.md:

    # In your CLAUDE.md
Read the skill file at /path/to/agent-harness/cli_anything/samgeo/skills/SKILL.md
for the full cli-anything-samgeo command reference. Use `--json` for all
cli-anything-samgeo commands so output is machine-readable.

    Option 2: On-the-fly instruction Paste the following into a Claude Code conversation: Read agent-harness/cli_anything/samgeo/skills/SKILL.md and use that CLI to segment this satellite image.

    Best Practices for Claude Code:

    • Always use the --json flag to provide structured output.
    • The --project flag must appear before the command group (e.g., cli-anything-samgeo --project proj.json segment automatic).
    • Use model check <model_name> to verify backends.