FXImageView

Purpose

FXImageView is a class designed to simplify the application of common visual effects such as reflections and drop-shadows to images. FXImageView includes sophisticated queuing and caching logic to maximise performance when rendering these effects in real time.

As a bonus, FXImageView includes a standalone UIImage category for cropping, scaling and applying effects directly to an image.

Supported iOS & SDK Versions

• Supported build target - iOS 10.3 (Xcode 8.3, Apple LLVM compiler 8.1)
• Earliest supported deployment target - iOS 8.0
• Earliest compatible deployment target - iOS 6.0

NOTE: 'Supported' means that the library has been tested with this version. 'Compatible' means that the library should work on this iOS version (i.e. it doesn't rely on any unavailable SDK features) but is no longer being tested for compatibility and may require tweaking or bug fixes to run correctly.

ARC Compatibility

As of version 1.3, FXImageView requires ARC. If you wish to use FXImageView in a non-ARC project, just add the -fobjc-arc compiler flag to the FXImageView.m class. To do this, go to the Build Phases tab in your target settings, open the Compile Sources group, double-click FXImageView.m in the list and type -fobjc-arc into the popover.

If you wish to convert your whole project to ARC, comment out the #error line in FXImageView.m, then run the Edit > Refactor > Convert to Objective-C ARC... tool in Xcode and make sure all files that you wish to use ARC for (including FXImageView.m) are checked.

Thread Safety

FXImageView is derived from UIView and - as with all UIKit components - it should only be accessed from the main thread. FXImageView uses threads internally to avoid blocking user interaction, but FXImageView's properties should only ever be accessed from the main thread.

The UIImage(FX) category methods are all thread-safe and may safely be called concurrently from multiple threads on the same UIImage instance.

Installation

Manual

To use FXImageView, just drag the class files into your project. You can create FXImageViews programatically, or create them in Interface Builder by dragging an ordinary UIImageView into your view and setting its class to FXImageView.

Cocoapods

To install FXImageView using Cocoapods, just add pod FXImageView to your Podfile and run pod install

Carthage

FXImageView is fully Carthage compatible. To include it, build your project with Carthage, then drag ./Carthage/Build/iOS/FXImageView.framework into your project and add this import:

#import <FXImage/Image.h>

UIImage extension methods

- (UIImage *)imageCroppedToRect:(CGRect)rect;

Returns a copy of the image cropped to the specified rectangle (in image coordinates).

- (UIImage *)imageScaledToSize:(CGSize)size;

Returns a copy of the image scaled to the specified size. This method may change the aspect ratio of the image.

- (UIImage *)imageScaledToFitSize:(CGSize)size;

Returns a copy of the image scaled to fit the specified size without changing its aspect ratio. The resultant image may be smaller than the size specified in one dimension if the aspect ratios do not match. No padding will be added.

- (UIImage *)imageScaledToFillSize:(CGSize)size;

Returns a copy of the image scaled to fit the specified size without changing its aspect ratio. If the image aspect ratio does not match the aspect ratio of the size specified, the image will be cropped to fit.

- (UIImage *)imageCroppedAndScaledToSize:(CGSize)size
                             contentMode:(UIViewContentMode)contentMode
                                padToFit:(BOOL)padToFit;

Returns a copy of the image scaled and/or cropped to the specified size using the specified UIViewContentMode. This method is useful for matching the effect of UIViewContentMode on an image when displayed in a UIImageView. If the padToFit argument is NO, the resultant image may be smaller than the size specified is the aspect ratios do not match. If padToFit is YES, additional transparent pixels will be added around the image to pad it out to the size specified.

- (UIImage *)reflectedImageWithScale:(CGFloat)scale;

Returns a vertically reflected copy of the image that tapers off to transparent with a gradient. The scale parameter determines that point at which the image tapers off and should have a value between 0.0 and 1.0.

- (UIImage *)imageWithReflectionWithScale:(CGFloat)scale gap:(CGFloat)gap alpha:(CGFloat)alpha;

Returns a copy of the image that includes a reflection with the specified scale, separation gap and alpha (opacity). The original image will be vertically centered within the new image, with he space above the image padded out with transparent pixels matching the height of the reflection below. This makes it easier to position the image within a UIImageView.

- (UIImage *)imageWithShadowColor:(UIColor *)color offset:(CGSize)offset blur:(CGFloat)blur;

Returns a copy of the image with a drop shadow rendered with the specified color, offset and blur. Regardless of the offset value, the original image will be vertically centered within the new image to make it easier to position the image within a UIImageView.

- (UIImage *)imageWithCornerRadius:(CGFloat)radius;

Returns a copy of the image with the corners clipped to the specified curvature radius.

- (UIImage *)imageWithAlpha:(CGFloat)alpha;

Returns a copy of the image with the specified alpha (opacity). The alpha is multiplied by the image's original alpha channel, so this method can only be used to make the image more transparent, not more opaque.

- (UIImage *)imageWithMask:(UIImage *)maskImage;

Clips the image using the specified mask image. The mask image should be an opaque, greyscale alpha mask. If you wish to use a transparent mask image, use the maskImageFromImageAlpha method to convert it to the correct format.

- (UIImage *)maskImageFromImageAlpha;

This method extracts the alpha channel from an image that has an embedded alpha mask and returns it as a standalone greyscale mask image, suitable for use with the imageWithMask: method.

FXImageView class methods

+ (NSOperationQueue *)processingQueue;

This is the shared NSOperationQueue used for queuing FXImageView images for processing. You can use this method to manipulate the maxConcurrentOperationCount for the queue, which may be useful when fine tuning performance. The default maximum concurrent operation count is 4.

+ (NSCache *)processedImageCache;

This is the shared NSCache used to cache processed FXImageView images for reuse. iOS automatically manages clearing this cache when iOS runs low on memory, but you may wish to manipulate the countLimit value, or manually clear the cache at specific points in your app.

FXImageView methods

- (void)setImage:(UIImage *)image;

This method is the setter method for the image property. See the image property documentation below.

- (void)setImageWithContentsOfFile:(NSString *)file;

This method sets the image by loading it from the specified file. If the specified file is not an absolute path it is assumed to be a relative path within with the application bundle resources directory. If the file does not include an extension it is assumed to be a PNG. If the asynchronous property is set, the file will be loaded on a background thread.

- (void)setImageWithContentsOfURL:(NSURL *)URL;

This method sets the image by loading it from the specified URL. If the asynchronous property is enabled, the image will be loaded on a background thread. The specified URL can be either a local or remote file, but note that loading remote URLs in synchronous mode is not recommended as it will block the main thread for an indeterminate time.

FXImageView properties

@property (nonatomic, assign, getter = isAsynchronous) BOOL asynchronous;

The shadow and reflection effects take time to render. In many cases this will be imperceptible, but for high-performance applications such as a scrolling carousel, this rendering delay may cause stuttering in the animation. This method toggles whether the shadow and reflection effects are applied immediately on the main thread (asynchronous = NO), or rendered in a background thread (asynchronous = YES). By rendering the effects in the background, the performance issues can be avoided. Defaults to NO.

@property (nonatomic, assign) NSTimeInterval crossfadeDuration;

This property controls the duration of the crossfade animation when the image finishes processing and is displayed, measured in seconds. The default duration is 0.25. Set the duration to zero to disable the crossfade altogether.

@property (nonatomic, assign) CGFloat reflectionGap;

The gap between the image and its reflection, measured in pixels (or points on a Retina Display device). This defaults to zero.

@property (nonatomic, assign) CGFloat reflectionScale;

The height of the reflection relative to the image. Should be in the range 0.0 to 1.0. Defaults to 0.0 (no reflection).

@property (nonatomic, assign) CGFloat reflectionAlpha;

The opacity of the reflection. Should be in the