Skip to content

Image utilities

The utkit.utils.image module provides helpers for working with images. get_valid_images scans a directory and returns only the images that pass a set of quality filters — discarding tiny icons, transparent PNGs, simple/flat images, extreme aspect ratios, and near-duplicates.

Installation

get_valid_images requires Pillow, numpy and imagehash. Install the standard extra:

pip install "utkit[standard]"

Or with uv:

uv add "utkit[standard]"

Quick start

from utkit.utils.image import get_valid_images

valid_images = get_valid_images("/tmp/extracted_images")

print(valid_images)

get_valid_images

Scan a directory and return only valid images. Each image is checked against a series of filters (size, aspect ratio, transparency, entropy, color count, and perceptual-hash duplicates); images that fail any filter are skipped.

def get_valid_images(
    folder_path: str | Path,
    extensions: list[str] | None = None,
    min_dimension: int = 80,
    min_area: int = 10_000,
    max_aspect_ratio: float = 8.0,
    min_aspect_ratio: float = 0.125,
    max_transparency: float = 0.8,
    min_entropy: float = 2.0,
    min_colors: int = 8,
    max_hash_distance: int = 5,
) -> list[Path]
Parameter Type Default Description
folder_path str | Path — Directory to scan for images.
extensions list[str] | None None Additional image extensions to include, combined with the default set. Extensions may be passed with or without a leading dot (e.g. "png" or ".png").
min_dimension int 80 Minimum width/height in pixels to keep an image.
min_area int 10_000 Minimum width * height to keep an image.
max_aspect_ratio float 8.0 Maximum width/height ratio to keep an image.
min_aspect_ratio float 0.125 Minimum width/height ratio to keep an image.
max_transparency float 0.8 Maximum fraction of near-transparent pixels allowed for RGBA images.
min_entropy float 2.0 Minimum entropy to keep an image (filters simple images).
min_colors int 8 Minimum number of distinct colors to keep an image.
max_hash_distance int 5 Maximum perceptual hash distance to consider two images duplicates.

Returns: list[Path] — Paths of the valid images found in the folder.

Default usage

from utkit.utils.image import get_valid_images

valid_images = get_valid_images("/tmp/extracted_images")

print(valid_images)

Custom extensions

from utkit.utils.image import get_valid_images

# Include .svg and .avif in addition to the default extensions
valid_images = get_valid_images("/tmp/extracted_images", extensions=["svg", ".avif"])

print(valid_images)

Custom filters

from utkit.utils.image import get_valid_images

# Only keep larger images and be stricter about duplicates
valid_images = get_valid_images(
    "/tmp/extracted_images",
    min_dimension=120,
    min_area=20_000,
    max_hash_distance=10,
)

print(valid_images)