SLICPosterizer

Fast artistic posterization with SLIC superpixels.

SLICPosterizer is a Python tool for artistic image posterization that transforms photographs into stylized artwork with reduced color palettes. It provides both a command-line interface and Python API for fine control over colors, edges, blur, and segmentation.

The program is inspired by PosterChild, although this implementation is my own. The primary difference is that in PosterChild the authors use KMeans from scikit-learn as well as SciPy ConvexHull. While their approach offers better visual results, I found the use of these algorithms (in particular KMeans) very slow on my computer.

The result is a faster posterization engine based entirely on SLIC superpixels. It works because SLIC itself is also a clustering algorithm, like KMeans, but optimized for image segmentation. Instead of clustering pixels based on color similarity, SLIC creates clusters based both on color similarity and spatial proximity.

This implementation also streamlines dependencies and uses only the necessary imports to function and is provided as a single file for ease of use.

---

Table of Contents

• Features
• Examples
• Installation
• Usage
  • CLI
  • Python API
• License
• Author
• Acknowledgments

---

Features

• SLIC superpixel segmentation with adjustable compactness and count
• Color palette optimization and posterization
• Edge preservation with threshold controls
• Optional overlay of superpixel boundaries
• Command-line usage or import as a Python module

---

Examples

These images are taken from Lorem Picsum. Thank you to the developers for such a useful service! Note: for this service, curl must be used with -L to follow redirects.

Original	Posterized	Command
		curl -L https://picsum.photos/id/222/1920/1080 | slicposterizer curl_test.jpg
		slicposterizer person.jpeg person_posterized.jpeg
		uv run slicposterizer.py examples/car.jpeg examples/car_posterized.png -c 24

You can also see the superpixel overlays with the --overlay option:

Landscape	Person	Car

---

Installation

Requirements: Python 3.10+ (tested on Linux; Windows and macOS support should work but is untested)

"numpy>=1.26.4",
"opencv-python>=4.11.0.86",
"pillow>=11.3.0",
"scikit-image>=0.25.2",
"scipy>=1.16.1",

You can use the package either:

• Directly by running the script file, or
• By building and installing locally via uv:

uv build
uv pip install -e .

Note: This package is not yet published on PyPI.

---

Usage

Quick start

slicposterizer input.jpg output.jpg -c 32 -S 3000 --overlay

---

CLI

Run the CLI tool with:

slicposterizer input.jpg output.jpg [options]

Or pipe to it:

curl -L https://picsum.photos/id/222/1920/1080 | slicposterizer curl_test.jpg [options]

Full CLI options:

usage: slicposterizer [-h] [-m MIXING] [-p PALETTE] [-c COLORS] [-S SUPERPIXELS]
                      [--compactness COMPACTNESS] [-b BLUR] [-e EDGE_THRESHOLD]
                      [-d DOWNSAMPLE] [--no-edge-preserve] [--detail-blend DETAIL_BLEND]
                      [--quality QUALITY] [-s [1-10]] [--overlay]
                      input output

SLIC Posterizer - SLIC-Based Artistic Posterization

positional arguments:
  input                 Input image path (default: None)
  output                Output posterized image path (default: None)

options:
  -h, --help            show this help message and exit
  -c COLORS, --colors COLORS
                        Number of colors in palette (default: 64)
  -b BLUR, --blur BLUR  Blur radius for smoothing (default: 1)
  -s [1-10], --smoothing [1-10]
                        Smoothing strength level (1-10) (default: 3)
  -S SUPERPIXELS, --superpixels SUPERPIXELS
                        Number of superpixels (default: 4500)
  --compactness COMPACTNESS
                        SLIC superpixel compactness parameter (default: 15.0)
  --overlay             Overlay superpixel boundaries on the final image (default: False)
  -m MIXING, --mixing MIXING
                        Output prefix for additive mixing layers (default: None)
  -p PALETTE, --palette PALETTE
                        Output path for palette swatch (default: None)
  -e EDGE_THRESHOLD, --edge-threshold EDGE_THRESHOLD
                        Edge detection threshold (default: 0.1)
  -d DOWNSAMPLE, --downsample DOWNSAMPLE
                        Downsample factor (>=1) (default: 1)
  --detail-blend DETAIL_BLEND
                        Blend factor for detail preservation (default: 0.1)
  --quality QUALITY     JPEG quality (if saving JPEG) (default: 95)
  --no-edge-preserve    Disable edge preservation (default: False)
  --strict-size MAX_DIM
                        Resize longest image dimension to this value, keeping aspect ratio (e.g. 1920) (default: None)

---

Python API

You can use the posterizer programmatically by importing posterize:

from slicposterizer import posterize

posterize(
    input_path="input.jpg",
    output_path="output.jpg",
    num_colors=64,
    num_superpixels=4500,
    blur_radius=1.0,
    edge_threshold=0.1,
    preserve_edges=True,
    overlay_superpixels=False,
)

Or create a reusable SLICPosterizer instance:

from slicposterizer import SLICPosterizer

posterizer = SLICPosterizer(
    num_colors=64,
    blur_radius=1.0,
    edge_threshold=0.1,
    downsample_factor=1,
    preserve_edges=True,
    num_superpixels=4500,
    superpixel_compactness=15.0,
    detail_blend_strength=0.1,
    smoothing=3,
    overlay_superpixels=False,
)

posterizer.posterize(
    input_path="input.jpg",
    output_path="output.jpg",
    palette_path=None,
    mixing_prefix=None,
    quality=95,
)

---

License

This project is licensed under the GPL-3.0-or-later license. See the LICENSE file for details.

---

Author

Adnan Valdes - blog

---

Acknowledgments

• Chao, C.-K. T., Singh, K., & Gingold, Y. (2021) PosterChild: Blend-Aware Artistic Posterization DOI | PDF

• Achanta, R., Shaji, A., & Smith, K. (2010) SLIC Superpixels EPFL Report | PDF