fill-voids

2.1.2 verified Fri May 01 auth: no python

Fill voids (holes) in 3D binary images (numpy arrays) using a flood-fill algorithm. Fast and memory-efficient algorithm for hole filling in labeled or binary volumes. Current version 2.1.2, released Oct 2024. Releases are occasional, with breaking changes in the past (e.g., v2.0).

pip install fill-voids

Common errors

error ModuleNotFoundError: No module named 'fill_voids' ↓

cause The package is not installed or is installed in a different environment.

fix

Run 'pip install fill-voids'. If using a virtual environment, ensure it is activated.

error ImportError: cannot import name 'fill' from 'fill_voids' ↓

cause In fill-voids v2.0+, the function was renamed from 'fill' to 'fill_voids'.

fix

Change import to 'from fill_voids import fill_voids' and call fill_voids().

error ValueError: Input array must be 3D ↓

cause fill_voids expects a 3D numpy array (height, width, depth). 2D or other dimensions cause this error.

fix

Reshape your 2D data to 3D by adding an axis: image = image[np.newaxis, ...] (or using np.expand_dims).

error AttributeError: module 'fill_voids' has no attribute 'fill_multichannel' ↓

cause fill_multichannel is available only in v2.1+ and must be imported separately.

fix

Ensure you have v2.1+ installed (pip install --upgrade fill-voids) and import it: from fill_voids import fill_multichannel.

Warnings

breaking In v2.0, the main function was renamed from 'fill' to 'fill_voids'. Code using 'from fill_voids import fill' will break. ↓

fix Update import to 'from fill_voids import fill_voids' and call fill_voids() instead of fill().

breaking In v2.0, the library no longer accepts 2D arrays by default. Use fill_voids with 3D or upgrade to handle 2D via a workaround (e.g., add a dummy axis). ↓

fix Ensure input is 3D (shape (Z, Y, X)). For 2D, reshape: image_3d = image[np.newaxis, ...]; then fill; then squeeze.

gotcha fill_voids fills fully enclosed background regions only. It does not fill holes touching the image border by default. ↓

fix Pad the array with a border of foreground voxels before filling, or use the 'in_place' argument if available.

gotcha The function modifies the input array in place if in_place=True (default False). Setting in_place=True can save memory but alters the original array. ↓

fix Use in_place=False (default) to preserve input; copy the array first if needed.

Install

pip install fill-voids[all]

Imports

fill_voids

wrong

from fill_voids import fill

correct

from fill_voids import fill_voids

Function name is fill_voids, not fill.

fill_multichannel

wrong

fill_voids.fill_multichannel (wrong if not imported)

correct

from fill_voids import fill_multichannel

Must import explicitly or use module prefix.

Quickstart

Fills holes in a 3D binary numpy array.

import numpy as np
from fill_voids import fill_voids

# Create a binary volume with a hole
image = np.ones((5,5,5), dtype=bool)
image[2:4, 2:4, 2:4] = False  # hole

# Fill the hole
filled = fill_voids(image)
print(filled.all())  # Should be True