Implementation:Ggml org Ggml Stb image

Implementation Metadata

File Name	examples/stb_image.h
Repository	ggml-org/ggml
Lines	7987
Language	C
Domain Tags	Image_Processing, Third_Party, IO
Status	Active
Last Updated	2025-05-15 12:00 GMT
Knowledge Sources	ggml-org/ggml repository

Overview

examples/stb_image.h is a third-party single-header public domain image loading library (stb_image v2.28) by Sean Barrett. It is vendored into the GGML repository as a dependency used by example programs (such as SAM and YOLO) that need to load image files for inference, avoiding external image library dependencies.

Description

The library provides functions to load images from files or memory in multiple formats:

• JPEG -- Baseline and progressive (12 bpc/arithmetic not supported)
• PNG -- 1/2/4/8/16-bit-per-channel
• TGA, BMP, PSD, GIF, HDR, PIC, PNM

Key features:

• Single-header implementation pattern (define STB_IMAGE_IMPLEMENTATION before including)
• Returns decoded pixel data as simple arrays with configurable channel counts (1-4)
• SIMD optimizations for SSE2 (x86/x64) and NEON (ARM)
• Customizable memory allocators (STBI_MALLOC, STBI_REALLOC, STBI_FREE)
• Decode from memory, FILE, or arbitrary I/O callbacks

Usage

#define STB_IMAGE_IMPLEMENTATION
#include "stb_image.h"

int width, height, channels;
unsigned char * data = stbi_load("image.png", &width, &height, &channels, 0);
// Use pixel data...
stbi_image_free(data);

Code Reference

Source Location

Repository	File	Lines
ggml-org/ggml	examples/stb_image.h	7987

Key Signatures

// Load from file
STBIDEF stbi_uc * stbi_load(char const * filename, int * x, int * y, int * channels_in_file,
    int desired_channels);

// Load from memory
STBIDEF stbi_uc * stbi_load_from_memory(stbi_uc const * buffer, int len, int * x, int * y,
    int * channels_in_file, int desired_channels);

// Load 16-bit images
STBIDEF stbi_us * stbi_load_16(char const * filename, int * x, int * y, int * channels_in_file,
    int desired_channels);

// Load HDR images (returns float)
STBIDEF float * stbi_loadf(char const * filename, int * x, int * y, int * channels_in_file,
    int desired_channels);

// Query image info without decoding
STBIDEF int stbi_info(char const * filename, int * x, int * y, int * comp);

// Free loaded image data
STBIDEF void stbi_image_free(void * retval_from_stbi_load);

I/O Contract

Inputs

• Image file -- File path, memory buffer, or I/O callbacks
• Desired channels -- 0 for original, or 1-4 for forced channel count

Outputs

• Pixel data -- Decoded image as contiguous array (left-to-right, top-to-bottom)
• Dimensions -- Width, height, and number of channels
• NULL on failure -- Returns NULL with error message via stbi_failure_reason()

Usage Examples

Loading an image for GGML inference:

#define STB_IMAGE_IMPLEMENTATION
#include "stb_image.h"

// Load image as RGB
int w, h, c;
unsigned char * img = stbi_load("input.jpg", &w, &h, &c, 3);
if (!img) {
    fprintf(stderr, "Failed to load: %s\n", stbi_failure_reason());
    return 1;
}

// Convert to float tensor for model input
for (int i = 0; i < w * h * 3; i++) {
    tensor_data[i] = img[i] / 255.0f;
}

stbi_image_free(img);

Related Pages

Implements Principle

• Principle:Ggml_org_Ggml_Image_IO

Related Implementations

• Implementation:Ggml_org_Ggml_Stb_image_write -- Companion image writing library
• Implementation:Ggml_org_Ggml_Sam_image_preprocess -- SAM example using this library