DMSReaderResult


@interface DMSReaderResult : NSObject

The ReaderResult class wraps data that is returned from a Reader class. This includes the payloads, which represent each different symbol found in the processed image frame. A ReaderResult may contain some or no payloads. In addition, a ReaderResult may contain additional metadata that is specific to the detection operation, such as timing information. A ReaderResult may asynchrounously add more Payloads after it’s been returned from a reader. Payloads that can be found locally on the device will be immediately available, while payloads that require additional resources such as cloud resources might be added asynchronously. The deferredPayloadResultsQueue contains an operation for each potential payload that is still being search for in the frame. If you would like to synchronize against any potential payloads that are still being processed, there are several options.

  • The waitForAllDeferredPayloads option will pause the current thread and continue execution once the remaining potential payloads have been processed.
  • The deferredPayloadResultsQueue that will contain an operation for each potential new payload, and can be inspected or have additional task dependencies added by a developer.
  • The payloads property is KVO compliant, so changes to the payloads can be observed.

Retrieving Detected Payloads from the Reader Result

  • The payloads detected by the reader.

    Declaration

    Objective-C

    @property (copy, readonly, nonnull) NSArray<DMSPayload *> *payloads;

    Swift

    var payloads: [Payload] { get }

  • Payloads that likely entered into frame, assuming images are being passed in a sequential stream. This includes both payloads being seen for the first time, and payloads that have not been seen for an indeterminate amount of time, but are being seen again. If images are not being passed into the reader sequentially, or the source is not a capture session, this property should be ignored.

    Declaration

    Objective-C

    @property (copy, readonly, getter=newPayloads, nonnull) NSArray<DMSPayload *> *newPayloads;

    Swift

    var newPayloads: [Payload] { get }

Retrieving the Image Associated With the Reader Result

  • The sample buffer that the read was performed on. This property is transient, and ReaderResult will not retain the sample buffer. For capture readers, this property will only be available inside of the context of the capture reader delegate result method.

    Declaration

    Objective-C

    @property (readonly, nullable) CMSampleBufferRef sourceSampleBuffer;

    Swift

    var sourceSampleBuffer: CMSampleBuffer? { get }

  • Returns the source sample buffer as a UIImage. Returns nil if the source sample buffer is not image data, or if the source sample buffer has been released.

    Declaration

    Objective-C

    - (nullable UIImage *)newImageFromSourceSampleBuffer;

    Swift

    func newImageFromSourceSampleBuffer() -> UIImage?

Managing Deferred Payloads

  • A queue containing an operation for detection operations that are executing asynchronously. Operations in this queue may be using resources from remote or cloud resources. After a ReaderResult is returned by a reader, new operations will not be added to a queue. All operations in the queue will represent the total amount of outstanding work. If there are no operations in this queue, no deferred payloads will be added.

    Declaration

    Objective-C

    @property (readonly, nonnull) NSOperationQueue *deferredPayloadResultsQueue;

    Swift

    var deferredPayloadResultsQueue: OperationQueue { get }

  • Pauses the current thread until all deferred payloads have been loaded. Returns an array of any new payloads that were found while the thread was paused.

    Declaration

    Objective-C

    - (nonnull NSArray<DMSPayload *> *)waitForAllDeferredPayloads;

    Swift

    func waitForAllDeferredPayloads() -> [Payload]

Errors

  • Array of errors that occured as a result of detection operations. This array could contain multiple errors for different symbology types. KVO compliant.

    Declaration

    Objective-C

    @property (readonly, nonnull) NSArray<NSError *> *errors;

    Swift

    var errors: [any Error] { get }

Retrieving Metadata for a Payload

  • The time at which the reader result was recorded. This time is in the context of the stream that originated the image. If the image that was passed for detection contained no timing metadata, the value is kCMTimeInvalid.

    Declaration

    Objective-C

    @property CMTime time;

    Swift

    var time: CMTime { get set }

  • The symbologies for this result that detections were actually executed for. DMSDK performs load balancing based on the current device and other conditions. Where possible (such as video frames), DMSDK may not perform detections for each configured symbology on every frame. Applications that are sensitive to this behavior should either monitor this property, or use the DMSImageReaderOptionStrategyKey and it’s associated DMSReaderStrategy values with an image reader or a video capture reader. For most use cases, this property can be safely ignored. At present, audio based detectors will always have executed for every result.

    Declaration

    Objective-C

    @property (readonly) DMSSymbologies executedSymbologies;

    Swift

    var executedSymbologies: Symbologies { get }

  • Rotation of a given payload. Rotation may be applicable for payloads that are formed by a repeating grid. These payloads don’t have a clear detection bounding box, but the plane of the grid may have an angle relative to the image frame.

    Declaration

    Objective-C

    - (nullable DMSPayloadMetadata *)metadataForPayload:
    (nonnull DMSPayload *)payload;

    Swift

    func metadata(for payload: Payload) -> PayloadMetadata?

    Parameters

    payload

    The payload to return the metadata for. The payload must be a member of the read result’s payloads and cannot be a copy.

    Return Value

    The metadata dictionary of the payload. The keys of the dictionary are defined by the result metadata types.