142 lines
3.8 KiB
Markdown
142 lines
3.8 KiB
Markdown
---
|
||
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)
|
||
```
|
||
|
||
{.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()
|
||
```
|
||
|
||
{.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()
|
||
```
|
||
|
||
{.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).
|