SDWebImageHEIFCoder

4.x compatibility

SDWebImage 5.x change the custom image coder API. This master branch follow the 5.x branch of SDWebImage. For 4.x compatibility HEIF coder support, checkout 4.x branch.

What's for

This is a SDWebImage coder plugin to add High Efficiency Image File Format (HEIF) support. Which is built based on the open-sourced libheif codec.

This HEIF coder plugin currently support HEIF single/still image decoding as well as HEIC image encoding.

The decoding supports HDR HEIF image with 10/12 bit depth (larger than normal 8 bit) as well.

It support iOS 9+/macOS 10.11+ device without the dependency of Apple's Image/IO framework.

For iOS 8+/macOS 10.10+, use version lower than 0.10.0.

Performance

Apple's Image/IO framework supports Hardware-Accelerated HEIF decoding (A9+ chip) and encoding on (A10+ chip). And provide a backup Software decoding and encoding on all iOS 11+/macOS 10.13+ devices.

This coder is used for backward-compatible solution. And the codec only do Software decoding / encoding, which is slower than Image/IO. So if possible, choose to use Image/IO (SDWebImage's built-in coder) firstly.

Requirements

• iOS 9.0
• tvOS 9.0
• macOS 10.11
• watchOS 2.0
• Xcode 11.0

Installation

CocoaPods

SDWebImageHEIFCoder is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'SDWebImageHEIFCoder'

SDWebImageHEIFCoder contains subspecs libde265 & libx265. Which integrate the codec plugin for libheif to support HEIF image decoding/encoding.

To enable HEIF decoding, you should add libde265 subspec:

pod 'SDWebImageHEIFCoder/libde265'

To enable HEIF encoding, you should add libx265 subspec:

pod 'SDWebImageHEIFCoder/libx265'

By default will contains only libde265 subspec for most people's usage. Using libx265 encoding subspec only if you want HEIF encoding.

Carthage

SDWebImageHEIFCoder is available through Carthage.

Carthage does not support like CocoaPods' subspec, since most of user use HEIF decoding without x265 library. The framework through Carthage only supports libde265 for HEIF decoding.

github "SDWebImage/SDWebImageHEIFCoder"

Swift Package Manager (Xcode 11+)

SDWebImageHEIFCoder is available through Swift Package Manager.

The framework through SwiftPM only supports libde265 for HEIF decoding.

let package = Package(
    dependencies: [
        .package(url: "https://github.com/SDWebImage/SDWebImageHEIFCoder.git", from: "0.6")
    ]
)

Usage

Add Coder

To use HEIF coder, you should firstly add the SDImageHEIFCoder.sharedCoder to the coders manager. You can also detect the target platform compatibility for HEIF and choose add coder.

• Objective-C

if (@available(iOS 11.0, macOS 10.13, tvOS 11.0, *)) {
    // These version supports Image/IO built-in decoding
} else {
    // Don't support HEIF decoding, add coder
    SDImageHEIFCoder *HEIFCoder = [SDImageHEIFCoder sharedCoder];
    [[SDImageCodersManager sharedManager] addCoder:HEIFCoder];
}

• Swift

if #available(iOS 11.0, macOS 10.13, tvOS 11.0, *) {
    // These version supports Image/IO built-in decoding
} else {
    // Don't support HEIF decoding, add coder
    let HEIFCoder = SDImageHEIFCoder.shared
    SDImageCodersManager.shared.addCoder(HEIFCoder)
}

Loading

Then you can call the View Category method to start load HEIF images.

• Objective-C

UIImageView *imageView;
[imageView sd_setImageWithURL:url];

• Swift

let imageView: UIImageView
imageView.sd_setImage(with: url)

Decoding

SDImageHEIFCoder currently supports decode the static HEIF images.

Note HEIF sequence images(.heics) is not supported currently, only supported in built-in coder from SDWebImage for iOS 13+/macOS 10.15+, also supported by Safari and WebKit.

