MultiClean is a Python library for morphological cleaning of multiclass 2D numpy arrays (segmentation masks and classification rasters). It provides efficient tools for edge smoothing and small-island removal across multiple classes, then fills gaps using the nearest valid class.

Visual Example

Below: Land Use before/after cleaning (smoothed edges, small-island removal, nearest-class gap fill).

Installation

pip install multiclean

or

uv add multiclean

or

conda install -c conda-forge multiclean

Quick Start

importnumpyasnpfrommulticleanimportclean_array# Create a sample classification array with classes 0, 1, 2, 3array=np.random.randint(0, 4, (1000, 1000), dtype=np.int32)
# Clean with default parameterscleaned=clean_array(array)
# Custom parameterscleaned=clean_array(
array,
class_values=[0, 1, 2, 3],
smooth_edge_size=2, # kernel width, larger value increases smoothnessmin_island_size=100, # remove components with area < 100connectivity=8, # 4 or 8max_workers=4,
fill_nan=False# enable/disable the filling of nan values in input array
)

Use Cases

MultiClean is designed for cleaning segmentation outputs from:

• Remote sensing: Land cover classification, crop mapping
• Computer vision: Semantic segmentation post-processing
• Geospatial analysis: Raster classification cleaning
• Machine learning: Neural network output refinement

Key Features

• Multi-class processing: Clean all classes in one pass
• Edge smoothing: Morphological opening to reduce jagged boundaries
• Island removal: Remove small connected components per class
• Gap filling: Fill invalids via nearest valid class (distance transform)
• Fast: NumPy + OpenCV with parallelism

How It Works

MultiClean uses morphological operations to clean classification arrays:

1. Edge smoothing (per class): Morphological opening with a circular kernel.
2. Island removal (per class): Find connected components (OpenCV) and mark components with area < min_island_size as invalid.
3. Gap filling: Compute a distance transform to copy the nearest valid class into invalid pixels.

Classes are processed together and the result maintains a valid label at every pixel.

API Reference

clean_array

frommulticleanimportclean_arrayout=clean_array(
array: np.ndarray,
class_values: int|list[int] |None=None,
smooth_edge_size: int=2,
min_island_size: int=100,
connectivity: int=4,
max_workers: int|None=None,
fill_nan: bool=False
)

• array: 2D numpy array of class labels (int or float). For float arrays, NaN is treated as nodata and will remain NaN unless fill_nan is set to True.
• class_values: Classes to consider. If None, inferred from array (ignores NaN for floats). An int restricts cleaning to a single class.
• smooth_edge_size: Kernel size (pixels) for morphological opening. Use 0 to disable.
• min_island_size: Remove components with area strictly < min_island_size. Use 1 to keep single pixels.
• connectivity: Pixel connectivity for components, 4 or 8.
• max_workers: Parallelism for per-class operations (None lets the executor choose).
• fill_nan: If True will fill NAN values from input array with nearest valid value.

Returns a numpy array matching the input shape and dtype. Float arrays with NaN are supported and can be filled or remain as NaN.

Examples

Cleaning Land Cover Data

frommulticleanimportclean_arrayimportrasterio# Read land cover classificationwithrasterio.open('landcover.tif') assrc:
landcover=src.read(1)
# Clean with appropriate parameters for satellite datacleaned=clean_array(
landcover,
class_values=[0, 1, 2, 3, 4], # forest, water, urban, crop, othersmooth_edge_size=1,
min_island_size=25,
connectivity=8,
fill_nan=False
)

Cleaning Neural Network Segmentation Output

frommulticleanimportclean_array# Model produces logits; convert to class predictionsnp_pred=np_model_logits.argmax(axis=0) # shape: (H, W)# Clean the segmentationcleaned=clean_array(
np_pred,
smooth_edge_size=2,
min_island_size=100,
connectivity=4,
)

Notebooks

See the notebooks folder for end-to-end examples:

• Land Use Example Notebook: land use classification cleaning
• Cloud Example Notebook: cloud/shadow classification cleaning

Try in Colab

Changelog

Release notes and the full version history are kept in CHANGELOG.md.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Maintainers: see RELEASING.md for how to cut a release.

License

This project is licensed under the MIT License - see the LICENSE file for details.