Class

CIImage

A representation of an image to be processed or produced by Core Image filters.

Overview

You use CIImage objects in conjunction with other Core Image classes—such as CIFilter, CIContext, CIVector, and CIColor—to take advantage of the built-in Core Image filters when processing images. You can create CIImage objects with data supplied from a variety of sources, including Quartz 2D images, Core Video image buffers (CVImageBufferRef), URL-based objects, and NSData objects.

Although a CIImage object has image data associated with it, it is not an image. You can think of a CIImage object as an image “recipe.” A CIImage object has all the information necessary to produce an image, but Core Image doesn’t actually render an image until it is told to do so. This “lazy evaluation” method allows Core Image to operate as efficiently as possible.

CIContext and CIImage objects are immutable, which means each can be shared safely among threads. Multiple threads can use the same GPU or CPU CIContext object to render CIImage objects. However, this is not the case for CIFilter objects, which are mutable. A CIFilter object cannot be shared safely among threads. If you app is multithreaded, each thread must create its own CIFilter objects. Otherwise, your app could behave unexpectedly.

Core Image also provides autoadjustment methods. These methods analyze an image for common deficiencies and return a set of filters to correct those deficiencies. The filters are preset with values for improving image quality by altering values for skin tones, saturation, contrast, and shadows and for removing red-eye or other artifacts caused by flash. (See Getting Autoadjustment Filters.)

For a discussion of all the methods you can use to create CIImage objects on iOS and macOS, see Core Image Programming Guide.

Topics

Creating an Image

emptyImage

Creates and returns an empty image object.

imageWithColor:

Creates and returns an image of infinite extent whose entire content is the specified color.

imageWithBitmapData:bytesPerRow:size:format:colorSpace:

Creates and returns an image object from bitmap data.

imageWithCGImage:

Creates and returns an image object from a Quartz 2D image.

imageWithCGImage:options:

Creates and returns an image object from a Quartz 2D image using the specified options.

imageWithCGLayer:

Creates and returns an image object from the contents supplied by a CGLayer object.

Deprecated
imageWithCGLayer:options:

Creates and returns an image object from the contents supplied by a CGLayer object, using the specified options.

Deprecated
imageWithContentsOfURL:

Creates and returns an image object from the contents of a file.

imageWithContentsOfURL:options:

Creates and returns an image object from the contents of a file, using the specified options.

imageWithCVImageBuffer:

Creates and returns an image object from the contents of CVImageBuffer object.

imageWithCVImageBuffer:options:

Creates and returns an image object from the contents of CVImageBuffer object, using the specified options.

imageWithCVPixelBuffer:

Creates and returns an image object from the contents of CVPixelBuffer object.

imageWithCVPixelBuffer:options:

Creates and returns an image object from the contents of CVPixelBuffer object, using the specified options.

imageWithData:

Creates and returns an image object initialized with the supplied image data.

imageWithData:options:

Creates and returns an image object initialized with the supplied image data, using the specified options.

imageWithImageProvider:size::format:colorSpace:options:

Creates and returns an image object initialized with data provided by an image provider.

imageWithTexture:size:flipped:colorSpace:

Creates and returns an image object initialized with data supplied by an OpenGL texture.

imageWithTexture:size:flipped:options:

Creates and returns an image object initialized with data supplied by an OpenGL texture.

imageWithMTLTexture:options:

Creates and returns an image object with data supplied by a Metal texture.

imageWithIOSurface:

Creates and returns an image from the contents of an IOSurface.

imageWithIOSurface:options:

Creates, using the specified options, and returns an image from the contents of an IOSurface.

Initializing an Image

initWithColor:

Initializes an image of infinite extent whose entire content is the specified color.

initWithBitmapData:bytesPerRow:size:format:colorSpace:

Initializes an image object with bitmap data.

initWithCGImage:

Initializes an image object with a Quartz 2D image.

initWithCGImage:options:

Initializes an image object with a Quartz 2D image, using the specified options.

initWithBitmapImageRep:

Initializes an image object with the specified bitmap image representation.

initWithImage:

Initializes an image object with the specified UIKit image object.

initWithImage:options:

Initializes an image object with the specified UIKit image object, using the specified options.

initWithCGLayer:

Initializes an image object from the contents supplied by a CGLayer object.

Deprecated
initWithCGLayer:options:

Initializes an image object from the contents supplied by a CGLayer object, using the specified options.

Deprecated
initWithContentsOfURL:

Initializes an image object by reading an image from a URL.

initWithContentsOfURL:options:

Initializes an image object by reading an image from a URL, using the specified options.

initWithCVImageBuffer:

Initializes an image object from the contents of a Core Video image buffer.

initWithCVImageBuffer:options:

Initializes an image object from the contents of a Core Video image buffer, using the specified options.

initWithCVPixelBuffer:

