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 (CVImageBuffer), 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.

Symbols

Creating an Image

class func empty()

Creates and returns an empty image object.

Initializing an Image

init(color: CIColor)

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

init(cgImage: CGImage)

Initializes an image object with a Quartz 2D image.

init(cgImage: CGImage, options: [String : Any]? = nil)

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

init?(bitmapImageRep: NSBitmapImageRep)

Initializes an image object with the specified bitmap image representation.

init?(image: UIImage)

Initializes an image object with the specified UIKit image object.

init?(image: UIImage, options: [AnyHashable : Any]? = nil)

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

init(cgLayer: CGLayer)

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

Deprecated
init(cgLayer: CGLayer, options: [String : Any]? = nil)

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

Deprecated
init?(contentsOf: URL)

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

init?(contentsOf: URL, options: [String : Any]? = nil)

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

init(cvImageBuffer: CVImageBuffer)

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

init(cvImageBuffer: CVImageBuffer, options: [String : Any]? = nil)

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

init(cvPixelBuffer: CVPixelBuffer)

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

init(cvPixelBuffer: CVPixelBuffer, options: [String : Any]? = nil)

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

init?(data: Data)

Initializes an image object with the supplied image data.

init?(data: Data, options: [String : Any]? = nil)

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

init(imageProvider: Any, size: Int, Int, format: CIFormat, colorSpace: CGColorSpace?, options: [String : Any]? = nil)

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

init(texture: UInt32, size: CGSize, flipped: Bool, colorSpace: CGColorSpace?)

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

init(texture: UInt32, size: CGSize, flipped: Bool, options: [String : Any]? = nil)

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

init?(mtlTexture: MTLTexture, options: [String : Any]? = nil)

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

init(ioSurface: IOSurfaceRef)

Initializes an image with the contents of an IOSurface.

init(ioSurface: IOSurfaceRef, options: [String : Any]? = nil)

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

init(ioSurface: IOSurfaceRef, plane: Int, format: CIFormat, options: [String : Any]? = nil)

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

func applyingFilter(String, withInputParameters: [String : Any]?)

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

func applying(CGAffineTransform)

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

func cropping(to: CGRect)

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

func applyingOrientation(Int32)

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

func clampingToExtent()

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

func clamping(to: CGRect)

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.

func compositingOverImage(CIImage)

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

func matchedToWorkingSpace(from: CGColorSpace)

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

func matchedFromWorkingSpace(to: CGColorSpace)

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

func premultiplyingAlpha()

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

func unpremultiplyingAlpha()

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

func settingAlphaOne(inExtent: CGRect)

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.

func applyingGaussianBlur(withSigma: Double)

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

func settingProperties([AnyHashable : Any])

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

Getting Image Information

var definition: CIFilterShape

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

var extent: CGRect

A rectangle that specifies the extent of the image.

var properties: [String : Any]

A dictionary containing metadata about the image.

var url: URL?

The URL from which the image was loaded.

var colorSpace: CGColorSpace?

The color space of the image.

func imageTransform(forOrientation: Int32)

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

Drawing images

func draw(at: NSPoint, from: NSRect, operation: NSCompositingOperation, fraction: CGFloat)

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

func draw(in: NSRect, from: NSRect, operation: NSCompositingOperation, fraction: CGFloat)

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

Getting Autoadjustment Filters

func autoAdjustmentFilters()

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

func autoAdjustmentFilters(options: [String : Any]? = nil)

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

Working with Filter Regions of Interest

func regionOfInterest(for: CIImage, in: CGRect)

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

Accessing Original Image Content

var cgImage: CGImage?

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

var pixelBuffer: CVPixelBuffer?

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

Constants

CIFormat

A data type used for specifying image pixel formats.

Pixel Formats

Image data pixel formats.

Image Dictionary Keys

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

Autoadjustment Keys

Constants used as keys in the options dictionary for the autoAdjustmentFilters(options:) method.

Relationships

Inherits From