Metadata-Version: 2.4
Name: pixelification
Version: 0.1.0
Summary: Pixel Rearrangement Tool — Keyboard-Navigated Terminal UI
Requires-Python: >=3.10
Requires-Dist: numpy>=1.20.0
Requires-Dist: opencv-python>=4.0.0
Requires-Dist: prompt-toolkit>=3.0.0
Description-Content-Type: text/markdown

# Pixelification

A terminal tool that rearranges pixels from a source image to approximate a target image using optimal transport via color sorting — then animates each pixel physically sliding to its new position.

No new pixels are created. Every pixel in the output comes from the source image, just rearranged.

## How it works

```mermaid
flowchart LR
    A[Source Image] --> C[Color sort<br/>lexsort by<br/>lum→hue→sat]
    B[Target Image] --> D[Color sort<br/>lexsort by<br/>lum→hue→sat]
    C --> E["s_order[i]"]
    D --> F["t_order[i]"]
    E --> G["forward[s_order] = t_order"]
    F --> G
    G --> H[Per-pixel<br/>position lerp]
    H --> I[Scatter render<br/>np.add.at]
    I --> J[60 frames<br/>slide animation]
```

1. **Sort by colour** — every pixel in both images is sorted by luminance, then hue, then saturation. The darkest source pixel gets rank 0, the lightest gets rank *N*−1. Same for the target.

2. **Map by rank** — a source pixel with rank *i* maps to the target position with rank *i*. This is the optimal transport: the *i*th darkest pixel in the source ends up where the *i*th darkest pixel was in the target.

```
   Source pixels (sorted)         Target positions (sorted)
   ┌─────────────────────┐       ┌─────────────────────┐
   │  rank 0 (darkest)   │──────→│  rank 0             │
   │  rank 1             │──────→│  rank 1             │
   │  rank 2             │──────→│  rank 2             │
   │  ...                │       │  ...                │
   │  rank N−1 (lightest)│──────→│  rank N−1           │
   └─────────────────────┘       └─────────────────────┘
```

3. **Animate** — each pixel slides from its original position to its mapped position over 60 frames using linear interpolation. All pixels move simultaneously. When multiple pixels land on the same display cell, their colours are averaged.

```
   Frame 0               Frame 30              Frame 60
   ┌────────┐            ┌────────┐            ┌────────┐
   │• •     │            │  ••    │            │   ••   │
   │  ••    │  ───────→  │ • ••   │  ───────→  │ ••     │
   │   • •  │    lerp    │    • • │    lerp    │ •  •   │
   └────────┘            └────────┘            └────────┘
   source positions      midway                target positions
```

## Usage

```bash
python rearrange_pixels_tui.py
```

A keyboard-navigated terminal interface opens. Use arrow keys to select images, press Enter to run.

```
↑↓  navigate  •  Enter  select  •  1-4  shortcut  •  q  quit
```

An OpenCV window opens with three panels:

| Source | Target | Reconstruction |
|--------|--------|----------------|
| Your image | Layout to approximate | Pixels sliding into place |

Press `ESC` or `q` during the animation to quit.

## Requirements

- Python 3.10+
- OpenCV (`cv2`)
- NumPy
- `prompt_toolkit`

```bash
pip install opencv-python numpy prompt_toolkit
```
