Contents

UIImage

An object that manages image data in your app.

Declaration

class UIImage

Mentioned in

Overview

You use image objects to represent image data of all kinds, and the UIImage class is capable of managing data for all image formats supported by the underlying platform. Image objects are immutable, so you always create them from existing image data, such as an image file on disk or programmatically created image data. An image object may contain a single image or a sequence of images for use in an animation.

You can use image objects in several different ways:

  • Assign an image to a UIImageView object to display the image in your interface.

  • Use an image to customize system controls such as buttons, sliders, and segmented controls.

  • Draw an image directly into a view or other graphics context.

  • Pass an image to other APIs that might require image data.

Although image objects support all platform-native image formats, it’s recommended that you use PNG or JPEG files for most images in your app. Image objects are optimized for reading and displaying both formats, and those formats offer better performance than most other image formats. Because the PNG format is lossless, it’s especially recommended for the images you use in your app’s interface.

Create image objects

When creating image objects using the methods of this class, you must have existing image data located in a file or data structure. You can’t create an empty image and draw content into it. There are many options for creating image objects, each of which is best for specific situations:

Other methods of the UIImage class let you create animations from specific types of data, such as Core Graphics images or image data you create yourself. UIKit also provides the UIGraphicsGetImageFromCurrentImageContext() function to create images from content you draw yourself. You use that function in conjunction with a bitmap-based graphics context, which you use to capture your drawing commands.

Image assets are the easiest way to manage the images that ship with your app. Each new Xcode project contains an assets library, to which you can add multiple image sets. An image set contains the variations of a single image that your app uses. A single image set can provide different versions of an image for different platforms, for different trait environments (compact or regular), and for different scale factors.

In addition to loading images from disk, you can ask the user to supply images from an available camera or photo library using a UIImagePickerController object. An image picker displays a custom user interface for selecting images. Accessing user-supplied images requires explicit user permission. For more information about using an image picker, see UIImagePickerController.

Define a stretchable image

A stretchable image is one that defines regions where you can duplicate the underlying image data in an aesthetically pleasing way. Stretchable images are commonly used to create backgrounds that can grow or shrink to fill the available space.

Define a stretchable image by adding insets to an existing image using the resizableImage(withCapInsets:) or resizableImage(withCapInsets:resizingMode:) method. The insets subdivide the image into two or more parts. Specifying nonzero values for each inset yields an image divided into nine parts, as shown in the following image:

[Image]

Each inset defines the portion of the image that doesn’t stretch in the given dimension. The regions inside an image’s top and bottom insets maintain a fixed height, and the areas inside the left and right insets maintain a fixed width. The following image shows how each part of a nine-part image stretches as the image itself is stretched to fill the available space. The corners of the image don’t change size because they’re inside both a horizontal and vertical inset:

[Image]

Compare images

The isEqual(_:) method is the only reliable way to determine whether two image objects contain the same image data. The following code illustrates the correct and incorrect ways to compare images.

Access the image data

Image objects don’t provide direct access to their underlying image data. However, you can retrieve the image data in other formats for use in your app. Specifically, you can use the cgImage and ciImage properties to retrieve versions of the image that are compatible with Core Graphics and Core Image, respectively. You can also use the pngData() and jpegData(compressionQuality:) functions to generate an NSData object containing the image data in either the PNG or JPEG format.

Topics

Loading and caching images

Loading images for display

Creating and initializing image objects

Creating animated images

Changing the image attributes

Getting standard system images

Getting the image data

Getting the image size and scale

Accessing image attributes

Getting the image configuration

Specifying the dynamic range

Managing the baseline

Getting rendering information

Tinting the image

Drawing images

Exporting standard bitmap formats

Deprecated

Initializers

See Also

Representations