---
layout: page
title: SAP
description: Python package to compute morphological hierarchies of images and more. 
img: /assets/img/sap.svg
importance: 1
category: thesis
---

SAP (for Simple Attribute Profiles) is a Python package to easily
compute *attribute profiles* of images. I have developed this package as
part of my PhD thesis.

The source code is available on [github][git]. I used this project to
experiments CI/CD with gitlab pipelines (the project was initially
hosted on the INRIA's gitlab) and lately with Github [actions].
[Testing][test], [code coverage][cover], release publishing on
[PyPI][pypi] and [online documentation][doc] are all automatically
updated.

[git]: https://github.com/fguiotte/sap
[doc]: https://python-sap.rtfd.io
[actions]: https://github.com/fguiotte/sap/actions
[pypi]: https://pypi.org/project/sap/
[test]: https://github.com/fguiotte/sap/tree/master/test
[cover]: https://app.codecov.io/gh/fguiotte/sap/tree/master/sap


## Installation 

To start tinkering images with the package, you just have to:

```bash
pip install sap
```

## Quick start

A small Python snippet to get you started quickly:

```python
import sap
import numpy as np
import matplotlib.pyplot as plt

image = np.random.random((512, 512))

t = sap.MaxTree(image)
area = t.get_attribute('area')
filtered_image = t.reconstruct(area < 100)

plt.imshow(filtered_image)
plt.show()
```

## Slower launch 

This package is a combination of three submodules.

### Trees

The first submodule `sap.trees` is to build trees from images, to compute
attributes, and to filter them.

For example, we can build the max-tree of an image, compute the area
attributes of the nodes and reconstruct a filtered image removing nodes
with area less than 100 pixels:

```python
t = sap.MaxTree(image)
area = t.get_attribute('area')
filtered_image = t.reconstruct(area < 100)
```



### Profiles

The second submodule `sap.profiles` is provided to compute *Attribute
Profiles* (and other profiles) of images. The submodule contains the
utils to easily concatenate the profiles (*Extended Attribute Profiles*)
and to display them.

```python
import imageio.v3 as iio # Reads and writes images
import sap

image = iio.imread('image.png')

ap = sap.attribute_profiles(image, {'area': [100, 1000]})
sap.show_profiles(ap)
```

![Attribute profiles stacks connected component filtering of images (opening and closing) at several scales.](/assets/img/ap_area.png){.img-fluid .rounded .z-depth-1}

### Spectra

The third submodule is `sap.spectra`. We use it to compute Pattern
Spectra of trees and to display them. Pattern Spectra can be useful to
set thresholds of attribute filters and Attribute Profiles.


```python
import rasterio as rio # Reads and writes geospatial raster data
from matplotlib import pyplot as plt # Display plots and images
import sap

dsm = rio.open('dsm.tif').read()[0]

max_tree = sap.MaxTree(dsm)

plt.imshow(max_tree.reconstruct())
plt.show()
```

![](/assets/img/sap_1.png){.img-fluid .z-depth-1 .rounded}

```python
ps = sap.spectrum2d(max_tree, 'area', 'compactness', x_log=True)

sap.show_spectrum(*ps)

plt.xlabel('area')
plt.ylabel('compactness')
plt.colorbar()
plt.title('SAP 2D spectrum')

plt.show()
```

![](/assets/img/sap_2.png){.img-fluid .z-depth-1 .rounded}


To go further, please have a look to the [online documentation][doc-api].


This package has been used, amongst other projects, to perform an
experimental comparison of the attribute profiles and their variations
in a published paper [^1].

[doc-api]: https://python-sap.readthedocs.io/en/master/source/sap.html

[^1]: Deise Santana Maia, Minh-Tan Pham, Erchan Aptoula, Florent
  Guiotte, et Sébastien Lefèvre, « *Classification of Remote Sensing
  Data With Morphological Attribute Profiles: A decade of advances* »,
  GRSM, vol. 9, nᵒ 3, p. 43‑71, sept. 2021, doi:
  [10.1109/MGRS.2021.3051859](https://doi.org/10.1109/MGRS.2021.3051859).