Principle:Ggml org Ggml Image IO
| Knowledge Sources | |
|---|---|
| Domains | Image_Processing, IO |
| Last Updated | 2026-02-10 |
Overview
Image IO provides the ability to load and write image files in common formats using single-header C libraries embedded directly in the GGML examples.
Description
Vision models and image-processing examples in GGML (such as SAM and YOLO) need to read input images and write output images in standard formats. Rather than introducing a heavy dependency on platform-specific imaging libraries (libpng, libjpeg, etc.), GGML bundles two single-header C libraries from the stb collection:
stb_image.h(v2.28) -- A public-domain image loader that decodes JPEG (baseline and progressive), PNG (1/2/4/8/16-bit per channel), BMP, TGA, PSD, GIF, HDR, PIC, and PNM formats. It provides a simple API: callstbi_loadwith a filename and receive a pointer to decoded pixel data along with width, height, and channel count. It supports both file-based and memory-based decoding, SIMD acceleration (SSE2 on x86, NEON on ARM), and custom memory allocators.
stb_image_write.h(v1.16) -- A public-domain image writer that encodes PNG, BMP, TGA, JPEG, and HDR formats. Each format has a dedicated function (e.g.,stbi_write_png,stbi_write_jpg) that takes pixel data, dimensions, and component count, and writes to a file or a callback.
Both libraries follow the single-header implementation pattern: the entire library is contained in one .h file, and the implementation is activated by defining a macro (STB_IMAGE_IMPLEMENTATION or STB_IMAGE_WRITE_IMPLEMENTATION) in exactly one translation unit. This eliminates build-system complexity and makes the libraries trivially portable across platforms.
Usage
Apply this principle when building GGML examples or applications that need to process image data. Include stb_image.h to load input images into raw pixel buffers suitable for preprocessing into GGML tensors. Include stb_image_write.h to save output images (e.g., segmentation masks from SAM, annotated detection results from YOLO). The single-header approach means no additional build configuration is needed beyond including the header and defining the implementation macro in one source file.
Theoretical Basis
The Image IO principle rests on several design considerations:
- Minimal Dependency Principle -- Machine-learning inference libraries should minimize external dependencies to remain portable and easy to build. By embedding self-contained single-header libraries, GGML avoids requiring users to install system-level imaging packages, which vary across Linux distributions, macOS, and Windows. The stb libraries have no dependencies beyond the C standard library.
- Single-Header Library Pattern -- The entire implementation resides in a header file, guarded by an
IMPLEMENTATIONmacro. This pattern, popularized by Sean Barrett's stb libraries, trades compilation time (the implementation is compiled once per translation unit that defines the macro) for distribution simplicity (one file to copy, no build scripts). It is particularly well-suited for auxiliary functionality in projects like GGML where image IO is supporting infrastructure, not a core feature. - Format Coverage vs. Compliance Trade-off -- stb_image supports the most common image formats but does not aim for full specification compliance (e.g., it omits 12-bit JPEG and arithmetic coding). This is an intentional trade-off: full compliance would multiply the code size and complexity for format variants that machine-learning workloads rarely encounter. The supported subset covers the vast majority of images used in model evaluation and demo applications.
- SIMD-Accelerated Decoding -- stb_image uses SSE2 (x86) and NEON (ARM) intrinsics for performance-critical decoding paths, particularly JPEG IDCT and PNG filtering. This keeps image loading fast enough that it does not become a bottleneck relative to model inference, even for high-resolution inputs.
- Decoupled Read and Write -- Loading and writing are in separate headers with independent APIs, allowing applications to include only the functionality they need. An inference-only application that reads images but never writes them can omit
stb_image_write.hentirely, reducing compiled code size.