segment-geospatial 1.2.3__tar.gz → 1.3.0__tar.gz

{segment_geospatial-1.2.3 → segment_geospatial-1.3.0}/.github/workflows/docker-publish.yml

@@ -16,13 +16,13 @@ jobs:
               uses: actions/checkout@v6
 
             - name: Log in to Docker Hub
-              uses: docker/login-action@v3
+              uses: docker/login-action@v4
               with:
                   username: ${{ secrets.DOCKER_USERNAME }}
                   password: ${{ secrets.DOCKER_PASSWORD }}
 
             - name: Log in to the Container registry
-              uses: docker/login-action@v3
+              uses: docker/login-action@v4
               with:
                   registry: ghcr.io
                   username: ${{ github.actor }}
@@ -30,14 +30,14 @@ jobs:
 
             - name: Extract metadata (tags, labels) for Docker
               id: meta
-              uses: docker/metadata-action@v5
+              uses: docker/metadata-action@v6
               with:
                   images: |
                       giswqs/segment-geospatial
                       ghcr.io/${{ github.repository }}
 
             - name: Build and push Docker images
-              uses: docker/build-push-action@v6
+              uses: docker/build-push-action@v7
               with:
                   context: .
                   push: true

{segment_geospatial-1.2.3 → segment_geospatial-1.3.0}/.pre-commit-config.yaml

@@ -12,14 +12,14 @@ repos:
             args: ["--maxkb=500"]
 
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.15.2
+      rev: v0.15.6
       hooks:
           - id: ruff
             types_or: [pyi, jupyter]
             args: [--fix, --unsafe-fixes]
 
     - repo: https://github.com/codespell-project/codespell
-      rev: v2.4.1
+      rev: v2.4.2
       hooks:
           - id: codespell
             args:

