DFImageManager

Image loading, processing, caching and preheating

Code Quality Rank: L4

Programming language: Objective-C

License: MIT License

Tags: Media     Image    

Latest version: v2.0.2

README

Advanced framework for loading, caching, processing, displaying and preheating images.

This framework is no longer maintained.

Programming in Swift? Check out Nuke!

Features

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

Loading

• Uses NSURLSession with HTTP/2 support
• Optional AFNetworking integration, combine the power of both frameworks!
• Uses a single fetch operation for 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

Processing

• Optional FLAnimatedImage integration
• Optional WebP integration
• Progressive image decoding including progressive JPEG
• Background image decompression and scaling in a single step
• 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 and compose image managers into a tree of responsibility

Getting Started

• Take a look at comprehensive demo using pod try DFImageManager command
• Check out complete documentation and Wiki
• Install, @import DFImageManager and enjoy!

Usage

Zero Config

[[DFImageManager imageTaskForResource:<#imageURL#> completion:^(UIImage *image, NSError *error, DFImageResponse *response, DFImageTask *task){
    // Use loaded image
}] resume];

Adding Request Options

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

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

[[DFImageManager 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 *task = [DFImageManager imageTaskForResource:<#imageURL#> completion:nil];
NSProgress *progress = task.progress;
task.priority = DFImageRequestPriorityHigh; // Change priority of executing task
[task cancel];

Using UI Components

Use methods from UIImageView category for simple cases:

UIImageView *imageView = ...;
[imageView df_setImageWithResource:<#imageURL#>];

Use DFImageView for more advanced features:

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

[imageView prepareForReuse];
[imageView setImageWithResource:<#imageURL#>];

UICollectionView

- (UICollectionViewCell *)collectionView:(UICollectionView *)collectionView cellForItemAtIndexPath:(NSIndexPath *)indexPath {
    UICollectionViewCell *cell = <#cell#>
    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 *)[cell viewWithTag:15]) prepareForReuse];
}

Preheating Images

NSArray<DFImageRequest *> *requestsForAddedItems = <#requests#>;
[DFImageManager startPreheatingImagesForRequests:requestsForAddedItems];

NSArray<DFImageRequest *> *requestsForRemovedItems = <#requests#>;
[DFImageManager stopPreheatingImagesForRequests:requestsForRemovedItems];

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 = <#request#>;

DFImageTask *task = <#task#>;
task.progressiveImageHandler = ^(UIImage *__nonnull image){
    imageView.image = image;
};
[task resume];

Customizing Image Manager

id<DFImageFetching> fetcher = <#fetcher#>;
id<DFImageDecoding> decoder = <#decoder#>;
id<DFImageProcessing> processor = <#processor#>;
id<DFImageCaching> cache = <#cache#>;

DFImageManagerConfiguration *configuration = [[DFImageManagerConfiguration alloc] initWithFetcher:fetcher];
configuration.decoder = decoder;
configuration.processor = processor;
configuration.cache = cache;

[DFImageManager setSharedManager:[[DFImageManager alloc] initWithConfiguration:configuration]];

Composing Image Managers

The DFCompositeImageManager constructs a tree of responsibility from image managers and dynamically dispatch requests between them. Each manager should conform to DFImageManaging protocol. The DFCompositeImageManager also conforms to DFImageManaging protocol so that individual managers and compositions can be treated uniformly.

id<DFImageManaging> manager1 = <#manager#>
id<DFImageManaging> manager2 = <#manager#>
id<DFImageManaging> composite = [[DFCompositeImageManager alloc] initWithImageManagers:@[manager1, manager2]];

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

CocoaPods

To install DFImageManager add a dependency in your Podfile:

pod 'DFImageManager'

By default it will install these subspecs:

• DFImageManager/Core - DFImageManager core classes
• DFImageManager/UI - UI components

There are four 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
• DFImageManager/PhotosKit - Photos Framework support

To install optional subspecs include them in your Podfile:

pod 'DFImageManager'
pod 'DFImageManager/AFNetworking'
pod 'DFImageManager/GIF'
pod 'DFImageManager/WebP'
pod 'DFImageManager/PhotosKit'

Carthage

DFImageManager has a limited Carthage support that doesn't feature FLAnimatedImage and AFNetworking integration. To install DFImageManager add a dependency to your Cartfile:

github "kean/DFImageManager"

Requirements

• iOS 8.0+ / watchOS 2
• Xcode 7.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.