Skip to main content
Version: v8xxx

Scanning use cases

note

Added in BlinkID Web v8003.0.0, and in BlinkID Android and iOS v8002.0.0. Earlier v8xxx versions don't have use cases; configure session settings and scanning settings directly instead.

BlinkID has more than 30 scanning settings. Instead of setting them one by one, you can describe your use case and let BlinkID build the matching session settings for you.

You can override individual settings before you start the scanning session.

Use cases​

We offer the following main use cases:

  • Document video: live document scanning from a camera stream.
  • Document photo: document scanning from a single photo or gallery image.
  • Standalone barcode: barcode scanning without document detection.
  • Verify capture: live camera capture for images you send to BlinkID Verify.

Use cases are represented by their corresponding builders, functions which return the final session settings.

The builders are functions on the core instance returned by loadBlinkIdCore, and on the presetBuilder that createBlinkId passes to presetScanningSettingsBuilder. Each returns a promise that resolves to the session settings.

  • Document video: buildDocumentVideoSettings(useCase?: DocumentVideoUseCase)
  • Document photo: buildDocumentPhotoSettings(useCase?: DocumentPhotoUseCase)
  • Standalone barcode: buildStandaloneBarcodeSettings()
  • Verify capture: buildVerifyCaptureSettings()

Build session settings from a use case​

Pass a use case object to the builder. Every option is optional; options you leave out use their default value.

With the @microblink/blinkid package, pass presetScanningSettingsBuilder to createBlinkId. The callback receives a builder that exposes the four builder functions. You can't combine presetScanningSettingsBuilder with the scanningSettings and scanningMode options.

import { createBlinkId } from "@microblink/blinkid";

const blinkId = await createBlinkId({
  licenseKey: "your-license-key",
  presetScanningSettingsBuilder: (presetBuilder) =>
    presetBuilder.buildDocumentVideoSettings({
      scenario: "mrz-mandatory",
      quality: "high-accuracy",
    }),
});

With the @microblink/blinkid-core package, the builder functions are available on the loaded core instance. Pass the result to createScanningSession:

import { loadBlinkIdCore } from "@microblink/blinkid-core";

const blinkIdCore = await loadBlinkIdCore({ licenseKey: "your-license-key" });

const sessionSettings = await blinkIdCore.buildDocumentVideoSettings({
  scenario: "mrz-mandatory",
  quality: "high-accuracy",
});

const session = await blinkIdCore.createScanningSession(sessionSettings);

Options​

The document video use case has three options: scenario, quality, and captureEnvironment. The document photo use case has two: scenario and quality. The standalone barcode and Verify capture builders take no options.

scenario

type: DocumentScenario, default: "general"

Available in DocumentVideoUseCase and DocumentPhotoUseCase. Selects which extraction modules run, and what must be present for a successful scan. Document capture is always enabled.

  • "general": standard ID scanning with all modules enabled
  • "mrz-mandatory": the scan only completes if an MRZ is present; VIZ and barcode are still read
  • "mrz-only": single-side scan that reads only the MRZ
  • "barcode-only": single-side scan that reads only the barcode of a detected document

quality (video)

type: VideoQualityProfile, default: "balanced"

Available in DocumentVideoUseCase. Selects the trade-off between capture speed and result accuracy.

  • "balanced": default balance between capture speed and result accuracy
  • "high-speed": selects the fastest acceptable frame and lowers blur, glare, and tilt sensitivity
  • "high-accuracy": raises quality thresholds, requires a face image, and reads the VIZ from a single best frame instead of combining multiple frames
  • "permissive": lowers quality thresholds and accepts frames with blur, glare, poor lighting, or hand occlusion

quality (photo)

type: PhotoQualityProfile, default: "balanced"

Available in DocumentPhotoUseCase. Selects the trade-off between result accuracy and tolerance for lower-quality input.

  • "balanced": default quality settings for photo input
  • "high-accuracy": raises quality thresholds and requires a face image
  • "permissive": lowers quality thresholds, accepts images with quality issues, and turns off VIZ character validation

captureEnvironment

type: VideoCaptureEnvironment, default: "hand-held"

