HEIF/HEIC image codec for PascalAI. Read Apple iPhone photos (.heic), encode images in HEIF format with HEVC or AV1 compression — better quality at half the JPEG file size. Supports HDR, wide color, thumbnails, depth maps, and embedded EXIF/XMP metadata.
CLib package — Ubuntu/Debian: sudo apt install libheif-dev
ppm install libheif
Copy
Quick Start
Read an iPhone HEIC photo
uses libheif;
{ One-shot convert to RGBA }
var w, h: Integer;
var rgba := HeicToRGBA ('/photos/IMG_1234.heic' , w, h);
WriteLn ('Size: ' + IntToStr (w) + 'x' + IntToStr (h));
WriteLn ('Pixels: ' + IntToStr (Length (rgba)) + ' bytes' );
{ Or convert to PNG/JPEG }
HeicToPNG ('/photos/IMG_1234.heic' , '/output/photo.png' );
HeicToJPEG ('/photos/IMG_1234.heic' , '/output/photo.jpg' , 90 );Read with metadata access
uses libheif;
var ctx := OpenFile ('/photos/burst.heic' );
WriteLn ('Images in file: ' + IntToStr (ImageCount (ctx)));
var h := GetPrimaryHandle (ctx);
var info := GetInfo (h);
WriteLn ('HDR: ' + BoolToStr (info.IsHDR));
{ Read EXIF data }
var exif := GetEXIF (h);
var xmp := GetXMP (h);
var rgba := DecodeRGBA (h);
FreeHandle (h);
FreeContext (ctx);Encode HEIF (requires x265 or AV1 encoder plugin)
uses libheif;
if CanEncode ('hevc' ) then
begin
var opts: THeifEncodeOptions;
opts.Quality := 85 ;
opts.Lossless := False ;
opts.Threads := 4 ;
opts.Codec := 'hevc' ;
EncodeRGBAToFile (rgbaBytes, 4032 , 3024 , '/output/photo.heic' , opts);
end ;
Open/Close API
Function Signature Description
OpenFile OpenFile(path: string): THeifContext Load a HEIF/HEIC file from disk into a context. Supports .heic, .heif, and .avif extensions. OpenBytes OpenBytes(data: TBytes): THeifContext Load a HEIF file from an in-memory byte array. FreeContext FreeContext(ctx: THeifContext) Release all resources held by the context. Always call when done. ImageCount ImageCount(ctx: THeifContext): Integer Return the number of top-level images (items) in the file. Burst photos may contain many.
Handle API
Function / Field Type Description
GetImageHandle GetImageHandle(ctx: THeifContext; index: Integer): THeifHandle Get a handle to the image at the given 0-based index. GetPrimaryHandle GetPrimaryHandle(ctx: THeifContext): THeifHandle Get a handle to the primary (main) image. Equivalent to the photo you see in the camera roll. FreeHandle FreeHandle(h: THeifHandle) Release the handle. The parent context remains valid. GetInfo GetInfo(h: THeifHandle): THeifInfo Read image properties without fully decoding the pixel data. THeifInfo.Width Integer Image width in pixels. THeifInfo.Height Integer Image height in pixels. THeifInfo.IsHDR Boolean True if the image has more than 8 bits per channel (HDR content). THeifInfo.HasAlpha Boolean True if an alpha channel is present. THeifInfo.BitDepth Integer Bits per channel (8, 10, or 12). THeifInfo.ColorProfile string Color profile name (e.g., "sRGB", "Display P3").
Decode API
Function Signature Description
DecodeRGB DecodeRGB(h: THeifHandle): TBytes Decode to a flat RGB byte array (width × height × 3 bytes). DecodeRGBA DecodeRGBA(h: THeifHandle): TBytes Decode to a flat RGBA byte array (width × height × 4 bytes). DecodeGray DecodeGray(h: THeifHandle): TBytes Decode to grayscale (width × height × 1 byte per pixel). DecodeImage DecodeImage(h: THeifHandle; colorspace: THeifColorspace): THeifImage Decode to a structured image object with named planes. FreeImage FreeImage(img: THeifImage) Release a decoded THeifImage object. GetImagePlane GetImagePlane(img: THeifImage; channel: THeifChannel): TBytes Extract a single channel plane (hcY, hcCb, hcCr, hcR, hcG, hcB, hcAlpha) from a decoded image.
Thumbnail API
Function Signature Description
ThumbnailCount ThumbnailCount(h: THeifHandle): Integer Return the number of embedded thumbnails for this image. iPhone photos typically include one. GetThumbnail GetThumbnail(h: THeifHandle; index: Integer): THeifHandle Get a handle to the thumbnail at the given index. Decode it with DecodeRGBA or DecodeRGB as usual.
Encode API
Encoder plugins required: HEVC encoding requires sudo apt install libde265-dev x265 and a libheif build with HEVC write support. AV1 encoding requires sudo apt install libaom-dev.
Function / Field Type / Signature Description
EncodeRGBToFile EncodeRGBToFile(data: TBytes; w, h: Integer; path: string; opts: THeifEncodeOptions) Encode a flat RGB byte array to a HEIF file on disk. EncodeRGBAToFile EncodeRGBAToFile(data: TBytes; w, h: Integer; path: string; opts: THeifEncodeOptions) Encode a flat RGBA byte array to a HEIF file on disk. EncodeRGBToBytes EncodeRGBToBytes(data: TBytes; w, h: Integer; opts: THeifEncodeOptions): TBytes Encode to HEIF and return the result as an in-memory byte array. THeifEncodeOptions.Quality Integer (1–100) Visual quality level. 85 is a good default for photographs. THeifEncodeOptions.Lossless Boolean When True, forces lossless encoding (Quality is ignored). THeifEncodeOptions.Threads Integer Number of encoder threads. Use 0 for automatic (hardware concurrency). THeifEncodeOptions.Codec string ('hevc' or 'av1') Compression codec to use. 'hevc' for maximum compatibility, 'av1' for best compression.
Metadata API
Function Signature Description
GetEXIF GetEXIF(h: THeifHandle): TBytes Extract the raw EXIF block as bytes. Parse with a dedicated EXIF library (e.g. libexif) for tag-level access. GetXMP GetXMP(h: THeifHandle): string Extract the XMP metadata block as a UTF-8 XML string. GetICCProfile GetICCProfile(h: THeifHandle): TBytes Extract the embedded ICC color profile as raw bytes. Returns empty array if no profile is present.
Conversion Helpers
Function Signature Description
HeicToRGBA HeicToRGBA(path: string; out w, h: Integer): TBytes One-shot: open, decode primary image to RGBA, close. Returns pixel bytes and sets w/h. HeicToPNG HeicToPNG(heicPath, pngPath: string) One-shot: convert the primary image of a HEIC file to a PNG file. HeicToJPEG HeicToJPEG(heicPath, jpegPath: string; quality: Integer) One-shot: convert the primary image of a HEIC file to a JPEG file at the given quality (1–100).
Codec Support
Function Signature Description
CanDecode CanDecode(codec: string): Boolean Return True if the named codec (e.g. 'hevc', 'av1') is available for decoding in the current libheif build. CanEncode CanEncode(codec: string): Boolean Return True if the named codec is available for encoding. Always check before calling EncodeRGBAToFile. ListDecoders ListDecoders(): array of string Return the names of all available decode plugins. ListEncoders ListEncoders(): array of string Return the names of all available encode plugins.
Installing codec plugins (Ubuntu) sudo apt install libde265-dev •
HEVC encode: sudo apt install x265 •
AV1 decode/encode: sudo apt install libaom-dev
HEIF vs JPEG
Feature HEIF/HEIC JPEG
File size (same quality) ~50% smaller Baseline HDR support Yes (10-bit, 12-bit) No (8-bit only) Wide color gamut Yes (Display P3) sRGB only Multi-image (burst) Yes No Depth maps Yes No Browser support Partial (Safari only) Universal Encoding speed Slower (HEVC/AV1) Fast