PyMatting

1.1.15 · active · verified Sat Apr 11

PyMatting is a Python library for alpha matting, a fundamental technique in image processing and computer vision used to accurately extract foreground objects from images. It offers various implementations for alpha matting and foreground estimation methods, leveraging CPU, CUDA, and OpenCL for performance. The current version is 1.1.15, with active development leading to periodic releases for bug fixes and feature enhancements.

Warnings

gotcha The first time PyMatting functions are imported or called, there might be a significant delay due to Numba's Just-In-Time (JIT) compilation. Subsequent calls will be much faster.
Fix: Be aware of this initial delay, especially in performance-critical applications or interactive environments. There is no direct fix for the initial compilation, but it's a one-time overhead per session.
gotcha Trimaps must be provided as NumPy arrays of type `np.float64` where values are 0.0 (background), 1.0 (foreground), or anything in between (unknown region). Incorrect data types or value ranges can lead to unexpected results or errors.
Fix: Ensure your trimap images are loaded and converted to `numpy.ndarray` with `dtype=np.float64`. Normalize background pixels to 0.0 and foreground pixels to 1.0.
gotcha GPU acceleration for PyMatting currently only supports 'foreground estimation' methods (e.g., `estimate_foreground_ml_cupy`, `estimate_foreground_ml_pyopencl`), not 'alpha estimation'. Additionally, specific GPU-compatible libraries (CuPy, PyOpenCL) and their respective drivers must be installed separately.
Fix: If GPU acceleration is critical for alpha estimation, consider alternative libraries or CPU-based methods within PyMatting. For foreground estimation, ensure you install `cupy` or `pyopencl` and relevant GPU drivers, then use the specific GPU-enabled functions.
deprecated Prior to version 1.1.11, PyMatting used `np.bool8`. This has been replaced with `np.bool_` to align with newer NumPy conventions. While direct impact on user code might be minimal, it could cause issues if interacting with internal PyMatting types using `np.bool8` in older environments with newer NumPy.
Fix: Upgrade to PyMatting version 1.1.11 or newer. If you are handling boolean NumPy arrays, prefer `np.bool_` for compatibility.

Install

pip install pymatting Install PyMatting

Imports

cutout
```
from pymatting import cutout
```
The primary function for simple, end-to-end alpha matting and foreground extraction.
estimate_alpha_cf
```
from pymatting import estimate_alpha_cf
```
One of several specific alpha estimation methods, often imported directly from the top-level package or 'pymatting.alpha'.
estimate_foreground_ml
```
from pymatting import estimate_foreground_ml
```
One of several specific foreground estimation methods, often imported directly from the top-level package or 'pymatting.foreground'.

Quickstart

This quickstart demonstrates the simplest way to use PyMatting: the `cutout` function. It takes an input image and a trimap, then generates a new image with the foreground extracted. The example includes creating dummy image and trimap files for immediate runnable demonstration. In a real-world scenario, you would replace these with paths to your actual image and trimap files.

import numpy as np
from PIL import Image
from pymatting import cutout
import os

# Create dummy image and trimap files for demonstration
def create_dummy_image(path, size=(64, 64), color=(255, 0, 0)):
    img = Image.new('RGB', size, color)
    img.save(path)

def create_dummy_trimap(path, size=(64, 64)):
    # A simple trimap: top-left foreground (1.0), bottom-right background (0.0), middle unknown (0.5)
    trimap_data = np.zeros(size, dtype=np.float64)
    trimap_data[:size[0]//2, :size[1]//2] = 1.0 # Foreground
    trimap_data[size[0]//2:, size[1]//2:] = 0.0 # Background
    trimap_data[size[0]//4:size[0]*3//4, size[1]//4:size[1]*3//4] = 0.5 # Unknown
    
    # Convert to PIL image and save (e.g., as grayscale PNG)
    trimap_img = Image.fromarray((trimap_data * 255).astype(np.uint8), mode='L')
    trimap_img.save(path)

input_image_path = "dummy_input.png"
input_trimap_path = "dummy_trimap.png"
output_cutout_path = "dummy_cutout.png"

create_dummy_image(input_image_path, color=(100, 150, 200))
create_dummy_trimap(input_trimap_path)

print(f"Processing image: {input_image_path} with trimap: {input_trimap_path}")

try:
    # Perform the cutout operation
    # Note: The first import/call might be slow due to Numba compilation
    cutout(
        input_image_path,
        input_trimap_path,
        output_cutout_path
    )
    print(f"Cutout saved to: {output_cutout_path}")
except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up dummy files
    if os.path.exists(input_image_path):
        os.remove(input_image_path)
    if os.path.exists(input_trimap_path):
        os.remove(input_trimap_path)
    # Keep output_cutout_path for verification if successful
    # if os.path.exists(output_cutout_path):
    #     os.remove(output_cutout_path)

view raw JSON →