pymatting 1.1.15: estimate_alpha_lkm

# PyMatting estimate_alpha_lkm API

This sample pins `pymatting` 1.1.15 and verifies `pymatting.estimate_alpha_lkm` for Large Kernel Matting (LKM) alpha matte estimation.

## Proved Behavior
- `estimate_alpha_lkm` calculates continuous alpha mattes bounded in `[0.0, 1.0]` from RGB images and trimap arrays.
- Hard constraints are preserved: known background pixels (`trimap <= 0.1`) evaluate to `0.0`, and known foreground pixels (`trimap >= 0.9`) evaluate to `1.0`.
- Supports solver customization via `laplacian_kwargs` (e.g. `epsilon`, `radius`) and `cg_kwargs` (e.g. `maxiter`, `rtol`).
- Input validation: raises `ValueError` when the trimap lacks foreground pixels (`>= 0.9`) or background pixels (`<= 0.1`).
- Input validation: raises `ValueError` when the input image is not a 3-channel RGB image.

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.estimate_alpha_lkm 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.estimate_alpha_lkm
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:594c53a20efab84fffd20334dd815e387bd31f33dabc5968351270da04dee2c8","contract":["assert estimate_alpha_lkm calculates continuous alpha values bounded in [0.0, 1.0] from RGB image and trimap","assert estimate_alpha_lkm preserves hard constraints for known background (0.0) and foreground (1.0) pixels","assert estimate_alpha_lkm supports custom laplacian_kwargs and cg_kwargs solver parameters","assert estimate_alpha_lkm raises ValueError when trimap lacks foreground pixels (values \u003e= 0.9)","assert estimate_alpha_lkm raises ValueError when trimap lacks background pixels (values \u003c= 0.1)","assert estimate_alpha_lkm raises ValueError when image does not have 3 color channels"],"goal":"verify pymatting.estimate_alpha_lkm in pkg:pypi/pymatting@1.1.15","kind":"HOW","packages":["pkg:pypi/pymatting@1.1.15"],"schemaVersion":1,"symbols":["pymatting.estimate_alpha_lkm"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"pypi","executionContext":"python","language":"python","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"pip","runtime":"python","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/pymatting@1.1.15"],"schemaVersion":1,"subject":"pkg:pypi/pymatting@1.1.15","symbols":["pymatting.estimate_alpha_lkm"],"verifierAdapter":"python@1"}

llvmlite==0.49.0
numba==0.67.0
numpy==2.5.2
pillow==12.3.0
pymatting==1.1.15
scipy==1.18.1

{
  "schemaVersion": 1,
  "goal": "verify pymatting.estimate_alpha_lkm in pkg:pypi/pymatting@1.1.15",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/pymatting@1.1.15"
  ],
  "symbols": [
    "pymatting.estimate_alpha_lkm"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

"""Contract test proving pymatting.estimate_alpha_lkm."""

import warnings
import numpy as np
import pymatting
from pymatting import estimate_alpha_lkm

# ============================================================================
# 1. Continuous alpha estimation with boundary constraints
# ============================================================================
h, w = 64, 64
image = np.zeros((h, w, 3), dtype=np.float64)
# Left region is blue, right region is red
image[:, :32] = [0.1, 0.2, 0.7]
image[:, 32:] = [0.8, 0.3, 0.1]

# Trimap: 0.0 = background (cols 0..7), 1.0 = foreground (cols 56..63), 0.5 = unknown (cols 8..55)
trimap = np.full((h, w), 0.5, dtype=np.float64)
trimap[:, :8] = 0.0
trimap[:, 56:] = 1.0

alpha = estimate_alpha_lkm(image, trimap, laplacian_kwargs={"epsilon": 1e-6, "radius": 2})

assert alpha.shape == (h, w), f"Expected shape {(h, w)}, got {alpha.shape}"
assert np.all(alpha >= 0.0) and np.all(alpha <= 1.0), "Alpha values must be bounded in [0.0, 1.0]"
assert np.allclose(alpha[:, :8], 0.0, atol=1e-3), "Background constraint violated"
assert np.allclose(alpha[:, 56:], 1.0, atol=1e-3), "Foreground constraint violated"
assert 0.0 < np.mean(alpha[:, 8:56]) < 1.0, "Transition region alpha must be between 0 and 1"

# ============================================================================
# 2. Custom solver parameters: laplacian_kwargs and cg_kwargs
# ============================================================================
alpha_custom = estimate_alpha_lkm(
    image,
    trimap,
    laplacian_kwargs={"epsilon": 1e-5, "radius": 2},
    cg_kwargs={"maxiter": 500, "rtol": 1e-5},
)
assert alpha_custom.shape == (h, w)
assert np.all(alpha_custom >= 0.0) and np.all(alpha_custom <= 1.0)
assert np.allclose(alpha, alpha_custom, atol=5e-2)

# ============================================================================
# 3. Trimap validation: missing foreground raises ValueError
# ============================================================================
trimap_no_fg = np.zeros((h, w), dtype=np.float64)
try:
    estimate_alpha_lkm(image, trimap_no_fg, laplacian_kwargs={"radius": 2})
    raise AssertionError("Should have raised ValueError for trimap without foreground")
except ValueError as e:
    assert "Trimap did not contain foreground values" in str(e)

# ============================================================================
# 4. Trimap validation: missing background raises ValueError
# ============================================================================
trimap_no_bg = np.ones((h, w), dtype=np.float64)
try:
    estimate_alpha_lkm(image, trimap_no_bg, laplacian_kwargs={"radius": 2})
    raise AssertionError("Should have raised ValueError for trimap without background")
except ValueError as e:
    assert "Trimap did not contain background values" in str(e)

# ============================================================================
# 5. Image dimension validation: 2D image raises ValueError
# ============================================================================
image_2d = np.zeros((h, w), dtype=np.float64)
with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    try:
        estimate_alpha_lkm(image_2d, trimap, laplacian_kwargs={"radius": 2})
        raise AssertionError("Should have raised ValueError for 2D image")
    except ValueError:
        pass

print(f"CONTRACT PASS: pymatting {pymatting.__version__} estimate_alpha_lkm verified")