From c787702fc328ef4448d144ce50dea4823464e62c Mon Sep 17 00:00:00 2001 From: DMGithubPublisher Date: Tue, 14 May 2024 22:34:06 -0700 Subject: [PATCH] update to internal commit b3118d6c --- assets/js/ddnMobileVersionSearch.json | 81 +++- ...ed-document-normalizer-settings-v2.2.10.md | 100 +++++ ...simplified-document-normalizer-settings.md | 34 +- .../android/release-notes/android-2.md | 4 + programming/android/release-notes/index.md | 1 + programming/android/user-guide-v2.2.10.md | 408 ++++++++++++++++++ programming/android/user-guide.md | 2 +- programming/ios/user-guide.md | 2 +- 8 files changed, 614 insertions(+), 18 deletions(-) create mode 100644 programming/android/api-reference/simplified-document-normalizer-settings-v2.2.10.md create mode 100644 programming/android/user-guide-v2.2.10.md diff --git a/assets/js/ddnMobileVersionSearch.json b/assets/js/ddnMobileVersionSearch.json index 735de31..f096358 100644 --- a/assets/js/ddnMobileVersionSearch.json +++ b/assets/js/ddnMobileVersionSearch.json @@ -2,56 +2,107 @@ { "version": "2.2.11", "matchList": { + "android":{ + "dcvRepoMobile": [ + { + "path": "/programming/android/api-reference/utility", + "version": "1.2.20" + }, { + "path": "/programming/android/api-reference/license", + "version": "3.2.20" + }, { + "path": "/programming/android/api-reference/capture-vision-router", + "version": "2.2.30" + }, { + "path": "/programming/android/api-reference/core", + "version": "3.2.30" + }, { + "path": "/programming/android/api-reference/image-processing", + "version": "2.2.30" + } + ], + "dcvRepoCore": [ + { + "path": "/introduction/", + "version": "2.2.10" + }, { + "path": "/enums/capture-vision-router", + "version": "2.2.30" + }, { + "path": "/enums/core", + "version": "3.2.30" + },{ + "path": "/parameters/reference/capture-vision-template", + "version": "2.2.30" + },{ + "path": "/parameters/reference/target-roi-def", + "version": "2.2.30" + },{ + "path": "/parameters/reference/document-normalizer-task-settings", + "version": "2.2.10" + },{ + "path": "/parameters/reference/image-parameter", + "version": "2.2.30" + },{ + "path": "/parameters/reference/image-source-options", + "version": "3.2.30" + },{ + "path": "/parameters/reference/global-parameter", + "version": "2.2.30" + } + ], + "dce": "4.2.10" + }, "ios":{ "dcvRepoMobile": [ { "path": "/programming/objectivec-swift/api-reference/utility", - "version": "1.2.11" + "version": "1.2.20" }, { "path": "/programming/objectivec-swift/api-reference/license", - "version": "3.2.11" + "version": "3.2.20" }, { "path": "/programming/objectivec-swift/api-reference/capture-vision-router", - "version": "2.2.11" + "version": "2.2.30" }, { "path": "/programming/objectivec-swift/api-reference/core", - "version": "3.2.11" + "version": "3.2.30" }, { "path": "/programming/objectivec-swift/api-reference/image-processing", - "version": "2.2.11" + "version": "2.2.30" } ], "dcvRepoCore": [ { "path": "/introduction/", - "version": "2.2.11" + "version": "2.2.10" }, { "path": "/enums/capture-vision-router", - "version": "2.2.11" + "version": "2.2.30" }, { "path": "/enums/core", - "version": "3.2.11" + "version": "3.2.30" },{ "path": "/parameters/reference/capture-vision-template", - "version": "2.2.11" + "version": "2.2.30" },{ "path": "/parameters/reference/target-roi-def", - "version": "2.2.11" + "version": "2.2.30" },{ "path": "/parameters/reference/document-normalizer-task-settings", - "version": "2.2.11" + "version": "2.2.10" },{ "path": "/parameters/reference/image-parameter", - "version": "2.2.11" + "version": "2.2.30" },{ "path": "/parameters/reference/image-source-options", - "version": "3.2.11" + "version": "3.2.30" },{ "path": "/parameters/reference/global-parameter", - "version": "2.2.11" + "version": "2.2.30" } ], - "dce": "4.2.1" + "dce": "4.2.10" } } },{ diff --git a/programming/android/api-reference/simplified-document-normalizer-settings-v2.2.10.md b/programming/android/api-reference/simplified-document-normalizer-settings-v2.2.10.md new file mode 100644 index 0000000..c8e90ad --- /dev/null +++ b/programming/android/api-reference/simplified-document-normalizer-settings-v2.2.10.md @@ -0,0 +1,100 @@ +--- +layout: default-layout +title: SimplifiedDocumentNormalizerSettings - Dynamsoft Document Normalizer module Android Edition API Reference +description: The class SimplifiedDocumentNormalizerSettings of Dynamsoft Document Normalizer module Android edition represents the simplified document normalizer settings. +keywords: document normalizer settings, Android, java +needGenerateH3Content: true +needAutoGenerateSidebar: true +noTitleIndex: true +--- + +# SimplifiedDocumentNormalizerSettings + +The `SimplifiedDocumentNormalizerSettings` class represents a series of simple settings related to the Document Normalizer. Please note that this is not the full list of settings that can be utilized by the Document Normalizer, which you can find on the [Dynamsoft Document Normalizer Parameters]({{ site.parameters }}reference/index.html){:target="_blank"} page. + +## Definition + +*Namespace:* com.dynamsoft.ddn + +*Assembly:* DynamsoftDocumentNormalizer.aar + +```java +class SimplifiedDocumentNormalizerSettings +``` + +## Attributes + +| Attributes | Type | Description | +| ---------- | ---- | ----------- | +| [`grayscaleTransformationModes`](#grayscaletransformationmodes) | *EnumGrayscaleTransformationMode[]* | An array of GrayscaleTransformationMode. It controls whether to detect the inverted document boundary. | +| [`grayscaleEnhancementModes`](#grayscaleenhancementmodes) | *EnumGrayscaleEnhancementModes[]* | An array of GrayscaleEnhancementModes. | +| [`colourMode`](#colourmode) | *EnumImageColourMode* | The grayscale transformation mode. It controls whether to decode the inverted text. | +| [`pageSize`](#pagesize) | *int[]* | The page size. | +| [`brightness`](#brightness) | *int* | The brightness. | +| [`contrast`](#contrast) | *int* | The contrast. | +| [`maxThreadsInOneTask`](#maxthreadsinonetask) | *int* | The maximum number of threads in one task. | +| [`scaleDownThreshold`](#scaledownthreshold) | *int* | The scale down threshold. | + +### grayscaleTransformationModes + +Defines the grayscale transformation modes with an array of [`EnumGrayscaleTransformationMode`]({{ site.dcv_enumerations }}core/grayscale-transformation-mode.html?lang=android) items. This parameter is important when working with inverted documents, and must be used in order to locate the inverted document boundary. + +```java +EnumGrayscaleTransformationMode[] grayscaleTransformationModes; +``` + +### grayscaleEnhancementModes + +Defines the grayscale enhancement modes with an array of [`EnumGrayscaleEnhancementModes`]({{ site.dcv_enumerations }}core/grayscale-enhancement-modes.html?lang=android) items. This parameter can be quite powerful in increasing the border detection rate of your application should you experience any trouble in that area. To learn more about the `grayscaleEnhancementModes` and how they can be used, please visit the main [GrayscaleEnhancementModes]({{ site.dcv_parameters }}reference/image-parameter/grayscale-enhancement-modes.html) parameter page. + +```java +EnumGrayscaleEnhancementMode[] grayscaleEnhancementModes; +``` + +### colourMode + +Defines the colour mode of the normalized image with an [`EnumImageColourMode`]({{ site.dcv_enumerations }}document-normalizer/image-colour-mode.html?lang=android) member. By default, the normalized image will output in colour. In order to make the result image grayscale or binary, setting the `colourMode` to the corresponding pixel type will do the trick. + +```java +EnumImageColourMode colourMode; +``` + +### pageSize + +Defines the page size of the normalized image through an integer array. + +```java +int[] pageSize; +``` + +### brightness + +Defines the brightness of the normalized image result with an integer. + +```java +int brightness; +``` + +### contrast + +Defines the contrast of the normalized image result with an integer. + +```java +int contrast; +``` + +### maxThreadsInOneTask + +Defines the maximum number of threads dedicated to a single task. + +```java +int maxThreadsInOneTask; +``` + +### scaleDownThreshold + +If the original image size is quite large, then the `scaledownThreshold` can be used to shrink the image and speed up the processing. If the shorter edge size is larger than the defined scale down threshold, the library will calculate the required width and height of the image and shrink it to that size before moving forward in the process. + +```java +int scaleDownThreshold; +``` diff --git a/programming/android/api-reference/simplified-document-normalizer-settings.md b/programming/android/api-reference/simplified-document-normalizer-settings.md index c8e90ad..0e73c87 100644 --- a/programming/android/api-reference/simplified-document-normalizer-settings.md +++ b/programming/android/api-reference/simplified-document-normalizer-settings.md @@ -22,7 +22,7 @@ The `SimplifiedDocumentNormalizerSettings` class represents a series of simple s class SimplifiedDocumentNormalizerSettings ``` -## Attributes +## Methods & Attributes | Attributes | Type | Description | | ---------- | ---- | ----------- | @@ -35,6 +35,10 @@ class SimplifiedDocumentNormalizerSettings | [`maxThreadsInOneTask`](#maxthreadsinonetask) | *int* | The maximum number of threads in one task. | | [`scaleDownThreshold`](#scaledownthreshold) | *int* | The scale down threshold. | +| Methods | Description | +| [`toJson`](#tojson) | Generate a JSON string from this `SimplifiedDocumentNormalizerSettings` object. | +| [`fromJson`](#fromjson) | Create a `SimplifiedDocumentNormalizerSettings` object from a JSON string. | + ### grayscaleTransformationModes Defines the grayscale transformation modes with an array of [`EnumGrayscaleTransformationMode`]({{ site.dcv_enumerations }}core/grayscale-transformation-mode.html?lang=android) items. This parameter is important when working with inverted documents, and must be used in order to locate the inverted document boundary. @@ -98,3 +102,31 @@ If the original image size is quite large, then the `scaledownThreshold` can be ```java int scaleDownThreshold; ``` + +### toJson + +Generate a JSON string from this `SimplifiedDocumentNormalizerSettings` object. + +```java +String toJson() +``` + +**Return Value** + +A JSON string that contains all the information of this object. + +### fromJson + +Create a `SimplifiedDocumentNormalizerSettings` object from a JSON string. + +```java +static SimplifiedDocumentNormalizerSettings fromJson(String json); +``` + +**Parameters** + +* `json`: A JSON string that contains all `SimplifiedDocumentNormalizerSettings` required information. + +**Return Value** + +A `SimplifiedDocumentNormalizerSettings` object. diff --git a/programming/android/release-notes/android-2.md b/programming/android/release-notes/android-2.md index d1b5287..5851c05 100644 --- a/programming/android/release-notes/android-2.md +++ b/programming/android/release-notes/android-2.md @@ -11,6 +11,10 @@ permalink: /programming/android/release-notes/android-2.html # Release Notes for Android SDK - v2.x +## 2.2.11 (05/15/2024) + +- Added new methods `toJson` & `fromJson` to the [`SimplifiedDocumentNormalizerSettings`]({{ site.dbr_android_api }}simplified-document-normalizer-settings.html) class. + ## 2.2.10 (03/07/2024) ### New diff --git a/programming/android/release-notes/index.md b/programming/android/release-notes/index.md index 99ef65f..ecbc1f1 100644 --- a/programming/android/release-notes/index.md +++ b/programming/android/release-notes/index.md @@ -10,6 +10,7 @@ permalink: /programming/android/release-notes/index.html # Release Notes - Android Edition +- [2.2.11 (05/15/2024)]({{ site.android_release_notes }}android-2.html#2211-05152024) - [2.2.10 (03/07/2024)]({{ site.android_release_notes }}android-2.html#2210-03072024) - [2.0.20 (12/12/2023)]({{ site.android_release_notes }}android-2.html#2020-12122023) - [2.0.10 (08/10/2023)]({{ site.android_release_notes }}android-2.html#2010-08102023) diff --git a/programming/android/user-guide-v2.2.10.md b/programming/android/user-guide-v2.2.10.md new file mode 100644 index 0000000..a5aeaf3 --- /dev/null +++ b/programming/android/user-guide-v2.2.10.md @@ -0,0 +1,408 @@ +--- +layout: default-layout +title: Dynamsoft Document Normalizer for Android - User Guide +description: This is the user guide of Dynamsoft Document Normalizer for Android SDK. +keywords: user guide, android +needAutoGenerateSidebar: true +needGenerateH4Content: true +noTitleIndex: true +permalink: /programming/android/user-guide.html +--- + +# Getting Started with Android + +In this guide, you will learn step by step on how to build a document normalization application with Dynamsoft Document Normalizer Android SDK. + +> Read more on [Dynamsoft Document Normalizer Features](https://www.dynamsoft.com/document-normalizer/docs/core/introduction/index.html){:target="_blank"} + +- [Getting Started with Android](#getting-started-with-android) + - [Requirements](#requirements) + - [Build Your First Application](#build-your-first-application) + - [Create a New Project](#create-a-new-project) + - [Add the SDK](#add-the-sdk) + - [Add the Library Manually](#add-the-library-manually) + - [Add the Library via Maven](#add-the-library-via-maven) + - [Initialize License](#initialize-license) + - [MainActivity for Realtime Document Normalization](#mainactivity-for-realtime-document-normalization) + - [Initialize Camera Module](#initialize-camera-module) + - [Initialize Capture Vision Router](#initialize-capture-vision-router) + - [Add a Captured Result Receiver and Filter](#add-a-captured-result-receiver-and-filter) + - [Start and Stop Video Document Normalization](#start-and-stop-video-document-normalization) + - [Additional Steps in MainActivity](#additional-steps-in-mainactivity) + - [ResultActivity for Displaying the Normalized Image](#resultactivity-for-displaying-the-normalized-image) + - [Display the Normalized Image](#display-the-normalized-image) + - [Build and Run the Project](#build-and-run-the-project) + +## Requirements + +- Supported OS: Android 5.0 (API Level 21) or higher. +- Supported ABI: **armeabi-v7a**, **arm64-v8a**, **x86** and **x86_64**. +- Development Environment: Android Studio 2022.2.1 or higher. + +## Build Your First Application + +In this section, let's see how to create a HelloWorld app for normalizing documents from camera video input. + +>Note: +> +> - Android Studio 2022.2.1 is used here in this guide. +> - You can get the source code of the HelloWord app from the following link +> - [Java](https://github.com/Dynamsoft/document-normalizer-mobile-samples/tree/main/android/HelloWorld/AutoNormalize){:target="_blank"}. +> - [Kotlin](https://github.com/Dynamsoft/document-normalizer-mobile-samples/tree/main/android/HelloWorld/AutoNormalizeKt){:target="_blank"}. + +### Create a New Project + +1. Open Android Studio, select **File > New > New Project**. + +2. Choose the correct template for your project. In this sample, we use **Empty Activity**. + +3. When prompted, choose your app name 'HelloWorld' and set the **Save** location, **Language**, and **Minimum SDK** (we use 21 here). + > Note: + > + > - With **minSdkVersion** set to 21, your app is compatible with more than 94.1% of devices on the Google Play Store (last update: March 2021). + +### Add the SDK + +There are two ways to add the SDK into your project - **Manually** and **Maven**. + +#### Add the Library Manually + +1. Download the SDK package from the Dynamsoft website. After unzipping, You can find the following **aar** files under the **Dynamsoft\Libs** directory: + + | File | Description | + |---------|-------------| + | `DynamsoftDocumentNormalizer.aar` | The Dynamsoft Document Normalizer SDK which includes the document normalizer related APIs. | + | `DynamsoftCore.aar` | The core library of the Dynamsoft Capture Vision SDK which includes basic structures and intermediate result related APIs. | + | `DynamsoftCaptureVisionRouter.aar` | The CaptureVisionRouter is used to coordinate the image-processing and semantic-processing products that are being used in the application. It accepts an image source and returns processing results which may contain final results or intermediate results. | + | `DynamsoftImageProcessing.aar` | The image processing library of the Dynamsoft Capture Vision SDK, and so includes the image processing algorithms and APIs. | + | `DynamsoftLicense.aar` | This module includes the licensing API. | + | `DynamsoftCameraEnhancer.aar` | The [Dynamsoft Camera Enhancer SDK]({{ site.dce_android_api }}) defines the camera control and frame preprocessing API. | + | `DynamsoftUtility.aar (Optional)` | The module includes functional APIs that support you to integrate the input, filtering the results, generating result images, etc. | + +2. Copy the above six (seven if the Utility is included) **aar** files to the target directory `HelloWorld\app\libs` + +3. Open the file `HelloWorld\app\build.gradle` and add reference in the dependencies: + + ```groovy + dependencies { + implementation fileTree(dir: 'libs', include: ['*.aar']) + + def camerax_version = '1.1.0' + implementation "androidx.camera:camera-core:$camerax_version" + implementation "androidx.camera:camera-camera2:$camerax_version" + implementation "androidx.camera:camera-lifecycle:$camerax_version" + implementation "androidx.camera:camera-view:$camerax_version" + } + ``` + + > Note: + > + > DCE 4.x is based on Android CameraX, so you need to add the CameraX dependency manually. + +4. Click **Sync Now**. After the synchronization completes, the SDK is added to the project. + +#### Add the Library via Maven + +1. Open the file `HelloWorld\app\build.gradle` and add the remote repository: + + ```groovy + repositories { + maven { + url "https://download2.dynamsoft.com/maven/aar" + } + } + ``` + +2. Add reference in the dependencies: + + ```groovy + dependencies { + implementation 'com.dynamsoft:dynamsoftdocumentnormalizerbundle:2.2.10' + } + ``` + +3. Click **Sync Now**. After the synchronization completes, the SDK is added to the project. + +### Initialize License + +1. Import the `LicenseManager` class and initialize the license in the file `MyApplication.java`. + + ```java + import com.dynamsoft.license.LicenseManager; + + public class MyApplication extends Application { + private static final String TAG = "MyApplication"; + private static final String LICENSE = "DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9"; + + @Override + public void onCreate() { + super.onCreate(); + LicenseManager.initLicense(LICENSE, this, (isSuccess, error) -> { + if (!isSuccess) { + Log.e(TAG, "InitLicense Error: " + error); + } + }); + } + } + ``` + + >Note: + > + >- Network connection is required for the license to work. + >- The license string here will grant you a time-limited trial license. + >- If the license has expired, you can go to the customer portal to request for an extension. + +### MainActivity for Realtime Document Normalization + +#### Initialize Camera Module + +1. In the Project window, open **app > res > layout > `activity_main.xml`** and create a DCE camera view section under the root node. + + ```xml + + + ``` + +2. Import the camera module, initialize the camera view and bind to the created Camera Enhancer instance in the file `MainActivity.java`. + + ```java + ... + + import com.dynamsoft.dce.CameraView; + import com.dynamsoft.dce.CameraEnhancer; + import com.dynamsoft.dce.CameraEnhancerException; + import com.dynamsoft.dce.utils.PermissionUtil; + + public class MainActivity extends AppCompatActivity { + private CameraEnhancer mCamera; + + @Override + protected void onCreate(Bundle savedInstanceState) { + + ... + + CameraView cameraView = findViewById(R.id.camera_view); + mCamera = new CameraEnhancer(cameraView, MainActivity.this); + + PermissionUtil.requestCameraPermission(MainActivity.this); + } + } + ``` + +#### Initialize Capture Vision Router + +1. Import and initialize the capture vision router, and set the created Camera Enhancer instance as the input image source. + + ```java + ... + + import com.dynamsoft.cvr.CaptureVisionRouter; + import com.dynamsoft.cvr.CaptureVisionException; + + public class MainActivity extends AppCompatActivity { + + ... + + private CaptureVisionRouter mRouter; + + @Override + protected void onCreate(Bundle savedInstanceState) { + + ... + + mRouter = new CaptureVisionRouter(MainActivity.this); + try { + mRouter.setInput(mCamera); + } catch (CaptureVisionRouterException e) { + e.printStackTrace(); + } + } + } + ``` + +#### Add a Captured Result Receiver and Filter + +1. Add a result receiver to get the normalized image results. + + ```java + ... + + import com.dynamsoft.core.basic_structures.CapturedResultReceiver; + import com.dynamsoft.core.basic_structures.ImageData; + import com.dynamsoft.cvr.EnumPresetTemplate; + import com.dynamsoft.ddn.NormalizedImagesResult; + + public class MainActivity extends AppCompatActivity { + + ... + + public static ImageData mNormalizedImageData; + private boolean mJumpToOtherActivity = false; + + @Override + protected void onCreate(Bundle savedInstanceState) { + + ... + + mRouter.addResultReceiver(new CapturedResultReceiver() { + @Override + public void onNormalizedImagesReceived(NormalizedImagesResult result) { + if (mJumpToOtherActivity && result.getItems().length > 0) { + mJumpToOtherActivity = false; + + mNormalizedImageData = result.getItems()[0].getImageData(); + + Intent intent = new Intent(MainActivity.this, ResultActivity.class); + startActivity(intent); + } + } + }); + } + } + ``` + +2. Add a result cross filter to validate the normalized image result across multiple frames. + + ```java + ... + + import com.dynamsoft.utility.MultiFrameResultCrossFilter; + + public class MainActivity extends AppCompatActivity { + + ... + + @Override + protected void onCreate(Bundle savedInstanceState) { + + ... + + MultiFrameResultCrossFilter filter = new MultiFrameResultCrossFilter(); + filter.enableResultCrossVerification(CRIT_NORMALIZED_IMAGE, true); + mRouter.addResultFilter(filter); + } + } + ``` + +#### Start and Stop Video Document Normalization + +1. Override the `MainActivity.onResume` function to open camera and start video document normalization, override the `MainActivity.onPause` function to close camera and stop video document normalization. + + ```java + public class MainActivity extends AppCompatActivity { + + ... + + @Override + public void onResume() { + super.onResume(); + try { + mCamera.open(); + mRouter.startCapturing(EnumPresetTemplate.PT_DETECT_AND_NORMALIZE_DOCUMENT); + } catch (CameraEnhancerException | CaptureVisionRouterException e) { + e.printStackTrace(); + } + } + + @Override + public void onPause() { + super.onPause(); + try { + mCamera.close(); + } catch (CameraEnhancerException e) { + e.printStackTrace(); + } + + mRouter.stopCapturing(); + } + } + ``` + +2. Add `onCaptureBtnClick` function to start the video document normalization. After start capturing, the SDK will process the video frames from the Camera Enhancer, then send the normalized image results to the registered result receiver. + + ```java + public class MainActivity extends AppCompatActivity { + + ... + + public void onCaptureBtnClick(View v) { + mJumpToOtherActivity = true; + } + } + ``` + +#### Additional Steps in MainActivity + +1. In the Project window, open **app > res > layout > `activity_main.xml`**, create a button under the root node to capture the quads detected on the image. + + ```xml + ... + +