Morphology (MSPA)#

Morphological Spatial Pattern Analysis (MSPA) is a multi-scale image processing approach that classifies the pixels of a binary foreground/background image into mutually exclusive morphological classes based on their spatial context. Further details about MSPA are available in the MSPA product sheet.

MSPA Classes#

MSPA classifies foreground pixels into up to 22 foreground classes (11 internal + 11 external) and 3 background classes. Results are aggregated into 7 foreground feature classes (Core, Islet, Perforation, Edge, Loop, Bridge, Branch) and 3 background feature classes (Background, Border-Opening, Core-Opening).

Class names, color codes, and byte values for MSPA feature classes.#
Class	Color	RGB	Pxl value External	Pxl value Internal
Core	Green	000/200/000	17	117
Islet	Brown	160/060/000	9	109
Perforation	Blue	000/000/255	5	105
Edge	Black	000/000/000	3	103
Loop	Yellow	255/255/000	65	165
Loop in Edge	Yellow	255/255/000	67	167
Loop in Perforation	Yellow	255/255/000	69	169
Bridge	Red	255/000/000	33	133
Bridge in Edge	Red	255/000/000	35	135
Bridge in Perforation	Red	255/000/000	37	137
Branch	Orange	255/140/000	1	101
Background	Light Grey	220/220/220	0	0
Border-Opening	Grey	194/194/194	N/A	220
Core-Opening	Dark Grey	136/136/136	N/A	100
No Data	White	255/255/255	129	129

MSPA classes — Map and list of the 7 aggregated feature classes of MSPA.#

Usage#

import pyguidos as pg

result = pg.mspa(
    in_tiff="my_map.tif",
    edge_width=1,
    connectivity=8,
    transition=True,
    int_ext=True,
    outdir="output/",
    statists=True,
    stat_files=True,
    return_array=False,
    verb=False
)

Parameters#

Parameter	Type	Default	Description
`in_tiff`	str or Path	–	Path to input GeoTIFF
`edge_width`	int	–	Edge width in pixels, >= 1
`connectivity`	int	8	Pixel connectivity, 4 or 8
`transition`	bool	True	Enable transition zones
`int_ext`	bool	True	Distinguish internal/external subclasses
`outdir`	str or Path	None	Output directory
`statists`	bool	True	Compute statistics
`stat_files`	bool	True	Write statistics to files
`return_array`	bool	False	Return output array
`verb`	bool	False	Print progress messages

Output Files#

File	Description
`<name>_mspa_<conn>_<ew>_<tr>_<ie>.tif`	MSPA result GeoTIFF with colour palette
`<name>_mspa_<conn>_<ew>_<tr>_<ie>.txt`	Statistics report

Result Object#

mspa() returns an MSPAResult dataclass:

result = pg.mspa("my_map.tif", edge_width=1)

# Access statistics
print(result.stats.keys())
# dict_keys(['output paths', 'input stats', 'output stats'])

# Input pixel counts
print(result.stats["input stats"])
# {'foreground pxl': 12500, 'background pxl': 37500, 'missing pxl': 0}

# Per-class pixel counts
print(result.stats["output stats"])
# {'core pxl': 8200, 'edge pxl': 2100, 'perforation pxl': 500, ...}

# Output file paths
print(result.stats["output paths"])
# {'path tif': 'output/my_map_mspa_8_1_1_1.tif',
#  'path txt': 'output/my_map_mspa_8_1_1_1.txt'}

# Access array (only if return_array=True)
print(result.array)

Note

result.stats["output paths"] is None when stat_files=False. All other keys are always populated regardless of stat_files.

Computing Statistics Separately#

If you already have an MSPA output GeoTIFF, you can compute statistics without rerunning the analysis:

stats = pg.mspa_stats(
    mspa_tiff="output/my_map_mspa_8_1_1_1.tif",
    outfile=True,
    outdir="output/",
    source_tiff="my_map.tif"
)

Note

mspa_stats() requires the input GeoTIFF to be an pyGuidos (or GTB) output raster file. See Input Format for details.

References#

Vogt P, Riitters K, 2017. GuidosToolbox: universal digital image object analysis. European Journal of Remote Sensing 50(1), 352-361. DOI: 10.1080/22797254.2017.1330650.
Soille P, Vogt P, 2009. Morphological segmentation of binary patterns. Pattern Recognition Letters 30(4):456-459. DOI: 10.1016/j.patrec.2008.10.015