PictureSharp.Heif 0.6.2

PictureSharp.Heif

HEIC/HEIF plugin for PictureSharp, written entirely in C#.

Reads and writes HEIC, the default photo format of iPhones, on .NET 10 and later. No native libraries and no P/Invoke: the only dependency is the PictureSharp package (0.7.6 or later).

dotnet add package PictureSharp.Heif

1. Register the plugin

Register the format once at startup. After that, Image.Load, Image.Identify and Save handle .heic files like any built-in format.

using PictureSharp;
using PictureSharp.Formats.Heif;

ImageConfiguration.Default = ImageConfiguration.Default.ToBuilder()
    .AddFormat(new HeifFormat())
    .Build();

2. Decode

using var image = Image.Load("IMG_0001.heic");
Console.WriteLine($"{image.Width} × {image.Height}");

image.Mutate(x => x.Resize(1600, 0));
image.Save("photo.jpg");

Rotation, mirroring and cropping from the file are already applied, and the image keeps its alpha, ICC profile, EXIF and XMP. To read only the size or metadata without decoding pixels, use Image.Identify("IMG_0001.heic") or Image.ReadMetadata("IMG_0001.heic").

Photos and embedded previews (0.6.2)

A file may contain several photos, thumbnails and auxiliary images. Open its catalogue to select a photo or preview:

var document = await HeifDocument.OpenAsync("burst.heic",
    new HeifDocumentOptions { MaxInputBytes = 64L << 20 });
foreach (var photo in document.TopLevelImages)
    Console.WriteLine($"{photo.Id}: {photo.Name}, {photo.DisplaySize}");

using Image full = document.LoadImage(document.PrimaryImage.Id);
using Image preview = document.LoadPreview(new System.Drawing.Size(320, 240));

Opening copies the input without decoding pixels. Each read accepts its own DecoderOptions. LoadPreview chooses a matching embedded thumbnail or resizes the photo. An embedded preview can differ in framing, compression and colour; use LoadImage with TargetSize when the photo itself is required. Catalogue and relationships explain item roles, ownership and limits.

For an ID already known, Image.Load, Identify and ReadMetadata also accept new DecoderOptions { FormatOptions = [new HeifDecoderOptions { ItemId = 2 }] }; null ItemId selects the primary photo.

3. Encode

using var image = Image.Load("photo.png");
image.SaveAsHeic("photo.heic");                                          // quality 50
image.SaveAsHeic("small.heic", new HeifEncoderOptions { Quality = 35 }); // smaller file
image.SaveAsHeic("preview.heic", new HeifEncoderOptions { ThumbnailMaxDimension = 320 });

Alpha, ICC, EXIF and XMP are written too. Every option is described in encoding.

HDR photos

iPhone photos carry an HDR gain map. Ask for it while loading, then reconstruct or tone-map the HDR image:

using var photo = Image.Load("IMG_0001.heic", new DecoderOptions { LoadGainMap = true });
using HdrImage hdr = photo.ToHdr();
using Image sdr = hdr.ToneMap();

Supported

• Reading: HEVC Main, Main Still Picture and Main 10 (4:2:0 and monochrome), tile grids, alpha, rotation, mirroring and cropping, ICC/nclx colour, EXIF, XMP, HDR gain maps (Apple and ISO 21496-1).
• Writing: HEVC Main 8-bit 4:2:0, a single image or a tile grid, alpha, ICC, EXIF, XMP, optional embedded thumbnail.
• Not supported: image sequences, Live Photos, depth maps as depth data (an auxiliary depth image decodes as a plain image through HeifDecoderOptions.ItemId), 4:2:2/4:4:4, PQ/HLG, AVIF, writing gain maps and editing metadata in place (Image.EditMetadata).

PictureSharp's limits (MaxPixels, MaxInputBytes), cancellation and thumbnails while loading (TargetSize) work for HEIC as for the built-in formats.

More

• Decoding: colour conversion, HDR gain maps, metadata-only reads.
• Encoding: options, file layout, quality and speed measurements.
• Container: identification, limits and the test oracles.

Decoded pixels match the HM reference decoder and libheif's heif-dec exactly; encoded files decode identically in both.

License and patents

MIT. Ported code comes only from MIT-compatible sources (the ITU-T H.265 specification, HM and kvazaar, both BSD-3); see THIRD-PARTY-NOTICES.txt. libheif, libde265 and x265 are used only as test oracles.

HEVC is covered by patents licensed through patent pools. This package does not include a patent license; check whether your use requires one before shipping it.

Building from source

dotnet build -c Release
dotnet test -c Release