Metadata-Version: 2.4
Name: obia
Version: 0.1.4
Summary: A Python package for object-based image analysis with multimodal data sources
Author-email: Joseph Emile Honour Percival <ipercival@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/iosefa/obia
Project-URL: Repository, https://github.com/iosefa/obia
Project-URL: Issues, https://github.com/iosefa/obia/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.1.1
Requires-Dist: rasterio>=1.3.11
Requires-Dist: shapely>=2.0.3
Requires-Dist: pillow>=10.3.0
Requires-Dist: pandas>=2.2.2
Requires-Dist: geopandas>=1.0.1
Requires-Dist: scipy>=1.14.1
Requires-Dist: scikit-image>=0.23.2
Requires-Dist: tqdm>=4.66.2
Requires-Dist: scikit-learn>=1.4.2
Requires-Dist: affine>=2.4.0
Requires-Dist: pyproj>=3.6.1
Requires-Dist: opencv-python>=4.10
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
Requires-Dist: mkdocs-jupyter>=0.24; extra == "docs"
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2; extra == "docs"
Provides-Extra: detection
Requires-Dist: torch>=2.3; extra == "detection"
Requires-Dist: torchvision>=0.18; extra == "detection"
Requires-Dist: albumentations>=1.4; extra == "detection"
Requires-Dist: matplotlib>=3.8; extra == "detection"
Provides-Extra: pointcloud
Requires-Dist: pdal; extra == "pointcloud"
Requires-Dist: pyforestscan; extra == "pointcloud"
Provides-Extra: explain
Requires-Dist: shap>=0.46.0; extra == "explain"
Provides-Extra: test
Requires-Dist: pytest>=7.4; extra == "test"
Dynamic: license-file

# OBIA

[![PyPI](https://img.shields.io/pypi/v/obia.svg)](https://pypi.org/project/obia/)
[![PyPI Downloads](https://static.pepy.tech/badge/obia)](https://pepy.tech/projects/obia)
[![Docker Pulls](https://img.shields.io/docker/pulls/iosefa/obia?logo=docker&label=pulls)](https://hub.docker.com/r/iosefa/obia)
[![Tests](https://img.shields.io/github/actions/workflow/status/iosefa/obia/tests.yml?branch=main&label=tests)](https://github.com/iosefa/obia/actions/workflows/tests.yml)
[![Docs](https://img.shields.io/github/actions/workflow/status/iosefa/obia/docs.yml?branch=main&label=docs)](https://github.com/iosefa/obia/actions/workflows/docs.yml)
[![Contributors](https://img.shields.io/github/contributors/iosefa/obia.svg?label=contributors)](https://github.com/iosefa/obia/graphs/contributors)
[![License](https://img.shields.io/github/license/iosefa/obia)](https://github.com/iosefa/obia/blob/main/LICENSE)

Object-based image analysis tools for geospatial rasters.

OBIA groups raster pixels into spatial objects, calculates object-level features, and supports downstream segment classification. The main output is a GeoDataFrame or GeoPackage of segment polygons with feature columns, optional point-cloud metrics, and predicted classes.

Current scope:

- GeoTIFF loading with Rasterio metadata preserved
- SLIC and quickshift segmentation
- segment-level spectral and texture features
- optional point-cloud features joined to the same segment objects
- point-to-segment labelling utilities
- random forest and MLP segment classification
- tiled SLIC utilities for large rasters
- experimental RetinaNet-based detection modules

## Install

### From PyPI

```bash
pip install obia
```

### Point-cloud support

Point-cloud workflows need PDAL. Install PDAL with conda-forge first, then install OBIA with `pip` inside that environment:

```bash
conda create -n obia-pointcloud -c conda-forge python=3.11 pdal python-pdal
conda activate obia-pointcloud
pip install obia
```

### Docker

Build the image from the repository root:

```bash
docker build -t obia .
```

Release images are published to Docker Hub as `iosefa/obia`:

```bash
docker pull iosefa/obia:latest
```

The image includes OBIA, PDAL, the PDAL Python bindings, and `pyforestscan`.

### Developer install

```bash
git clone https://github.com/iosefa/obia.git
cd obia
conda env create -f environment.yml
conda activate obia
```

The development environment installs the package in editable mode with documentation and optional workflow dependencies.

## Basic Segmentation

```python
from obia.handlers.geotif import open_geotiff
from obia.segmentation.segment import segment

image = open_geotiff("/path/to/image.tif")

objects = segment(
    image,
    segmentation_bands=[0, 1, 2],
    statistics_bands=[0, 1, 2, 3],
    method="slic",
    n_segments=3000,
    compactness=10,
)

segments = objects.segments
segments.to_file("segments.gpkg", driver="GPKG")
```

## Point-Cloud Features

```python
from obia.pointcloud import add_pointcloud_features

segments = add_pointcloud_features(
    segments,
    pointcloud="/path/to/points.laz",
    metrics=["height", "intensity", "density"],
)
```

Point-cloud features are appended as `pc_*` columns, so the enriched segment table can be labelled and classified with the raster-derived features.

## Segment Classification

```python
import geopandas as gpd

from obia.classification.classify import classify
from obia.utils.utils import label_segments

labelled_points = gpd.read_file("/path/to/labelled_points.gpkg")
training_segments, mixed_segments = label_segments(
    segments,
    labelled_points,
)

result = classify(
    segments,
    training_segments,
    method="rf",
    n_estimators=300,
    random_state=42,
)

result.classified.to_file("classified_segments.gpkg", driver="GPKG")
```

## Documentation

Published documentation is available at `https://obia.sefa.ai`.

Preview the docs locally:

```bash
mkdocs serve
```

Open `http://127.0.0.1:8000`. If the port is already in use:

```bash
mkdocs serve -a 127.0.0.1:8001
```

Documentation source lives in `docs/`.

## License

MIT (`LICENSE`)
