multinerd-forks / imaginary

:unicorn: Remote images, as easy as one, two, three.

Imaginary

Description

Using remote images in an application is more or less a requirement these days. This process should be easy, straight-forward and hassle free, and with Imaginary, it is. The library comes with a narrow yet flexible public API and a bunch of built-in unicorny features:

• Asynchronous image downloading
• Memory and disk cache
• Image decompression
• Default transition animations
• Possibility to pre-process and modify the original image

Regular usage

Set image with URL

let imageView = UIImageView()
let imageUrl = URL(string: "https://avatars2.githubusercontent.com/u/1340892?v=3&s=200")

imageView.setImage(url: imageUrl)

Apply placeholder images

let imageView = UIImageView()
let placeholder = UIImage(named: "PlaceholderImage")
let imageUrl = URL(string: "https://avatars2.githubusercontent.com/u/1340892?v=3&s=200")

imageView.setImage(url: imageUrl, placeholder: placeholder)

Use callback for when the image is set to the image view

let imageView = UIImageView()
let imageUrl = URL(string: "https://avatars2.githubusercontent.com/u/1340892?v=3&s=200")

imageView.setImage(url: imageUrl) { image in
  /// This closure gets called when the image is set to the image view.
}

Advanced usage

Images pre-processing

preprocess closure is a good place to modify the original image before it's being cached and displayed on the screen.

let imageView = UIImageView()
let imageUrl = URL(string: "https://avatars2.githubusercontent.com/u/1340892?v=3&s=200")

imageView.setImage(url: imageUrl, preprocess: { image in
  /// Apply pre-process here ...
  let effect = TintDrawer(tintColor: UIColor.blue)
  return image.modify(with: effect) ?? image
})

TintDrawer, which comes together with Imaginary, is an implementation of the color blend effect. For the time being it's the only built-in "preprocessor", but you have all the power in your hands to do apply custom filters and transformations to make the image shine.

Transition animations

If you're not satisfied with default transition animations there is always a chance to improve or even disable them:

Imaginary.preConfigure = { imageView in
  // Prepare the image view before the image is fetched.
}

Imaginary.transitionClosure = { imageView, newImage in
  // Transition animations go here.
}

Imaginary.postConfigure = { imageView in
  // Setup the image view when the image is set.
}

ImageManager

There are usecases where you need to fetch an image from a remote location without using an image view. This is where ImageManager comes in. With ImageManager you can asynchronously fetch images by using fetchImage(from:)

imageManager.fetchImage(from: URL(string: "http://remote-location/image.png")!) { image in
  // Handle image
}

By default, ImageManager uses the same cache storage as the image view extension. If you want to opt-out from using cache, you can set useCache to false at the call-site.

imageManager.fetchImage(from: URL(string: "http://remote-location/image.png")!, useCache: false) { image in
  // Handle image
}

Cache

Imaginary uses Cache under the hood to store images in memory and on the disk. It's possible to change the default Cache<Image> instance and use your custom configured cache:

Imaginary.Configuration.imageCache = Cache<Image>(
  name: "Imaginary",
  config: customConfig
)

Read more about cache configuration here

Installation

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

pod 'Imaginary'

Imaginary is also available through Carthage. To install just write into your Cartfile:

github "hyperoslo/Imaginary"

Imaginary can also be installed manually. Just download and drop Sources folders in your project.

Author

Hyper Interaktiv AS, [email protected]

License

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