DMSImageReader


@interface DMSImageReader : DMSReader

Image readers synchronously process images and will return an array of payload classes that reflect the results found in the image. An image reader takes a CMSampleBuffer as input, which is the native media type of camera and video frames on iOS. The image will accept CMSampleBufferRefs that contain any image format, but the reader will work the most efficiently when the sample buffers contain an image in a YpCbCr8:420 Bi Planar format. AVFoundation can be configured to return CMSampleBufferRefs in this format directly.

  • Custom initializer for a new image reader for the given symbologies.

    Declaration

    Objective-C

    - (nullable instancetype)
        initWithSymbologies:(DMSSymbologies)symbologies
              detectionType:(DMSImageDetectionType)detectionType
         allowFrameSkipping:(BOOL)allowFrameSkipping
                    options:(nonnull NSDictionary<DMSReaderOptionKey, id> *)options
                      error:(NSError *_Nullable *_Nullable)error;

    Swift

    init(symbologies: Symbologies, detectionType: ImageDetectionType, allowFrameSkipping: Bool, options: [ReaderOptionKey : Any] = [:]) throws

    Parameters

    symbologies

    The set of symbologies the reader should attempt to detect. This is defined by the DMSSymbology set. The ImageDigimarc detector must be in the list of provided detectors.

    options

    A dictionary of options for the reader.

    error

    An error returned by this function. Typically returned if a set of options is inconsistent, or if the current or supplied license key is invalid.

    detectionType

    The type of detection to perform. This argument can be used to control of detection should be done quickly but less accurately (which is suitable for video frames), or throughly but intensive (for a still image.) This will override any related option supplied in the options dictionary.

    allowFrameSkipping

    If true, allows the reader to drop frames in order to preserve battery life and CPU. This setting is recommended, unless you are doing your own frame dropping, or are working on with image buffers where results cannot be dropped. In most situations, detecting at the full frame rate of a camera is not necessary. This will override any related option supplied in the options dictionary.

    Return Value

    Returns a new image detector. May return nil.

  • Designated initializer for a new image reader for the given symbologies.

    Declaration

    Objective-C

    - (nullable instancetype)
        initWithSymbologies:(DMSSymbologies)symbologies
              detectionType:(DMSImageDetectionType)detectionType
         allowFrameSkipping:(BOOL)allowFrameSkipping
                    options:(nonnull NSDictionary<DMSReaderOptionKey, id> *)options
                     APIKey:(NSString *_Nullable)APIKey
                      error:(NSError *_Nullable *_Nullable)error;

    Swift

    init(symbologies: Symbologies, detectionType: ImageDetectionType, allowFrameSkipping: Bool, options: [ReaderOptionKey : Any] = [:], apiKey APIKey: String?) throws

    Parameters

    symbologies

    The set of symbologies the reader should attempt to detect. This is defined by the DMSSymbology set. The ImageDigimarc detector must be in the list of provided detectors.

    options

    A dictionary of options for the reader.

    detectionType

    The type of detection to perform. This argument can be used to control of detection should be done quickly but less accurately (which is suitable for video frames), or throughly but intensive (for a still image.) This will override any related option supplied in the options dictionary.

    allowFrameSkipping

    If true, allows the reader to drop frames in order to preserve battery life and CPU. This setting is recommended, unless you are doing your own frame dropping, or are working on with image buffers where results cannot be dropped. In most situations, detecting at the full frame rate of a camera is not necessary. This will override any related option supplied in the options dictionary.

    error

    An error returned by this function. Typically returned if a set of options is inconsistent, or if the current or supplied license key is invalid.

    APIKey

    Custom API key to use. Will override any other currently set API key.

    Return Value

    Returns a new image detector. May return nil.

  • Processes a single sample buffer and returns either an empty array, or an array of results as payload objects.

    Declaration

    Objective-C

    - (nullable DMSReaderResult *)
        processSampleBuffer:(nonnull CMSampleBufferRef)buffer
                      error:(NSError *_Nullable *_Nullable)error;

    Swift

    func process(sampleBuffer buffer: CMSampleBuffer) throws -> ReaderResult

    Parameters

    buffer

    The sample buffer to process. The sample buffer should be in YpCbCr8:420 Bi Planar format for maximum performance.

    error

    An error resulting from processing the sample buffer. Examples of errors include being unable to handle the CMSampleBuffer, or being passed a sample buffer that does not contain an image.

    Return Value

    A reader result containing zero or more payloads. Returns null if an error occurred.

  • Processes a single pixel buffer and returns either an empty array, or an array of results as payload objects. The processSampleBuffer:error: function should be preferred over this function. CMSampleBuffers contain extra information about the image that can be used to better inform the detection process. Using a CVPixelBuffer may cause detection to be less robust, or more expensive. If it is not recommended that developers manually unpack a CVPixelBuffer from a CMSampleBuffer themselves. This function is meant to provide compatiblity with APIs that only provide CVPixelBuffers, like ARKit.

    Declaration

    Objective-C

    - (nullable DMSReaderResult *)
        processPixelBuffer:(nonnull CVPixelBufferRef)buffer
                     error:(NSError *_Nullable *_Nullable)error;

    Swift

    func process(pixelBuffer buffer: CVPixelBuffer) throws -> ReaderResult

    Parameters

    buffer

    The pixel buffer to process.

    error

    If not nil, an error preventing processing the pixel buffer.

    Return Value

    A reader result containing zero or more payloads. Returns null if an error occurred.

  • Processes a single CGImage and returns either an empty array, or an array of results as payload objects. The processSampleBuffer:error: function should be preferred over this function. CGImages are encoded in a less ideal format that CMSampleBuffers. Only use this function if your source data is CGImage, like a bitmap image from a file. This function may need to internally convert the image to a more comptiable format, which will take extra time.

    Declaration

    Objective-C

    - (nullable DMSReaderResult *)processCGImage:(nonnull CGImageRef)image
                                           error:
                                               (NSError *_Nullable *_Nullable)error;

    Swift

    func processCGImage(_ image: CGImage) throws -> ReaderResult

    Parameters

    image

    The pixel buffer to process.

    error

    If not nil, an error preventing processing the pixel buffer.

    Return Value

    A reader result containing zero or more payloads. Returns null if an error occurred.

  • The symbologies that the image reader is configured to detect.

    Declaration

    Objective-C

    @property (atomic, readonly) DMSSymbologies symbologies;

    Swift

    var symbologies: Symbologies { get }
  • Sets symbologies and reader options.

    Declaration

    Objective-C

    - (BOOL)setSymbologies:(DMSSymbologies)symbologies
                   options:(nonnull NSDictionary<DMSReaderOptionKey, id> *)options
                     error:(NSError *_Nullable *_Nullable)error;

    Swift

    func setSymbologies(_ symbologies: Symbologies, options: [ReaderOptionKey : Any] = [:]) throws

    Parameters

    symbologies

    Symbologies to configure the reader to detect.

    options

    Options to configure the reader with.

    error

    An error returned by this function. Typically returned if a set of options is inconsistent, or if the current or supplied license key is invalid.

  • Limits the detection area to a specific region. rectOfInterest is a normalized value that defines the region of interest between 0..1 for both the height and the width of the image. This rect interoperates with AVFoundation’s rectOfInterest class of functions for converting between real pixel values and normalized values.

    Declaration

    Objective-C

    @property (atomic, assign, unsafe_unretained, readwrite) CGRect rectOfInterest;

    Swift

    var rectOfInterest: CGRect { get set }
  • Resets the reader to its default state. Any previously detected payloads will be reported as new payloads again.

    Declaration

    Objective-C

    - (void)reset;

    Swift

    func reset()
  • Configures the device with the best possible camera settings for this image readers configuration.

    Detection of Digimarc Barcode generally requires a resolution of at least 1080p, with 2592x1936 or equivelent being the recommended resolution. For detections from distances longer than a few feet, 4k resolution is suggested. This function will attempt to set the proper resolution and other settings based on how the detector has been configured. Content that has been embedded with Digimarc Barcode can have varying detection strength. Lower resolutions may impact readability of certain content. Capture at resolutions lower than 1080p is supported but not recommended. Digimarc strongly recommends testing your application with the content your application is intended to be used with if your application is using a lower resolution than recommended.

    Some third party frameworks, such as ARKit, may take control of the camera and offer a restricted ability to configure the camera. When integrating with these frameworks, you may have to manually configure the camera to a desirable resoluition instead of using this function.

    Other attributes of the capture device, such as lack of autofocus, may also impact reliability and robustness of detection. Some Apple devices, like Macs with 720p webcams, may provide a degraded detection experience. These types of cameras may work best with Digimarc Barcodes that have been embedded at a high strength.

    Declaration

    Objective-C

    - (void)applyBestCaptureSettingsToDevice:(nonnull AVCaptureDevice *)device;

    Swift

    func applyBestCaptureSettings(to device: AVCaptureDevice)

    Parameters

    device

    The device to configure.

  • The Metal device that will be used for acceleration. If nil, only the CPU will be used. This will be automatically populated with the most ideal device, if present. If you want to use a different Metal device, or disable Metal completely, this device can be changed through the setDevice:error: function.

    Declaration

    Objective-C

    @property (atomic, readonly, nullable) id<MTLDevice> device;

    Swift

    var device: MTLDevice? { get }
  • Sets the Metal device used for acceleration. An image reader can optionally use Metal for some, but not all, of the operations it executes. The use of Metal may be changed or expanded in the future.

    Declaration

    Objective-C

    - (BOOL)setDevice:(id<MTLDevice> _Nullable)device
                error:(NSError *_Nullable *_Nullable)error;

    Swift

    func setDevice(_ device: MTLDevice?) throws

    Parameters

    device

    The device to use for Metal acceleration. Can be nil, in which case Metal will be disabled. When Metal is disabled, the image reader will use a CPU path.

    error

    Error value if the Metal device could not be set. Examples of this include if the device is not capable, or the OS is not compatible. Notably some devices like the iPhone 5S, and some OS versions like iOS 10 are not supported for Metal. If an error occurs, the developer might want to pick a different Metal device, or do nothing and allow DMSDK to pick the best strategy. As a gemeral rule, any device that is compatible with Metal Performance Shaders should work. But this support may change in the future, and there are other factors that will currently determine if a device is compatible.