{"id":22213138,"url":"https://github.com/sdwebimage/sdwebimagephotosplugin","last_synced_at":"2026-03-03T23:02:35.997Z","repository":{"id":54915410,"uuid":"132429852","full_name":"SDWebImage/SDWebImagePhotosPlugin","owner":"SDWebImage","description":"A SDWebImage plugin to support Photos framework image loading","archived":false,"fork":false,"pushed_at":"2025-02-28T03:27:15.000Z","size":379,"stargazers_count":65,"open_issues_count":1,"forks_count":10,"subscribers_count":8,"default_branch":"master","last_synced_at":"2026-02-08T17:42:29.132Z","etag":null,"topics":["cocoapods","ios","macos","objective-c","photoslibrary","sdwebimage","tvos"],"latest_commit_sha":null,"homepage":null,"language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SDWebImage.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-05-07T08:23:10.000Z","updated_at":"2025-10-01T16:06:35.000Z","dependencies_parsed_at":"2025-06-03T19:28:43.708Z","dependency_job_id":"40427d97-be0f-4b58-bb1f-24bd5379380f","html_url":"https://github.com/SDWebImage/SDWebImagePhotosPlugin","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/SDWebImage/SDWebImagePhotosPlugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SDWebImage%2FSDWebImagePhotosPlugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SDWebImage%2FSDWebImagePhotosPlugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SDWebImage%2FSDWebImagePhotosPlugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SDWebImage%2FSDWebImagePhotosPlugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SDWebImage","download_url":"https://codeload.github.com/SDWebImage/SDWebImagePhotosPlugin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SDWebImage%2FSDWebImagePhotosPlugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30064791,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-03T18:21:05.932Z","status":"ssl_error","status_checked_at":"2026-03-03T18:20:59.341Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cocoapods","ios","macos","objective-c","photoslibrary","sdwebimage","tvos"],"created_at":"2024-12-02T21:08:41.866Z","updated_at":"2026-03-03T23:02:35.979Z","avatar_url":"https://github.com/SDWebImage.png","language":"Objective-C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SDWebImagePhotosPlugin\n\n[![CI Status](https://img.shields.io/travis/SDWebImage/SDWebImagePhotosPlugin.svg?style=flat)](https://travis-ci.org/SDWebImage/SDWebImagePhotosPlugin)\n[![Version](https://img.shields.io/cocoapods/v/SDWebImagePhotosPlugin.svg?style=flat)](https://cocoapods.org/pods/SDWebImagePhotosPlugin)\n[![License](https://img.shields.io/cocoapods/l/SDWebImagePhotosPlugin.svg?style=flat)](https://cocoapods.org/pods/SDWebImagePhotosPlugin)\n[![Platform](https://img.shields.io/cocoapods/p/SDWebImagePhotosPlugin.svg?style=flat)](https://cocoapods.org/pods/SDWebImagePhotosPlugin)\n[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-brightgreen.svg?style=flat)](https://github.com/SDWebImage/SDWebImagePhotosPlugin)\n[![SwiftPM compatible](https://img.shields.io/badge/SwiftPM-compatible-brightgreen.svg?style=flat)](https://swift.org/package-manager/)\n[![codecov](https://codecov.io/gh/SDWebImage/SDWebImagePhotosPlugin/branch/master/graph/badge.svg)](https://codecov.io/gh/SDWebImage/SDWebImagePhotosPlugin)\n\n## What it's for\nSDWebImagePhotosPlugin is a plugin for the [SDWebImage](https://github.com/rs/SDWebImage/) framework, which provides image loading support for the [Photos Library](https://developer.apple.com/documentation/photokit).\n\nThis plugin allows you to use your familiar View Category method from SDWebImage, for loading Photos images with `PHAsset` or `localIdentifier`.\n\n\n## Requirements\n\n+ iOS 9+\n+ macOS 10.13+\n+ tvOS 10+\n+ Xcode 10+\n\n## Installation\n\n#### CocoaPods\n\nSDWebImagePhotosPlugin is available through [CocoaPods](https://cocoapods.org). To install\nit, simply add the following line to your Podfile:\n\n```ruby\npod 'SDWebImagePhotosPlugin'\n```\n\n#### Carthage\n\nSDWebImagePhotosPlugin is available through [Carthage](https://github.com/Carthage/Carthage).\n\n```\ngithub \"SDWebImage/SDWebImagePhotosPlugin\"\n```\n\n#### Swift Package Manager (Xcode 11+)\n\nSDWebImagePhotosPlugin is available through [Swift Package Manager](https://swift.org/package-manager).\n\n```swift\nlet package = Package(\n    dependencies: [\n        .package(url: \"https://github.com/SDWebImage/SDWebImagePhotosPlugin.git\", from: \"1.0\")\n    ]\n)\n```\n\n## Usage\n**Important!** To use this Photos Library plugin, you first need to register the photos loader to image manager.\n\nThere 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).\n\n#### Use custom manager (temporarily)\nYou 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.\n\n+ Objective-C\n\n```objectivec\n// Assign loader to custom manager\nSDWebImageManager *manager = [[SDWebImageManager alloc] initWithCache:SDImageCache.sharedImageCache loader:SDImagePhotosLoader.sharedLoader];\n```\n\n+ Swift\n\n```swift\n// Assign loader to custom manager\nlet manager = SDWebImageManager(cache: SDImageCache.shared, loader: SDImagePhotosLoader.shared)\n```\n\n#### Use loaders manager (globally)\nYou can replace the default manager's loader implementation using [loaders manager](https://github.com/rs/SDWebImage/wiki/Advanced-Usage#loaders-manager) to support both HTTP \u0026\u0026 Photos URL globally. Put these code just at the application launch time (or some time just before `SDWebImageManager.sharedManager` is initialized).\n\n+ Objective-C\n\n```objectivec\n// Supports HTTP URL as well as Photos URL globally\nSDImageLoadersManager.sharedManager.loaders = @[SDWebImageDownloader.sharedDownloader, SDImagePhotosLoader.sharedLoader];\n// Replace default manager's loader implementation\nSDWebImageManager.defaultImageLoader = SDImageLoadersManager.sharedManager;\n```\n\n+ Swift\n\n```swift\n// Supports HTTP URL as well as Photos URL globally\nSDImageLoadersManager.shared.loaders = [SDWebImageDownloader.shared, SDImagePhotosLoader.shared]\n// Replace default manager's loader implementation\nSDWebImageManager.defaultImageLoader = SDImageLoadersManager.shared\n```\n\n#### Load Images\nTo start loading the Photos Library image, use the `NSURL+SDWebImagePhotosPlugin` to create a Photos URL and call View Category method.\n\n+ Objective-C\n\n```objectivec\n// Create with `PHAsset`\nPHAsset *asset;\nNSURL *photosURL = asset.sd_URLRepresentation;\n// The same as `[NSURL sd_URLWithAsset:asset];`\n// Create with `localIdentifier`\nNSString *identifier;\nNSURL *potosURL = [NSURL sd_URLWithAssetLocalIdentifier:identifier];\n\n// Load image (assume using custom manager)\n[imageView sd_setImageWithURL:photosURL placeholderImage:nil context:@{SDWebImageContextCustomManager: manager}];\n```\n\n+ Swift\n\n```swift\n// Create with `PHAsset`\nlet asset: PHAsset\nlet photosURL = asset.sd_URLRepresentation\n// The same as `NSURL.sd_URL(with: asset) as URL`\n// Create with `localIdentifier`\nlet identifier: String\nlet potosURL = NSURL.sd_URL(withAssetLocalIdentifier: identifier) as URL\n\n// Load image (assume using custom manager)\nimageView.sd_setImage(with: photosURL, placeholderImage: nil, context: [.customManager: manager])\n```\n\n#### Animated Images\nSDWebImagePhotosPlugin 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](https://github.com/rs/SDWebImage/wiki/Advanced-Usage#animated-image-50))\n\n\n#### Video Assets\nSDWebImagePhotosPlugin 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.\n\n+ Objective-C\n\n```objectivec\nSDImagePhotosLoader.sharedLoader.requestImageAssetOnly = NO;\n``` \n\n+ Swift\n\n```swift\nSDImagePhotosLoader.shared.requestImageAssetOnly = false\n```\n\nThen just request the PHAssets or using the fetch options, which the media type is `.video`.\n\n#### HDR Photo Rendering\nTo enable HDR decoding and rendering, upgrade SDWebImage to 5.21.0+, then, request the image data from Photos Library and turn on HDR decoding.\n\n+ Objective-C\n\n```objective-c\n#if TARGET_OS_OSX\nBOOL supportsHDR = NSScreen.mainScreen.maximumPotentialExtendedDynamicRangeColorComponentValue \u003e 1.0;\n#else\n#define NSImageDynamicRangeHigh UIImageDynamicRangeHigh\nBOOL supportsHDR = UIScreen.mainScreen.potentialEDRHeadroom \u003e 1.0;\n#endif\nSDWebImageMutableContext *context = [@{SDWebImageContextStoreCacheType: @(SDImageCacheTypeNone)} mutableCopy];\nif (supportsHDR) {\n    if (@available (macOS 14.0, iOS 17, *)) {\n        cell.imageViewDisplay.preferredImageDynamicRange = NSImageDynamicRangeHigh; // Enable Image View Level control for HDR\n    }\n    context[SDWebImageContextPhotosRequestImageData] = @(YES); // Photos Library only load HDR info when requestImageData\n    context[SDWebImageContextImageDecodeToHDR] = @(YES); // When decoding HDR data, we need explicit enable HDR decoding\n}\n// Then loading HDR assets with context option\n[imageView sd_setImageWithURL:photosURL placeholderImage:nil context:context];\n```\n\n+ Swift\n\n```swift\n#if os(macOS)\nlet supportsHDR = NSScreen.main.maximumPotentialExtendedDynamicRangeColorComponentValue \u003e 1.0\n#else\nlet supportsHDR = UIScreen.main.potentialEDRHeadroom \u003e 1.0\n#endif\nvar context = [\n    SDWebImageContextStoreCacheType: SDImageCacheType.none.rawValue\n]\nif supportsHDR {\n    if #available(macOS 14.0, iOS 17, *) {\n        cell.imageViewDisplay.preferredImageDynamicRange = .high // Enable Image View Level control for HDR\n    }\n    context[.photosRequestImageData] = true // Photos Library only load HDR info when requestImageData\n    context[.imageDecodeToHDR] = true // When decoding HDR data, we need explicit enable HDR decoding\n}\n// Then loading HDR assets with context option\nimageView.sd_setImage(with: photosURL, placeholderImage: nil, context:context)\n```\n\n#### Fetch/Request Options\nTo 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.\n\n+ Objective-C\n\n```objectivec\n// loader-level options\n// ignore iCloud Shared Album (`localIdentifier` Photos URL only)\nPHFetchOptions *fetchOptions = SDImagePhotosLoader.sharedLoader.fetchOptions;\nfetchOptions.predicate = [NSPredicate predicateWithFormat:@\"sourceType != %d\", PHAssetSourceTypeCloudShared];\n\n// request-level options\n// disable iCloud Photos Library (networkAccessAllowed defaults to YES)\nPHImageRequestOptions *requestOptions = [PHImageRequestOptions new];\nrequestOptions.networkAccessAllowed = NO;\n[imageView sd_setImageWithURL:photosURL placeholderImage:nil context:@{SDWebImageContextPhotosImageRequestOptions: requestOptions, SDWebImageContextCustomManager: manager}];\n```\n\n+ Swift\n\n```swift\n// loader-level options\n// ignore iCloud Shared Album (`localIdentifier` Photos URL only)\nlet fetchOptions = SDImagePhotosLoader.shared.fetchOptions\nfetchOptions.predicate = NSPredicate(format: \"sourceType != %d\", PHAssetSourceType.typeCloudShared.rawValue)\n\n// request-level options\n// disable iCloud Photos Library (networkAccessAllowed defaults to YES)\nlet requestOptions = PHImageRequestOptions()\nrequestOptions.networkAccessAllowed = false\nimageView.sd_setImage(with: photosURL, placeholderImage: nil, context:[.photosImageRequestOptions: requestOptions, .customManager: manager])\n```\n\n#### Control Query Image Size\nPhotos 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).\n\nBy default, we query the target size that matches the original image's largest size (see: [PHImageManagerMaximumSize](https://developer.apple.com/documentation/photokit/phimagemanagermaximumsize?language=objc)), 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.\n\nYou can change the fetch image size by either using the `PHImageRequestOptions.sd_targetSize`, or [Thumbnail Decoding](https://github.com/SDWebImage/SDWebImage/wiki/Advanced-Usage#thumbnail-decoding-550) via `.imageThumbnailPixelSize` context option.\n\nControl query image size limit in global:\n\n+ Objective-C\n\n```objective-c\nSDImagePhotosLoader.sharedLoader.imageRequestOptions.sd_targetSize = CGSizeMake(1000, 1000); // Limit 1000x1000 pixels\n```\n\n+ Swift\n\n```swift\nSDImagePhotosLoader.shared.imageRequestOptions.sd_targetSize = CGSize(width: 1000, height: 1000) // Limit 1000x1000 pixels\n```\n\nControl query image size for individual assets:\n\n+ Objective-C\n\n```objective-c\nUIImageView *imageView;\nPHAsset *asset;\nNSURL *url = asset.sd_URLRepresentation;\n[imageView.sd_setImageWithURL:url options:0 context:@{SDWebImageContextImageThumbnailPixelSize: @(imageView.bounds.size)}]; // Fetch image based on image view size\n```\n\n+ Swift\n\n```swift\nlet imageView: UIImageView\nlet asset: PHAsset\nlet url = asset.sd_URLRepresentation\nimageView.sd_setImage(with: url, context: [.imageThumbnailPixelSize : imageView.bounds.size]) // Fetch image based on image view size\n```\n\nNote: 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.\n\n\n## Tips\n\n1. 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.\n2. 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`)\n3. By default, we will prefer using Photos [requestImageForAsset:targetSize:contentMode:options:resultHandler:](https://developer.apple.com/documentation/photokit/phimagemanager/1616964-requestimageforasset?language=objc) API for normal images, using [requestImageDataForAsset:options:resultHandler:](https://developer.apple.com/documentation/photokit/phimagemanager/1616957-requestimagedataforasset?language=objc) 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](https://github.com/SDWebImage/SDWebImage/wiki/Advanced-Usage#image-transformer-50) feature from SDWebImage 5.0.\n\n## Demo\n\nIf you have some issue about usage, SDWebImagePhotosPlugin provide a demo for iOS \u0026 macOS platform. To run the demo, clone the repo and run the following command.\n\n```bash\ncd Example/\npod install\nopen SDWebImagePhotosPlugin.xcworkspace\n```\n\nAfter the Xcode project is opened, click \u003ckbd\u003eRun\u003c/kbd\u003e to build and run the demo.\n\n## Author\n\nDreamPiggy, lizhuoli1126@126.com\n\n## License\n\nSDWebImagePhotosPlugin is available under the MIT license. See the LICENSE file for more info.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsdwebimage%2Fsdwebimagephotosplugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsdwebimage%2Fsdwebimagephotosplugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsdwebimage%2Fsdwebimagephotosplugin/lists"}