Merge pull request #8 from BlinkID/release/1.4.0

Release/1.4.0

Author: i1E

CaptureSample/app-direct-api/src/main/java/com/microblink/capture/sample/camera/CustomCameraActivity.kt

@@ -23,6 +23,7 @@ import androidx.camera.view.PreviewView
 import androidx.core.content.ContextCompat
 import androidx.core.os.BundleCompat
 import androidx.core.widget.TextViewCompat
+import com.microblink.capture.analysis.CaptureState
 import com.microblink.capture.analysis.FrameAnalysisResult
 import com.microblink.capture.analysis.FrameAnalysisStatus
 import com.microblink.capture.directapi.AnalyzerRunner
@@ -181,12 +182,12 @@ class CustomCameraActivity : AppCompatActivity() {
 
     private fun handleFrameAnalysisResult(frameAnalysisResult: FrameAnalysisResult) {
         when (frameAnalysisResult.captureState) {
-            FrameAnalysisResult.CaptureState.FirstSideCaptureInProgress,
-            FrameAnalysisResult.CaptureState.SecondSideCaptureInProgress -> run {
+            CaptureState.FirstSideCaptureInProgress,
+            CaptureState.SecondSideCaptureInProgress -> run {
                 val processingFailure = getProcessingFailureTypeFromAnalysisResult(frameAnalysisResult.frameAnalysisStatus)
                 nextUiMessage = when (processingFailure) {
                     ProcessingFailureType.DOCUMENT_FRAMING_NO_DOCUMENT -> {
-                        if (frameAnalysisResult.captureState == FrameAnalysisResult.CaptureState.FirstSideCaptureInProgress) {
+                        if (frameAnalysisResult.captureState == CaptureState.FirstSideCaptureInProgress) {
                             UiMessage.SENSING_FRONT_SIDE
                         } else {
                             UiMessage.SENSING_BACK_SIDE
@@ -207,10 +208,10 @@ class CustomCameraActivity : AppCompatActivity() {
                     null -> UiMessage.PROCESSING
                 }
             }
-            FrameAnalysisResult.CaptureState.SideCaptured -> {
+            CaptureState.SideCaptured -> {
                 nextUiMessage = UiMessage.FLIP_DOCUMENT_SIDE
             }
-            FrameAnalysisResult.CaptureState.DocumentCaptured -> {
+            CaptureState.DocumentCaptured -> {
                 // pause scanning early here to avoid further analysis while finishing activity
                 captureStreamAnalyzer.pauseAnalysis()
 

CaptureSample/build.gradle.kts

@@ -1,19 +1,19 @@
 buildscript {
     val kotlin_compiler_extension_version by extra("1.4.7")
     val core_ktx_version by extra("1.12.0")
-    val material_version by extra("1.11.0")
+    val material_version by extra("1.12.0")
     val appcompat_version by extra("1.6.1")
     val compose_version by extra("1.4.3")
     val compose_bom_version by extra("2023.08.00")
     val navigation_compose_version by extra("2.7.7")
-    val camerax_version by extra("1.2.3")
+    val camerax_version by extra("1.3.4")
     // Capture SDK version
-    val capture_version by extra("1.3.0")
+    val capture_version by extra("1.4.0")
 
 }
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 plugins {
-    id("com.android.application") version "8.3.0" apply false
-    id("com.android.library") version "8.3.0" apply false
+    id("com.android.application") version "8.4.1" apply false
+    id("com.android.library") version "8.4.1" apply false
     id("org.jetbrains.kotlin.android") version "1.8.21" apply false
 }

CaptureSample/gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 #Mon Jun 12 11:41:55 CEST 2023
 distributionBase=GRADLE_USER_HOME
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
 distributionPath=wrapper/dists
 zipStorePath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME

CaptureSample/lib-common/src/main/assets/com.microblink.capture.sample.mblic

@@ -22,9 +22,12 @@ In the results, you can get a cropped, perspective-corrected image of the docume
 * [Customizing the look and UX](#customizing-the-look)
 * [Changing default strings and localization](#changing-strings-and-localization)
     * [Defining your own string resources for UI elements](#using-own-string-resources)
+* [Using Capture filter](#capture-filter)
+    * [Using provided `BlinkIdCaptureFilter`](#blinkid-capture-filter)
 * [Completely custom UX with Direct API (advanced)](#direct-api)
     * [The `AnalyzerRunner`](#analyzer-runner)
 * [Troubleshooting](#troubleshoot)
+    * [Resolving conflict on `libc++_shared.so`](#dynamicCppRuntime)
 * [Additional info](#additional-info)
     * [Capture SDK size](#sdk-size)
     * [API documentation](#api-documentation)
@@ -65,7 +68,7 @@ Add _Capture_ as a dependency in module level build.gradle(.kts):
 
 ```
 dependencies {
-    implementation("com.microblink:capture-ux:1.3.0")
+    implementation("com.microblink:capture-ux:1.4.0")
 }
 ```
 
@@ -122,7 +125,7 @@ dependencies {
     // method within MyActivity from previous step
     public fun startScanning() {
         // Start scanning
-        resultLauncher.launch()
+        captureLauncher.launch(CaptureSettings())
     }
     ```
 
@@ -325,6 +328,72 @@ val captureSettings = CaptureSettings(
 
 ```
 
+# <a name="capture-filter"></a> Using Capture filter
+
+If you need additional checks on Capture result images, you can use [CaptureFilter](https://blinkid.github.io/capture-android/capture-ux/com.microblink.capture.analysis/-capture-filter/index.html). This feature is optional.
+
+Capture filter can be used with an external validation tool, such as `BlinkID`, to confirm that the image is of sufficient quality before ending the scanning process. During this, the scanning session is not stopping or restarting, therefore not causing friction on the end-user side.
+
+Capture filter filters capture results after each successful side capture (accepts or drops captured side). If the captured image is filtered out, the capture process is restarted for the current side and the same side is captured again in the same camera session.
+
+You can set your implementation of the `CaptureFilter` on the `CaptureSettings` like this:
+
+```kotlin
+val captureSettings = CaptureSettings(
+    filterSettings = FilterSettings (
+        // your implementation of the CaptureFilter interface
+        YourCaptureFilterImplementation()
+    )
+)
+
+```
+
+We are providing one specific implementation of the `CaptureFilter` which uses the BlinkID SDK and accepts document images that are extractable by the BlinkID SDK. Usage of the `BlinkIdCaptureFilter` is described in the following section.
+
+## <a name="blinkid-capture-filter"></a> Using provided `BlinkIdCaptureFilter`
+
+[BlinkIdCaptureFilter](https://blinkid.github.io/capture-android/capture-filter-blinkid/com.microblink.capture.filter.blinkid/-blink-id-capture-filter/index.html)  implementation uses BlinkID SDK for filtering of capture results. For each successful side capture, this filter runs BlinkID extraction on the captured side image and side capture results are accepted only if the image is extractable by the BlinkID SDK.
+
+To use the `BlinkIdCaptureFilter`, you first need to add additional dependency in module level build.gradle(.kts):
+
+
+```kotlin
+dependencies {
+    // this will also add transitive dependency to the BlinkID SDK
+    implementation("com.microblink:capture-filter-blinkid:1.0.0")
+}
+```
+
+Because `BlinkIdCaptureFiler` internally uses BlinkID SDK, you will also need to set the valid license key for the BlinkID SDK. We recommend that you extend [Android Application class](https://developer.android.com/reference/android/app/Application.html) and set the license in [onCreate callback](https://developer.android.com/reference/android/app/Application.html#onCreate()), it can be done in the same place as for the Capture SDK license key:
+
+
+```kotlin
+   public class MyApplication : Application() {
+       override fun onCreate() {
+           // setting license key for the Capture SDK like before
+           CaptureSDK.setLicenseFile("path/to/license/file/within/assets/dir", this)
+           // additionally set the license key for the BlinkID SDK
+           com.microblink.blinkid.MicroblinkSDK.setLicenseFile("path/to/blinkid/license/file/within/assets/dir", this);
+       }
+   }
+```
+
+
+To activate `BlinkIdCaptureFilter` filter, set it on the `CaptureSettings` like this:
+
+```kotlin
+val captureSettings = CaptureSettings(
+    filterSettings = FilterSettings (
+        // use provided BlinkID filter implementation
+        BlinkIdCaptureFilter(
+            // optionally you can set extraction result listener for
+            // obtaining the extraction results from the filter
+            extractionResultListener = YourExtractionResultListener()
+        )
+    )
+)
+```
+
 # <a name="direct-api"></a> Completely custom UX with Direct API (advanced)
 
 When using the **Direct API**, you are responsible for preparing input image stream (or static images) for analysis and building a completely custom UX from scratch based on the image-by-image feedback from the SDK. 
@@ -347,7 +416,7 @@ Add _capture-core_ library as a dependency in module level build.gradle(.kts):
 
 ```
 dependencies {
-    implementation("com.microblink:capture-core:1.3.0")
+    implementation("com.microblink:capture-core:1.4.0")
 }
 ```
 
@@ -415,6 +484,36 @@ AnalyzerRunner.settings = AnalyzerSettings(
 ### Integration difficulties
 In case of problems with SDK integration, first make sure that you have followed [integration instructions](#sdk-integration) and [device requirements](#device-requirements). If you're still having problems, please contact us at [help.microblink.com](http://help.microblink.com).
 
+### <a name="dynamicCppRuntime"></a> Resolving conflict on `libc++_shared.so`
+
+_Capture_ contains native code that depends on the C++ runtime. This runtime is provided by the `libc++_shared.so`, which needs to be available in your app that is using _Capture_. However, the same file is also used by various other libraries that contain native components. If you happen to integrate both such library together with _Capture_ in your app, your build will fail with an error similar to this one:
+
+```
+* What went wrong:
+2 files found with path 'lib/arm64-v8a/libc++_shared.so' from inputs:
+ - /Users/igrce/.gradle/caches/transforms-4/960385a07004d962827b3e095ca2f9ae/transformed/capture-core-xxx/jni/arm64-v8a/libc++_shared.so
+ - /Users/igrce/.gradle/caches/transforms-4/0639c19a4f322d7b8c731d9105a5cf64/transformed/blinkid-xxx/jni/arm64-v8a/libc++_shared.so
+```
+
+The error states that multiple different dependencies provide the same file `lib/arm64/libc++_shared.so` (in this case, Capture and BlinkID).
+
+You can resolve this issue by making sure that the dependency that uses _newer version of `libc++_shared.so`_ is listed first in your dependency list, and then, simply add the following to your `build.gradle`:
+
+```
+android {
+    packaging {
+        jniLibs {
+            pickFirsts.add("lib/armeabi-v7a/libc++_shared.so")
+            pickFirsts.add("lib/arm64-v8a/libc++_shared.so")
+        }
+    }
+}
+```
+
+**IMPORTANT NOTE**
+
+The code above will always select the first `libc++_shared.so` from your dependency list, so make sure that the dependency that uses the *latest version of `libc++_shared.so`* is listed first. This is because `libc++_shared.so` is backward-compatible, but not forward-compatible. This means that, e.g. `libBlinkID.so` built against `libc++_shared.so` from NDK r24 will work without problems when you package it together with `libc++_shared.so` from NDK r26, but will crash when you package it together with `libc++_shared.so` from NDK r21. This is true for all your native dependencies.
+
 ### Other problems
 If you are having problems like undesired behaviour on specific device(s), crashes inside _Capture_ SDK or anything unmentioned, please contact us at [help.microblink.com](http://help.microblink.com) describing your problem and provide following information:
 

README.md

@@ -1,5 +1,29 @@
 # Release notes
 
+## v1.4.0
+
+### Improvements
+
+- Introduced **CaptureFilter**:
+    - If you need additional checks on Capture result images, you can use [CaptureFilter](https://blinkid.github.io/capture-android/capture-ux/com.microblink.capture.analysis/-capture-filter/index.html). This feature is optional.
+    - Capture filter filters capture results after each successful side capture (accepts or drops captured side). If the captured image is filtered out, the capture process is restarted for the current side and the same side is captured again in the same camera session.
+    - We are providing one specific implementation of the `CaptureFilter` in `capture-filter-blinkid` library which uses the BlinkID SDK and accepts document images that are extractable by the BlinkID SDK.
+- Updated introduction dialog with new image and "Turn your phone to landscape mode" message
+- Introduced `AnalyzerRunner.resetSide` function used to retake the current document side.
+- Upgraded CameraX dependency to the latest stable version v1.3.4.
+
+
+### Other changes
+
+- Native code is now built using NDK r27
+
+### Bugfixes
+
+- Fix for "Rotate card or turn phone to landscape" animation being displayed too often and even when it shouldn't be:
+    - improved `DocumentFramingStatus.CameraOrientationUnsuitable` (if you are using  the Direct API)
+    - fix for case when document met all requirements but it was too close to the camera
+    - fix for case when passport is scanned in landscape
+
 ## v1.3.0
 
 ### Improvements