Implementation:LaurentMazare Tch rs Stb Image

Knowledge Sources	LaurentMazare_Tch_rs
Domains	Image Processing, C Libraries, Vendored Dependencies
Last Updated	2026-02-08 00:00 GMT

Overview

Three vendored single-header C libraries by Sean Barrett (stb_image.h, stb_image_write.h, stb_image_resize.h) providing image loading, writing, and resizing functionality without external dependencies.

Description

The torch-sys crate vendors three stb single-header libraries to provide lightweight image I/O capabilities. These are public domain libraries from the nothings/stb collection. They are compiled into the torch-sys binary via the #define STB_IMAGE_IMPLEMENTATION / #define STB_IMAGE_WRITE_IMPLEMENTATION / #define STB_IMAGE_RESIZE_IMPLEMENTATION preprocessor directives in torch_api.cpp.

stb_image.h (v2.21, 7,530 lines):

Decodes images from files or memory buffers
Supported formats: JPEG (baseline and progressive), PNG (1/2/4/8/16-bit), TGA, BMP (non-1bpp, non-RLE), PSD (composited view), GIF, HDR (radiance rgbE), PIC, PNM (PPM/PGM binary)
SIMD acceleration on x86/x64 (SSE2) and ARM (NEON)
Key functions: stbi_load, stbi_load_from_memory, stbi_failure_reason, stbi_image_free

stb_image_write.h (v1.11, 1,621 lines):

Writes images to files via C stdio
Supported output formats: PNG, BMP, TGA, JPEG, HDR
Key functions: stbi_write_png, stbi_write_bmp, stbi_write_tga, stbi_write_jpg, stbi_write_hdr
Also supports writing via arbitrary callbacks

stb_image_resize.h (v0.95, 2,627 lines):

Performs image scaling and translation
Uses Mitchell filter for downsampling, cubic interpolation for upsampling
Key functions: stbir_resize_uint8, stbir_resize_float, stbir_resize_uint8_srgb
Supports sRGB-aware resizing and various edge modes (clamp, wrap, reflect, zero)

These libraries are used by the torch_api.cpp image I/O functions:

at_load_image calls stbi_load to decode image files into raw pixel data, then wraps the result in a PyTorch tensor
at_load_image_from_memory calls stbi_load_from_memory for in-memory image decoding
at_save_image calls stbi_write_jpg, stbi_write_bmp, stbi_write_tga, or stbi_write_png based on the file extension
at_resize_image calls stbir_resize_uint8 to resize image tensors

Usage

These libraries are internal implementation details of the torch-sys crate. End users interact with image operations through the tch crate's tch::vision::image module. The vendored approach eliminates external dependencies on image processing libraries, making tch-rs easier to build across platforms.

Code Reference

Source Location

Repository: LaurentMazare_Tch_rs
File: torch-sys/libtch/stb_image.h (7,530 lines)
File: torch-sys/libtch/stb_image_write.h (1,621 lines)
File: torch-sys/libtch/stb_image_resize.h (2,627 lines)
Total Lines: 11,778
License: Public domain / MIT (dual-licensed)
Author: Sean Barrett (nothings.org)

Signature

// stb_image.h - Image loading
extern unsigned char *stbi_load(
    char const *filename, int *x, int *y, int *channels_in_file,
    int desired_channels);
extern unsigned char *stbi_load_from_memory(
    unsigned char const *buffer, int len,
    int *x, int *y, int *channels_in_file, int desired_channels);
extern const char *stbi_failure_reason(void);
extern void stbi_image_free(void *retval_from_stbi_load);

// stb_image_write.h - Image writing
extern int stbi_write_png(
    char const *filename, int w, int h, int comp,
    const void *data, int stride_in_bytes);
extern int stbi_write_bmp(
    char const *filename, int w, int h, int comp,
    const void *data);
extern int stbi_write_tga(
    char const *filename, int w, int h, int comp,
    const void *data);
extern int stbi_write_jpg(
    char const *filename, int w, int h, int comp,
    const void *data, int quality);
