Mac Developer Library

Developer

Core Image Reference Collection 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.

  • Creates and returns a configured detector.

    Declaration

    Swift

    init(ofType type: String, context context: CIContext?, options options: [String : AnyObject]?)

    Objective-C

    + (CIDetector *)detectorOfType:(NSString *)type context:(CIContext *)context options:(NSDictionary<NSString *,id> *)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.

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    let CIDetectorTypeFace: String let CIDetectorTypeRectangle: String let CIDetectorTypeQRCode: String let CIDetectorTypeText: String

    Objective-C

    NSString* const CIDetectorTypeFace; NSString* const CIDetectorTypeRectangle; NSString* const CIDetectorTypeQRCode; NSString* const CIDetectorTypeText;

    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 OS X v10.7 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 OS X v10.10 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 OS X v10.10 and later.

    • CIDetectorTypeText

      CIDetectorTypeText

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

      The text detector finds areas that are likely to contain upright text, but does not perform optical character recognition.

      Available in OS X v10.11 and later.

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

    Declaration

    Swift

    let CIDetectorAccuracy: String let CIDetectorTracking: String let CIDetectorMinFeatureSize: String let CIDetectorNumberOfAngles: String

    Objective-C

    NSString* const CIDetectorAccuracy; NSString* const CIDetectorTracking; NSString* const CIDetectorMinFeatureSize; NSString* const CIDetectorNumberOfAngles;

    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 OS X v10.7 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 OS X v10.8 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 OS X v10.8 and later.

    • CIDetectorNumberOfAngles

      CIDetectorNumberOfAngles

      The number of perspectives to use for detecting a face in video input.

      The value for this key is an NSNumber object containing the number 1, 3, 5, 7, 9, or 11. At higher numbers of angles, face detection in video becomes more accurate, but at a higher computational cost.

      Available in OS X v10.11 and later.

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

    Declaration

    Swift

    let CIDetectorAccuracyLow: String let CIDetectorAccuracyHigh: String

    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 OS X v10.7 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 OS X v10.7 and later.

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

    Declaration

    Swift

    let CIDetectorImageOrientation: String let CIDetectorEyeBlink: String let CIDetectorSmile: String let CIDetectorFocalLength: String let CIDetectorAspectRatio: String let CIDetectorReturnSubFeatures: String

    Objective-C

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

    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 OS X v10.8 and later.

    • CIDetectorEyeBlink

      CIDetectorEyeBlink

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

      Available in OS X v10.9 and later.

    • CIDetectorSmile

      CIDetectorSmile

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

      Available in OS X v10.9 and later.

    • CIDetectorFocalLength

      CIDetectorFocalLength

      An option identifying the focal length in pixels 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. Use this option with the CIDetectorTypeRectangle detector type to control the effect of the CIDetectorAspectRatio option on feature detection.

      This option’s value can be 0.0, -1.0, or any positive value:

      • The special value of -1.0 (the default) disables the aspect ratio test for the returned rectangle.

      • The special value of 0.0 enables a less precise test of aspect ratio that approximates an orthographic (non-perspective) projection. Use this value if you want to specify the aspect ratio of the rectangle via the CIDetectorAspectRatio option, but have no means of determining the value for the focal length in pixels. See below for a method to compute an approximate value for the focal length in pixels.

      • Any other value specifies the camera focal length, in pixels, allowing the aspect ratio specification to account for perspective distortion of rectangles in the input image.

      If you know the diagonal field of view of the camera (the scene angle subtended by the diagonal corners of an image), you can use the following formula to compute an approximate focal length in pixels:

      focal_length_pixels = (image_diagonal_pixels/2)/tan(FOV/2)

      In this formula, image_diagonal_pixels is the length (in pixels) of the image diagonal of the maximum resolution of the camera sensor. (For example, this value is 4080 pixels for a 3264 x 2448 (8 megapixel) sensor, and 5000 pixels for a 4096x3024 (12 megapixel) sensor.)

      To measure diagonal field of view, put the camera on a tripod so that it is perpendicular to a surface and the center of the image is oriented on a mark on the surface. Measure the distance from the mark to one of the corner points of the image (Y). Measure the distance from the camera to the surface (Z). The field of view is then 2*arctan(Y/Z).

      You must specify this value in terms of the maximum sensor resolution. If the supplied CIImage has been scaled relative relative to the maximum sensor resolution, the supplied focal length must also be similarly scaled.

      Available in OS X v10.10 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 OS X v10.10 and later.

    • CIDetectorReturnSubFeatures

      CIDetectorReturnSubFeatures

      An option specifying whether to return feature information for components of detected features..

      The value of this key is an NSNumber object with a Boolean value. Use this option with the CIDetectorTypeText detector type to choose whether to detect only regions likely to contain text (NOfalse, the default) or to also identify sub-regions likely to contain individual characters of text (YEStrue).

      Available in OS X v10.11 and later.