We introduce the PyMatting package for Python which implements various methods to solve the alpha matting problem.

Given an input image and a hand-drawn trimap (top row), alpha matting estimates the alpha channel of a foreground object which can then be composed onto a different background (bottom row).

PyMatting provides:

  • Alpha matting implementations for:
    • Closed Form Alpha Matting [1]
    • Large Kernel Matting [2]
    • KNN Matting [3]
    • Learning Based Digital Matting [4]
    • Random Walk Matting [5]
  • Foreground estimation implementations for:
    • Closed Form Foreground Estimation [1]
    • Fast Multi-Level Foreground Estimation (CPU, CUDA and OpenCL) [6]
  • Fast multithreaded KNN search
  • Preconditioners to accelerate the convergence rate of conjugate gradient descent:
    • The incomplete thresholded Cholesky decomposition (Incomplete is part of the name. The implementation is quite complete.)
    • The V-Cycle Geometric Multigrid preconditioner
  • Readable code leveraging NumPy, SciPy and Numba

Getting Started


Minimal requiremens

  • numpy>=1.16.0
  • pillow>=5.2.0
  • numba>=0.47.0
  • scipy>=1.1.0

Additional requirements for GPU support

  • cupy-cuda90>=6.5.0 or similar
  • pyopencl>=2019.1.2

Requirements to run the tests

  • pytest>=5.3.4

Installation with PyPI

pip3 install pymatting

Installation from Source

git clone
cd pymatting
pip3 install .


from pymatting import cutout

    # input image path
    # input trimap path
    # output cutout path

More advanced examples

Trimap Construction

All implemented methods rely on trimaps which roughly classify the image into foreground, background and unknown reagions.
Trimaps are expected to be numpy.ndarrays of type np.float64 having the same shape as the input image with only one color-channel.
Trimap values of 0.0 denote pixels which are 100% background.
Similarly, trimap values of 1.0 denote pixels which are 100% foreground.
All other values indicate unknown pixels which will be estimated by the algorithm.


Run the tests from the main directory:

 python3 tests/
 pip3 install -r requirements_tests.txt

Currently 89% of the code is covered by tests.


pip3 install --upgrade pymatting
python3 -c "import pymatting"

The last line is necessary to rebuild the ahead-of-time compiled module. Without it, the module will be rebuilt on first import, but the old module will already be loaded at that point, which might cause compatibility issues. Simply re-running the code should usually fix it.

Bug Reports, Questions and Pull-Requests

Please, see our community guidelines.


  • Thomas Germer
  • Tobias Uelwer
  • Stefan Conrad
  • Stefan Harmeling

See also the list of contributors who participated in this project.