DMSImageReader Class Reference

Creating an Image Reader


                    
                    
                    -initWithSymbologies:detectionType:allowFrameSkipping:options:error:

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.


                    
                    
                    -initWithSymbologies:detectionType:allowFrameSkipping:options:APIKey:error:

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:(nullable NSString *)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.

Getting Reader Results from Image Data


                    
                    
                    -processSampleBuffer:error:

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.


                    
                    
                    -processPixelBuffer:error:

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.


                    
                    
                    -processCGImage:error:

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.

Configuring Image Reader Options

symbologies
The symbologies that the image reader is configured to detect.
Declaration
Objective-C

@property (readonly) DMSSymbologies symbologies;
Swift

var symbologies: Symbologies { get }


                    
                    
                    -setSymbologies:options:error:

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.

rectOfInterest
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 CGRect rectOfInterest;
Swift

var rectOfInterest: CGRect { get set }

Managing the Image Reader

-reset
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()


                    
                    
                    -applyBestCaptureSettingsToDevice:

Configures the device with the best possible camera settings for this image readers configuration.

Detection of Digimarc digital watermark generally requires a resolution of at least 1080p, with 2592x1936 or equivalent 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 digital watermarks 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.

GPU Processing Configuration (Optional)

device
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 (readonly, nullable) id<MTLDevice> device;
Swift

var device: (any MTLDevice)? { get }


                    
                    
                    -setDevice:error:

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:(nullable id<MTLDevice>)device
            error:(NSError *_Nullable *_Nullable)error;

Swift

func setDevice(_ device: (any 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.