Use this page for a quick lookup of a term, an error string, or an authoritative source. It is organised in three parts: glossary, error-message index, and external resources.
| Term |
Definition |
| libvips |
A high-performance image-processing library written in C that processes large images with low memory overhead through demand-driven evaluation and a thread pool. |
| Demand-driven evaluation |
An execution model that builds a processing graph first and computes only the requested regions when an exporter or downstream consumer reads pixels. |
| Materialisation |
Fully decoding and buffering an image into memory or a temporary file so that subsequent random-access operations can read pixels in any order. |
| ImageRef |
govips’ CGO handle owning a libvips VipsImage*; every successfully created handle must be released with Close(). |
| multi-page / pages |
Models GIF, animated WebP/AVIF, PDF, and multi-page TIFF uniformly as multi-page images; n=1 loads only the first page, n=-1 loads all pages. |
| NumPages |
govips import parameter (ImportParams.NumPages) controlling how many pages or frames are read. |
| toilet-roll |
Frame misalignment seen when an animation is resized or rotated without loading all pages or maintaining page-height. |
| ICC profile |
A colour-characteristic profile that defines how pixel values are interpreted and keeps colour reproduction consistent across devices and colour spaces. |
| CMYK |
Cyan/magenta/yellow/black ink-separation channels; transform CMYK to a working colour space such as sRGB via an ICC profile before resizing. |
| StripMetadata |
Whether EXIF/IPTC/ICC metadata is stripped on export; defaults to false in govips. |
| EXIF / IPTC |
Embedded image metadata such as camera settings, orientation, and copyright. |
| Alpha & premultiplication |
The transparency channel and the step of scaling colour channels by alpha before interpolation or blur to prevent dark fringes. |
| side-effect import |
Importing a Go package solely for its init() registration (e.g. _ "image/png"). govips v2.19.0 already registers Go’s GIF, JPEG, PNG, and WebP decoders internally, so application code does not need extra imports for govips. |
| comparison-pending |
Indicates that an example across bindings has been run, while pixel-for-pixel equivalence or default-parameter alignment is not asserted. |
| Error or symptom |
Meaning and where to debug |
VipsJpeg: out of order read |
A sequential input encountered a vertical flip, rotation, or second consumer that requires random access. → Diagnosing out of order read |
image: unknown format |
Header signature was not recognised by govips (truncated file, unrecognised animated sub-format), or libvips lacked a native loader and the Go fallback could not decode it. → Unknown formats and codecs |
xxxsave not found / xxxload not found |
Runtime libvips is too old or was built without the optional codec library. → Unknown formats and codecs, Install, linking, and ABI |
bad grid geometry / tall single image |
Whole-image operation on an animation without NumPages=-1, or joining frames without SetPageHeight. → Animation and multi-page images |
Wrong JPEG library version |
Compile-time and runtime libjpeg versions conflict. → Install, linking, and ABI |
Segfault / SIGSEGV under concurrency |
Sharing a non-thread-safe ImageRef across goroutines or closing a source image too early. → Concurrency and ImageRef |
| Growing RSS |
Unclosed ImageRef handles, unbounded cache warm-up, or native allocator fragmentation. → Growing RSS and memory leaks |
GIF Quality has no effect |
Native gifsave uses a palette encoder and ignores JPEG-style Quality; use Effort and Bitdepth instead. → GIF Quality has no effect |
| Colour shift or WebP drops ICC |
CMYK was resized before ICC conversion, or WebP export hit the known ICC-dropping edge. → Colour, ICC, and CMYK |
- Term definitions defer to the official source and documentation; this page is a fast index for production debugging.
- The error-message index points to the matching troubleshooting page in this handbook; see those pages for full reproduction steps and version boundaries.
