libstb

Python bindings for the stb single-header libraries. pip install libstb and you have image/font processing with no system dependencies and no Python dependencies. The C++ library is usable from CMake too.

numpy is optional: pip install "libstb[numpy]" if you want img.numpy() / libstb.imread(). It is imported only when one of those is first used, never by import libstb, and without it they raise an ImportError that says so. Everything else works without numpy, including Image(array) from any buffer (a memoryview, array.array, a bytearray, a PIL-exported buffer...), and img.tobytes() and memoryview(img) give you the pixels with no numpy at all.

Python

import numpy as np
import libstb

img = libstb.Image.open("photo.png")                # or bytes; also: channels=4, flip=True
img.width, img.height, img.channels                 # 640, 480, 3
img.numpy()                                         # uint8 pixels (H, W, C), no copy; np.asarray(img) works too
np.from_dlpack(img)                                 # DLPack: also torch/jax/cupy.from_dlpack(img), zero-copy
libstb.Image.from_dlpack(tensor)                    # and back: a torch/jax/cupy/numpy uint8 array -> Image
pixels = libstb.imread("photo.png")                 # just the ndarray (same options as Image.open)
libstb.imwrite("out.jpg", pixels, quality=80)       # an ndarray or an Image; format from the extension
libstb.ImageInfo.read("photo.png")                  # header only: (width, height, channels)
libstb.Image(np.zeros((8, 8, 4), np.uint8))         # from your own uint8 array (no copy, see below)
img.copy()                                          # an independent image (deep copy)

img.write("out.jpg")                                 # format from the extension, default settings
img.write_jpg("out.jpg", quality=80)                # or pick the format and its settings
data = img.to_png(compression=9)                    # -> bytes (to_png / to_jpg / to_bmp / to_tga)

small = img.resize(320, 240)                        # new Image; default Resizer()
small = img.resize(320, 240, "cubic")               # filter by name (see the table below)
libstb.Resizer("cubic")                             # same name works on Resizer itself
libstb.Resizer(libstb.Resizer.Filter.MITCHELL, libstb.Resizer.Edge.WRAP, srgb=False)
img.resize(320, 240, libstb.Resizer("linear", srgb=False))  # name + other options

font = libstb.Font.open("font.ttf")                 # trusted fonts only, see below
text = font.render("Hello\nworld", 32)              # RenderedText(bitmap: Image (1 channel), origin_x, origin_y)
text.bitmap.write("hello.png")
font.metrics(32), font.advance("A", 32), font.kerning("A", "V", 32), font.measure("Hello", 32)
font.render_glyph("A", 32)                          # Glyph(bitmap, x_offset, y_offset, advance)
atlas = font.make_atlas("ABCabc123", 32, 256, 256)  # Atlas: .image and atlas["A"] -> AtlasGlyph

libstb.iminfo("photo.png")                          # shortcut: ImageInfo.read(...)

Encoding. Every format has a pair of methods with its own settings, all defaulted: to_png(compression=8), to_jpg(quality=90), to_bmp(), to_tga(rle=True) return the file's bytes, and write_png(path, ...), write_jpg(path, ...), write_bmp(path), write_tga(path, ...) do the same and write it (only after encoding succeeded, so a failure never leaves a truncated file). write(path) is the shortcut: it picks the format from the extension (.png .jpg .jpeg .bmp .tga, case-insensitive; ValueError for anything else) and uses the defaults. For other settings call write_*.

libstb.imwrite(path, image, *, quality=None, compression=None, rle=None) is the functional form: it takes an Image or a uint8 array, picks the format from the extension, and passes the options that format has (quality for jpg, compression for png, rle for tga). An option the format does not have is a ValueError, not silently ignored. libstb.imread(source, *, channels, flip, max_bytes) is its counterpart and returns an ndarray.

Resize filters by name. Image.resize(w, h, x) and Resizer(x) accept a Resizer.Filter, or a case-insensitive name (- and space count as _). Any other option (edge, srgb, max_bytes) is a keyword of Resizer(...). Image.resize also takes a ready-made Resizer, or None for the default.

An unknown name raises ValueError listing the valid ones. There is no lanczos: stb_image_resize2 does not have it.

Fonts: trusted files only. stb_truetype does no bounds checking; its author writes "NO SECURITY GUARANTEE -- DO NOT USE THIS ON UNTRUSTED FONT FILES". Load your own or vetted system fonts, never user uploads. (Images are different: stb_image is fuzzed, and libstb adds dimension and size limits.)

Errors mirror the C++ hierarchy: libstb.Error (a RuntimeError) with DecodeError, EncodeError, LimitError below it, so a single except libstb.Error catches every libstb failure. Bad arguments raise ValueError, unreadable files OSError (FileNotFoundError, PermissionError, ... as the OS says). Images whose decoded size would exceed max_bytes (default 512 MiB) are rejected from the header, before any pixel memory is allocated.

libstb.Image is stb::image itself, not a wrapper: open, resize, to_* and write* are the C++ members, run without the GIL. img.numpy() / np.asarray(img) are numpy views of its pixels (kept alive by the view); memoryview(img) is the same zero-copy view as a plain 3-D memoryview (numpy reads it too), and img.tobytes() is a copy, both without numpy.

