posterize 2.10.0__py3-none-any.whl

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/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/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/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/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)