Skip to main content

Using ScanbotCameraView | Android Document Scanner

The Android camera API might seem very tricky and far from being developer-friendly (in fact, very far). To help you avoid the same issues which we have encountered while developing Scanbot, we created the ScanbotCameraView.

Getting Started#

ScanbotCameraView is available with the SDK Package 1. To get started, you have to undertake 3 steps.

First: Add this permission to the AndroidManifest.xml

<uses-permission android:name="android.permission.CAMERA" />

Second: Add it to your layout, which is as simple as:

<io.scanbot.sdk.camera.ScanbotCameraView        android:id="@+id/camera"        android:layout_width="match_parent"        android:layout_height="match_parent" />

Third: Delegate onResume and onPause methods of your Activity (or Fragment, whatever you are using) to ScanbotCameraView:

class MyActivity : Activity() {
    ...
    override fun onResume() {        super.onResume()        scanbotCameraView.onResume()    }
    override fun onPause() {        scanbotCameraView.onPause()        super.onPause()    }}

You can start your app and you should see the camera preview.

Preview Mode#

The ScanbotCameraView supports 2 preview modes:

  • CameraPreviewMode.FIT_IN - in this mode camera preview frames will be downscaled to the layout view size. Full preview frame content will be visible, but unused edges might appear in the preview layout.
  • CameraPreviewMode.FILL_IN - in this mode camera preview frames fill the layout view. The preview frames may contain additional content on the edges that is not visible in the preview layout.

By default, ScanbotCameraView uses FILL_IN mode. You can change it using the cameraView.setPreviewMode(CameraPreviewMode.FIT_IN) method.

Auto-focus Sound and Shutter Sound#

You can enable/disable auto-focus sounds and/or shutter sounds using setters in ScanbotCameraView.

cameraView.setCameraOpenCallback(object : CameraOpenCallback {    override fun onCameraOpened() {        cameraView.postDelayed({            cameraView.setAutoFocusSound(false)            cameraView.setShutterSound(false)        }, 700)    }})

cameraView.setShutterSound(boolean enabled) set the camera shutter sound state. By default - true, the camera plays the system-defined camera shutter sound when takePicture() is called.

Note that devices may not always allow disabling the camera shutter sound. If the shutter sound state cannot be set to the desired value, this method will be ignored (link).

Continuous Focus Mode#

For most use cases it is recommended to enable the "Continuous Focus Mode" of the Camera. Use the continuousFocus() method of ScanbotCameraView for this. It should be called from the main thread and only when the camera is opened (CameraOpenCallback):

cameraView.setCameraOpenCallback(object : CameraOpenCallback {    override fun onCameraOpened() {        cameraView.postDelayed({            cameraView.continuousFocus()        }, 700)    }})

Please note: The Continuous Focus Mode will be automatically disabled after:

  • autoFocus method call;
  • a tap on the ScanbotCameraView to perform auto focus;
  • takePicture event.

In these cases you have to call the continuousFocus() method again to re-enable the Continuous Focus Mode.

Example for the takePicture event, handled in the onPictureTaken(..) method of PictureCallback:

override fun onPictureTaken(image: ByteArray, captureInfo: CaptureInfo) {    // image processing ...    // ...
    cameraView.post {        cameraView.continuousFocus()        cameraView.startPreview()    }}

Auto Focus Troubleshooting#

If there is a case where the camera snaps a document (barcode, etc) before auto focus has ended properly, consider checking the delayAfterFocusComplete property of camera view to make the camera wait before snapping after the core component has been notified that auto focus has ended.

Orientation Lock#

By default the ScanbotCameraView will create pictures with orientation based on the current device orientation. It is important to understand that the orientation of the taken picture is independent of the locked orientation mode of the Activity!

For example: if you just lock the Activity to portrait mode, the orientation of the taken image will still be based on the current device orientation!

Since version 1.31.1 the Scanbot SDK provides the functionality to apply a real orientation lock in ScanbotCameraView. You can use the new methods cameraView.lockToLandscape(lockPicture: Boolean) or cameraView.lockToPortrait(lockPicture: Boolean) to lock the Activity and the taken picture to a desired orientation.

Front Facing Camera#

The Scanbot SDK provides an ability to set up a front facing camera as a source for the preview content. To enable it you have to set a front facing camera mode with the method setCameraModule(cameraModule: CameraModule) in ScanbotCameraView or ScanbotCameraXView. By default - CameraModule.BACK.

Possible options here include:

  • CameraModule.BACK - default back facing camera will be used.
  • CameraModule.FRONT - the default front facing camera will be used. The visual preview on the screen, buffer byte array in all FrameHandlers and snapped pictures will be in the origin state.
  • CameraModule.FRONT_MIRRORED - the default front facing camera will be used. The visual preview on the screen and buffer byte array in all FrameHandlers will be mirrored, but snapped pictures will be in the origin state.

Advanced: Preview Size and Picture Size#

By default the ScanbotCameraView selects the best available picture size (resolution of the taken picture) and a suitable preview size (preview frames).

You can change these values using the setter methods of ScanbotCameraView:

cameraView.setCameraOpenCallback {    cameraView.stopPreview()
    val supportedPictureSizes: List<Camera.Size> = cameraView.supportedPictureSizes    // For demo purposes we just take the first picture size from the supported list!    cameraView.setPictureSize(supportedPictureSizes[0])
    val supportedPreviewSizes: List<Camera.Size> = cameraView.supportedPreviewSizes    // For demo purposes we just take the first preview size from the supported list!    cameraView.setPreviewSize(supportedPreviewSizes[0])
    cameraView.startPreview()}
caution

Please take the following into account when changing these values: on most devices the aspect ratio of the camera sensor (camera picture) does not match the aspect ratio of the display.