An object that manages image data in your app.
SDKs
- iOS 2.0+
- tvOS 9.0+
- watchOS 2.0+
Framework
- UIKit
Declaration
class UIImage : NSObject
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 you intend to use in an animation.
You can use image objects in several different ways:
Assign an image to a
UIImageobject to display the image in your interface.View 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 is 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 is especially recommended for the images you use in your app’s interface.
Creating 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 cannot 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:
Use the
init(named:method (or thein: compatible With:) init(named:)method) to create an image from an image asset or image file located in your app’s main bundle (or some other known bundle). Because these methods cache the image data automatically, they are especially recommended for images that you use frequently.Use the
imageorWith Contents Of File: init(contentsmethod to create an image object where the initial data is not in a bundle. These methods load the image data from disk each time, so you should not use them to load the same image repeatedly.Of File:) Use the
animatedandImage(with: duration:) animatedmethods to create a singleImage Named(_: duration:) UIImageobject comprised of multiple sequential images. Install the resulting image in aUIImageobject to create animations in your interface.View
Other methods of the UIImage class let you create animations from specific types of data, such as Core Graphics images or image data that you create yourself. UIKit also provides the UIGraphics function for creating images from content that 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 UIImage 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 UIImage.
Defining a Stretchable Image
A stretchable image is one that defines regions where the underlying image data can be duplicated in an aesthetically pleasing way. Stretchable images are commonly used to create backgrounds that can grow or shrink to fill the available space.
You define a stretchable image by adding insets to an existing image using the resizable or resizable 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 Figure 1.
Using insets to define stretchable regions
Each inset defines the portion of the image that does not 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. Figure 2 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 do not change size because they are inside both a horizontal and vertical inset.
Stretchable portions of a nine-part image
Comparing Images
The is method is the only reliable way to determine whether two images contain the same image data. The image objects you create may be different from each other, even when you initialize them with the same cached image data. The only way to determine their equality is to use the is method, which compares the actual image data. Listing 1 illustrates the correct and incorrect ways to compare images.
Comparing two images
let image1 = UIImage(named: "MyImage")
let image2 = UIImage(named: "MyImage")
if image1 != nil && image1!.isEqual(image2) {
// Correct. This technique compares the image data correctly.
}
if image1 == image2 {
// Incorrect! Direct object comparisons may not work.
}
Accessing the Image Data
Image objects not 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 cg and ci properties to retrieve versions of the image that are compatible with Core Graphics and Core Image, respectively. You can also use the png and jpeg functions to generate an NSData object containing the image data in either the PNG or JPEG format.