SDWebImagePhotosPlugin

What it's for

SDWebImagePhotosPlugin is a plugin for the SDWebImage framework, which provides image loading support for the Photos Library.

This plugin allows you to use your familiar View Category method from SDWebImage, for loading Photos images with PHAsset or localIdentifier.

Requirements

• iOS 9+
• macOS 10.13+
• tvOS 10+
• Xcode 10+

Installation

CocoaPods

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

pod 'SDWebImagePhotosPlugin'

Carthage

SDWebImagePhotosPlugin is available through Carthage.

github "SDWebImage/SDWebImagePhotosPlugin"

Swift Package Manager (Xcode 11+)

SDWebImagePhotosPlugin is available through Swift Package Manager.

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

Usage

Important! To use this Photos Library plugin, you first need to register the photos loader to image manager.

There are two ways to register the photos loader. One is for temporarily usage (when providing URL is definitely Photos URL but not HTTP URL), and another for global support (don't need any check, supports both HTTP URL as well as Photos URL).

Use custom manager (temporarily)

You can create a custom manager for temporary usage. When you use custom manager, be sure to specify SDWebImageContextCustomManager context option with your custom manager for View Category methods.

• Objective-C

// Assign loader to custom manager
SDWebImageManager *manager = [[SDWebImageManager alloc] initWithCache:SDImageCache.sharedImageCache loader:SDImagePhotosLoader.sharedLoader];

• Swift

// Assign loader to custom manager
let manager = SDWebImageManager(cache: SDImageCache.shared, loader: SDImagePhotosLoader.shared)

Use loaders manager (globally)

You can replace the default manager's loader implementation using loaders manager to support both HTTP && Photos URL globally. Put these code just at the application launch time (or some time just before SDWebImageManager.sharedManager is initialized).

• Objective-C

// Supports HTTP URL as well as Photos URL globally
SDImageLoadersManager.sharedManager.loaders = @[SDWebImageDownloader.sharedDownloader, SDImagePhotosLoader.sharedLoader];
// Replace default manager's loader implementation
SDWebImageManager.defaultImageLoader = SDImageLoadersManager.sharedManager;

• Swift

// Supports HTTP URL as well as Photos URL globally
SDImageLoadersManager.shared.loaders = [SDWebImageDownloader.shared, SDImagePhotosLoader.shared]
// Replace default manager's loader implementation
SDWebImageManager.defaultImageLoader = SDImageLoadersManager.shared

Load Images

To start loading the Photos Library image, use the NSURL+SDWebImagePhotosPlugin to create a Photos URL and call View Category method.

• Objective-C

// Create with `PHAsset`
PHAsset *asset;
NSURL *photosURL = asset.sd_URLRepresentation;
// The same as `[NSURL sd_URLWithAsset:asset];`
// Create with `localIdentifier`
NSString *identifier;
NSURL *potosURL = [NSURL sd_URLWithAssetLocalIdentifier:identifier];

// Load image (assume using custom manager)
[imageView sd_setImageWithURL:photosURL placeholderImage:nil context:@{SDWebImageContextCustomManager: manager}];

• Swift

// Create with `PHAsset`
let asset: PHAsset
let photosURL = asset.sd_URLRepresentation
// The same as `NSURL.sd_URL(with: asset) as URL`
// Create with `localIdentifier`
let identifier: String
let potosURL = NSURL.sd_URL(withAssetLocalIdentifier: identifier) as URL

// Load image (assume using custom manager)
imageView.sd_setImage(with: photosURL, placeholderImage: nil, context: [.customManager: manager])

Animated Images

SDWebImagePhotosPlugin supports GIF images stored in Photos Library as well. Just use the same API as normal images to query the asset. We will query the image data and decode the animated images (compatible with UIImageView as well as SDAnimatedImageView)

Video Assets

SDWebImagePhotosPlugin supports loading Video Asset poster as well. By default, we don't allow non-image type assets, to avoid accidentally picking a wrong Asset. But you can disable this limit as well.

• Objective-C

SDImagePhotosLoader.sharedLoader.requestImageAssetOnly = NO;

• Swift

SDImagePhotosLoader.shared.requestImageAssetOnly = false

Then just request the PHAssets or using the fetch options, which the media type is .video.

Fetch/Request Options

To specify options like PHFetchOptions or PHImageRequestOptions for Photos Library. Either to change the correspond properties in loader, or provide a context options for each image request.

• Objective-C

// loader-level options
// ignore iCloud Shared Album (`localIdentifier` Photos URL only)
PHFetchOptions *fetchOptions = [PHFetchOptions new];
fetchOptions.predicate = [NSPredicate predicateWithFormat:@"sourceType != %d", PHAssetSourceTypeCloudShared];
SDImagePhotosLoader.sharedLoader.fetchOptions = fetchOptions;

// request-level options
// allows iCloud Photos Library
PHImageRequestOptions *requestOptions = [PHImageRequestOptions new];
requestOptions.networkAccessAllowed = YES;
[imageView sd_setImageWithURL:photosURL placeholderImage:nil context:@{SDWebImageContextPhotosImageRequestOptions: requestOptions, SDWebImageContextCustomManager: manager}];

• Swift

// loader-level options
// ignore iCloud Shared Album (`localIdentifier` Photos URL only)
let fetchOptions = PHFetchOptions()
fetchOptions.predicate = NSPredicate(format: "sourceType != %d", PHAssetSourceType.typeCloudShared.rawValue)
SDImagePhotosLoader.shared.fetchOptions = fetchOptions

// request-level options
// allows iCloud Photos Library
let requestOptions = PHImageRequestOptions()
requestOptions.networkAccessAllowed = true
imageView.sd_setImage(with: photosURL, placeholderImage: nil, context:[.photosImageRequestOptions: requestOptions, .customManager: manager])

Control Query Image Size

Photos taken by the iPhone camera may have a really large pixel size (4K+). So, if you want to load large Photos Library assets for rendering, you should specify target size with a limited size (for example, the size of the imageView that you are loading into).

By default, we query the target size that matches the original image's largest size (see: PHImageManagerMaximumSize), which may consume too much memory on iOS devices. There are also two built-in dynamic values SDWebImagePhotosPixelSize/SDWebImagePhotosPointSize which are suitable for some cases.

You can change the fetch image size by either using the PHImageRequestOptions.sd_targetSize, or Thumbnail Decoding via .imageThumbnailPixelSize context option.

Control query image size limit in global:

• Objective-C

SDImagePhotosLoader.sharedLoader.imageRequestOptions.sd_targetSize = CGSizeMake(1000, 1000); // Limit 1000x1000 pixels

• Swift

SDImagePhotosLoader.shared.imageRequestOptions.sd_targetSize = CGSize(width: 1000, height: 1000) // Limit 1000x1000 pixels

Control query image size for individual assets:

• Objective-C

UIImageView *imageView;
PHAsset *asset;
NSURL *url = asset.sd_URLRepresentation;
[imageView.sd_setImageWithURL:url options:0 context:@{SDWebImageContextImageThumbnailPixelSize: @(imageView.bounds.size)}]; // Fetch image based on image view size

• Swift

let imageView: UIImageView
let asset: PHAsset
let url = asset.sd_URLRepresentation
imageView.sd_setImage(with: url, context: [.imageThumbnailPixelSize : imageView.bounds.size]) // Fetch image based on image view size

Note: You can also use SDWebImageContextPhotosImageRequestOptions as shown above. But the thumbnail pixel size can be used for normal Network URL as well, which can help you to unify the logic for HTTP URL and PHAsset URL.

Tips

1. Images from the Photos Library are already stored on the device disk, and query speed is fast enough for small resolution images, so cache storage might be unnecessary. You can use SDWebImageContextStoreCacheType with SDImageCacheTypeNone to disable cache storage, and use SDWebImageFromLoaderOnly to disable cache queries.
2. If you use PHImageRequestOptionsDeliveryModeOpportunistic (default) to load the image, PhotosKit will return a degraded thumbnail image first and again with the full pixel image. When the image is degraded, the loader completion block will set finished = NO. However, this will not trigger the View Category completion block, and only trigger a image refresh (like progressive loading behavior for network image using SDWebImageProgressiveLoad)
3. By default, we will prefer using Photos requestImageForAsset:targetSize:contentMode:options:resultHandler: API for normal images, using requestImageDataForAsset:options:resultHandler: for animated images like GIF asset. If you need the raw image data for further image processing, you can always pass the SDWebImageContextPhotosRequestImageData context option to force using the request data API instead. Note that when requesting data, the targetSize and contentMode options are ignored. If you need smaller image sizes, consider using Image Transformer feature from SDWebImage 5.0.

Demo

If you have some issue about usage, SDWebImagePhotosPlugin provide a demo for iOS & macOS platform. To run the demo, clone the repo and run the following command.

cd Example/
pod install
open SDWebImagePhotosPlugin.xcworkspace

After the Xcode project is opened, click Run to build and run the demo.

Author

DreamPiggy, [email protected]

License

SDWebImagePhotosPlugin is available under the MIT license. See the LICENSE file for more info.