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

{segment_geospatial-1.2.2 → segment_geospatial-1.2.3}/.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@v6
+              uses: actions/upload-artifact@v7
               with:
                   name: paper
                   # This is the output path where Pandoc will write the compiled

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

@@ -12,7 +12,7 @@ repos:
             args: ["--maxkb=500"]
 
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.14.14
+      rev: v0.15.2
       hooks:
           - id: ruff
             types_or: [pyi, jupyter]
@@ -29,6 +29,6 @@ repos:
                 ]
 
     - repo: https://github.com/kynan/nbstripout
-      rev: 0.9.0
+      rev: 0.9.1
       hooks:
           - id: nbstripout

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: segment-geospatial
-Version: 1.2.2
+Version: 1.2.3
 Summary: Meta AI's Segment Anything Model (SAM) for Geospatial Data.
 Author-email: Qiusheng Wu <giswqs@gmail.com>
 License: MIT license

segment_geospatial-1.2.3/docs/detectree2.md

@@ -0,0 +1,3 @@
+# detectree2 module
+
+::: samgeo.detectree2

segment_geospatial-1.2.3/docs/examples/detectree2.ipynb

@@ -0,0 +1,376 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Tree Crown Delineation with detectree2\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/detectree2.ipynb)\n",
+    "\n",
+    "This notebook demonstrates how to use the detectree2 module for automatic tree crown delineation in aerial RGB imagery using Mask R-CNN.\n",
+    "\n",
+    "## Overview\n",
+    "\n",
+    "[detectree2](https://github.com/PatBall1/detectree2) is a Python package for automatic tree crown delineation based on the Detectron2 implementation of Mask R-CNN. It has been designed to delineate trees in challenging dense tropical forests and has been validated across various forest types.\n",
+    "\n",
+    "**Reference:**\n",
+    "Ball, J.G.C., et al. (2023). Accurate delineation of individual tree crowns in tropical forests from aerial RGB imagery using Mask R-CNN. Remote Sens Ecol Conserv. 9(5):641-655. https://doi.org/10.1002/rse2.332"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Installation\n",
+    "\n",
+    "First, install the required packages. detectree2 requires PyTorch and Detectron2 to be installed first."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Install PyTorch (adjust for your CUDA version)\n",
+    "# %pip install torch torchvision\n",
+    "\n",
+    "# Install Detectron2\n",
+    "# %pip install 'git+https://github.com/facebookresearch/detectron2.git'\n",
+    "\n",
+    "# Install detectree2\n",
+    "# %pip install git+https://github.com/PatBall1/detectree2.git\n",
+    "\n",
+    "# Install segment-geospatial\n",
+    "# %pip install segment-geospatial"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Import Libraries"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import leafmap\n",
+    "from samgeo.detectree2 import (\n",
+    "    TreeCrownDelineator,\n",
+    "    list_pretrained_models,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## List Available Pre-trained Models\n",
+    "\n",
+    "detectree2 provides several pre-trained models from different forest types:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "models = list_pretrained_models()\n",
+    "for name, url in models.items():\n",
+    "    print(f\"{name}: {url}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Download Sample Image\n",
+    "\n",
+    "Download a sample tree image for testing:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "image_url = (\n",
+    "    \"https://github.com/opengeos/datasets/releases/download/samgeo/tree_image.tif\"\n",
+    ")\n",
+    "image_path = leafmap.download_file(image_url)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Visualize the Sample Image"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "m = leafmap.Map()\n",
+    "m.add_raster(image_path, layer_name=\"Tree Image\")\n",
+    "m"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Initialize the Tree Crown Delineator\n",
+    "\n",
+    "Initialize the `TreeCrownDelineator` with a pre-trained model. The model will be automatically downloaded on first use."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "delineator = TreeCrownDelineator(\n",
+    "    model_name=\"default\",  # Options: 'paracou', 'sepilok', 'danum', 'default'\n",
+    "    confidence_threshold=0.5,  # Minimum confidence for predictions\n",
+    "    nms_threshold=0.3,  # Non-maximum suppression threshold\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Predict Tree Crowns\n",
+    "\n",
+    "Run the prediction on the sample image:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "output_path = \"tree_crowns.gpkg\"\n",
+    "\n",
+    "crowns = delineator.predict(\n",
+    "    image_path=image_path,\n",
+    "    output_path=output_path,\n",
+    "    tile_width=20,  # Tile width in meters\n",
+    "    tile_height=20,  # Tile height in meters\n",
+    "    buffer=30,  # Buffer around tiles in meters\n",
+    "    simplify_tolerance=0.2,  # Simplify crown geometries\n",
+    "    min_confidence=0.3,  # Minimum confidence to keep\n",
+    "    iou_threshold=0.6,  # IoU threshold for removing overlaps\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Examine the Results"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(f\"Detected {len(crowns)} tree crowns\")\n",
+    "crowns.head()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Visualize Results on Map\n",
+    "\n",
+    "Display the detected tree crowns overlaid on the original image:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "m = leafmap.Map()\n",
+    "m.add_raster(image_path, layer_name=\"Tree Image\")\n",
+    "m.add_vector(\n",
+    "    output_path,\n",
+    "    layer_name=\"Tree Crowns\",\n",
+    "    style={\"color\": \"yellow\", \"fillColor\": \"yellow\", \"fillOpacity\": 0.3, \"weight\": 2},\n",
+    ")\n",
+    "m"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Using a Custom Model\n",
+    "\n",
+    "If you have trained your own model, you can use it instead of the pre-trained models:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Initialize with a custom model\n",
+    "# delineator = TreeCrownDelineator(\n",
+    "#     model_path=\"path/to/your/model.pth\",\n",
+    "#     confidence_threshold=0.5,\n",
+    "# )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Tiling Orthomosaics\n",
+    "\n",
+    "For large orthomosaics, you may want to tile them first before running predictions:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Tile an orthomosaic for prediction\n",
+    "# tiles_dir = tile_orthomosaic(\n",
+    "#     image_path=\"path/to/orthomosaic.tif\",\n",
+    "#     output_dir=\"./tiles\",\n",
+    "#     tile_width=40,\n",
+    "#     tile_height=40,\n",
+    "#     buffer=30,\n",
+    "#     mode=\"rgb\",  # Use 'ms' for multispectral imagery\n",
+    "# )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Preparing Training Data\n",
+    "\n",
+    "If you want to train a custom model, you'll need to prepare your training data with manually delineated crown polygons:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Prepare training and test data\n",
+    "# train_dir, test_dir = prepare_training_data(\n",
+    "#     image_path=\"path/to/orthomosaic.tif\",\n",
+    "#     crowns_path=\"path/to/manual_crowns.gpkg\",\n",
+    "#     output_dir=\"./training_data\",\n",
+    "#     tile_width=40,\n",
+    "#     tile_height=40,\n",
+    "#     buffer=30,\n",
+    "#     threshold=0.6,  # Minimum crown coverage per tile\n",
+    "#     test_fraction=0.15,  # Fraction for testing\n",
+    "# )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Stitching Predictions\n",
+    "\n",
+    "After running predictions on tiles, you can stitch them together:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Stitch tile predictions into a single crown map\n",
+    "# crowns = stitch_predictions(\n",
+    "#     geo_predictions_dir=\"./predictions_geo\",\n",
+    "#     output_path=\"final_crowns.gpkg\",\n",
+    "#     iou_threshold=0.6,\n",
+    "#     min_confidence=0.5,\n",
+    "#     simplify_tolerance=0.3,\n",
+    "# )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Tips for Best Results\n",
+    "\n",
+    "1. **Image Resolution**: detectree2 works best with high-resolution imagery (10cm or better).\n",
+    "\n",
+    "2. **Tile Size**: The default tile size of 40x40 meters works well for most applications. Adjust based on your tree sizes.\n",
+    "\n",
+    "3. **Buffer Size**: A buffer of 30 meters helps handle trees at tile edges.\n",
+    "\n",
+    "4. **Confidence Threshold**: Start with 0.5 and adjust based on your precision/recall needs.\n",
+    "\n",
+    "5. **Training Data**: If training custom models, ensure your manual crowns are:\n",
+    "   - Densely clustered (not scattered)\n",
+    "   - Comprehensively labeled (no missing trees in labeled areas)\n",
+    "   - Accurately delineated\n",
+    "\n",
+    "6. **GPU**: For faster predictions, use a CUDA-enabled GPU."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## References\n",
+    "\n",
+    "- [detectree2 GitHub Repository](https://github.com/PatBall1/detectree2)\n",
+    "- [detectree2 Documentation](https://patball1.github.io/detectree2/)\n",
+    "- [Pre-trained Models (Model Garden)](https://github.com/PatBall1/detectree2/tree/master/model_garden)\n",
+    "- [Sample Data](https://zenodo.org/records/8136161)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "version": "3.11.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

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

@@ -82,6 +82,7 @@ nav:
           - examples/sam3_point_prompts_batch.ipynb
           - examples/sam3_box_prompts.ipynb
           - examples/sam3_tiled_segmentation.ipynb
+          - examples/detectree2.ipynb
     - Workshops:
           - workshops/purdue.ipynb
           - workshops/cn_workshop.ipynb
@@ -96,4 +97,5 @@ nav:
           - fast_sam module: fast_sam.md
           - hq_sam module: hq_sam.md
           - text_sam module: text_sam.md
+          - detectree2 module: detectree2.md
           #   - fer module: fer.md

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

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

segment_geospatial-1.2.3/samgeo/__init__.py

@@ -0,0 +1,23 @@
+"""Top-level package for segment-geospatial."""
+
+__author__ = """Qiusheng Wu"""
+__email__ = "giswqs@gmail.com"
+__version__ = "1.2.3"
+
+
+from .samgeo import *  # noqa: F403
+from .samgeo2 import *  # noqa: F403
+from .samgeo3 import *  # noqa: F403
+
+# Optional detectree2 support for tree crown delineation
+try:
+    from .detectree2 import (
+        TreeCrownDelineator,
+        tile_orthomosaic,
+        prepare_training_data,
+        stitch_predictions,
+        list_pretrained_models,
+        download_sample_data,
+    )
+except ImportError:
+    pass  # detectree2 not installed