Last updated: May-15-2023
After you or your users have uploaded image assets to Cloudinary, you can deliver them via dynamic URLs. You can include instructions in your dynamic URLs that tell Cloudinary to transform your assets using a set of transformation parameters. All transformations are performed automatically in the cloud and your transformed assets are automatically optimized before they are routed through a fast CDN to the end user for optimal user experience.
For example, you can resize and crop, add overlay images, blur or pixelate faces, apply a large variety of special effects and filters, and apply settings to optimize your images and to deliver them responsively.
Cloudinary's iOS library simplifies the generation of transformation URLs for easy embedding of assets in your iOS application.
See also: iOS video transformation
Generate image URLs
createUrl method to generate an image URL.
You can add transformations to your
createUrl method by defining a
transformation object and then passing it with the
In general, when using an SDK, you will probably take advantage of the SDK parameter names for improved readability and maintenance of your code. However, you can also optionally pass a raw transformation parameter, whose value is a literal URL transformation definition. Note that the string you pass as the raw transformation value will be appended as is (with no processing or validation) to the end of any other transformation parameters passed in the same component of the transformation chain.
You can link transformations together with the
chain method, where each transformation is applied to the result of the previous transformation:
For example, the following code crops the image to 150x150, rounds the corners, applies a sepia effect, adds text to the top center of the resized image, and then rotates the entire result by 20 degrees.
For more information and examples of image transformations, see Applying common image transformations.
fetchImage method of the
CLDDownloader class to download an image. The method accepts a
url parameter with the location of the image to download. Every download request returns an instance of
CLDFetchImageRequest, which allows options such as cancelling, suspending or resuming the download. The download is performed asynchronously in a separate thread so you must also provide a callback closure to handle the results of the download:
Caching images on the users device will improve performance when loading your media assets. There are currently two ways to cache images with the iOS SDK when using the
fetchImage method of the
The default caching mechanism differs based on the SDK version you are using:
- CLDURLCache for v4.0.0 and newer
- CLDImageCachePolicy for versions older then v4.0.0
CLDURLCache mechanism is a more innovative cache system based on the iOS class URLCache, it stores the response, and verifies attributes of the
cache-control header, specifically the
CLDURLCache is the caching system used in the iOS SDK v4.0.0 and newer and is enabled by default. If you're upgrading from an older version, the caching will be switched and all cached images will need to be re-downloaded. As a result, you may see bandwidth usage increase initially. To disable this, set
cloudinary.enableUrlCache = false and re-enable the old cache mechanism by setting
cloudinary.cachePolicy = .disk.
CLDURLCache works by making an initial HTTP request for an image by default and returning the image with a 200 HTTP status code if successful. Once complete, the request will be cached on both disk and memory. From that point on, for every cache hit, the SDK will check if the request has expired (by checking if it has exceeded the max-age attribute).
If the request has not expired, it is retrieved from the cache.
If the request has expired, the
if-modified-since header with the original date of the request received will be sent. One of two responses will be returned based on whether the image has been updated:
200- the image has been updated and the SDK will get the new image and cache the response.
304- the image is unchanged and the SDK will get the image from the cache.
The first time that the
fetchImage method is called for downloading a particular resource, Cloudinary also stores it in the device's cache. Each subsequent call to
fetchImage first attempts to find the image in the local cache, and retrieves it from the cache if it was found. This default behavior can be customized with the
cacheMaxMemoryTotalCost properties of your
|cachePolicy||CLDImageCachePolicy||Set the caching policy for downloaded images
|cacheMaxDiskCapacity||Int||(Relevant only if the disk option is selected for policy) The maximum capacity of the disk cache in bytes. Default: 150 * 1024 * 1024|
|cacheMaxMemoryTotalCost||Int||(Relevant only if the memory option is selected for policy) Maximum size for the memory cache in bytes. Default: 150 * 1024 * 1024|
For example, to use the device's memory for caching images, and limiting the disk cache size to 50 MB:
Deliver images using UI extensions
The Cloudinary SDK provides extensions to three iOS UI elements for presenting images. These extensions provide a
cldSetImage method that automatically fetches and downloads an image in the background, as well as setting it to be displayed in the UI. The extension is available for:
For example, setting a UIImageView component named "photoImageView" to fetch and display an image that was uploaded with the public id of "dog", scaled to 400 pixels wide:
Thanks for your time!
Apply common image transformations
This section provides an overview and examples of the following commonly used image transformation features, along with links to more detailed documentation on these features:
- Resizing and cropping
- Converting to another image format
- Applying image effects and filters
- Adding text and image overlays
- Image optimizations
Keep in mind that this section is only intended to introduce you to the basics of using image transformations with iOS.
For comprehensive explanations of how to implement a wide variety of transformations, see Image transformations. For a full list of all supported image transformations and their usage, see the Transformation URL API Reference.
Resizing and cropping
There are a variety of different ways to resize and/or crop your images, and to control the area of the image that is preserved during a crop.
The following example uses the
fill cropping method to generate the dynamic URL for an image that completely fills the requested 250x250 size while retaining the original aspect ratio. It uses face detection gravity to ensure that all the faces in the image are retained and centered when the image is cropped:
You can also use automatic gravity to determine what to keep in the crop automatically.
For details on all resizing and cropping options, see resizing and cropping images.
Converting to another image format
You can deliver any image uploaded to Cloudinary in essentially any image format. There are two main ways to convert and deliver in another format:
- Specify the image's public ID with the desired extension.
- Explicitly set the desired format using the
Generate the dynamic URL for an image in the GIF format by specifying the file extension:
Generate the dynamic URL for an image in the GIF format by specifying the
For more details, see Image format support.
Applying image effects and filters
You can select from a large selection of image effects, enhancements, and filters to apply to your images. The available effects include a variety of color balance and level effects, tinting, blurring, pixelating, sharpening, automatic improvement effects, artistic filters, image and text overlays, distortion and shape changing effects, outlines, backgrounds, shadows, and more.
For example, the code below generates the dynamic URL for an image with a cartoonify effect, a rounding corners effect, and a background color effect (and then scales the image down to a height of 300 pixels).
For more details on the available image effects and filters, see Visual image effects and enhancements.
Adding text and image overlays
You can add images and text as overlays on your main image. You can apply the same types of transformations on your overlay images as you can with any image and you can use gravity settings or x and y coordinates to control the location of the overlays. You can also apply a variety of transformations on text, such as color, font, size, rotation, and more.
For example, the transformation below overlays a couple's photo on a mug image. The overlay photo is cropped using face detection with adjusted color saturation and a vignette effect applied. The word love is added in a pink, fancy font and rotated to fit the design. A balloon graphic is also added. Additionally, the final image is cropped and the corners are rounded.
By default, Cloudinary automatically performs certain optimizations on all transformed images. There are also a number of additional features that enable you to further optimize the images you use in your iOS application. These include optimizations to image quality, format, and size, among others.
For example, you can use the
auto value for the
quality attribute to automatically deliver an image that minimizes file size while meeting the required quality level. In the example below, the automatic quality parameter is applied, resulting in a 50% file size reduction (1.4 MB vs. 784 KB) with no visible change in quality.
For an in-depth review of the many ways you can optimize your images, see Image optimization.
Responsive design is a method of providing an optimal viewing experience to users, tailored to their device, viewport size, orientation, and resolution. An App designed responsively adapts its layout to the viewing environment, resizing and moving elements dynamically and based on the properties of the device the App is being displayed on.
When it comes to images, a responsively designed App should not just send the highest resolution image and then use client-side resizing to display the image on all the various devices: that would be a huge waste of bandwidth for users on small, low-resolution displays. The best solution is to prepare an image in various resolutions and sizes, and then deliver the best possible resolution image, based on the device's resolution and the dimensions available, without needlessly wasting bandwidth or loading time. Cloudinary can help reduce the complexity with dynamic image transformations. You can simply build image URLs with any image width or height based on the specific device resolution and viewport size. This means you don't have to pre-create the images, with dynamic resizing taking place on the fly as needed.
A responsive method is available for the Cloudinary
UIImageView component. Use the
cldSetImage method to automatically fetch and download the optimal image in the background, as well as setting it to be displayed in the UI. To make the generated URL responsive, pass the
cldSetImage method 5 parameters: the
publicId of the image, the Cloudinary
resourceType, the Cloudinary instance, the responsive parameters, and any transformation to apply to the image. The responsive parameters are passed as a
CLDResponsiveParams object as follows:
autoWidth: boolean - adjust according to the available width
autoHeight: boolean - adjust according to the available height
cropMode: String - the crop mode to apply when adjusting the image
gravity: String - the location in the image to be used as the focus for the transformation
Instead of specifying the 5 responsive parameters individually, you can add one of the following "preset" methods:
autoFill(): Adjusts both height and width of the image, retaining the aspect-ratio, to fill the ImageView, using automatic gravity to determine which part of the image is visible if necessary (shortcut for: true, true, "fill", "auto").
fit(): Adjusts both height and width of the image, retaining the aspect-ratio, to completely fit within the bounds of the ImageView. The whole image will be shown (shortcut for: true, true, "fit", "center")
For example, setting a UIImageView component named "photoImageView" to responsively fetch and display an image that was uploaded with the public id of "sample", in JPEG format, and automatically resized to fill the available width and height:
Which is equivalent to:
cldSetImage with method retrieves the exact available dimensions for the UIImageView component and then rounds up the height and width for the image to the nearest step (100 by default). For example, if the exact width is 284 logical pixels then the requested width is rounded up to 300 pixels. This prevents too many image versions being generated and reduced cache hits for subsequent requests from other devices.
The default values for the responsive calculation can be overridden by calling the
setMaxDimension methods of
CLDResponsiveParams and passing the new values (default values are 50, 50 and 350 logical pixels respectively).
For example, to set the step size to every 100 logical pixels and limit the dimensions to between 100 and 300 logical pixels: