Metadata-Version: 2.4
Name: orthomasker
Version: 0.9.4
Summary: A CLI tool and Python library for extracting vector features from geospatial raster (TIF) files using the Segment Anything Model (SAM), and exporting them as GeoJSON.
Author-email: Nicholas McCarty <nick@upskilled.consulting>
License: Apache-2.0
Project-URL: Homepage, https://github.com/nickmccarty/orthomasker
Project-URL: Repository, https://github.com/nickmccarty/orthomasker
Project-URL: Issues, https://github.com/nickmccarty/orthomasker/issues
Keywords: gis,geojson,tif,mask,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: GDAL>=3.8.0
Requires-Dist: geopandas>=1.0.0
Requires-Dist: matplotlib>=3.10.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: opencv-contrib-python>=4.11.0
Requires-Dist: opencv-python>=4.11.0
Requires-Dist: opencv-python-headless>=4.11.0
Requires-Dist: pandas>=2.2.0
Requires-Dist: pillow>=11.2.0
Requires-Dist: rasterio>=1.4.0
Requires-Dist: shapely>=2.1.0
Requires-Dist: geojson>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: openpyxl>=3.1.0; extra == "dev"
Provides-Extra: ml
Requires-Dist: torch; extra == "ml"
Requires-Dist: segment-anything-py; extra == "ml"
Dynamic: license-file

# Raster Feature Extractor

A CLI tool and Python library for extracting vector features from geospatial raster (TIF) files using the Segment Anything Model (SAM), and exporting them as GeoJSON.

## Installation

```bash
pip install orthomasker
```

## Usage

```bash
# Using CLI
orthomasker your_input_filename.tif your_output_filename.geojson

# Using Python
from orthomasker.feature_extractor import RasterFeatureExtractor

# Provide your own test TIF file (upload or use a sample)
input_tif = "your_input_filename.tif"
output_geojson = "your_output_filename.geojson"

# Set up the extractor (use the path to your .pth file)
extractor = RasterFeatureExtractor()

extractor.convert(input_tif, output_geojson)
```

### Options

- `--sam-checkpoint`: Path to SAM model weights (default: sam_vit_h_4b8939.pth)

- `--model-type`: SAM model type (`vit_h`, `vit_l`, `vit_b`; default: vit_h)

- `--confidence-threshold`: Minimum stability score to keep a mask (0–100; default: 0, no filter)

- `--tile-size`: Tile size for processing (default: 1024)

- `--overlap`: Tile overlap in pixels (default: 128)

- `--class-name`: Class label for output features (default: sam_object)

- `--min-area`: Minimum area (in square units of TIF CRS) for output features (optional)

- `--max-area`: Maximum area (in square units of TIF CRS) for output features (optional)

- `--compactness`: Minimum compactness threshold (0.0–1.0) using Polsby-Popper metric for filtering irregular shapes (optional)

- `--fixed-bounds`: Bounding box (minx, miny, maxx, maxy) in image CRS

- `--merge`: Merge overlapping polygons in output (optional)

- `--verbose`: Enable verbose output

## Compactness Filtering

The `--compactness` option allows you to filter out irregular or elongated shapes by setting a minimum compactness threshold. This uses the Polsby-Popper compactness metric:
<br>
<br>
`Compactness = (4π × Area) / (Perimeter²)`

- Perfect circle: compactness = 1.0
- Square: compactness ≈ 0.785
- Elongated shapes: compactness approaches 0.0

Common threshold values:

- 0.1: Very permissive (removes only extremely irregular shapes)
- 0.3: Moderate filtering (removes highly irregular shapes)
- 0.6: Strict filtering (keeps only relatively compact shapes)
- 0.8: Very strict (keeps only very round/square shapes)

## Development

### Setup

```bash
git clone https://github.com/nickmccarty/orthomasker.git
cd orthomasker
pip install -r requirements.txt
pip install -e ".[ml,dev]"
```

## Acknowledgments

This project leverages [Meta AI’s Segment Anything Model (SAM)](https://github.com/facebookresearch/segment-anything) for automatic mask generation, which is faciliated by utilizing [`segment-anything-py`](https://pypi.org/project/segment-anything-py/) as a dependency; many thanks to  Qiusheng Wu, et al. for their work!

## Citations

```
@article{kirillov2023segany,
title={Segment Anything},
author={Kirillov, Alexander and Mintun, Eric and Ravi, Nikhila and Mao, Hanzi and Rolland, Chloe and Gustafson, Laura and Xiao, Tete and Whitehead, Spencer and Berg, Alexander C. and Lo, Wan-Yen and Doll{'a}r, Piotr and Girshick, Ross},
journal={arXiv:2304.02643},
year={2023}
}
```

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
