Metadata-Version: 2.4
Name: mumfordshah2d
Version: 0.5.1
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.7
License-File: LICENSE
Summary: Mumford-Shah edge-preserving image restoration — Python/Rust port of MATLAB/Java MumfordShah2D (Hohm, Storath & Weinmann)
Keywords: mumford-shah,image-processing,edge-preserving,denoising,deconvolution,inpainting,regularization,variational-methods
Author: Kilian Hohm, Martin Storath, Andreas Weinmann
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/mstorath/MumfordShah2D/issues
Project-URL: Changelog, https://github.com/mstorath/MumfordShah2D/blob/master/CHANGELOG.md
Project-URL: Homepage, https://github.com/mstorath/MumfordShah2D
Project-URL: Repository, https://github.com/mstorath/MumfordShah2D

# mumfordshah2d (Python / Rust)

Python / Rust port of the MATLAB / Java [MumfordShah2D](README.md) library.
Edge-preserving image restoration via the piecewise-smooth Mumford-Shah model
of Hohm, Storath, and Weinmann (Inverse Problems 31(11), 2015).

> **Status: Phase 1 alpha (0.1.0).** The build, scaffolding, and small
> primitives (`Point`, `GaussElim`/`GaussL2Mum`, `Image`, MATLAB utility
> ports, prox handles) are in place. The full 2D solver lands in Phase 4.
> See [`PORTED_BY.md`](PORTED_BY.md) for the phasing plan.

## Installation

From source (requires Rust + maturin):

```bash
pip install maturin
maturin develop --release
```

Or as a regular editable install (also builds the Rust core):

```bash
pip install -e .
```

Once Phase 5 ships, the package will be on PyPI as `mumfordshah2d`.

## Quick check

```python
import mumfordshah2d
print(mumfordshah2d.__version__)             # 0.1.0
print(mumfordshah2d.__original_authors__)    # Kilian Hohm, Martin Storath, Andreas Weinmann

import numpy as np
from mumfordshah2d import gauss_l2_mum_solve

# L2-Mumford-Shah within-segment smoothing on a noisy step:
y = np.array([0.0, 0.1, -0.05, 1.05, 0.95, 1.1])
mu = gauss_l2_mum_solve(y, alpha=2.0)
print(mu)
```

## What's currently exported

```python
# Utilities
soft_threshold, hard_threshold, expand_weights, rotate90, psnr

# Prox handles for the ADMM data-fidelity term
make_prox_l2w, make_prox_l1w, make_prox_l0w, make_prox_inpaint

# Phase 1 Rust primitive (exposed for testing)
gauss_l2_mum_solve

# Metadata
__version__, __original_authors__, __ported_by__
```

The full public API (`min_l2_l2_mumford_shah_2d` etc.) ships in Phase 4. Until
then, **use the original MATLAB code** in `mumfordShah2D.m` for end-to-end
restoration — that path is unchanged by this port.

## Array conventions

- **Python API**: grayscale arrays are `(rows, cols)`; colour/multichannel
  arrays are `(rows, cols, channels)` (numpy / imageio convention).
- **Internal Rust core**: `(channels, rows, cols)` (Java / MATLAB convention).
- A single conversion happens at the PyO3 boundary in `src/lib.rs`.

## Verification approach (Phases 2–5)

The Java `.class` files in `Java/bin/mumfordShah/` are kept on disk as a
reference oracle. From Phase 2 onwards, every Rust algorithm is fuzzed
against the Java implementation via a small `TestHarness.java` subprocess
shim, ensuring bit-equivalent (≤ 1e-12) results on hundreds of random
inputs.

## License

MIT, copyright Kilian Hohm, Martin Storath, Andreas Weinmann (original) and
the Claude Sonnet coding agent contribution (Anthropic, 2026, port). See
[`LICENSE`](LICENSE) and [`PORTED_BY.md`](PORTED_BY.md).

