jsooriah / dfimagemanager

Advanced framework for managing images

Advanced framework for loading, caching, processing, displaying and preheating images. It uses latest advancements in iOS SDK and doesn't reinvent existing technologies.

DFImageManager is a pipeline that loads images using multiple dependencies which can be injected in runtime. It features multiple subspecs that integrate things like FLAnimatedImage, libwebp, and more.

Programming in Swift? Try Nuke.

1. Getting Started
2. Usage
3. Design
4. Installation
5. Requirements
6. Supported Image Formats
7. Contribution

Features

• Zero config
• Works great with both Objective-C and Swift
• Performant, asynchronous, thread safe
• Comprehensive unit test coverage

Loading

• Uses NSURLSession with HTTP/2 support
• Has optional AFNetworking integration, combine the power of both frameworks!
• Uses a single fetch operation for multiple equivalent requests
• Intelligent preheating of images close to the viewport

Caching

• Doesn't reinvent caching, relies on HTTP cache and its implementation in Foundation
• Caching is completely transparent to the client
• Two cache layers, including top level memory cache for decompressed images

Decoding and Processing

• Animated GIF support using best-in-class FLAnimatedImage library
• WebP support
• Progressive image decoding (including progressive JPEG)
• Background image decompression and scaling in a single step
• Scale large images (~6000x4000 px) and prepare them for display with ease
• Resize and crop loaded images to fit displayed size, add rounded corners or circle

Advanced

• Customize different parts of the framework using dependency injection
• Create custom image managers
• Compose image managers into a tree of responsibility

Getting Started

• Download latest release version
• Take a look at comprehensive demo, it's easy to install with pod try DFImageManager command
• Check out complete documentation
• View the growing project Wiki and FAQ
• Install using CocoaPods, import <DFImageManager/DFImageManagerKit.h> and enjoy!

Usage

Zero Config

[[[DFImageManager sharedManager] imageTaskForResource:[NSURL URLWithString:@"http://..."] completion:^(UIImage *image, NSError *error, DFImageResponse *response, DFImageTask *task){
    // Use loaded image
}] resume];

Adding Request Options

NSURL *imageURL = [NSURL URLWithString:@"http://..."];

DFMutableImageRequestOptions *options = [DFMutableImageRequestOptions new]; // builder
options.priority = DFImageRequestPriorityHigh;
options.allowsClipping = YES;

DFImageRequest *request = [DFImageRequest requestWithResource:imageURL targetSize:CGSizeMake(100.f, 100.f) contentMode:DFImageContentModeAspectFill options:options.options];

[[[DFImageManager sharedManager] imageTaskForRequest:request completion:^(UIImage *image, NSError *error, DFImageResponse *response, DFImageTask *imageTask) {
    // Image is resized and clipped to fill 100x100px square
    if (response.isFastResponse) {
        // Image was returned synchronously from the memory cache
    }
}] resume];

Using Image Task

DFImageTask *imageTask = [[DFImageManager sharedManager] imageTaskForResource:[NSURL URLWithString:@"http://..."] completion:nil];
[imageTask resume];

// Use progress object to track load progress
NSProgress *progress = imageTask.progress;

// Change priority of the already executing task
imageTask.priority = DFImageRequestPriorityHigh;

// Cancel image task
[imageTask cancel];

Using UI Components

Use methods from UIImageView category for simple cases:

UIImageView *imageView = ...;
[imageView df_setImageWithResource:[NSURL URLWithString:@"http://..."]];

Use DFImageView for more advanced features:

DFImageView *imageView = ...;
imageView.allowsAnimations = YES; // Animates images when the response isn't fast enough
imageView.managesRequestPriorities = YES; // Automatically changes current request priority when image view gets added/removed from the window

[imageView prepareForReuse];
[imageView setImageWithResource:[NSURL URLWithString:@"http://..."]];

UICollectionView

