Awesome
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
<img src="https://raw.githubusercontent.com/SDWebImage/SDWebImageHEIFCoder/master/Example/Screenshot/HEIFDemo.png" width="300" /> <img src="https://raw.githubusercontent.com/SDWebImage/SDWebImageHEIFCoder/master/Example/Screenshot/HEIFDemo-macOS.png" width="600" />The images are from HEIF official site example
Author
DreamPiggy, lizhuoli1126@126.com
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.