• Objective-C

// HEIF image decoding
NSData *heifData;
UIImage *image = [[SDImageHEIFCoder sharedCoder] decodedImageWithData:heifData options:nil];

• Swift

// HEIF image decoding
let heifData: Data
let image = SDImageHEIFCoder.shared.decodedImage(with: data, options: nil)

Thumbnail Decoding (0.7.0+)

HEIF image container supports embed thumbnail image. If we can found a suitable thumbnail image, we pick that instead for quickly display, else we will decode full pixel image and scale down.

• Objective-C

// HEIF thumbnail image decoding
NSData *heifData;
CGSize thumbnailSize = CGSizeMake(300, 300);
UIImage *thumbnailImage = [[SDImageHEIFCoder sharedCoder] decodedImageWithData:heifData options:@{SDImageCoderDecodeThumbnailPixelSize : @(thumbnailSize}];

• Swift

// HEIF thumbnail image decoding
let heifData: Data
let thumbnailSize = CGSize(width: 300, height: 300)
let image = SDImageHEIFCoder.shared.decodedImage(with: data, options: [.decodeThumbnailPixelSize: thumbnailSize])

Encoding

SDWebImageHEIFCoder also support HEIF encoding (need x265 subspec). You can encode UIImage to HEIF compressed image data.

• Objective-C

UIImage *image;
NSData *imageData = [image sd_imageDataAsFormat:SDImageFormatHEIF];
// Encode Quality
NSData *lossyData = [[SDImageHEIFCoder sharedCoder] encodedDataWithImage:image format:SDImageFormatHEIF options:@{SDImageCoderEncodeCompressionQuality : @(0.1)}]; // [0, 1] compression quality
NSData *limitedData = [[SDImageHEIFCoder sharedCoder] encodedDataWithImage:image format:SDImageFormatHEIF options:@{SDImageCoderEncodeMaxFileSize : @(1024 * 10)}]; // v0.8.0 feature, limit output file size <= 10KB

• Swift

let image;
let imageData = image.sd_imageData(as: .HEIF)
// Encode Quality
let lossyData = SDImageHEIFCoder.shared.encodedData(with: image, format: .heif, options: [.encodeCompressionQuality: 0.1]) // [0, 1] compression quality
let limitedData = SDImageHEIFCoder.shared.encodedData(with: image, format: .heif, options: [.encodeMaxFileSize: 1024 * 10]) // v0.8.0 feature, limit output file size <= 10KB

Thumbnail Encoding (0.8.0+)

• Objective-C

// HEIF image thumbnail encoding
UIImage *image;
NSData *thumbnailData = [[SDImageHEIFCoder sharedCoder] encodedDataWithImage:image format:SDImageFormatHEIF options:@{SDImageCoderEncodeMaxPixelSize : @(CGSizeMake(200, 200)}, SDImageCoderEncodeEmbedThumbnail : @(YES)];
// v0.8.0 feature, encoding max pixel size
// v0.9.0 feature, control whether to embed thumbnail (max 320x320 pixels)

• Swift

// HEIF image thumbnail encoding
let image: UIImage
let thumbnailData = SDImageHEIFCoder.shared.encodedData(with: image, format: .heif, options: [.encodeMaxPixelSize: CGSize(width: 200, height: 200), .encodeEmbedThumbnail : true])
// v0.8.0 feature, encoding max pixel size
// v0.9.0 feature, control whether to embed thumbnail (max 320x320 pixels)

See more documentation in SDWebImage Wiki - Coders

Screenshot

The images are from HEIF official site example

Author

DreamPiggy, [email protected]

License

SDWebImageHEIFCoder itself is available under the MIT license. See the LICENSE file for more info. However, when using libx265, the license will be subject to GPL licence (or commercial licence if you have one). Check x265.org for more information.

Thanks

• libheif
• libde265
• libx265