onnx-light-kernel-images#

ImageDecoder kernel extension for onnx-light.

Registers the ONNX ImageDecoder operator (ai.onnx, since opset 20) with the onnx-light kernel dispatch table. The kernel decodes encoded image bytestreams into (H, W, C) tensor(uint8) arrays in channel-last layout.

Supported formats#

Format	Variants
BMP	24-bit uncompressed (BI_RGB, BITMAPINFOHEADER)
TIFF	Baseline 8-bit-per-sample chunky, uncompressed or compressed with PackBits, LZW or Deflate/ZIP (with optional horizontal predictor)
JPEG	Baseline JFIF (SOF0, 8-bit, 1 or 3 components)
JPEG2000	JP2 file format and raw J2K codestream (via `libopenjp2`)
PNG	8-bit non-interlaced grayscale / truecolor
WebP	Decoded via `libwebp`
PNM	Netpbm family (P1–P6 with 8-bit samples)

JPEG2000 and WebP are decoded through the OpenJPEG (libopenjp2) and libwebp shared libraries, which are loaded dynamically at runtime. When the corresponding library is not available the decoder returns an empty matrix, as described by the ONNX ImageDecoder schema.

Build from source#

Prerequisites#

C++20 compiler
CMake ≥ 3.15
Python ≥ 3.10
nanobind ≥ 1.3.2

Python wheel (recommended)#

pip install .

Pixi environment#

pixi install
pixi run install
pixi run test-python

setup.py with C++ tests#

Build the extension and run the C++ unit tests with ctest:

python setup.py build_ext --inplace --cpp-tests

To build and test against the exact C++ runtime loaded by a locally built, importable sibling checkout of onnx-light, use:

PYTHONPATH=../onnx-light \
python setup.py build_ext --inplace --cpp-tests --onnx-light-source

--onnx-light-source rejects mixed installations: the imported Python package, headers, extension, and shared C++ libraries must all come from the same onnx-light checkout.

Pure CMake (C++ only)#

cmake -S . -B build -DONNX_LIGHT_KERNEL_IMAGES_BUILD_TESTS=ON \
      -DONNX_LIGHT_KERNEL_IMAGES_BUILD_PYTHON=OFF
cmake --build build
ctest --test-dir build

The build automatically downloads the onnx-light 0.1.9 C++ release archive. To use a custom install, set -DONNX_LIGHT_ROOT=/path/to/onnx-light-cpp.

Compiler hardening#

Pass -DONNX_HARDENING=ON to build every C++ target with the OpenSSF Compiler Options Hardening Guide for C and C++ flags (for example -D_FORTIFY_SOURCE, -fstack-protector-strong, -fstack-clash-protection, -fcf-protection, RELRO/now linking on GCC/Clang and /GS, /guard:cf, /Qspectre, /DYNAMICBASE on MSVC). Each flag is probed and silently skipped when the active toolchain does not support it. With a pip build the option is forwarded via -C cmake.define.ONNX_HARDENING=ON.

macOS: onnx-light publishes prebuilt C++ archives only for Linux and Windows. On macOS, build and install the onnx-light C++ SDK from source (-DONNX_LIGHT_BUILD_PYTHON=OFF) and point the build at it with -DONNX_LIGHT_ROOT=/path/to/onnx-light-install.

C++ usage#

#include <onnx_light_kernel_images/register_image_kernels.h>

int main() {
    // Register the ImageDecoder kernel once before running models.
    onnx_light_kernel_images::RegisterImageKernels();
    // ... use onnx-light RuntimeSession with ImageDecoder nodes ...
}

Link against onnx_light_kernel_images::lib_onnx_light_kernel_images:

find_package(onnx_light_kernel_images REQUIRED)
target_link_libraries(my_app PRIVATE
    onnx_light_kernel_images::lib_onnx_light_kernel_images)

Python usage#

from onnx_light_kernel_images.onnx_py._imgpykernels import register_image_kernels

# Register the kernel once before running models.
register_image_kernels()

Once the kernels are registered, build an ImageDecoder ONNX model and run it through onnx-light’s ReferenceEvaluator, feeding the encoded bytestream as a uint8 tensor and reading back the decoded (H, W, C) uint8 image.

See the examples gallery for a script that saves an image in every supported format with Pillow and reloads each one through such a model.

Testing#

C++ tests#

cmake -S . -B build -DONNX_LIGHT_KERNEL_IMAGES_BUILD_TESTS=ON \
      -DONNX_LIGHT_KERNEL_IMAGES_BUILD_PYTHON=OFF
cmake --build build
ctest --test-dir build --output-on-failure

Python tests#

pip install -e .
pytest unittests/python/

Fuzzing#

libFuzzer harnesses under fuzz/ exercise the image decoders and the custom TIFF-compression front-end with random / malformed inputs. They require Clang:

CC=clang CXX=clang++ cmake -S . -B build-fuzz -G Ninja \
      -DONNX_LIGHT_KERNEL_IMAGES_BUILD_FUZZERS=ON \
      -DONNX_LIGHT_KERNEL_IMAGES_BUILD_PYTHON=OFF \
      -DONNX_LIGHT_KERNEL_IMAGES_INSTALL=OFF
cmake --build build-fuzz
./build-fuzz/fuzz_image_decoder -runs=4000
./build-fuzz/fuzz_tiff_compression -runs=4000

See fuzz/README.md for details.

License#

Apache-2.0. See LICENSE.