How Headroom Image Compression Works with the ML Router and Tile Optimizer

Headroom compresses images through a coordinated two-stage pipeline: first, the Tile Optimizer resizes images to 512-pixel multiples and converts formats, then the ML Router selects the optimal compression model based on image metadata and estimated token costs.

The open-source chopratejas/headroom repository implements an intelligent image compression system designed to reduce token costs for LLM APIs while preserving visual fidelity. By combining deterministic tile alignment with machine learning-based routing, the system optimizes images before they reach language models, creating predictable token budgets for image-heavy requests.

The Two-Stage Compression Architecture

Headroom processes images through two distinct phases that work together to minimize byte size while maintaining quality. This architecture separates geometric preprocessing from content-aware compression.

Stage 1: Tile Alignment with the Tile Optimizer

Before any machine learning model processes the image, the Tile Optimizer (located in headroom/image/tile_optimizer.py) prepares the raw bytes through deterministic geometric operations.

The optimizer scans incoming image dimensions and computes the smallest integer number of 512-pixel tiles that can cover the image. It then pads or crops the picture so that width and height become exact multiples of 512. This alignment allows downstream ML models to treat the image as a fixed-size grid, dramatically reducing encoding complexity while preserving visual fidelity.

During this phase, the system also re-encodes the image (for example, converting JPEG to PNG) to a format optimized for the chosen tile size. The TileOptimizer.align_to_tiles() method handles this transformation, returning a padded image object ready for the ML pipeline.

Stage 2: ML-Based Routing

After tile alignment, Headroom hands the image to the ML Router to determine the optimal compression strategy. The router code resides in two files: headroom/image/trained_router.py (primary path) and headroom/image/onnx_router.py (ONNX fallback).

The router inspects image metadata—including format, size, and estimated token cost—and decides which compression technique to apply. Small images that fit within a single tile may skip additional processing, as the tile optimizer already yields an acceptable token budget. For larger images, the router selects a pre-trained ONNX model based on the image's "detail level": high-detail images receive models that preserve texture, while low-detail images get higher-compression variants.

Orchestration and Token Cost Management

The ImageCompressor class in headroom/image/compressor.py coordinates the entire workflow, exposing a single compress() method that downstream components call.

When the image_optimize configuration flag is enabled, the compressor first estimates token costs via estimate_openai_tokens() in headroom/tokenizers/base.py. This estimation determines whether tiling alone suffices or if the system should delegate to the ML Router. For example, the OpenAI proxy handler in headroom/proxy/handlers/openai.py triggers this compression pipeline when processing image uploads.

The orchestration follows this flow:

1. User message arrives at the proxy handler
2. ImageCompressor.compress() receives the raw bytes
3. TileOptimizer.align_to_tiles() performs 512-pixel alignment
4. MLRouter.route() selects the compression model (or skips if unnecessary)
5. Compressed bytes return to the caller

Implementation Examples

Basic Usage with ImageCompressor

Use the ImageCompressor class directly to process image bytes before sending them to an LLM API:

from headroom.image.compressor import ImageCompressor

def maybe_compress(image_bytes: bytes) -> bytes:
    compressor = ImageCompressor()
    # Returns compressed image or original if compression is disabled

    return compressor.compress(image_bytes).bytes

Direct Tile Optimization

Access the tile alignment logic directly when you need fine-grained control over the 512-pixel grid:

from headroom.image.tile_optimizer import TileOptimizer

tiles = TileOptimizer.align_to_tiles(
    image_bytes,   # raw image bytes

    tile_size=512  # default tile size used throughout Headroom

)

# `tiles` now contains a padded image with dimensions as multiples of 512

Manual ML Routing

While the ImageCompressor handles routing automatically, you can interact with the router directly for custom compression workflows:

from headroom.image.trained_router import TrainedRouter

router = TrainedRouter()
compressed = router.route(tiles)  # returns a compressed image object

Summary

• Headroom image compression operates through two coordinated stages: deterministic tile alignment followed by ML-based routing.
• The Tile Optimizer in headroom/image/tile_optimizer.py resizes images to 512-pixel multiples and handles format conversion, creating efficient grid structures for downstream processing.
• The ML Router chooses between trained_router.py and onnx_router.py implementations based on image characteristics, selecting models that balance compression ratio against detail preservation.
• Token cost estimation via estimate_openai_tokens() in headroom/tokenizers/base.py determines whether to apply ML compression or skip processing for small images.
• The ImageCompressor class in headroom/image/compressor.py provides a unified entry point that proxy handlers call to orchestrate the entire pipeline.

Frequently Asked Questions

What is the default tile size used by Headroom's Tile Optimizer?

Headroom uses a 512-pixel tile size as the default grid unit. The TileOptimizer.align_to_tiles() method automatically pads or crops images so that both width and height become exact multiples of 512, ensuring compatibility with the downstream ML models' expected input dimensions.

How does the ML Router decide which compression model to use?

The ML Router analyzes image metadata including format, dimensions, and estimated token cost to determine the compression strategy. For images classified as high-detail, it selects models that preserve texture; for low-detail images, it chooses higher-compression models. The router implementation in headroom/image/trained_router.py handles these decisions, falling back to headroom/image/onnx_router.py when native model execution is unavailable.

Can I use Headroom's image compression without the ML Router?

Yes. When the image_optimize flag is disabled, the ImageCompressor bypasses processing entirely, returning original bytes untouched. Additionally, if token cost estimation indicates an image fits within a single 512-pixel tile, the system may skip ML routing and return the tile-optimized image directly without applying learned compression models.

Where does the image compression occur in the request lifecycle?

Image compression occurs within the proxy layer before the request reaches the LLM API. Specifically, the OpenAI proxy handler in headroom/proxy/handlers/openai.py instantiates ImageCompressor and calls compress() on image attachments, ensuring optimized bytes travel to the language model while maintaining the original message structure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}