{"id":19319706,"url":"https://github.com/hyperoslo/imaginary","last_synced_at":"2025-05-16T16:09:24.229Z","repository":{"id":2568285,"uuid":"46869276","full_name":"hyperoslo/Imaginary","owner":"hyperoslo","description":":unicorn: Remote images, as easy as one, two, three.","archived":false,"fork":false,"pushed_at":"2022-06-29T19:44:45.000Z","size":1443,"stargazers_count":615,"open_issues_count":7,"forks_count":64,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-05-16T16:08:39.452Z","etag":null,"topics":["image","loader"],"latest_commit_sha":null,"homepage":"https://www.hyper.no","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperoslo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-11-25T15:14:54.000Z","updated_at":"2025-04-21T16:54:17.000Z","dependencies_parsed_at":"2022-09-01T08:51:23.161Z","dependency_job_id":null,"html_url":"https://github.com/hyperoslo/Imaginary","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperoslo%2FImaginary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperoslo%2FImaginary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperoslo%2FImaginary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperoslo%2FImaginary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperoslo","download_url":"https://codeload.github.com/hyperoslo/Imaginary/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254564191,"owners_count":22092123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["image","loader"],"created_at":"2024-11-10T01:24:54.071Z","updated_at":"2025-05-16T16:09:24.198Z","avatar_url":"https://github.com/hyperoslo.png","language":"Swift","readme":"# Imaginary\n\n[![CI Status](https://circleci.com/gh/hyperoslo/Imaginary.png)](https://circleci.com/gh/hyperoslo/Imaginary)\n[![Version](https://img.shields.io/cocoapods/v/Imaginary.svg?style=flat)](http://cocoadocs.org/docsets/Imaginary)\n[![License](https://img.shields.io/cocoapods/l/Imaginary.svg?style=flat)](http://cocoadocs.org/docsets/Imaginary)\n[![Platform](https://img.shields.io/cocoapods/p/Imaginary.svg?style=flat)](http://cocoadocs.org/docsets/Imaginary)\n![Swift](https://img.shields.io/badge/%20in-swift%204.0-orange.svg)\n\n\u003cimg src=\"https://raw.githubusercontent.com/hyperoslo/Imaginary/master/Images/icon.png\" alt=\"Brick Icon\" align=\"right\" /\u003e\n\n## Table of Contents\n\n- [Description](#description)\n- [Usage](#usage)\n  - [Basic](#basic)\n  - [Advanced](#advanced)\n  - [Configuration](#configuration)\n  - [ImageFetcher](#imagefetcher)\n- [Installation](#installation)\n\n## Description\n\nUsing remote images in an application is more or less a requirement these days.\nThis process should be easy, straight-forward and hassle free, and with\n`Imaginary`, it is. The library comes with a narrow yet flexible public API and\na bunch of built-in unicorny features:\n\n- [x] Asynchronous image downloading\n- [x] Memory and disk cache based on [Cache](https://github.com/hyperoslo/Cache)\n- [x] Image decompression\n- [x] Default transition animations\n- [x] Possibility to pre-process and modify the original image\n- [x] Works on any view, including `ImageView`, `Button`, ...\n- [x] Supports iOS, tvOS, macOS\n\n## Usage\n\nIn the most common case, you want to set remote image from url onto `ImageView`. `Imaginary` does the heavy job of downloading and caching images. The caching is done via 2 cache layers (memory and disk) to allow fast retrieval. It also manages expiry for you. And the good news is that you can customise most of these features.\n\n## Basic\n\n#### Set image with URL\n\nSimply pass `URL` to fetch.\n\n```swift\nlet imageUrl = URL(string: \"https://avatars2.githubusercontent.com/u/1340892?v=3\u0026s=200\")\nimageView.setImage(url: imageUrl)\n```\n\n#### Use placeholder\n\nPlaceholder is optional. But the users would be much pleased if they see something while images are being fetched.\n\n```swift\nlet placeholder = UIImage(named: \"PlaceholderImage\")\nlet imageUrl = URL(string: \"https://avatars2.githubusercontent.com/u/1340892?v=3\u0026s=200\")\n\nimageView.setImage(url: imageUrl, placeholder: placeholder)\n```\n\n#### Use callback for when the image is fetched\n\nIf you want to get more info on the fetching result, you can pass a closure as `completion`.\n\n```swift\nimageView.setImage(url: imageUrl) { result in\n  switch result {\n  case .value(let image):\n    print(image)\n  case .error(let error):\n    print(error)\n  }\n}\n```\n\n`result` is an enum `Result` that let you know if the operation succeeded or failed. The possible error is of `ImaginaryError`.\n\n## Advanced\n\n### Passing option\n\nYou can also pass `Option` when fetching images; it allows fine grain control over the fetching process. `Option` defaults to no pre-processor and a displayer for `ImageView`.\n\n```\nlet option = Option()\nimageView.setImage(url: imageUrl, option: option)\n```\n\n### Pre-processing\n\nImages are fetched, decompressed and pre-processed in the background. If you want to modify, simply implement your own `ImageProcessor` and specify it in the `Option`. The pre-processing is done in the background, before the image is set into view.\n\n```swift\npublic protocol ImageProcessor {\n  func process(image: Image) -\u003e Image\n}\n```\n\nThis is how you apply tint color before setting images.\n\n\n```swift\nlet option = Option(imagePreprocessor: TintImageProcessor(tintColor: .orange))\nimageView.setImage(url: imageUrl, option: option)\n```\n\n`Imaginary` provides the following built in pre-processors\n\n- [x] `TintImageProcessor`: apply tint color using color blend effect\n- [ ] `ResizeImageProcessor`: resize\n- [ ] `RoundImageProcessor`: make round corner\n\n### Displaying\n\n`Imaginary` supports any `View`, it can be `UIImageView`, `UIButton`, `MKAnnotationView`, `UINavigationBar`, ... As you can see, the fetching is the same, the difference is the way the image is displayed. To avoid code duplication, `Imaginary` take advantages of Swift protocols to allow fully customisation.\n\nYou can roll out your own `displayer` by comforming to `ImageDisplayer` and specify that in `Option`\n\n```swift\npublic protocol ImageDisplayer {\n  func display(placeholder: Image, onto view: View)\n  func display(image: Image, onto view: View)\n}\n```\n\nThis is how you set an image for `UIButton`\n\n```swift\nlet option = Option(imageDisplayer: ButtonDisplayer())\nbutton.setImage(url: imageUrl, option: option)\n\nlet option = Option(imageDisplayer: ImageDisplayer(animationOption: .transitionCurlUp))\nimageView.setImage(url: imageUrl, option: option)\n```\n\nThese are the buit in displayers. You need to supply the correct displayer for your view\n\n- [x] ImageDisplayer: display onto `UI|NSImageView`. This is the default with cross dissolve animation.\n- [x] ButtonDisplayer: display onto `UI|NSButton` using `setImage(_ image: UIImage?, for state: UIControlState)`\n- [x] ButtonBackgroundDisplayer: display onto `UI|NSButton` using `setBackgroundImage(_ image: UIImage?, for state: UIControlState)`\n\n### Downloading\n\n`Imaginary` uses `ImageFetcher` under the hood, which has downloader and storage.  You can specify your own `ImageDownloader` together with a `modifyRequest` closure, there you can change request body or add more HTTP headers.\n\n```swift\nvar option = Option()\noption.downloaderMaker = {\n  return ImageDownloader(modifyRequest: { \n    var request = $0\n    request.addValue(\"Bearer 123\", forHTTPHeaderField: \"Authorization\")\n    return request \n  })\n}\n\nimageView.setImage(imageUrl, option: option)\n```\n\n### Caching\n\nThe storage defaults to `Configuration.storage`, but you can use your own `Storage`, this allows you to group saved images for particular feature. What if you want forced downloading and ignore storage? Then simply return `nil`. For how to configure `storage`, see [Storage](https://github.com/hyperoslo/Cache#storage)\n\n```swift\nvar option = Option()\noption.storageMaker = {\n  return Configuration.imageStorage\n}\n```\n\n## Configuration\n\nYou can customise the overal experience with `Imaginary` through `Configuration`.\n\n- `trackBytesDownloaded`: track how many bytes have been used to download a specific image\n- `trackError`: track if any error occured when fetching an image.\n- `imageStorage`: the storage used by all fetching operations.\n\n## ImageFetcher\n\n`Imaginary` uses `ImageFetcher` under the hood. But you can use it as a standalone component.\n\n### ImageDownloader\n\nIts main task is to download image and perform all kinds of sanity checkings.\n\n```swift\nlet downloader = ImageDownloader()\ndownloader.download(url: imageUrl) { result in\n  // handle result\n}\n```\n\n### ImageFetcher\n\nThis knows how to fetch and cache the images. It first checks memory and disk cache to see if there's image. If there isn't it will perform network download. You can optionally ignore the cache by setting storage to `nil`.\n\n```swift\nlet fetcher = ImageFetcher(downloader: ImageDownloader(), storage: myStorage()\nfetcher.fetch(url: imageUrl) { result in\n  // handle result\n}\n```\n\n### MultipleImageFetcher\n\nIt sometimes makes sense to pre download images beforehand to improve user experience. We have `MultipleImageFetcher` for you\n\n```swift\nlet multipleFetcher = MultipleImageFetcher(fetcherMaker: {\n  return ImageFetcher()\n})\n\nmultipleFetcher.fetch(urls: imageUrls, each: { result in\n  // handle when each image is fetched\n}, completion: {\n  // handle when all images are fetched\n})\n```\n\nThis is ideal for the new [prefetching mode in UICollectionView](https://developer.apple.com/documentation/uikit/uicollectionview/1771771-prefetchingenabled)\n\n\n## Installation\n\n**Imaginary** is available through [CocoaPods](http://cocoapods.org). To install\nit, simply add the following line to your Podfile:\n\n```ruby\npod 'Imaginary'\n```\n\n**Imaginary** is also available through [Carthage](https://github.com/Carthage/Carthage).\nTo install just write into your Cartfile:\n\n```ruby\ngithub \"hyperoslo/Imaginary\"\n```\n\n**Imaginary** can also be installed manually. Just download and drop `Sources`\nfolders in your project.\n\n## Author\n\nHyper Interaktiv AS, ios@hyper.no\n\n## License\n\n**Imaginary** is available under the MIT license. See the LICENSE file for more info.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperoslo%2Fimaginary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperoslo%2Fimaginary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperoslo%2Fimaginary/lists"}