Available in DocumentVideoUseCase. Describes the physical setup of the camera.

  • "hand-held": a hand-held mobile camera
  • "stationary": a fixed camera, such as a kiosk; the document may reach the edge of the frame
tip

The barcode-only scenario still detects the document and reads its barcode. To read barcodes directly from the frame, without detecting a document, use the standalone barcode builder instead.

Settings applied by each option​

Each builder starts from the default session settings and changes only the settings listed below. All other settings keep their default values. Unless stated otherwise, the quality settings are in documentCaptureModule.

Scenario

  • "general": no changes
  • "mrz-mandatory":
    • scanningMode: "automatic"
    • mrzModule.presenceMandatory: true
  • "mrz-only":
    • scanningMode: "single"
    • vizModule: null
    • barcodeModule: null
    • mrzModule.presenceMandatory: true
  • "barcode-only":
    • scanningMode: "single"
    • vizModule: null
    • mrzModule: null
    • barcodeModule.presenceMandatory: true

Video quality

  • "balanced": no changes
  • "high-speed":
    • inputImageSelectionStrategy: "optimize-for-speed"
    • blurSensitivityLevel: "low"
    • glareSensitivityLevel: "low"
    • tiltSensitivityLevel: "low"
  • "high-accuracy":
    • inputImageSelectionStrategy: "optimize-for-quality"
    • dotsPerInch: 400
    • blurSensitivityLevel: "high"
    • glareSensitivityLevel: "high"
    • tiltSensitivityLevel: "high"
    • faceImageExtractionEnabled: true
    • faceImagePresenceMandatory: true
    • vizModule.resultAggregationEnabled: false
  • "permissive":
    • inputImageSelectionStrategy: "single-image"
    • blurSensitivityLevel: "low"
    • glareSensitivityLevel: "low"
    • tiltSensitivityLevel: "low"
    • imageWithBlurRejected: false
    • imageWithGlareRejected: false
    • imageWithPoorLightingRejected: false
    • imageWithHandOcclusionRejected: false

Photo quality

The document photo builder always sets inputImageSource to "photo".

  • "balanced": no other changes
  • "high-accuracy":
    • dotsPerInch: 400
    • blurSensitivityLevel: "high"
    • glareSensitivityLevel: "high"
    • tiltSensitivityLevel: "high"
    • faceImageExtractionEnabled: true
    • faceImagePresenceMandatory: true
  • "permissive":
    • cropType: "unknown"
    • blurSensitivityLevel: "low"
    • glareSensitivityLevel: "low"
    • tiltSensitivityLevel: "off"
    • imageWithBlurRejected: false
    • imageWithGlareRejected: false
    • imageWithPoorLightingRejected: false
    • imageWithHandOcclusionRejected: false
    • vizModule.characterValidationEnabled: false

Capture environment

  • "hand-held": no changes
  • "stationary":
    • documentCaptureModule.inputImageMargin: 0.0

Standalone barcode

  • scanningMode: "single"
  • documentCaptureModule: null
  • vizModule: null
  • mrzModule: null
  • barcodeModule.presenceMandatory: true
  • all barcode formats enabled: PDF417, QR, UPC-A, UPC-E, EAN-8, EAN-13, Code 128, Code 39, ITF, Data Matrix, and Aztec

Verify capture

Starts from the default document video settings ("general", "balanced", "hand-held"), then sets:

  • documentCaptureModule.faceImageExtractionEnabled: true
  • documentCaptureModule.inputImageReturnEnabled: true
  • vizModule.resultAggregationEnabled: false
  • barcodeModule.barcodeImageReturnEnabled: true

Change individual settings​

The builders return regular session settings, so you can change any setting before you start the session. The following example starts from the default document video settings and also returns the cropped document image.

import { createBlinkId } from "@microblink/blinkid";

const blinkId = await createBlinkId({
  licenseKey: "your-license-key",
  presetScanningSettingsBuilder: async (presetBuilder) => {
    const settings = await presetBuilder.buildDocumentVideoSettings();

    return {
      ...settings,
      scanningSettings: {
        ...settings.scanningSettings,
        documentCaptureModule: {
          ...settings.scanningSettings.documentCaptureModule,
          documentImageReturnEnabled: true,
        },
      },
    };
  },
});

Changed settings are still subject to settings validation.

Last updated on