# mlx-vision

Image preprocessing and Apple Vision framework interop for MLX on Apple Silicon.

`mlx-vision` provides two layers:

- MLX-native image loading and preprocessing for model pipelines
- optional Apple Vision framework integration for OCR, face detection, classification, and saliency

GitHub: <https://github.com/AmiraniLabs/mlx-vision>

## Install

Base install:

```bash
pip install mlx-vision
```

With Apple Vision support:

```bash
pip install mlx-vision[vision]
```

Development install:

```bash
pip install mlx-vision[dev]
```

Full install:

```bash
pip install mlx-vision[all]
```

## Quickstart

```python
import mlx_vision as mv

image = mv.load("photo.jpg")
image = mv.resize(image, (256, 256))
image = mv.center_crop(image, (224, 224))
image = mv.normalize(image)
image = mv.to_chw(image)
```

## Batch Loading

```python
import mlx_vision as mv

batch = mv.load_batch(["a.jpg", "b.jpg"], size=(224, 224))
batch = mv.normalize(batch)
batch = mv.to_chw(batch)
```

## Apple Vision Integration

```python
import mlx_vision as mv

if mv.is_vision_available():
    faces = mv.detect_faces("portrait.jpg")
    text = mv.detect_text("document.jpg")
    classes = mv.classify_image("photo.jpg")
    saliency = mv.attention_saliency_map("photo.jpg")
```

## API

Core image preprocessing:

- `load(path, color="rgb")`
- `load_batch(paths, color="rgb", size=None)`
- `resize(image, size, interpolation="linear")`
- `center_crop(image, size)`
- `pad(image, padding, fill=0, mode="constant")`
- `horizontal_flip(image)`
- `to_float(image, scale=True)`
- `normalize(image, mean=..., std=...)`
- `to_chw(image)`
- `to_hwc(image)`

Apple Vision framework:

- `is_vision_available()`
- `detect_faces(image)`
- `detect_text(image, recognition_level="accurate", languages=None)`
- `classify_image(image)`
- `saliency_map(image, kind="attention")`
- `attention_saliency_map(image)`

## Positioning

What `mlx-vision` is:

`mlx-vision` is the image and computer vision entry point for MLX pipelines on Apple Silicon. It provides model-ready image transforms and optional access to Apple's native Vision framework with outputs compatible with MLX workflows.

What it is not:

- not a full replacement for OpenCV
- not a training framework
- not a visionOS SDK
- not a general multimedia library

## Publishing

This package is configured for PyPI Trusted Publishing from the
`AmiraniLabs/mlx-vision` GitHub repository using
`.github/workflows/publish.yml`.
