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

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.