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

{segment_geospatial-1.2.1 → 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.1 → 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.10
+      rev: v0.15.2
       hooks:
           - id: ruff
             types_or: [pyi, jupyter]
@@ -29,6 +29,6 @@ repos:
                 ]
 
     - repo: https://github.com/kynan/nbstripout
-      rev: 0.8.2
+      rev: 0.9.1
       hooks:
           - id: nbstripout

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: segment-geospatial
-Version: 1.2.1
-Summary: Meta AI' Segment Anything Model (SAM) for Geospatial Data.
+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
 Project-URL: Homepage, https://github.com/opengeos/segment-geospatial
@@ -146,6 +146,31 @@ SamGeo is also available as a [QGIS plugin](https://github.com/opengeos/qgis-sam
 
 ## Installation
 
+### Install with pixi (Recommended)
+
+For the most reliable installation experience, especially on Windows or when dealing with complex dependencies like PyTorch/CUDA and SAM 3, we recommend using [pixi](https://pixi.prefix.dev/latest). Pixi provides faster and more reliable dependency resolution than conda/mamba and avoids common numpy version conflicts. See the [full pixi installation guide](https://samgeo.gishub.org/installation/#install-with-pixi-recommended) for detailed instructions.
+
+Quick start with pixi:
+
+```bash
+# 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
+```
+
 ### Install from PyPI
 
 **segment-geospatial** is available on [PyPI](https://pypi.org/project/segment-geospatial/) and can be installed in several ways so that its dependencies can be controlled more granularly. This reduces package size for CI environments, since not every time all of the models will be used.
@@ -191,7 +216,7 @@ If your system has a GPU, but the above commands do not install the GPU version
 conda install -c conda-forge segment-geospatial "pytorch=*=cuda*"
 ```
 
-Samgeo-geospatial has some optional dependencies that are not included in the default conda environment. To install these dependencies, run the following command:
+segment-geospatial has some optional dependencies that are not included in the default conda environment. To install these dependencies, run the following command:
 
 ```bash
 conda install -c conda-forge groundingdino-py segment-anything-fast

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

@@ -47,6 +47,31 @@ SamGeo is also available as a [QGIS plugin](https://github.com/opengeos/qgis-sam
 
 ## Installation
 
+### Install with pixi (Recommended)
+
+For the most reliable installation experience, especially on Windows or when dealing with complex dependencies like PyTorch/CUDA and SAM 3, we recommend using [pixi](https://pixi.prefix.dev/latest). Pixi provides faster and more reliable dependency resolution than conda/mamba and avoids common numpy version conflicts. See the [full pixi installation guide](https://samgeo.gishub.org/installation/#install-with-pixi-recommended) for detailed instructions.
+
+Quick start with pixi:
+
+```bash
+# 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
+```
+
 ### Install from PyPI
 
 **segment-geospatial** is available on [PyPI](https://pypi.org/project/segment-geospatial/) and can be installed in several ways so that its dependencies can be controlled more granularly. This reduces package size for CI environments, since not every time all of the models will be used.
@@ -92,7 +117,7 @@ If your system has a GPU, but the above commands do not install the GPU version
 conda install -c conda-forge segment-geospatial "pytorch=*=cuda*"
 ```
 
-Samgeo-geospatial has some optional dependencies that are not included in the default conda environment. To install these dependencies, run the following command:
+segment-geospatial has some optional dependencies that are not included in the default conda environment. To install these dependencies, run the following command:
 
 ```bash
 conda install -c conda-forge groundingdino-py segment-anything-fast

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.3/docs/faq.md

@@ -0,0 +1,48 @@
+# Frequently Asked Questions (FAQ)
+
+## Coordinate Reference Systems (CRS)
+
+### Does samgeo automatically convert my imagery to EPSG:4326?
+
+**No.** samgeo does **NOT** automatically reproject or convert your GeoTIFF files to EPSG:4326. Your imagery stays in its native coordinate system throughout the entire segmentation process.
+
+**Key points:**
+- When you load a GeoTIFF with `set_image()` or use `generate_masks_tiled()`, the image data is read directly without any CRS transformation
+- The output masks inherit the same CRS as your input imagery
+- The `reproject()` function in `samgeo.common` has EPSG:4326 as a default parameter, but it's **only used when you explicitly call that function** - it is NOT called automatically during segmentation
+
+**Why might you see distortion?**
+1. Your visualization tool is displaying the results in EPSG:4326 (like some web map libraries)
+2. You're manually calling the `reproject()` function somewhere in your workflow
+3. Your original imagery already has CRS-related issues
+
+**Recommendation:**
+- Verify your input TIF has the correct CRS metadata using `gdalinfo` or rasterio (`src.crs`)
+- The output masks will preserve the same CRS as your input
+- If you need to reproject for visualization, do it as a separate step AFTER segmentation:
+  ```python
+  from samgeo import common
+  common.reproject("input_masks.tif", "output_epsg4326.tif", dst_crs="EPSG:4326")
+  ```
+
+### How can I check the CRS of my GeoTIFF?
+
+Using GDAL:
+```bash
+gdalinfo your_file.tif
+```
+
+Using Python with rasterio:
+```python
+import rasterio
+with rasterio.open("your_file.tif") as src:
+    print(f"CRS: {src.crs}")
+```
+
+### My imagery looks distorted during segmentation
+
+The segmentation algorithm works on pixel values, not geographic coordinates, so CRS should not affect segmentation quality. If you're seeing distortion:
+
+1. **Check if it's a visualization issue:** The distortion might only appear when viewing results in a different CRS
+2. **Verify your input data:** Use `gdalinfo` to check if the CRS metadata is correct
+3. **Try reprojecting to a more suitable CRS:** Some projections preserve shape better than others for specific regions (e.g., UTM for local areas)