- (UICollectionViewCell *)collectionView:(UICollectionView *)collectionView cellForItemAtIndexPath:(NSIndexPath *)indexPath {
    UICollectionViewCell *cell = [collectionView dequeueReusableCellWithReuseIdentifier:<#reuse_id#> forIndexPath:indexPath];
    cell.backgroundColor = [UIColor colorWithWhite:235.f/255.f alpha:1.f];

    DFImageView *imageView = (id)[cell viewWithTag:15];
    if (!imageView) {
        imageView = [[DFImageView alloc] initWithFrame:cell.bounds];
        imageView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
        imageView.tag = 15;
        [cell addSubview:imageView];
    }
    [imageView prepareForReuse];
    [imageView setImageWithResource:<#image_url#>];
    return cell;
}

Cancel image task as soon as the cell goes offscreen (optional):

- (void)collectionView:(UICollectionView *)collectionView didEndDisplayingCell:(UICollectionViewCell *)cell forItemAtIndexPath:(NSIndexPath *)indexPath {
    DFImageView *imageView = (id)[cell viewWithTag:15];
    [imageView prepareForReuse];
}

Preheating Images

NSArray *requestsForAddedItems = ...; // Create image requests
[[DFImageManager sharedManager] startPreheatingImagesForRequests:requestsForAddedItems];

NSArray *requestsForRemovedItems = ...; // Create image requests
[[DFImageManager sharedManager] stopPreheatingImagesForRequests:requestsForRemovedItems];

Requesting Image for PHAsset

PHAsset *asset = ...;
DFImageRequest *request = [DFImageRequest requestWithResource:asset targetSize:CGSizeMake(100.f, 100.f) contentMode:DFImageContentModeAspectFill options:nil];
[[[DFImageManager sharedManager] imageTaskForRequest:request completion:^(UIImage *image, NSDictionary *info) {
    // Image resized to 100x100px square
}] resume];

Progressive Image Decoding

// Enable progressive image decoding
[DFImageManagerConfiguration setAllowsProgressiveImage:YES];

// Create image request that allows progressive image
DFMutableImageRequestOptions *options = [DFMutableImageRequestOptions new];
options.allowsProgressiveImage = YES;
DFImageRequest *request = // Create request with given options

DFImageTask *imageTask = .../ Create image task
imageTask.progressiveImageHandler = ^(UIImage *__nonnull image){
    imageView.image = image;
};

[imageTask resume];

Creating Image Managers

You can either create DFImageManager instance with a custom configuration or even provide your own implementation of DFImageManaging protocol.

// Create dependencies. You can either use existing classes or provide your own.
id<DFImageFetching> fetcher = ...; // Create image fetcher
id<DFImageDecoding> decoder = ...; // Create image decoder
id<DFImageProcessing> processor = ...; // Create image processor
id<DFImageCaching> cache = ...; // Create image cache

// Create configuration to inject dependencies
DFImageManagerConfiguration *configuration = [[DFImageManagerConfiguration alloc] initWithFetcher:fetcher];
configuration.decoder = decoder;
configuration.processor = processor;
configuration.cache = cache;

// Create image manager with configuration
DFImageManager *imageManager = [[DFImageManager alloc] initWithConfiguration:configuration];

Composing Image Managers

The DFCompositeImageManager allows clients to construct a tree of responsibility from multiple image managers, where image requests are dynamically dispatched between them. Each manager should conform to DFImageManaging protocol. The DFCompositeImageManager also conforms to DFImageManaging protocol, which lets clients treat individual objects and compositions uniformly. The default [DFImageManager sharedManager] is a composite that contains all built in managers: the ones that support NSURL fetching, PHAsset objects, etc. It's easy for clients to add additional managers to the shared manager. For more info see Composing Image Managers.

id<DFImageManaging> manager = ...; // Create image manager

// Create composite manager with your custom manager and all built-in managers.
NSArray *managers = @[ manager, [DFImageManager sharedManager] ];
id<DFImageManaging> compositeImageManager = [[DFCompositeImageManager alloc] initWithImageManagers:managers];

// Use dependency injector to set shared manager
[DFImageManager setSharedManager:compositeImageManager];

Design

Protocol	Description
DFImageManaging	A high-level API for loading images
DFImageFetching	Performs fetching of image data (NSData)
DFImageDecoding	Converts NSData to UIImage objects
DFImageProcessing	Processes decoded images
DFImageCaching	Stores processed images into memory cache

Installation with CocoaPods

To install DFImageManager add a dependency in your Podfile:

# Podfile
# platform :ios, '7.0'
# platform :watchos, '2.0'
pod 'DFImageManager'

By default it will install these subspecs (if they are available for your platform):

• DFImageManager/Core - DFImageManager core classes
• DFImageManager/UI - UI components
• DFImageManager/NSURLSession - basic networking on top of NSURLSession
• DFImageManager/PhotosKit - Photos Framework support

There are three more optional subspecs:

• DFImageManager/AFNetworking - replaces networking stack with AFNetworking
• DFImageManager/GIF - GIF support with a FLAnimatedImage dependency
• DFImageManager/WebP - WebP support with a libwebp dependency

To install optional subspecs include them in your Podfile:

# Podfile
pod 'DFImageManager'
pod 'DFImageManager/AFNetworking'
pod 'DFImageManager/GIF'
pod 'DFImageManager/WebP'

Requirements

• iOS 7.0+ / watchOS 2
• Xcode 6.0+

Supported Image Formats

• Image formats supported by UIImage (JPEG, PNG, BMP, and more)
• GIF (GIF subspec)
• WebP (WebP subspec)

Contribution

• If you need help, use Stack Overflow. (Tag 'dfimagemanager')
• If you found a bug, and can provide steps to reproduce it, open an issue.
• If you have a feature request, open an issue.
• If you want to contribute, branch of the develop branch and submit a pull request.

Contacts

License

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