Initializes an image object from the contents of a Core Video pixel buffer.

initWithCVPixelBuffer:options:

Initializes an image object from the contents of a Core Video pixel buffer using the specified options.

initWithData:

Initializes an image object with the supplied image data.

initWithData:options:

Initializes an image object with the supplied image data, using the specified options.

initWithImageProvider:size::format:colorSpace:options:

Initializes an image object with data provided by an image provider, using the specified options.

kCIImageProviderTileSize

A key for the image tiles size. The associated value is an NSArray that containsNSNumber objects for the dimensions of the image tiles requested from the image provider.

kCIImageProviderUserInfo

A key for data needed by the image provider. The associated value is an object that contains the needed data.

initWithTexture:size:flipped:colorSpace:

Initializes an image object with data supplied by an OpenGL texture.

initWithTexture:size:flipped:options:

Initializes an image object with data supplied by an OpenGL texture.

initWithMTLTexture:options:

Initializes an image object with data supplied by a Metal texture.

initWithIOSurface:

Initializes an image with the contents of an IOSurface.

initWithIOSurface:options:

Initializes, using the specified options, an image with the contents of an IOSurface.

initWithIOSurface:plane:format:options:

Initializes, using the specified format and options, an image with the contents of a specific data plane in an IOSurface.

Deprecated

Creating an Image by Modifying an Existing Image

imageByApplyingFilter:withInputParameters:

Returns a new image created by applying a filter to the original image with the specified name and parameters.

imageByApplyingTransform:

Returns a new image that represents the original image after applying an affine transform.

imageByCroppingToRect:

Returns a new image that represents the original image after cropping to a rectangle.

imageByApplyingOrientation:

Returns a new image created by transforming the original image to the specified EXIF orientation.

imageByClampingToExtent

Returns a new image created by making the pixel colors along its edges extend infinitely in all directions.

imageByClampingToRect:

Returns a new image created by cropping to a specified area, then making the pixel colors along the edges of the cropped image extend infinitely in all directions.

imageByCompositingOverImage:

Returns a new image created by compositing the original image over the specified destination image.

imageByColorMatchingColorSpaceToWorkingSpace:

Returns a new image created by color matching from the specified color space to the context’s working color space.

imageByColorMatchingWorkingSpaceToColorSpace:

Returns a new image created by color matching from the context’s working color space to the specified color space.

imageByPremultiplyingAlpha

Returns a new image created by multiplying the image’s RGB values by its alpha values.

imageByUnpremultiplyingAlpha

Returns a new image created by dividing the image’s RGB values by its alpha values.

imageBySettingAlphaOneInExtent:

Returns a new image created by setting all alpha values to 1.0 within the specified rectangle and to 0.0 outside of that area.

imageByApplyingGaussianBlurWithSigma:

Returns a new image created by applying a Gaussian Blur filter to the image.

imageBySettingProperties:

Returns a new image created by adding the specified metadata properties to the image.

Getting Image Information

definition

Returns a filter shape object that represents the domain of definition of the image.

extent

A rectangle that specifies the extent of the image.

properties

A dictionary containing metadata about the image.

url

The URL from which the image was loaded.

colorSpace

The color space of the image.

imageTransformForOrientation:

Returns the transformation needed to reorient the image to the specified orientation.

Drawing images

drawAtPoint:fromRect:operation:fraction:

Draws all or part of the image at the specified point in the current coordinate system.

drawInRect:fromRect:operation:fraction:

Draws all or part of the image in the specified rectangle in the current coordinate system

Getting Autoadjustment Filters

autoAdjustmentFilters

Returns all possible automatically selected and configured filters for adjusting the image.

autoAdjustmentFiltersWithOptions:

Returns a subset of automatically selected and configured filters for adjusting the image.

Autoadjustment Keys

Constants used as keys in the options dictionary for the autoAdjustmentFiltersWithOptions: method.

Working with Filter Regions of Interest

regionOfInterestForImage:inRect:

Returns the region of interest for the filter chain that generates the image.

Accessing Original Image Content

CGImage

The CoreGraphics image object this image was created from, if applicable.

pixelBuffer

The CoreVideo pixel buffer this image was created from, if applicable.

Image Dictionary Keys

Constants used as keys in the options dictionary when initializing an image.

kCIImageColorSpace

The key for a color space.

kCIImageProperties

The key for image metadata properties.

kCIImageTextureTarget

The key for an OpenGL texture target.

kCIImageTextureFormat

The key for an OpenGL texture format.

Instance Properties

Relationships

Inherits From

See Also

First Steps

CIFilter

An image processor that produces an image by manipulating one or more input images or by generating new image data.

CIContext

An evaluation context for rendering image processing results and performing image analysis.

Basic Data Types

Colors, vectors, and other types used in applying or creating image filters.