Skip to main content

Image format (.png, .jpg, .jpeg, .gif, .bmp, .tif, .tiff, .webp, .heic, .heif, .avif)

The Image format reads raster images as documents. PNG and JPEG decode natively; GIF, BMP, TIFF and WebP decode in-core (pure Go); and the ISOBMFF still images HEIC/HEIF and AVIF are transcoded with ffmpeg (the kapi-av bundle) when it is available, degrading to a Media-only asset when it is not. The image itself is always emitted as a Media part by reference — the pixel bytes are never loaded into the kapi process — so an image is a valid, inspectable document even with no OCR engine installed. This is the whole-image localization mode: the picture is an asset to be replaced rather than read.

When the kapi-vision plugin is installed and ocr is enabled, the reader recognizes in-image text and emits positioned text Blocks, recovering tier-2 structure (headings, paragraphs, tables) from the OCR line geometry the same way the PDF geometry path does. With layout enabled it uses ML layout detection (regions + reading order) when the engine supports it, falling back to geometric inference otherwise.

An <image>.alt.txt sidecar beside the source supplies alt-text / caption copy: it is attached to the Media and emitted as a caption Block that translates through the normal block path; the writer folds the localized text back into a per-locale sidecar. Embedded metadata (PNG text chunks, XMP) is read without decoding pixels and mapped onto the document layer.

IDimage
SourceBuilt-in
Extensions.png, .jpg, .jpeg, .gif, .bmp, .tif, .tiff, .webp, .heic, .heif, .avif
MIME Typesimage/png, image/jpeg, image/gif, image/bmp, image/tiff, image/webp, image/heic, image/heif, image/avif
CapabilitiesRead + Write

This format has no configurable parameters.

Processing notes

  • The image is always emitted as a Media part by reference; OCR Blocks are additive enrichment and OCR failures are non-fatal.

  • Formats the vision engine can't read natively are normalized to PNG before OCR — GIF/BMP/TIFF/WebP in-core, HEIC/AVIF via ffmpeg — while the emitted Media keeps the original bytes.

  • Alt-text / caption copy travels through the standard block path — no special tool support — and is written back to a per-locale <image>.alt.txt sidecar.

Limitations

  • PNG/JPEG/GIF/BMP/TIFF are detected by magic-byte prefix; WebP and the ISOBMFF still images HEIC/HEIF and AVIF by content sniff (their markers sit past offset 0 and share the RIFF/ftyp container with audio/video).

  • OCR of HEIC/HEIF and AVIF requires ffmpeg (the kapi-av bundle or PATH) to transcode the frame; without it those images are still emitted as a Media asset but are not OCR'd.

  • OCR and layout require the kapi-vision plugin; without it the image is a Media asset only.

← Back to the Format Reference