Metadata-Version: 2.4
Name: posterize
Version: 2.10.0
Summary: Posterize an image with stacked SVG geometry (generated by Potrace).
Author: Shay Hill
Author-email: Shay Hill <shay_public@hotmail.com>
License-Expression: MIT
Requires-Dist: basic-colormath>=1.1.1
Requires-Dist: cluster-colors>=0.13
Requires-Dist: diskcache>=5.6.3
Requires-Dist: numpy
Requires-Dist: svg-ultralight
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Posterize

Posterize an image with stacked SVG geometry (generated by Potrace).

## API

The package exposes four main functions and two result types:

- **`posterize(image_path, num_cols, *, savings_weight=None, vibrant_weight=None, max_dim=None)`**
  Load an image from disk and posterize it. Returns a `Posterization`.
  `image_path`: path to the image.
  `num_cols`: number of colors (layers) in the result; fewer may be returned if colors are exhausted.
  `savings_weight`: weight for sum savings vs average savings when choosing layer colors (default 0.25).
  `vibrant_weight`: bias toward more vibrant colors, 0–1 (default 0).
  `max_dim`: if set, resize the image so its longer side is at most this many pixels before processing.

- **`posterize_mono(pixels, num_cols, *, savings_weight=None, vibrant_weight=None)`**
  Posterize a grayscale pixel array. Returns a `Posterization`.
  `pixels`: `(r, c)` uint8 array (e.g. one channel of an image).
  `num_cols`, `savings_weight`, `vibrant_weight`: same as `posterize`.

- **`new_target_image(path, max_dim=None)`**
  Quantize an image file to at most 512 colors and return a `TargetImage` (palette, indices, cost matrix). Used internally by `posterize`; useful if you need the quantized image without building layers.
  `path`: path to an image file.
  `max_dim`: maximum width or height; image is thumbnailed if larger (default 500).

- **`new_target_image_mono(pixels)`**
  Quantize a grayscale `(r, c)` uint8 array to at most 256 colors. Returns a `TargetImage`. Used internally by `posterize_mono`.

**Result types:** `Posterization` (from `posterize` / `posterize_mono`) has `.write_svg(path, num_cols=None)` and methods for layers, colors, and SVG elements. `TargetImage` holds the quantized palette, indices, and cost matrix for layer-building.

### Example

```python
from posterize import posterize

posterized = posterize("image.png", 4)
posterized.write_svg("output.svg")
```

## Caching

- **`.cache_posterize`** (in the current working directory)
  Memoizes `posterize()` and `posterize_mono()` by their arguments. Repeated calls with the same inputs return the cached `Posterization` without recomputing layers.

- **`.cache_quantize`** (in the current working directory)
  Memoizes quantized image data: `quantize_image()` / `quantize_rgba()` and `quantize_mono()`. Used by `new_target_image()` and `new_target_image_mono()`, and indirectly by `posterize()` and `posterize_mono()`.

- **Temp directory** (`paths.CACHE_DIR`, under the system temp dir as `cluster_colors_cache`)
  Used while generating SVG paths: a temporary BMP and Potrace-generated SVG are written here during `layer_to_svgd()` and then removed. No long-lived cache.
