PictureSharp.Heif 0.6.7

PictureSharp.Heif

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

Reads and writes HEIC on .NET 10+ with PictureSharp 0.7.6+. No native libraries or P/Invoke.

dotnet add package PictureSharp.Heif

Use

Register the format once; Image.Load, Identify, ReadMetadata and Save then handle .heic:

using PictureSharp;
using PictureSharp.Formats.Heif;

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

using var image = Image.Load("photo.heic");     // rotation, crop, alpha, ICC, EXIF and XMP applied
image.Mutate(x => x.Resize(1600, 0));
image.SaveAsHeic("small.heic", new HeifEncoderOptions { Quality = 60 });

A library can pass its own configuration through DecoderOptions.Configuration and HeifEncoderOptions.Configuration instead of changing the default.

Inside the file

An iPhone HEIC holds more than one picture: tiles, thumbnails, a depth map, mattes and an HDR gain map. HeifDocument lists them without decoding pixels:

var document = await HeifDocument.OpenAsync("IMG_6655.HEIC");
HeifItemInfo photo = document.PrimaryImage;

using Image preview = document.LoadPreview(photo, new(320, 240));        // embedded thumbnail when one fits
using Image portrait = document.RenderPortrait(photo);                    // Portrait background blur
HeifDepthImage depth = document.LoadDepth(photo.FindDepthImage()!);       // raw depth or disparity samples
using Image map = depth.ToImage();                                         // the depth map as a greyscale image

using var withMap = Image.Load("IMG_6655.HEIC", new DecoderOptions { LoadGainMap = true });
using HdrImage hdr = withMap.ToHdr();                                     // HDR from the gain map

LivePhotoPair pair = LivePhotoPair.Read("IMG_8113.HEIC", "IMG_8113.MOV"); // Matched by ContentIdentifier

iPhone stores Portrait photos sharp and blurs them only when displaying, so a converted photo has no blur. RenderPortrait approximates the effect from the disparity map and the subject matte; it does not match Photos exactly.

Support

Limits (MaxPixels, MaxInputBytes, MaxMetadataBytes), cancellation and TargetSize work as for built-in formats. Decoded pixels match the HM reference decoder and libheif.

Guides: decoding · encoding · container and catalogue

0.6.7 release notes: portrait focus, hair and bokeh improvements and faster, machine-independent rendering; details with side-by-side iPhone / 0.6.6 / 0.6.7 comparisons.

0.6.6 release notes: faster HEVC decoding and encoding, with measured quality and speed comparisons.

License and patents

MIT. Ported code follows H.265, HM and kvazaar (BSD-3); see THIRD-PARTY-NOTICES.txt. libheif, libde265 and x265 are used only as test oracles. HEVC may require a patent license, which this package does not include.

Build

dotnet build -c Release
dotnet test -c Release