SBSDKScannerViewController

@interface SBSDKScannerViewController : UIViewController

UIViewController subclass showing a camera screen and running a user guiding Document detector. Detection result is visualized using a polygonal bezier path. This class cannot be instanced from a storyboard. Instead it is installing itself as a child view controller onto a given parent view controller.

  • The delegate. See SBSDKScannerViewControllerDelegate protocol. Weak.

    Declaration

    Objective-C

    @property (nonatomic, weak, readwrite, nullable)
    id<SBSDKScannerViewControllerDelegate>
        delegate;

    Swift

    weak var delegate: SBSDKScannerViewControllerDelegate? { get set }

  • The controllers camera session.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly, nonnull)
    SBSDKCameraSession *cameraSession;

    Swift

    var cameraSession: SBSDKCameraSession { get }

  • The mode of the document detector to be used for document outline detection. Defaults to standard mode.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    SBSDKDocumentDetectorMode detectorMode;

    Swift

    var detectorMode: SBSDKDocumentDetectorMode { get set }

  • YES, if energy saving is active. NO otherwise. Energy saving becomes active when shutter mode is SBSDKShutterModeSmart and, for a certain time no document has been detected and the device was not moved significantly.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL energySavingActive;

    Swift

    var energySavingActive: Bool { get }

  • The desired maximum detection rate of the receiver. The maximum number of video frames per second to

    • be analyzed. Defaults to 20.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    NSUInteger detectionRate;

    Swift

    var detectionRate: UInt { get set }

  • If set to YES (default), the camera session will be stopped entirely, when the receiver disappears and restarts when the receiver reappears. There is no CPU usage while the receiver is not on screen.

    NO will NOT stop the camera session, but pause the delivery of video frames and QR codes. There is some very low CPU activity while the receiver is not on screen, but there is also no lag when the receiver returns to the screen.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    BOOL stopsCameraSessionWhenDisappeared;

    Swift

    var stopsCameraSessionWhenDisappeared: Bool { get set }

  • The image storage. If not nil, cropped document images will be saved there, independently from what the delegate is doing. Weak.

    Declaration

    Objective-C

    @property (nonatomic, weak, readwrite, nullable) id<SBSDKImageStoring>
    imageStorage;

    Swift

    weak var imageStorage: SBSDKImageStoring? { get set }

  • Scaling factor being applied to captured still shots before processing. Must be in the range 0.0 < imageScale <= 1.0. Invalid values are treated as 1.0. Defaults to 0.8. Used to scale images before processing them. Lower numbers reduce memory pressure.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite) CGFloat imageScale;

    Swift

    var imageScale: CGFloat { get set }

  • Sensitivity factor for automatic capturing. Must be in the range [0.0…1.0]. Invalid values are treated as 1.0. Defaults to 0.66 (1 sec).s A value of 1.0 triggers automatic capturing immediately, a value of 0.0 delays the automatic by 3 seconds.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    CGFloat autoCaptureSensitivity;

    Swift

    var autoCaptureSensitivity: CGFloat { get set }

  • The minimum size in percent (0 - 100) of the screen size to accept a detected document. It is sufficient that height or width match the score. Default is 80.0. Warning: Lower values result in low resolution document images.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    double acceptedSizeScore;

    Swift

    var acceptedSizeScore: Double { get set }

  • The minimum score in percent (0 - 100) of the perspective distortion to accept a detected document. Default is 75.0. Set lower values to accept more perspective distortion. Warning: Lower values result in more blurred document images.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    double acceptedAngleScore;

    Swift

    var acceptedAngleScore: Double { get set }

  • Preferred aspect ratios for detector.

    • If nil or empty, aspect ratio will not take part in defining best document polygon.
    • If set, polygons with set aspect ratio will be more preferable.
    • Default is nil.

    Declaration

    Objective-C

    @property (nonatomic, strong, readwrite, nullable)
    NSArray<SBSDKAspectRatio *> *preferredAspectRatios;

    Swift

    var preferredAspectRatios: [SBSDKAspectRatio]? { get set }

  • Required aspect ratios for detector.

    • If not nil or empty, only polygons resulting in crops with one of the required aspect ratios will be detected.
    • Default is nil.

    Declaration

    Objective-C

    @property (nonatomic, strong, readwrite, nullable)
    NSArray<SBSDKAspectRatio *> *requiredAspectRatios;

    Swift

    var requiredAspectRatios: [SBSDKAspectRatio]? { get set }

  • The orientation captured images are locked onto. By default it is SBSDKOrientationLockNone. Setting this property to any other value will suppress the document detection status ‘SBSDKDocumentDetectionStatusOK_BadAspectRatio’. If the lock is enabled the detection status UI will be orientation-locked too.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    SBSDKOrientationLock imageOrientationLock;

    Swift

    var imageOrientationLock: SBSDKOrientationLock { get set }

  • Hides or unhides the shutter button.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    BOOL shutterButtonHidden;

    Swift

    var shutterButtonHidden: Bool { get set }

  • Hides or unhides the detection status label and polygon layer.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    BOOL detectionStatusHidden;

    Swift

    var detectionStatusHidden: Bool { get set }

  • The view finder mode of the receiver. Defaults to SBSDKFinderModeAspectRatioAutomatic.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    SBSDKFinderMode finderMode;

    Swift

    var finderMode: SBSDKFinderMode { get set }

  • If this property is set to YES, then SBSDKDocumentDetectionStatusOK_BadAspectRatio status will be suppressed and treated as SBSDKDocumentDetectionStatusOK. Default is NO.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    BOOL ignoreBadAspectRatio;

    Swift

    var ignoreBadAspectRatio: Bool { get set }

  • Machine code types (EAN, DataMatrix, Aztec, QR, etc) that can be returned in didDetectMachineReadableCodes delegate method. When nil or empty - all codes can be returned. Default is nil.

    Declaration

    Objective-C

    @property (nonatomic, strong, readwrite, nullable)
    NSArray<SBSDKBarcodeType *> *acceptedMachineCodeTypes;

    Swift

    var acceptedMachineCodeTypes: [SBSDKBarcodeType]? { get set }

  • The scanning state of the receiver. See SBSDKScannerStatus.

    Declaration

    Objective-C

    @property (nonatomic, readonly) int scannerStatus;

    Swift

    var scannerStatus: SBSDKScannerStatus { get }

  • The receivers shutter mode. See SBSDKShutterMode. Defaults to SBSDKShutterModeSmart.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    SBSDKShutterMode shutterMode;

    Swift

    var shutterMode: SBSDKShutterMode { get set }

  • Whether the receiver automatically releases the shutter or not. Powerful energy saver if combined with the delegate method (BOOL)scannerControllerShouldAnalyseVideoFrame:(SBSDKScannerViewController *)controller. If you return controller.autoShutterEnabled here the document detection is toggled off until you re-enable the auto shutter or significantly move your device.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL autoShutterEnabled;

    Swift

    var autoShutterEnabled: Bool { get }

  • The instance of the automatically created shutter button. If the receivers view is not loaded the property is nil. Setting a custom shutter button has no impact on the property.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) UIButton *defaultShutterButton;

    Swift

    var defaultShutterButton: UIButton? { get }

  • Specifies the format of the captured images handled via the delegate methods. Use SBSDKImageModeGrayscale if a grayscale image is sufficient and to avoid memory pressure. Defaults to SBSDKImageModeColor.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite) int imageMode;

    Swift

    var imageMode: SBSDKImageMode { get set }

  • Specifies the way of barcode images generation or disables this generation at all. Use, if you want to receive a full sized image with barcodes. Defaults to SBSDKBarcodeImageGenerationTypeNone.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    SBSDKBarcodeImageGenerationType barcodeImageGenerationType;

    Swift

    var barcodeImageGenerationType: SBSDKBarcodeImageGenerationType { get set }

  • Specifies the amount of frames barcode scanner takes before detecting. Uses the sharpest frame. So setting more frames generally improves recognition quality, but reduces recognition speed. Keep in mind, that detectionRate also has influence on recognition speed, as it determines the amount of frames that can be read per second. Default to 5.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    NSInteger barcodeAccumulatedFramesCount;

    Swift

    var barcodeAccumulatedFramesCount: Int { get set }

  • After capturing an image the receiver re-detects the document on the captured image in order to get a more accurate and refined document polygon. It then compares the refined polygon to the last valid polygon detected on the live video sample. An algorithm then determines automatically whether document polygon from the live video or the refined polygon from the captured image is used to finally crop the document image.

    This flags allows to override the algorithm making the polygon decision. If set to YES, always the refined polygon is used for the final cropping. Otherwise the algorithm chooses the polygon for final cropping.

    Defaults to NO.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    BOOL alwaysApplyRefinedPolygon;

    Swift

    var alwaysApplyRefinedPolygon: Bool { get set }

  • A transparent view that lies over the preview layer. You can add custom UI here. Read-only.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly, nonnull) UIView *HUDView;

    Swift

    var hudView: UIView { get }

  • Background color of detection status label. Default is red with alpha 0.5. Can be nil.

    Declaration

    Objective-C

    @property (nonatomic, strong, readwrite, nullable)
    UIColor *detectionStatusBackgroundColor;

    Swift

    var detectionStatusBackgroundColor: UIColor? { get set }

  • Text color of detection status label. Default is white. Can be nil.

    Declaration

    Objective-C

    @property (nonatomic, strong, readwrite, nullable)
    UIColor *detectionStatusTextColor;

    Swift

    var detectionStatusTextColor: UIColor? { get set }

  • Font of detection status label. Default is system font with size 17. Can be nil.

    Declaration

    Objective-C

    @property (nonatomic, strong, readwrite, nullable) UIFont *detectionStatusFont;

    Swift

    var detectionStatusFont: UIFont? { get set }

  • Background color of camera preview. Default is black. Can be nil.

    Declaration

    Objective-C

    @property (nonatomic, strong, readwrite, nullable)
    UIColor *previewBackgroundColor;

    Swift

    var previewBackgroundColor: UIColor? { get set }

  • Background color of the view finder. Default is white with 0.66 alpha. Must not be nil.

    Declaration

    Objective-C

    @property (nonatomic, strong, readwrite, nonnull)
    UIColor *viewFinderBackgroundColor;

    Swift

    var viewFinderBackgroundColor: UIColor { get set }

  • Not available.

    Declaration

    Objective-C

    - (nonnull instancetype)init;

  • Not available.

    Declaration

    Objective-C

    + (nonnull instancetype)new;

  • Line color of the view finder. Default is nil, which draws no border line for the view finder.

    Declaration

    Objective-C

    @property (nonatomic, strong, readwrite, nullable) UIColor *viewFinderLineColor;

    Swift

    var viewFinderLineColor: UIColor? { get set }

  • Line width of the view finder. Default is 2.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    CGFloat viewFinderLineWidth;

    Swift

    var viewFinderLineWidth: CGFloat { get set }

  • The current rectangle of the view finder if displayed, CGRectZero otherwise.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGRect currentViewFinderRect;

    Swift

    var currentViewFinderRect: CGRect { get }

  • Defines the region of interest when scanning barcodes or other machine readable codes. Machine readable codes found outside this region of interest are discarded and ignored during detection. The property describes the aspect ratio (width / height) of the region of interest. This aspect ratio, in conjunction with the screen size and capturingFrameMinimumInset parameter, is used to create an absolute region of interest and render a view finder like rounded rectangle on screen. The 0 aspect ratio or nil effectively disables the region of interest.

    Note: Only effective if finderMode equals SBSDKFinderModeCapturingFrame.

    Declaration

    Objective-C

    @property (nonatomic, strong, readwrite, nullable)
    SBSDKAspectRatio *capturingFrameAspectRatio;

    Swift

    var capturingFrameAspectRatio: SBSDKAspectRatio? { get set }

  • Defines a minimum inset for capturing frame. Width goes for horizontal inset, height - for vertical. Default is 32 for both parameters.

    To calculate maximum size of the finder frame you need to take the corresponding inset, multiply it by 2, and subtract it from finder’s container corresponding side. Example: If capturingFrameMinimumInset.width == 32 and finder’s container width == 320, the maximum width of finder frame will be 320 - (32 * 2) = 256

    Note: Only effective if finderMode equals SBSDKFinderModeCapturingFrame.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    UIEdgeInsets capturingFrameMinimumInset;

    Swift

    var capturingFrameMinimumInset: UIEdgeInsets { get set }

  • Designated initializer. Installs the receiver as child view controller onto the parent view controllers view using its entire bounds area.

    Declaration

    Objective-C

    - (nonnull instancetype)
    initWithParentViewController:
        (nonnull UIViewController *)parentViewController
                    imageStorage:(nullable id<SBSDKImageStoring>)storage;

    Swift

    init(parentViewController: UIViewController, imageStorage storage: SBSDKImageStoring?)

    Parameters

    parentViewController

    The view controller the newly created instance is embedded into. If parentViewController conforms to SBSDKScannerViewControllerDelegate, it is automatically set as delegate.
    storage

    The image storage to persist the shot document images. Can be nil.

  • Designated initializer. Installs the receiver as child view controller onto the parent view controllers view using its entire bounds area.

    Declaration

    Objective-C

    - (nullable instancetype)
    initWithParentViewController:
        (nonnull UIViewController *)parentViewController
                      parentView:(nullable UIView *)containerView
                    imageStorage:(nullable id<SBSDKImageStoring>)storage
           enableQRCodeDetection:(BOOL)qrCodeEnabled;

    Swift

    init?(parentViewController: UIViewController, parentView containerView: UIView?, imageStorage storage: SBSDKImageStoring?, enableQRCodeDetection qrCodeEnabled: Bool)

    Parameters

    parentViewController

    The view controller the newly created instance is embedded into. If parentViewController conforms to SBSDKScannerViewControllerDelegate, it is automatically set as delegate.
    containerView

    The view the newly created instance is embedded into. If nil the parentViewControllers view is used.
    storage

    The image storage to persist the shot document images. Can be nil.
    qrCodeEnabled

    Whether you are interested in QR code detection or not.

  • Designated initializer. Installs the receiver as child view controller onto the parent view controllers view using its entire bounds area.

    Declaration

    Objective-C

    - (nullable instancetype)
    initWithParentViewController:
        (nonnull UIViewController *)parentViewController
                      parentView:(nullable UIView *)containerView
                    imageStorage:(nullable id<SBSDKImageStoring>)storage
                documentDetector:(nullable SBSDKDocumentDetector *)detector
           enableQRCodeDetection:(BOOL)qrCodeEnabled;

    Swift

    init?(parentViewController: UIViewController, parentView containerView: UIView?, imageStorage storage: SBSDKImageStoring?, documentDetector detector: SBSDKDocumentDetector?, enableQRCodeDetection qrCodeEnabled: Bool)

    Parameters

    parentViewController

    The view controller the newly created instance is embedded into. If parentViewController conforms to SBSDKScannerViewControllerDelegate, it is automatically set as delegate.
    containerView

    The view the newly created instance is embedded into. If nil the parentViewControllers view is used.
    storage

    The image storage to persist the shot document images. Can be nil.
    detector

    The document detector instance for document outline detection.
    qrCodeEnabled

    Whether you are interested in QR code detection or not.

  • Captures a still image manually and calls the delegate methods.

    Declaration

    Objective-C

    - (BOOL)captureStillImage;

    Swift

    func captureStillImage() -> Bool

    Return Value

    YES, if the capture process has been initiated successfully. NO otherwise. Note: NO is returned if the device is currently capturing another image or if the camera session is not yet setup or broken.

  • Simulates capturing a still image manually and calls the delegate methods.

    Declaration

    Objective-C

    - (BOOL)simulateCaptureWithImage:(nullable UIImage *)image;

    Swift

    func simulateCapture(with image: UIImage?) -> Bool

    Parameters

    image

    The image that is being treated as the original image from camera.

    Return Value

    YES, if the capture process has been initiated successfully. NO otherwise. Note: NO is returned if the device is currently capturing another image or the image is nil.

  • Returns the time interval since the device has moved physically.

    Declaration

    Objective-C

    - (NSTimeInterval)timeSinceLastMotion;

    Swift

    func timeSinceLastMotion() -> TimeInterval

  • Returns the time interval since the last successful detection of a polygon.

    Declaration

    Objective-C

    - (NSTimeInterval)timeSinceLastDetectedPolygon;

    Swift

    func timeSinceLastDetectedPolygon() -> TimeInterval