iOS Developer Library

Developer

CoreImage Framework Reference CIDetector Class Reference

Options
Deployment Target:

On This Page
Language:

CIDetector

A CIDetector object uses image processing to search for and identify notable features (faces, rectangles, and barcodes) in a still image or video. Detected features are represented by CIFeature objects that provide more information about each feature.

This class can maintain many state variables that can impact performance. So for best performance, reuse CIDetector instances instead of creating new ones.

Inheritance


Conforms To


Import Statement


Swift

import CoreImage

Objective-C

@import CoreImage;

Availability


Available in iOS 5.0 and later.
  • Creates and returns a configured detector.

    Declaration

    Swift

    init!(ofType type: String!, context context: CIContext!, options options: [NSObject : AnyObject]!) -> CIDetector

    Objective-C

    + (CIDetector *)detectorOfType:(NSString *)type context:(CIContext *)context options:(NSDictionary *)options

    Parameters

    type

    A string indicating the kind of detector you are interested in. See “Detector Types”.

    context

    A Core Image context that the detector can use when analyzing an image.

    options

    A dictionary containing details on how you want the detector to be configured. See “Detector Configuration Keys”.

    Return Value

    A configured detector.

    Discussion

    A CIDetector object can potentially create and hold a significant amount of resources. Where possible, reuse the same CIDetector instance. Also, when processing images with a detector object, your application performs better if the CIContext used to initialize the detector is the same context used to process the CIImage objects.

    Import Statement

    Objective-C

    @import CoreImage;

    Swift

    import CoreImage

    Availability

    Available in iOS 5.0 and later.

  • Searches for features in an image.

    Declaration

    Swift

    func featuresInImage(_ image: CIImage!) -> [AnyObject]!

    Objective-C

    - (NSArray *)featuresInImage:(CIImage *)image

    Parameters

    image

    The image you want to examine.

    Return Value

    An array of CIFeature objects. Each object represents a feature detected in the image.

    Import Statement

    Objective-C

    @import CoreImage;

    Swift

    import CoreImage

    Availability

    Available in iOS 5.0 and later.

  • Searches for features in an image based on the specified image orientation.

    Declaration

    Swift

    func featuresInImage(_ image: CIImage!, options options: [NSObject : AnyObject]!) -> [AnyObject]!

    Objective-C

    - (NSArray *)featuresInImage:(CIImage *)image options:(NSDictionary *)options

    Parameters

    image

    The image you want to examine.

    options

    A dictionary that specifies feature detection options. See “Feature Detection Keys” for allowed keys and their possible values.

    Return Value

    An array of CIFeature objects. Each object represents a feature detected in the image.

    Discussion

    The options dictionary should contain a value for the key CIDetectorImageOrientation, and may contain other values specifying optional face-recognition features.

    Import Statement

    Objective-C

    @import CoreImage;

    Swift

    import CoreImage

    Availability

    Available in iOS 5.0 and later.

  • Strings used to declare the detector for which you are interested.

    Declaration

    Swift

    let CIDetectorTypeFace: NSString! let CIDetectorTypeRectangle: NSString! let CIDetectorTypeQRCode: NSString!

    Objective-C

    NSString* const CIDetectorTypeFace *NSString const CIDetectorTypeRectangle NSString* const CIDetectorTypeQRCode

    Constants

    • CIDetectorTypeFace

      CIDetectorTypeFace

      A detector that searches for faces in a still image or video, returning CIFaceFeature objects that provide information about detected faces.

      For better accuracy and performance in face detection, use the CIDetectorImageOrientation key to specify the image orientation when using the featuresInImage:options: method.

      Available in iOS 5.0 and later.

    • CIDetectorTypeRectangle

      CIDetectorTypeRectangle

      A detector that searches for rectangular areas in a still image or video, returning CIRectangleFeature objects that provide information about detected regions.

      The rectangle detector finds areas that are likely to represent rectangular objects that appear in perspective in the image, such as papers or books seen on a desktop.

      Available in iOS 8.0 and later.

    • CIDetectorTypeQRCode

      CIDetectorTypeQRCode

      A detector that searches for Quick Response codes (a type of 2D barcode) in a still image or video, returning CIQRCodeFeature objects that provide information about detected barcodes.

      Available in iOS 6.0 and later.

  • Keys used in the options dictionary to configure a detector.

    Declaration

    Swift

    let CIDetectorAccuracy: NSString! let CIDetectorTracking: NSString! let CIDetectorMinFeatureSize: NSString!

    Objective-C

    NSString* const CIDetectorAccuracy;

    Constants

    • CIDetectorAccuracy

      CIDetectorAccuracy

      A key used to specify the desired accuracy for the detector.

      The value associated with the key should be one of the values found in “Detector Accuracy Options”.

      Available in iOS 5.0 and later.

    • CIDetectorTracking

      CIDetectorTracking

      A key used to enable or disable face tracking for the detector. Use this option when you want to track faces across frames in a video.

      Available in iOS 6.0 and later.

    • CIDetectorMinFeatureSize

      CIDetectorMinFeatureSize

      A key used to specify the minimum size that the detector will recognize as a feature.

      The value for this key is an NSNumber object ranging from 0.0 through 1.0 that represents a fraction of the minor dimension of the image.

      Available in iOS 6.0 and later.

  • Value options used to specify the desired accuracy of the detector.

    Declaration

    Swift

    let CIDetectorAccuracyLow: NSString! let CIDetectorAccuracyHigh: NSString!

    Objective-C

    NSString* const CIDetectorAccuracyLow; NSString* const CIDetectorAccuracyHigh;

    Constants

    • CIDetectorAccuracyLow

      CIDetectorAccuracyLow

      Indicates that the detector should choose techniques that are lower in accuracy, but can be processed more quickly.

      Available in iOS 5.0 and later.

    • CIDetectorAccuracyHigh

      CIDetectorAccuracyHigh

      Indicates that the detector should choose techniques that are higher in accuracy, even if it requires more processing time.

      Available in iOS 5.0 and later.

  • Keys used in the options dictionary for featuresInImage:options:.

    Declaration

    Swift

    let CIDetectorImageOrientation: NSString! let CIDetectorEyeBlink: NSString! let CIDetectorSmile: NSString! let CIDetectorFocalLength: NSString! let CIDetectorAspectRatio: NSString!

    Objective-C

    NSString* const CIDetectorImageOrientation; NSString* const CIDetectorEyeBlink; NSString* const CIDetectorSmile; NSString* const CIDetectorFocalLength; NSString* const CIDetectorAspectRatio;

    Constants

    • CIDetectorImageOrientation

      CIDetectorImageOrientation

      An option for the display orientation of the image whose features you want to detect.

      The value of this key is an NSNumber object whose value is an integer between 1 and 8. The TIFF and EXIF specifications define these values to indicate where the pixel coordinate origin (0,0) of the image should appear when it is displayed. The default value is 1, indicating that the origin is in the top left corner of the image. For further details, see kCGImagePropertyOrientation.

      Core Image detects only faces whose orientation matches that of the image. You should provide a value for this key if you want to detect faces in a different orientation.

      Available in iOS 5.0 and later.

    • CIDetectorEyeBlink

      CIDetectorEyeBlink

      An option for whether Core Image will perform additional processing to recognize closed eyes in detected faces.

      Available in iOS 7.0 and later.

    • CIDetectorSmile

      CIDetectorSmile

      An option for whether Core Image will perform additional processing to recognize smiles in detected faces.

      Available in iOS 7.0 and later.

    • CIDetectorFocalLength

      CIDetectorFocalLength

      An option identifying the focal length used in capturing images to be processed by the detector.

      The value of this key is an NSNumber object whose value is a floating-point number between -1.0 and 1.0. Use this option with the CIDetectorTypeRectangle detector type to fine-tune the accuracy of the detector.

      Available in iOS 8.0 and later.

    • CIDetectorAspectRatio

      CIDetectorAspectRatio

      An option specifying the aspect ratio (width divided by height) of rectangles to search for.

      The value of this key is an NSNumber object whose value is a positive floating-point number. Use this option with the CIDetectorTypeRectangle detector type to fine-tune the accuracy of the detector. For example, to more accurately find a business card (3.5 x 2 inches) in an image, specify an aspect ratio of 1.75 (3.5 / 2).

      Available in iOS 8.0 and later.