focal

Image processing in C++20 with a zero-copy NumPy interface.

pip install focalpy

import focal

img = focal.imread("photo.jpg")            # linear float32, (h, w, c)
img = focal.exposure(img, 0.5)             # half a stop brighter
img = focal.resize(img, 1080, 1920)        # prefiltered, in linear light
img = focal.gaussian_blur(img, 2.0)
focal.imwrite("out.png", img)              # encodes back to sRGB

Why

Downscaling prefilters, so fine detail averages instead of aliasing. Shrinking by 4x means each output pixel must draw on about 4 input pixels. A resize that skips this doesn't lose fine detail gracefully — it invents patterns that were never in the image.

Filtering happens in linear light. Blurring and resizing mix pixels together, and mixing light is physics — it has to happen on linear values, not gamma-encoded ones. imread decodes sRGB on the way in and imwrite encodes on the way out, so every op in between is correct by construction.

Averaging equal black and white gives half the light, which displays as light grey (182/255). Doing it on encoded values gives 128/255 — visibly too dark, and it compounds every time an image is resized.

Nothing converts silently. Array arguments are declared .noconvert(), so a float64 or non-contiguous array raises TypeError rather than quietly costing a full-size copy. Converting is the caller's decision, not a hidden one.

What's here

Box blur, Sobel, and unsharp mask fall out of the primitives above:

box    = focal.separable_filter(img, k, k)                    # k = ones(n)/n
sobel  = focal.separable_filter(img, [-1,0,1], [1,2,1])
sharp  = focal.blend(img, focal.gaussian_blur(img, 2.0), -0.5)

Border modes (clamp, reflect, reflect101, wrap, constant) are shared by every spatial op and match scipy.ndimage's semantics.

Design

Everything is a view. The core type is a non-owning {pointer, dtype, shape, strides} struct, so a crop, a single channel, and a NumPy array handed over from Python are all the same type, and none of them copy. Strides are in bytes, matching NumPy exactly, so wrapping an incoming array is copying six integers.

Ops run on float32 linear. dtype conversion happens at the edges of a pipeline, never per pixel inside an op.

Correctness is checked against independent oracles. The test suite compares against scipy.ndimage and PIL wherever one exists — border handling is verified for every index from -2n to 3n across four modes and four image sizes, and resize matches PIL's interior to 1e-7.

Building from source

Needs a C++20 compiler and CMake:

git clone https://github.com/edisons3608/focal
cd focal
pip install -e . --no-build-isolation
pytest

OpenMP is used when available (-DFOCAL_USE_OPENMP=OFF to disable). On macOS that means brew install libomp.

Status

Early, and the API will change. Missing so far: color space conversion beyond sRGB, geometric warps, histogram operations, 16-bit and HDR file formats.

License

MIT. Bundles stb (public domain).