PictureSharp.Heif 0.6.8

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
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

Portrait blur and Photos edits

iPhone stores a Portrait photo sharp and blurs the background only on display, and Photos keeps the edits of its "Adjust" sliders in its library, so a converted photo has neither. Two approximations fitted to Photos exports bring them back:

using Image portrait = document.RenderPortrait(photo);                    // blur from the disparity map and matte
using Image edited = HeifPhotosEdit.Render(portrait, new HeifPhotosAdjustments { Brightness = 25, Warmth = 10 });

The slider values are not stored in a readable form, so the application supplies them. Neither result matches 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.8 release notes: Photos adjustment sliders.

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