DLPack. Image implements __dlpack__ / __dlpack_device__, so np.from_dlpack(img), torch.from_dlpack(img), jax.numpy.from_dlpack(img) and cupy.from_dlpack(img) share the pixels with no copy and no framework import on libstb's side. The layout is fixed: uint8, shape (height, width, channels), on the CPU (dl_device other than the CPU is a BufferError). The view keeps the image alive. It is writable with numpy 2.1 or newer (older numpy, the last one on Python 3.9 being 2.0.2, imports every DLPack view read-only and has no copy= argument; img.numpy() is always writable). Asking for copy=True gives an independent copy. The other way round, libstb.Image.from_dlpack(x) takes any DLPack object holding uint8 pixels of shape (H, W) or (H, W, 1..4) (a torch, jax, cupy or numpy array, another Image): a writable C-contiguous CPU array is shared, anything else is copied, and copy=True always copies. (Image(x) accepts the same objects; from_dlpack additionally insists on __dlpack__, so a stray bytes is a clear TypeError.) For a different layout or dtype (CHW, float32), convert on the framework side, e.g. torch.from_dlpack(img).permute(2, 0, 1).float() / 255.

Pixels are never copied behind your back. Image(array) uses a writable, C-contiguous uint8 array in place, so the image and the array share their pixels (changes show on both sides, and the image keeps the array alive). Any other array (read-only, or strided like arr[::-1]) cannot be shared and is copied. Image.open takes ownership of stb's own buffer, no copy either. When you want an independent image, say so: img.copy() (also copy.copy and copy.deepcopy).

C++ / CMake

# after `pip install libstb`
execute_process(COMMAND ${Python3_EXECUTABLE} -c "import libstb; print(libstb.get_cmake_dir())"
    OUTPUT_VARIABLE libstb_DIR OUTPUT_STRIP_TRAILING_WHITESPACE)
find_package(libstb CONFIG REQUIRED)
target_link_libraries(app PRIVATE libstb::core)

The C++ namespace and headers are stb (<stb.h>, <stb/*.hpp>); the CMake target (libstb::core) and the Python package (libstb) keep the project name.

#include <stb.h>

stb::image img = stb::image::open("in.png");        // throws stb::error subclasses
img(0, 0, 1) = 255;                                       // unchecked pixel access
stb::image dup = img.copy();                              // image is move-only: copies are explicit
img.write("out.jpg");                                      // format from the extension, default settings
img.write_jpg("out.jpg", 80);                             // or pick the format and its settings
std::vector<std::uint8_t> bytes = img.to_png(9);          // to_png / to_jpg / to_bmp / to_tga -> file bytes

stb::image small = img.resize(320, 240);              // default resizer
stb::image crisp = img.resize(320, 240, "cubic");      // filter by name, or by enum:
stb::image soft  = img.resize(320, 240, stb::resize_filter::mitchell);

stb::resize_options o;                                 // full control: filter, edge, srgb, max_bytes
o.edge = stb::resize_edge::wrap;
stb::resizer r(o);                                     // also: resizer("cubic"), resizer(resize_filter::box)
stb::image tile = img.resize(320, 240, &r);            // nullptr = default resizer; r.resize(img, w, h) works too

stb::font f = stb::font::open("font.ttf");          // cheap to copy, thread-safe
stb::text_bitmap t = f.render("h\xC3\xA9llo", 32);      // UTF-8 in, 1-channel image out
stb::atlas atlas = f.make_atlas(U"abc", 32, 256, 256);

Design: stb never appears in a public header. Where a class would hold stb state, it is hidden behind a pimpl: font keeps the font bytes and the stbtt_fontinfo in an opaque font::impl (shared and immutable, so copies are cheap and threads can share one). image and resizer carry no stb state at all (plain ints/enums), so a pimpl there would only add indirection. image is move-only: its pixels are a shared_ptr<uint8_t> whose deleter (or aliased owner) decides who frees them, so the same class holds memory it allocated, stb's decode buffer (adopted, not copied) or memory somebody else owns (image::wrap, which is how a numpy array becomes an image without a copy). A copy is always spelled copy(). The four output formats are a closed set, so there is no encoder class hierarchy: each format is a to_* / write_* pair on image with its own defaulted settings, next to decoding in src/core/image.cpp. Runtime failures derive from stb::error (decode_error, encode_error, limit_error, io_error); programmer errors throw std::invalid_argument.

Or cmake --install build and find_package(libstb) as usual.

Layout (mirrors httpp / ctoon)

include/stb.h               umbrella header, owns LIBSTB_VERSION_* (single source of truth)
include/stb/*.hpp           public API (error, image, resizer, font, utf8); never includes stb
src/core/*.cpp              implementation; the only place stb headers are compiled
src/third_party/stb/        vendored stb headers (committed, no submodules)
src/bindings/python/        nanobind module (bind_*.cpp, one per area) + the `libstb` Python package
cmake/                      DynamicVersion, Startup, Optimize, package config
tests/{cpp,python,cmake}    unit tests + find_package consumer test, all run by ctest
tests/data/                 synthetic test font (solid-rectangle glyphs) + the script that makes it

Each stb header is compiled with STB_*_STATIC, so no stbi_* symbol leaks from libstb_core: it links fine next to your own copy of stb.

Build & test

pip install -r requirements-dev.txt
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build --output-on-failure

Wheels: abi3 (cp312-abi3, covers 3.12+) plus one wheel each for cp39-cp311; see .github/workflows/wheels.yml. Free-threaded builds are not supported.

License

MIT for libstb. The vendored stb headers are MIT / public domain (see src/third_party/README.md).