{segment_geospatial-1.2.3 → segment_geospatial-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: segment-geospatial
-Version: 1.2.3
+Version: 1.3.0
 Summary: Meta AI's Segment Anything Model (SAM) for Geospatial Data.
 Author-email: Qiusheng Wu <giswqs@gmail.com>
 License: MIT license
@@ -86,8 +86,13 @@ Requires-Dist: xarray; extra == "samgeo3"
 Provides-Extra: text
 Requires-Dist: segment_geospatial[samgeo2]; extra == "text"
 Requires-Dist: groundingdino-py; extra == "text"
+Provides-Extra: api
+Requires-Dist: segment_geospatial[core]; extra == "api"
+Requires-Dist: fastapi>=0.100.0; extra == "api"
+Requires-Dist: uvicorn[standard]>=0.20.0; extra == "api"
+Requires-Dist: python-multipart>=0.0.6; extra == "api"
 Provides-Extra: all
-Requires-Dist: segment-geospatial[fast,fer,hq,samgeo,samgeo2,samgeo3,text]; extra == "all"
+Requires-Dist: segment-geospatial[api,fast,fer,hq,samgeo,samgeo2,samgeo3,text]; extra == "all"
 Provides-Extra: extra
 Requires-Dist: leafmap; extra == "extra"
 Requires-Dist: segment-geospatial[all]; extra == "extra"
@@ -137,6 +142,7 @@ The **SamGeo** package draws its inspiration from [segment-anything-eo](https://
 -   Save input prompts as GeoJSON files
 -   Visualize segmentation results on interactive maps
 -   Segment objects from timeseries remote sensing imagery
+-   REST API for serving segmentation over HTTP (see [API docs](https://samgeo.gishub.org/api))
 
 ## QGIS Plugin
 
@@ -185,6 +191,7 @@ Depending on what tools you need to use, you might want to do:
 -   `segment-geospatial[text]`: Installs Grounding DINO to use SAMGeo 1 and 2 with text prompts
 -   `segment-geospatial[fer]`: Installs the dependencies to run the feature
     edge reconstruction algorithm
+-   `segment-geospatial[api]`: Installs FastAPI and Uvicorn for serving segmentation as a REST API
 
 Additionally, these other two optional imports are defined:
 

{segment_geospatial-1.2.3 → segment_geospatial-1.3.0}/README.md

@@ -38,6 +38,7 @@ The **SamGeo** package draws its inspiration from [segment-anything-eo](https://
 -   Save input prompts as GeoJSON files
 -   Visualize segmentation results on interactive maps
 -   Segment objects from timeseries remote sensing imagery
+-   REST API for serving segmentation over HTTP (see [API docs](https://samgeo.gishub.org/api))
 
 ## QGIS Plugin
 
@@ -86,6 +87,7 @@ Depending on what tools you need to use, you might want to do:
 -   `segment-geospatial[text]`: Installs Grounding DINO to use SAMGeo 1 and 2 with text prompts
 -   `segment-geospatial[fer]`: Installs the dependencies to run the feature
     edge reconstruction algorithm
+-   `segment-geospatial[api]`: Installs FastAPI and Uvicorn for serving segmentation as a REST API
 
 Additionally, these other two optional imports are defined:
 

segment_geospatial-1.3.0/docs/api.md

@@ -0,0 +1,224 @@
+# REST API
+
+segment-geospatial includes a built-in REST API powered by [FastAPI](https://fastapi.tiangolo.com/) that allows you to run image segmentation over HTTP. This is useful for integrating segmentation into web applications, pipelines, and non-Python clients.
+
+## Installation
+
+Install the API dependencies with the `api` extra:
+
+```bash
+pip install "segment-geospatial[api]"
+```
+
+To also install a specific SAM model backend, combine extras:
+
+```bash
+pip install "segment-geospatial[api,samgeo3]"
+```
+
+## Starting the Server
+
+Use the `samgeo-api` command:
+
+```bash
+samgeo-api
+```
+
+Options:
+
+```bash
+samgeo-api --host 0.0.0.0 --port 8000        # Custom host/port
+samgeo-api --preload sam2:sam2-hiera-large     # Preload a model at startup
+samgeo-api --reload                            # Auto-reload for development
+```
+
+Alternatively, use `uvicorn` directly:
+
+```bash
+uvicorn samgeo.api:app --host 0.0.0.0 --port 8000
+```
+
+Once running, interactive API docs (Swagger UI) are available at [http://localhost:8000/docs](http://localhost:8000/docs).
+
+## Endpoints
+
+### Health Check
+
+```
+GET /health
+```
+
+Returns the server status and version.
+
+```bash
+curl http://localhost:8000/health
+```
+
+```json
+{"status": "ok", "version": "1.2.3"}
+```
+
+### List Models
+
+```
+GET /models
+```
+
+Returns available model versions/IDs and which models are currently loaded in memory.
+
+```bash
+curl http://localhost:8000/models
+```
+
+### Clear Models
+
+```
+DELETE /models
+```
+
+Clears the model cache and frees GPU memory.
+
+```bash
+curl -X DELETE http://localhost:8000/models
+```
+
+### Automatic Segmentation
+
+```
+POST /segment/automatic
+```
+
+Runs automatic mask generation on an uploaded image. Supports SAM, SAM2, and SAM3.
+
+**Parameters (multipart form):**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `file` | file | required | Image file (TIFF, PNG, JPEG) |
+| `model_version` | string | `sam2` | One of `sam`, `sam2`, `sam3` |
+| `model_id` | string | auto | Model identifier (e.g., `sam2-hiera-large`) |
+| `output_format` | string | `geojson` | One of `geojson`, `geotiff`, `png` |
+| `foreground` | bool | `true` | Extract foreground objects only |
+| `unique` | bool | `true` | Assign unique ID to each object |
+| `min_size` | int | `0` | Minimum mask size in pixels |
+| `max_size` | int | none | Maximum mask size in pixels |
+| `points_per_side` | int | `32` | Points sampled per side (SAM/SAM2) |
+| `pred_iou_thresh` | float | `0.8` | IoU threshold for filtering |
+| `stability_score_thresh` | float | `0.95` | Stability score threshold |
+
+**Example:**
+
+```bash
+curl -X POST http://localhost:8000/segment/automatic \
+  -F "file=@image.tif" \
+  -F "model_version=sam2" \
+  -F "output_format=geojson"
+```
+
+### Prompt-based Segmentation
+
+```
+POST /segment/predict
+```
+
+Runs segmentation with point or bounding box prompts. Supports SAM and SAM2.
+
+**Parameters (multipart form):**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `file` | file | required | Image file (TIFF, PNG, JPEG) |
+| `model_version` | string | `sam2` | One of `sam`, `sam2` |
+| `model_id` | string | auto | Model identifier |
+| `output_format` | string | `geojson` | One of `geojson`, `geotiff`, `png` |
+| `point_coords` | string | none | JSON array of `[[x, y], ...]` |
+| `point_labels` | string | none | JSON array of `[1, 0, ...]` (1=foreground, 0=background) |
+| `boxes` | string | none | JSON array of `[[xmin, ymin, xmax, ymax], ...]` |
+| `point_crs` | string | none | CRS string (e.g., `EPSG:4326`) |
+| `multimask_output` | bool | `false` | Return multiple masks per prompt |
+
+**Example with point prompts:**
+
+```bash
+curl -X POST http://localhost:8000/segment/predict \
+  -F "file=@image.tif" \
+  -F "point_coords=[[100, 200]]" \
+  -F "point_labels=[1]" \
+  -F "output_format=geojson"
+```
+
+**Example with box prompts:**
+
+```bash
+curl -X POST http://localhost:8000/segment/predict \
+  -F "file=@image.tif" \
+  -F "boxes=[[10, 20, 300, 400]]" \
+  -F "output_format=geotiff"
+```
+
+### Text-prompt Segmentation
+
+```
+POST /segment/text
+```
+
+Runs text-prompt segmentation using SAM3.
+
+**Parameters (multipart form):**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `file` | file | required | Image file (TIFF, PNG, JPEG) |
+| `prompt` | string | required | Text description (e.g., `building`, `tree`) |
+| `model_id` | string | auto | SAM3 model identifier |
+| `backend` | string | `meta` | One of `meta`, `transformers` |
+| `output_format` | string | `geojson` | One of `geojson`, `geotiff`, `png` |
+| `confidence_threshold` | float | `0.5` | Detection confidence threshold |
+| `min_size` | int | `0` | Minimum mask size in pixels |
+| `max_size` | int | none | Maximum mask size in pixels |
+
+**Example:**
+
+```bash
+curl -X POST http://localhost:8000/segment/text \
+  -F "file=@image.tif" \
+  -F "prompt=building" \
+  -F "output_format=geojson"
+```
+
+## Caching
+
+The API automatically caches models and image encodings for better performance:
+
+- **Model cache**: Models are loaded once and reused across requests. Use `DELETE /models` to free GPU memory.
+- **Image cache**: When the same image is sent multiple times (e.g., with different prompts), the expensive image encoding step is skipped. This makes subsequent requests significantly faster.
+
+Example timing with a 13 MB GeoTIFF:
+
+| Request | Description | Time |
+|---------|-------------|------|
+| 1st | Model load + image encoding | ~7s |
+| 2nd | Same image, different prompt | ~0.4s |
+| 3rd | Same image, another prompt | ~0.2s |
+
+## Python Client Example
+
+```python
+import requests
+
+url = "http://localhost:8000/segment/text"
+
+with open("image.tif", "rb") as f:
+    response = requests.post(
+        url,
+        files={"file": ("image.tif", f, "image/tiff")},
+        data={"prompt": "building", "output_format": "geojson"},
+    )
+
+geojson = response.json()
+print(f"Found {len(geojson['features'])} features")
+```
+
+## API Reference
+
+::: samgeo.api

{segment_geospatial-1.2.3 → segment_geospatial-1.3.0}/docs/index.md

@@ -38,6 +38,7 @@ The **SamGeo** package draws its inspiration from [segment-anything-eo](https://
 -   Save input prompts as GeoJSON files
 -   Visualize segmentation results on interactive maps
 -   Segment objects from timeseries remote sensing imagery
+-   REST API for serving segmentation over HTTP (see [API docs](https://samgeo.gishub.org/api))
 
 ## QGIS Plugin
 
@@ -61,6 +62,7 @@ Depending on what tools you need to use, you might want to do:
 -   `segment-geospatial[text]`: Installs Grounding DINO to use SAMGeo 1 and 2 with text prompts
 -   `segment-geospatial[fer]`: Installs the dependencies to run the feature
     edge reconstruction algorithm
+-   `segment-geospatial[api]`: Installs FastAPI and Uvicorn for serving segmentation as a REST API
 
 Additionally, these other two optional imports are defined:
 

{segment_geospatial-1.2.3 → segment_geospatial-1.3.0}/mkdocs.yml

@@ -44,6 +44,7 @@ nav:
     - Home: index.md
     - Installation: installation.md
     - Usage: usage.md
+    - REST API: api.md
     - Contributing: contributing.md
     - FAQ: faq.md
     - Changelog: changelog.md
@@ -98,4 +99,5 @@ nav:
           - hq_sam module: hq_sam.md
           - text_sam module: text_sam.md
           - detectree2 module: detectree2.md
+          - api module: api.md
           #   - fer module: fer.md

{segment_geospatial-1.2.3 → segment_geospatial-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "segment-geospatial"
-version = "1.2.3"
+version = "1.3.0"
 dynamic = [
     "dependencies",
 ]
@@ -86,8 +86,14 @@ text = [
     "segment_geospatial[samgeo2]",
     "groundingdino-py",
 ]
+api = [
+    "segment_geospatial[core]",
+    "fastapi>=0.100.0",
+    "uvicorn[standard]>=0.20.0",
+    "python-multipart>=0.0.6",
+]
 all = [
-    "segment-geospatial[fast, hq, fer, samgeo, samgeo2, samgeo3, text]",
+    "segment-geospatial[fast, hq, fer, samgeo, samgeo2, samgeo3, text, api]",
 ]
 extra = [
     "leafmap",
@@ -111,7 +117,7 @@ dependencies = {file = ["requirements.txt"]}
 universal = true
 
 [tool.bumpversion]
-current_version = "1.2.3"
+current_version = "1.3.0"
 commit = true
 tag = true
 
@@ -133,5 +139,8 @@ max-line-length = 88
 
 [tool.setuptools_scm]
 
+[project.scripts]
+samgeo-api = "samgeo.api:main"
+
 [project.urls]
 Homepage = "https://github.com/opengeos/segment-geospatial"

{segment_geospatial-1.2.3 → segment_geospatial-1.3.0}/samgeo/__init__.py

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