posterize 2.10.0__tar.gz

posterize-2.10.0/PKG-INFO

@@ -0,0 +1,65 @@
+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.

posterize-2.10.0/README.md

@@ -0,0 +1,50 @@
+# 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.

posterize-2.10.0/pyproject.toml

@@ -0,0 +1,86 @@
+[project]
+name = "posterize"
+version = "2.10.0"
+description = "Posterize an image with stacked SVG geometry (generated by Potrace)."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Shay Hill", email = "shay_public@hotmail.com" }]
+requires-python = ">=3.10"
+dependencies = [
+    "basic-colormath>=1.1.1",
+    "cluster-colors>=0.13",
+    "diskcache>=5.6.3",
+    "numpy",
+    "svg-ultralight",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.4,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["commitizen>=4.10.0", "pre-commit>=4.4.0", "pytest>=9.0.1"]
+
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = "2.10.0"
+tag_format = "$version"
+major-version-zero = true
+version_files = ["pyproject.toml:^version"]
+
+
+[tool.isort]
+profile = "black"
+
+[tool.pytest.ini_options]
+addopts = "--doctest-modules"
+pythonpath = "tests"
+log_cli = true
+
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = [
+    "S101",
+    "D",
+    "F401",
+] # Ignore assertions, docstrings, unused imports in test files
+
+[tool.ruff.format]
+docstring-code-line-length = 88
+
+[tool.ruff.lint]
+
+select = ["ALL"]
+
+ignore = [
+    "PLR",    # magic values
+    "COM",    # trailing commas
+    "ANN",    # forbid Any
+    "S",      # warnings about pickle, random, etc.
+    "N",      # names
+    "B019",   # memory leak warning for lru_cache
+    "ISC003", # implicit string concatenation
+]
+
+
+[tool.pyright]
+include = ["src"]
+exclude = ["**/__pycache__.py"]
+
+pythonVersion = "3.10"
+pythonPlatform = "All"
+
+typeCheckingMode = "strict"
+reportCallInDefaultInitializer = true
+reportImplicitStringConcatenation = true
+reportPropertyTypeMismatch = true
+reportUninitializedInstanceVariable = true
+reportUnnecessaryTypeIgnoreComment = true
+reportUnusedCallResult = true
+
+venvPath = "."
+venv = "./.venv"

posterize-2.10.0/src/posterize/__init__.py

@@ -0,0 +1,23 @@
+"""Import functions into the package namespace.
+
+:author: Shay Hill
+:created: 2024-05-09
+"""
+
+from posterize.main import extend_posterization, posterize, posterize_mono
+from posterize.posterization import Posterization
+from posterize.quantization import (
+    TargetImage,
+    new_target_image,
+    new_target_image_mono,
+)
+
+__all__ = [
+    "Posterization",
+    "TargetImage",
+    "extend_posterization",
+    "new_target_image",
+    "new_target_image_mono",
+    "posterize",
+    "posterize_mono",
+]

posterize-2.10.0/src/posterize/color_attributes.py

@@ -0,0 +1,85 @@
+"""Return quantified color attributes between 0 and 1 for a given color.
+
+For the purposes of this module, gray is (127, 127, 127). Values of (128, 128, 128)
+will be treated as *almost* gray.
+
+:author: Shay Hill
+:created: 2025-04-29
+"""
+
+from typing import Annotated, TypeAlias
+
+import numpy as np
+from numpy import typing as npt
+
+_RGB: TypeAlias = Annotated[npt.NDArray[np.uint8], (3,)]
+_RGBWCMYK: TypeAlias = Annotated[npt.NDArray[np.uint8], (8,)]
+
+
+def get_chromacity(color: _RGB) -> float:
+    """Return the chromacity of the color.
+
+    :param color: RGB color as a tuple of three integers in the range [0, 255]
+    :return: Chromacity score between 0 and 1, where 0 is gray and 1 is a pure
+        chromatic color (red, green, blue, etc.).
+
+    What is the inverse, relative distance to the color circle?
+
+    A color with a vibrance of 0 is a shade of gray, while a color with a vibrance of
+    1 is a pure color with maximum saturation and lightness.
+    """
+    r, g, b = map(float, color)
+    return (max((r, g, b)) - min((r, g, b))) / 255
+
+
+def _get_rgb_dist(rgb: _RGB) -> _RGBWCMYK:
+    """Convert red, green, blue to an 8-channel color distribution.
+
+    :param rgb: 3-channel RGB color
+    :return: 8-channel color distribution
+    """
+    r, g, b = map(float, rgb)
+    w: float = min(r, g, b)
+    k: float = 255 - max(r, g, b)
+    y: float = min(r, g) - w
+    c: float = min(g, b) - w
+    m: float = min(b, r) - w
+    r -= max(m, y) + w
+    g -= max(y, c) + w
+    b -= max(c, m) + w
+    return np.array([r, g, b, w, c, m, y, k])
+
+
+def get_purity(color: _RGB) -> float:
+    """Return the purity of the color.
+
+    :param color: RGB color as a tuple of three integers in the range [0, 255]
+    :return: Purity score between 0 and 1, where 0 is gray and 1 is a color on the
+        exterior of the color cube.
+
+    What is the inverse, relative distance to the surface of the color cube? A color
+    with a purity of 0 is pure gray (127, 127, 127). A color with a purity of one is
+    a pure color, a shaded (mixed with black) or a tinted (mixed with white) color.
+    """
+    _, _, _, white, _, _, _, black = map(float, _get_rgb_dist(color))
+    return 1 - (min(white, black) / 127)
+
+
+def get_vibrance(rgb: _RGB, chroma_weight: float = 0.75) -> float:
+    """Get the vibrance of a color.
+
+    :param rgb: RGB color as a tuple of three integers in the range [0, 255]
+    :param chroma_weight: Weighting factor for chromacity in the vibrance calculation.
+          Defaults to 0.75, meaning chromacity contributes 75% to the vibrance score.
+    :return: Vibrance score between 0 and 1, where 0 is gray, 1 is a pure color on
+        the color wheel, and black or white will be above 0 but below chromatic
+        colors.
+
+    Vibrance is a measure of how colorful a color is. Specifically, it is a weighted
+    average of the chromacity (closeness to color wheel) and purity (absence of gray)
+    of a color. Black would have a chromacity of 0 and a purity of 1. Red would have
+    a chromacity of 1 and a purity of 1. Pure gray would have a chromacity of 0 and a
+    purity of 0.
+    """
+    chroma_weight = 0.75
+    return get_chromacity(rgb) * chroma_weight + get_purity(rgb) * (1 - chroma_weight)

posterize-2.10.0/src/posterize/defaults.py

@@ -0,0 +1,28 @@
+"""Default values for posterization.
+
+:author: Shay Hill
+:created: 2026-02-08
+"""
+
+# Default weight for sum savings vs. average savings. Average savings is, by default,
+# weighted highly. These values are used when selecting the best candidate for the
+# next layer color. A higher average savings weight means colors that improve the
+# approximation a lot in a small area are chosen over colors that improve the
+# approximation a tiny amount over a large area. _DEFAULT_SAVINGS_WEIGHT is the
+# weight given to sum savings. (1 - _DEFAULT_SAVINGS_WEIGHT) is the weight given to
+# average savings.
+SAVINGS_WEIGHT = 0.25
+
+
+# A higher number (1.0 is maximum) means colors that are more vibrant are more likely
+# to be selected as layer colors. The default is 0.0, which will be good for most
+# images, but the parameter is available if you have an overall drab image with a few
+# bright highlights and want to pay less attention to the background.
+VIBRANT_WEIGHT = 0.0
+
+
+# Resize images larger than this to this maximum dimension. This value is necessary,
+# because you can only create arrays of a certain size. A smaller value might speed
+# up testing, but the quantization cache will need to be cleared if this value
+# changes.
+MAX_DIM = 500

posterize-2.10.0/src/posterize/image_processing.py

@@ -0,0 +1,97 @@
+"""Write images to disk, convert arrays to images, call potrace.
+
+:author: Shay Hill
+:created: 2024-10-13
+"""
+
+import importlib.resources
+import os
+import subprocess
+from pathlib import Path
+from typing import Annotated, Any, TypeAlias
+
+import numpy as np
+from lxml import etree
+from numpy import typing as npt
+from PIL import Image
+from svg_path_data import format_svgd_shortest
+
+from posterize.paths import CACHE_DIR
+
+POTRACE_EXE = importlib.resources.files("posterize.bin") / "potrace.exe"
+
+
+_IndexMatrix: TypeAlias = Annotated[npt.NDArray[np.integer[Any]], "(r,c)"]
+
+_TMP_BMP = CACHE_DIR / "temp.bmp"
+
+
+def _write_svg_from_mono_bmp(path_to_mono_bmp: str | os.PathLike[str]) -> Path:
+    """Write an svg from a monochrome image.
+
+    :param path_to_mono_bmp: path to the monochrome image
+    :return: path to the output svg
+
+    Images passed in this library will be not only grayscale, but monochrome. So, a
+    blacklevel of 0.5 can be hardcoded.
+    """
+    svg_path = (CACHE_DIR / Path(path_to_mono_bmp).name).with_suffix(".svg")
+    # fmt: off
+    command = [
+        str(POTRACE_EXE),
+        str(path_to_mono_bmp),
+        "-o", str(svg_path),  # output file
+        "-k", str(0.5),  # black level
+        "-u", "1",  # do not scale svg (points correspond to pixels array)
+        "--flat",  # all paths combined in one element
+        "-b", "svg",  # output format
+        "--opttolerance", "2.8",  # higher values make paths smoother
+    ]
+    # fmt: on
+    _ = subprocess.run(command, check=True)
+    return svg_path
+
+
+def _write_mono_bmp(layer: _IndexMatrix) -> Path:
+    """Write a monochrome bitmap from an index matrix.
+
+    :param layer: (r, c) array where -1 is transparent and opaque pixels are all
+        filled with the same index colormap.
+    :return: path to the monochrome bitmap
+
+    This bmp will be the input argument for potrace. Black pixels will be inside the
+    output path element.
+    """
+    mono_pixels = np.ones([*layer.shape, 3], dtype=np.uint8) * 255
+    mono_pixels[np.where(layer != -1)] = (0, 0, 0)
+    mono_bmp = Image.fromarray(mono_pixels)
+    output_path = _TMP_BMP
+    mono_bmp.save(output_path)
+    return output_path
+
+
+def layer_to_svgd(layer: _IndexMatrix) -> str:
+    """Convert a layer to an SVG data string.
+
+    :param layer: (r, c) array where -1 is transparent and opaque pixels are all
+        filled with the same index colormap.
+    :return: SVG data string
+
+    If the layer has no -1 values (solid layer), returns a rectangle path covering
+    the entire layer. Otherwise, writes a monochrome bitmap from the layer, converts
+    it to SVG using potrace, and returns the SVG content as a string.
+    """
+    if np.all(layer != -1):
+        height, width = layer.shape
+        return format_svgd_shortest(f"M0 0 {width} 0 {width} {height} 0 {height}z")
+    mono_bmp = _write_mono_bmp(layer)
+    svg_path: Path | None = None
+    try:
+        svg_path = _write_svg_from_mono_bmp(mono_bmp)
+        return format_svgd_shortest(
+            etree.parse(str(svg_path)).getroot()[1][0].attrib["d"]
+        )
+    finally:
+        mono_bmp.unlink()
+        if svg_path is not None:
+            svg_path.unlink()

posterize-2.10.0/src/posterize/layers.py

@@ -0,0 +1,64 @@
+"""Functions to deal with image-approximation layers.
+
+Each layer is 512 values, each either a single color index or -1.
+
+The original colormap is 512 unique values. For each layer, 1 color index is selected
+and each color in the original map is compared to it. Where the selected color index
+would improve the approximation (in comparison to lower layers), the value in that
+colormap position [0..511] is set to the selected color index. Where the selected
+color index would *not* improve the approximation, the value is set to -1.
+
+:author: Shay Hill
+:created: 2025-04-25
+"""
+
+from typing import TypeAlias
+
+import numpy as np
+from numpy import typing as npt
+
+_IntA: TypeAlias = npt.NDArray[np.intp]
+
+
+def merge_layers(*layers: _IntA, size: int | None = None) -> _IntA:
+    """Merge layers into a single layer.
+
+    :param layers: n shape (palette_size,) layer arrays, each containing at most two
+        values:
+        * a color index that will replace one or more indices in the quantized image
+        * -1 for transparent. The first layer will be a solid color and contain no -1
+    :param size: palette size; required only when no layers are provided, used to
+        shape the all-transparent result. For a color image, this should be 512. For
+        a mono image, this should be 256.
+    :return: one (palette_size,) array with the last non-transparent color in each
+        position
+    :raises ValueError: if no layers are provided and size is None
+
+    Where an image is a (rows, cols) array of indices---each layer of an
+    approximation will color some of those indices with one palette index per layer,
+    and others with -1 for transparency.
+    """
+    if not layers:
+        if size is None:
+            msg = "size is required when merging zero layers"
+            raise ValueError(msg)
+        return np.full(size, -1, dtype=np.intp)
+    merged: _IntA = layers[0] * 1
+    for layer in layers[1:]:
+        non_transparent = layer != -1
+        merged[non_transparent] = layer[non_transparent]
+    return merged
+
+
+def apply_mask(layer: _IntA, mask: _IntA | None) -> _IntA:
+    """Apply a mask to a layer if the mask is not None.
+
+    :param layer: the layer to apply the mask to (shape (512,) consisting of one
+        palette index and -1 where transparent)
+    :param mask: the mask to apply to the layer (shape (512,)) consisting of 1s and 0s
+    :return: the layer with the mask applied (shape (512,)) with, most likely,
+        additional transparent (-1) values
+    """
+    if mask is None:
+        return layer
+    return np.where(mask == 1, layer, -1)