extern int stbi_write_hdr(
    char const *filename, int w, int h, int comp,
    const float *data);

// stb_image_resize.h - Image resizing
extern int stbir_resize_uint8(
    const unsigned char *input_pixels, int input_w, int input_h,
    int input_stride_in_bytes,
    unsigned char *output_pixels, int output_w, int output_h,
    int output_stride_in_bytes, int num_channels);
extern int stbir_resize_float(
    const float *input_pixels, int input_w, int input_h,
    int input_stride_in_bytes,
    float *output_pixels, int output_w, int output_h,
    int output_stride_in_bytes, int num_channels);

Import

// In torch_api.cpp - these defines trigger implementation compilation:
#define STB_IMAGE_IMPLEMENTATION
#include "stb_image.h"

#define STB_IMAGE_WRITE_IMPLEMENTATION
#include "stb_image_write.h"

#define STB_IMAGE_RESIZE_IMPLEMENTATION
#include "stb_image_resize.h"

I/O Contract

Function	Input	Output	Notes
`stbi_load`	Filename string, desired channels	Heap-allocated pixel data (`unsigned char*`), width/height/channels via output params	Caller must free with `stbi_image_free`; returns NULL on failure
`stbi_load_from_memory`	Buffer pointer + length, desired channels	Same as `stbi_load`	Decodes from in-memory buffer
`stbi_write_png`	Filename, dimensions, components, pixel data, stride	Returns non-zero on success	PNG output is not optimally compressed (20-50% larger than optimized)
`stbi_write_jpg`	Filename, dimensions, components, pixel data, quality (1-100)	Returns non-zero on success	JPEG quality parameter controls compression ratio
`stbir_resize_uint8`	Input pixels, input dims, output pixels, output dims, channels	Returns 1 on success	Performs a single malloc internally; uses Mitchell filter for downsampling

Library	Supported Formats	Direction
stb_image.h	JPEG, PNG, TGA, BMP, PSD, GIF, HDR, PIC, PNM	Read (decode)
stb_image_write.h	PNG, BMP, TGA, JPEG, HDR	Write (encode)
stb_image_resize.h	Raw pixel buffers (uint8 or float)	Transform (resize)

Usage Examples

// How torch_api.cpp uses stb_image to load images as tensors:
tensor at_load_image(char *filename) {
  PROTECT(
    int w = -1, h = -1, c = -1;
    void *data = stbi_load(filename, &w, &h, &c, 3);
    if (data == nullptr)
      throw std::invalid_argument(stbi_failure_reason());
    torch::Tensor tensor = torch::zeros({ h, w, 3 }, at::ScalarType::Byte);
    memcpy(tensor.data_ptr(), data, h * w * 3);
    free(data);
    return new torch::Tensor(tensor);
  )
  return nullptr;
}

// How torch_api.cpp uses stb_image_write to save images:
int at_save_image(tensor tensor, char *filename) {
  PROTECT(
    // ... validation ...
    if (ends_with(filename, ".jpg"))
      return stbi_write_jpg(filename, w, h, c, tensor_data, 90);
    if (ends_with(filename, ".bmp"))
      return stbi_write_bmp(filename, w, h, c, tensor_data);
    return stbi_write_png(filename, w, h, c, tensor_data, 0);
  )
  return -1;
}

// How torch_api.cpp uses stb_image_resize:
tensor at_resize_image(tensor tensor, int out_w, int out_h) {
  PROTECT(
    // ... validation ...
    torch::Tensor out = torch::zeros({ out_h, out_w, c }, at::ScalarType::Byte);
    stbir_resize_uint8(tensor_data, w, h, 0,
        (unsigned char*)out.data_ptr(), out_w, out_h, 0, c);
    return new torch::Tensor(out);
  )
  return nullptr;
}

Related Pages

Principle:LaurentMazare_Tch_rs_Vendored_Image_IO
Implementation:LaurentMazare_Tch_rs_Torch_Api_Cpp - C++ file that includes and uses these libraries
Implementation:LaurentMazare_Tch_rs_Torch_Api_H - Header declaring the image I/O functions that wrap stb

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment