pixel-convert 0.2.0
PyO3-powered image transform for Pixel-convert (Rust core)
Requires Python: >=3.9
Keywords: image, rust, pyo3, pillow, clustering

pixel_convert (Python package)

This package exposes a Python API backed by the Rust `pixel_convert_rust` core via PyO3.

API
- `pixel_convert.transform(image: PIL.Image.Image, width: int, height: int, kmax: int, *, fast=False, stride=None, stride_x=None, stride_y=None, alpha=None, epsilon_palette=None, t_final=None, stag_eps=None, stag_limit=None, threads=None, iter_timings=False) -> PIL.Image.Image`
- `pixel_convert.transform_file(input_path: str, output_path: str, width: int, height: int, kmax: int, *, fast=False, stride=None, stride_x=None, stride_y=None, alpha=None, epsilon_palette=None, t_final=None, stag_eps=None, stag_limit=None, threads=None, iter_timings=False) -> None`
 - `pixel_convert.map_to_colors_image(image: PIL.Image.Image, colors: list[tuple[int,int,int]], algorithm: str = "rgb") -> PIL.Image.Image`
 - `pixel_convert.map_to_colors_file(input_path: str, output_path: str, colors: list[tuple[int,int,int]], algorithm: str = "rgb") -> None`
 - `pixel_convert.map_to_named_palette_image(image: PIL.Image.Image, palette_name: str, algorithm: str = "rgb") -> PIL.Image.Image`
 - `pixel_convert.map_to_named_palette_file(input_path: str, output_path: str, palette_name: str, algorithm: str = "rgb") -> None`

Color mapping algorithms
- `"rgb"` / `"rgb_euclidean"`: Euclidean distance in RGB.
- `"lab"` / `"deltae76"` / `"lab_euclidean"`: Euclidean distance in CIE Lab (D65).
- `"ciede2000"` / `"de2000"` / `"deltae2000"` / `"de00"`: CIEDE2000 perceptual distance.

Build from source
- `pip install maturin`
- `maturin build -m pixel_convert/Cargo.toml --release`
- `pip install target/wheels/*.whl`

Develop install for local testing
- `maturin develop -m pixel_convert/Cargo.toml`

Example
```
from PIL import Image
import pixel_convert as rx

img = Image.open("examples/input_images/dog3.jpg")
out = rx.transform(img, 128, 128, 30, fast=True)
out.save("examples/output_images/dog3_py_128x128_30.png")
```

Palette mapping (PIL image)
```
from PIL import Image
import pixel_convert as rx

img = Image.open("examples/input_images/dog3.jpg")
palette = [(0,0,0), (255,255,255), (220,20,60)]
for algo in ["rgb", "lab", "ciede2000"]:
    out = rx.map_to_colors_image(img, palette, algorithm=algo)
    out.save(f"examples/output_images/dog3_map_{algo}.png")
```

Palette mapping with named palette (DMC)
```
from PIL import Image
import pixel_convert as rx

img = Image.open("examples/input_images/dog3.jpg")
for algo in ["rgb", "lab", "ciede2000"]:
    out = rx.map_to_named_palette_image(img, "dmc", algorithm=algo)
    out.save(f"examples/output_images/dog3_map_dmc_{algo}.png")
```

File-to-file example (faster, Rust handles I/O)
```
import pixel_convert as rx

rx.transform_file(
    "examples/input_images/dog3.jpg",
    "examples/output_images/dog3_py_128x128_30.png",
    128,
    128,
    30,
    fast=True,
    threads=4,
)
```

Palette mapping (file-to-file)
```
import pixel_convert as rx
palette = [(0,0,0), (255,255,255), (220,20,60)]
rx.map_to_colors_file(
    "examples/input_images/dog3.jpg",
    "examples/output_images/dog3_map_ciede.png",
    palette,
    algorithm="ciede2000",
)
```

Palette mapping (file-to-file) with named palette
```
import pixel_convert as rx
rx.map_to_named_palette_file(
    "examples/input_images/dog3.jpg",
    "examples/output_images/dog3_map_dmc_lab.png",
    "dmc",
    algorithm="lab",
)
```

Timing per iteration (logs)
```
import pixel_convert as rx, os
os.environ["RUST_LOG"] = "info"
rx.transform_file("examples/input_images/dog3.jpg", "examples/output_images/dog3_py_128x128_30.png", 128, 128, 30, iter_timings=True)
```