Skip to content
VIPS HandbookVIPS Handbook

Build your first complete image pipeline

Copy page

A production image pipeline is more than a chain of image methods. It constrains the input before expensive pixel work, verifies facts after output, and leaves binding versions, timing, and failure stages for logs and monitoring.

Six stages

Section titled “Six stages”
Stage Decision Minimum evidence
1. Accept Allowed sources, byte limits, and timeouts Input identity and byte count
2. Probe Format, dimensions, pages, orientation, and colour data Normalized metadata
3. Normalize EXIF Orientation, alpha, and working colour space Predictable internal image
4. Transform Resize/crop order, enlargement, and background policy Target canvas
5. Encode Format, quality, metadata, and profile policy Original output file
6. Verify Format, dimensions, pages, file size, and readability Verification record

The Quickstart now executes one minimal path through these stages: it reads the project-owned JPEG, creates a no-upscale WebP thumbnail with govips, and records dimensions, format, byte size, and tool versions.

Gate of the Orient JPEG entering the minimal image pipeline
Accept and probe1938 × 1292 JPEG, 610,191 bytes
The 640-pixel night-scene thumbnail after resize and WebP encoding
Transform, encode, and verify640 × 427 WebP, 36,172 bytes

These results prove the basic path runs. It does not yet implement this page's untrusted-input limits, orientation normalization, or failure-stage observability, so it is not a complete production pipeline.

Probe before deciding

Section titled “Probe before deciding”

Do not select a loader from the filename extension alone. Compare detected format, dimensions, and page count with application limits, and reject oversized inputs before a costly full decode. For animated and multi-page inputs, explicitly process all pages, select the first page, or reject the input.

Normalization is not one fixed template

Section titled “Normalization is not one fixed template”

The older Chinese notes treated the loaded ImageRef as the starting point for later operations. That model remains useful, but production code must also decide:

  • whether EXIF Orientation is applied before cropping;
  • whether translucent pixels need premultiplication before resize or composition;
  • which destination colour space is used for CMYK or embedded-ICC inputs;
  • whether enlargement is allowed and how an out-of-bounds crop behaves.

Output must be verifiable

Section titled “Output must be verifiable”

Read the output header again and check at least format, dimensions, channels, page count, and file size, and confirm the output can be decoded again. Bindings can differ in their defaults for encoding parameters (quality, interpolation, colour space), so confirm these explicitly per binding in production instead of assuming identical results.

Observe the failure stage

Section titled “Observe the failure stage”

Logs should distinguish probe, load, normalize, transform, encode, and verify. Record both the binding and actual libvips versions so missing codecs, corrupt input, and invalid parameters do not collapse into one generic failure.

Continue from here

Section titled “Continue from here”

Sources

Section titled “Sources”