pymatting 1.1.15: lbdm_laplacian

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pymatting.lbdm_laplacian in pkg:pypi/pymatting@1.1.15
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/pymatting@1.1.15
Demonstrate these symbols/APIs:
  - pymatting.lbdm_laplacian

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:0de7da82b820ed4ec168eb7836e0c47912204b0b9605b858a57b8358a257a61d","contract":["assert lbdm_laplacian computes sparse CSR matting Laplacian matrix with shape (h*w, h*w) for RGB image","assert lbdm_laplacian matrix satisfies Laplacian zero row-sum property across all rows","assert lbdm_laplacian accepts custom regularization parameter epsilon and neighborhood window radius","assert lbdm_laplacian enables alpha matte estimation satisfying trimap boundary constraints"],"goal":"verify pymatting.lbdm_laplacian in pkg:pypi/pymatting@1.1.15","kind":"HOW","packages":["pkg:pypi/pymatting@1.1.15"],"schemaVersion":1,"symbols":["pymatting.lbdm_laplacian"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"pypi","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"pip","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/pymatting@1.1.15"],"schemaVersion":1,"subject":"pkg:pypi/pymatting@1.1.15","symbols":["pymatting.lbdm_laplacian"],"verifierAdapter":"python@1"}

[project]
name = "verify-pymatting-lbdm"
version = "0.1.0"
dependencies = [
    "pymatting==1.1.15",
    "numpy",
    "scipy",
    "pillow",
]

pymatting==1.1.15
numpy
scipy
pillow

"""Demonstration of Learning-Based Digital Matting (LBDM) Laplacian using pymatting.lbdm_laplacian."""

import numpy as np
import scipy.sparse
from pymatting import lbdm_laplacian, make_linear_system, cg, ichol


def compute_lbdm_laplacian(
    image: np.ndarray,
    epsilon: float = 1e-7,
    radius: int = 1,
) -> scipy.sparse.csr_matrix:
    """Compute the Learning-Based Digital Matting Laplacian matrix for an RGB image."""
    return lbdm_laplacian(image, epsilon=epsilon, radius=radius)


def extract_alpha_lbdm(
    image: np.ndarray,
    trimap: np.ndarray,
    epsilon: float = 1e-7,
    radius: int = 1,
) -> np.ndarray:
    """Estimate alpha matte using LBDM Laplacian and conjugate gradient solver with trimap constraints."""
    L = compute_lbdm_laplacian(image, epsilon=epsilon, radius=radius)
    A, b = make_linear_system(L, trimap)
    x = cg(A, b, M=ichol(A))
    return np.clip(x, 0.0, 1.0).reshape(trimap.shape)

{
  "schemaVersion": 1,
  "goal": "verify pymatting.lbdm_laplacian in pkg:pypi/pymatting@1.1.15",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/pymatting@1.1.15"
  ],
  "symbols": [
    "pymatting.lbdm_laplacian"
  ]
}

"""Contract verification test for pymatting.lbdm_laplacian."""

import os
import sys
import numpy as np
import scipy.sparse

# Ensure project root is on sys.path for local module imports
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

from pymatting import lbdm_laplacian
from sample import compute_lbdm_laplacian, extract_alpha_lbdm


def test_lbdm_laplacian_shape_and_type() -> None:
    """Assertion 1: assert lbdm_laplacian computes sparse CSR matting Laplacian matrix with shape (h*w, h*w) for RGB image."""
    h, w = 6, 8
    rng = np.random.RandomState(42)
    image = rng.rand(h, w, 3).astype(np.float64)

    L = lbdm_laplacian(image)
    assert scipy.sparse.isspmatrix_csr(L), "L must be a scipy.sparse.csr_matrix"
    assert L.shape == (h * w, h * w), f"Expected shape ({h * w}, {h * w}), got {L.shape}"
    assert L.nnz > 0, "L must contain non-zero entries"

    # Verify helper function
    L_helper = compute_lbdm_laplacian(image)
    assert scipy.sparse.isspmatrix_csr(L_helper)
    assert L_helper.shape == (h * w, h * w)


def test_lbdm_laplacian_zero_row_sums() -> None:
    """Assertion 2: assert lbdm_laplacian matrix satisfies Laplacian zero row-sum property across all rows."""
    h, w = 6, 6
    rng = np.random.RandomState(123)
    image = rng.rand(h, w, 3).astype(np.float64)

    L = lbdm_laplacian(image, epsilon=1e-7, radius=1)
    row_sums = np.array(L.sum(axis=1)).flatten()

    # The sum along each row of the Laplacian matrix should be zero
    assert np.allclose(row_sums, 0.0, atol=1e-10), f"Row sums not close to 0: max={np.max(np.abs(row_sums))}"


def test_lbdm_laplacian_custom_parameters() -> None:
    """Assertion 3: assert lbdm_laplacian accepts custom regularization parameter epsilon and neighborhood window radius."""
    h, w = 10, 10
    rng = np.random.RandomState(99)
    image = rng.rand(h, w, 3).astype(np.float64)

    # Compute with default radius=1 vs radius=2
    L_r1 = lbdm_laplacian(image, epsilon=1e-5, radius=1)
    L_r2 = lbdm_laplacian(image, epsilon=1e-5, radius=2)

    assert L_r1.shape == (100, 100)
    assert L_r2.shape == (100, 100)
    assert scipy.sparse.isspmatrix_csr(L_r1)
    assert scipy.sparse.isspmatrix_csr(L_r2)

    # Radius 2 considers a larger local window ((2*2+1)^2 = 25 pixels vs (2*1+1)^2 = 9 pixels)
    assert L_r2.nnz > L_r1.nnz, f"Radius 2 nnz ({L_r2.nnz}) should exceed Radius 1 nnz ({L_r1.nnz})"


def test_lbdm_laplacian_alpha_matte_estimation() -> None:
    """Assertion 4: assert lbdm_laplacian enables alpha matte estimation satisfying trimap boundary constraints."""
    h, w = 10, 10
    image = np.zeros((h, w, 3), dtype=np.float64)
    trimap = np.full((h, w), 0.5, dtype=np.float64)

    # Define background (0.0) on left, foreground (1.0) on right
    trimap[:, :3] = 0.0
    trimap[:, 7:] = 1.0

    image[:, :3] = [0.1, 0.1, 0.1]
    image[:, 7:] = [0.9, 0.9, 0.9]
    image[:, 3:7] = [0.5, 0.5, 0.5]

    alpha = extract_alpha_lbdm(image, trimap, epsilon=1e-7, radius=1)

    assert alpha.shape == (h, w), f"Expected alpha shape ({h}, {w}), got {alpha.shape}"
    assert np.all(alpha >= -1e-5) and np.all(alpha <= 1.0 + 1e-5), "Alpha values must be in [0, 1]"
    assert np.all(alpha[:, :3] < 0.1), "Background region alpha should be close to 0.0"
    assert np.all(alpha[:, 7:] > 0.9), "Foreground region alpha should be close to 1.0"


def main() -> None:
    test_lbdm_laplacian_shape_and_type()
    test_lbdm_laplacian_zero_row_sums()
    test_lbdm_laplacian_custom_parameters()
    test_lbdm_laplacian_alpha_matte_estimation()
    print("All contract assertions passed.")


if __name__ == "__main__":
    main()