Xamarin Document Scanning SDK

Pixelnetica Document Scanning SDK (DSSDK) provides developers with an intelligent, highly efficient toolkit, which offers an easy way to add image processing features that are optimized for document photos that are taken by a mobile device or document camera to their applications.

Designed to ensure the smooth operation of a paperless work-flow by preprocessing paper document images, SDK makes them easier to handle by text recognition (or optical character recognition - OCR) programs, enhancing the visual quality and legibility of documents.

For more information about DSSDK main Features and Benefits, please visit Pixelnetica website.

Prerequisites

• Installed the latest Microsoft Visual Studio with Xamarin Platform
• For Android projects: Android SDK
• For Apple iOS projects: macOS with the latest Xcode, Visual Studio Mac

Supported Android versions

• Google Android 5.1 (API Level 22) and higher.

Supported iOS versions

• Apple iOS 8.1 and above.

Demo Applications

To demonstrate most of the Document Scanning SDK features and the way how they should be used in real application, we prepared demo applications available in source codes available by the link below.

• DSSDK Demo application for Xamarin.Forms
• DSSDK Demo Application for Xamarin.Android
• DSSDK Demo Application for Xamarin.iOS

Demo application source code provided “as is” without warranties of any kind. It could be freely used in commercial products only in case of commercial DSSDK license purchase.

Licensing

Document Scanning SDK (DSSDK) is a commercial product and requires the license for each application on each platform (e.g. iOS, Android).

Commercial licensing schemes, pricing plans, discounts and purchase options available on Pixelnetica site.

Demo and Trial license

DSSDK Xamarin demo applications come with Demo License Keys which is similar to commercial except for results watermarking.
It could also be utilized in other applications for development and testing purposes only where it will generate final images (documents) with watermarks.

To test DSSDK without watermarks Free trial license available on request.

It is strictly prohibited to distribute, market, publish to application stores like, but not limited, App Store, Google Play, etc. or use other than for development or staging purposes Pixelnetica Document Scanning SDK demo or trial licenses.

Getting started

Installation

The Document Scanning SDK is provided as NuGet packages for Xamarin.

• Pixelnetica.DocScanSDK.Xamarin.Forms — for Xamarin.Forms applications
• ImageSDK.Pixelnetica — for native Xamarin.Android and Xamarin.iOS apps

To install DSSDK in Visual Studio IDE:

1. Open your App-Solution in Visual Studio.
2. Select your project and click on the menu item Project → Add NuGet Packages.
3. Set nuget.org as source and search for respectful package ID:
   • ImageSDK.Pixelnetica (for Xamarin native)
   • Pixelnetica.DocScanSDK.Xamarin.Forms (for Xamarin.Forms).
4. Click on Add Package to download and install the DSSDK into your project.
5. In iOS project
   • Add --linkskip libPxl3rdparty --linkskip libPxlImageSDK -gcc_flags "-lstdc++" to additional mtouch arguments.
   • Switch Enable the Mono interpreter option ON in project settings.

After following the steps above, Document Scanning SDK will be ready to use in your code.

Permissions

Android permissions

Make sure to add these permissions in your AndroidManifest.xml file:

• <uses-feature android:glEsVersion="0x00020000" android:required="true" />

• android:largeHeap and android:hardwareAccelerated="true" in <application> tag:
  <application android:label="@string/ApplicationName" android:icon="@drawable/Icon" android:largeHeap="true" android:hardwareAccelerated="true">

• To use ImageWriter object:
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

• To use ImageFileWriter object:
  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" /> or <uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE " />
  for Android >= 11

• To use device camera:
  <uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.FLASHLIGHT" />

Apple iOS permissions

To scan document from camera and load from Album

<key>NSCameraUsageDescription</key>
<string>This app needs access to the camera to take photos.</string>

<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs access to photos.</string>

Initialization

The DSSDK must be initialized before usage. Make sure to run the initialization only once per application lifetime.

On Android

ImageSdkWrapper.Droid.Main.Init();

On Apple iOS

ImageSdkWrapper.iOS.Main.Init(this.GetType().Assembly); 

License key should be passed as a parameter of Init(). Before this it could be read from text variable, from file, etc.
If Init() is utilized without parameters then the key will be read from the default locations: Assets/License.key on Android and License.key in the root of the project on iOS.

It is recommended, but not mandatory, to store a license key inside the application code. While storing keys inside app code maximizes SDK security and availability, it sometimes could be a trade-off with flexibility. E. g, in case of license update it will be necessary to recompile the whole project.
To avoid this, keys could be stored on an external server and read each time on SDK initialization. Of course, in this case SDK functioning will depend on this server availability - users without network access will not be able to use SDK.

Migration notes

DSSDK Xamarin v.2.6.x users

Remove parameters from DetectDocumentCorners. Should be as following

public Corners DetectDocumentCorners(MetaImage sourceBitmap);

DSSDK Xamarin v1-2.3.x users

1. Use ImageSdkWrapper.Droid.Main.Init() or ImageSdkWrapper.iOS.Main.Init() for initialize instead of ImageSdkLibrary.Load(app).
2. Use ImageSdkWrapper.PxlPoint/PxlPointF point coordinates instead of Android.Graphics.Point. You can use Droid.Convertor to convert between formats.
3. Do not use Bundle for passing multiple parameters inside SDK.
   Instead, utilize the Configure method from ImageWriter to pass parameters one by one.

writer.Configure(ImageWriter.EConfigParam.Paper, ImageWriter.EPaperFormatConfigValues.A4);
writer.Configure(ImageWriter.EConfigParam.Units, ImageWriter.EUnitsConfigValues.Inches);
writer.Configure(ImageWriter.EConfigParam.FooterHeight, 25);
writer.Configure(ImageWriter.EConfigParam.FooterText, "Test");

DetectDocumentCorners receives parameters in the usual way – all at once.

public Corners DetectDocumentCorners(MetaImage sourceBitmap, 
    bool bCheckDocumentGeometry, 
    out bool bDocumentAreaChecked, 
    out bool bDocumentDistortionChecked, 
    float fullnessThreshold = DocumentCutout.DEFAULT_Threshold_Value, 
    float distortionThreshold = DocumentCutout.DEFAULT_Threshold_Value)

Take a look at demo app source code to see how this works in the real application.

1. SafeGetBitmap returns an object that is a reference to Bitmap or UIImage depending on the OS.
2. Use string instead of Android.Net.Uri.
3. GetRealPathFromUri moved to Droid.Main class.
4. Use License key as a parameter of Init() or you can store the license key in the project file Assets/License.key in Android or License.key in the root of the project in iOS.

On iOS, old DocScanningSDK classes are still working (including InitializeWithKey), but for a new project it’s recommended to use new classes from ImageSdkWrapper.

For the reference, see how this works in the Demo applications source code.

Ready to use UI components

For now a ready-to-use UI components (e.g. Manual document boundary edit, Smart Camera) available only in Xamarin.Forms version.

Manual Crop

Ready to use component for document boundaries edit, rotation and cropping.

Could be integrated into application interface as View.

ImageSdkWrapper.Forms.PxlCropImageView

Additionally, toolbar could be more flexibly placed with buttons by receiving it using the TakeToolBar method. Another important method is UiSetMetaImage, which sets the picture and parameters from a scanner or file.

Component usage could be found in Xamarin Forms demo application source codes in MainPage.cs file.

Manual crop customization properties

Document boundary quadrilateral

Different states colors

• Color NonActiveEdgeColor
• Color EdgeActiveColor
• Color EdgeMoveColor
• Color EdgeInvalidColor

Corners properties

• Color CornerActiveColor
• Color CornerMoveColor
• Color CornerInvalidColor

Zoom on corner touch

• double ZoomInMovingMode

Touch radius

• double TouchRadius

Buttons toolbar

• Color ToolBarBackgroundColor
• double ToolBarHeight
• Thickness ToolBarPadding
• double ToolBarButtonsSpace

Safe Area padding thickness

• Thickness SafeAreaPadding

Toolbar Icons customization

• ImageButton MenuButton
• ImageButton RotateLeftButton
• ImageButton RotateRightButton
• ImageButton SelectButton
• ImageButton CloseButton

Events

• event EventHandler ActveChanged;

Called when the component enters edit mode or back.

• event System.EventHandler OnMenu;

Called for user menu display. To use the “menu” button of a component.

Smart Camera

Ready to use component to scan document with device camera.

Could be integrated into application interface as View.

• ImageSdkWrapper.Forms.PxlScannerView

After scanning, there will be a PictureReceiver event with a picture or CloseClicked if the user clicked on close button.

Component usage could be found in Xamarin Forms demo application in CameraMainPage.xaml.cs file.

p.PictureReceiver = MyPictureReceiver;

void MyPictureReceiver(MetaImage img, string errorTextOrNull)
{
            if (img == null)
            {
                Console.WriteLine(errorTextOrNull);
            }
            else
            {
  ...
            }
}

Smart Camera “detectors”

Smart camera have 3 “detectors” ShakeDetection, DocumentArea and TrapezoidDistortion helping user to scan document with maximum possible quality. They’re analyzing scene in viewfinder interactively preventing user make most common shooting mistakes such as: poorly detected document, high document distortion, low effective document area (when it occupies only small part of the whole image), blurred images (due to device shaking).

They could be disabled if necessary (e.g. to increase overall scanning speed).

For example ImageSdkWrapper.Forms.Camera.Settings.DocumentArea=false;

Camera UI customization properties

Bottom Toolbar

• Color PanelBackgroundColor
• Thickness PanelPadding
• Thickness CloseButtonPadding
• double ButtonsSize
• double CloseButtonsSize

Safe area padding for not square screen types.

• Thickness SafeAreaPadding

Main shutter button

• double ShotButtonSize
• Color ShotButtonBorderColor

Camera status parameters

• double StateTextVerticalDiv
• Color StateBackgroundColor
• Color StateTextColor
• Thickness StateTextPadding
• double StateTextFontSize

Localization

Camera messages localization strings could be found in source code as static strings in Xamarin Forms demo application in CameraMainPage.xaml.cs file.

• Msg.shot_busy = "Camera busy";
• Msg.shot_not_stable = "Camera is shaking";
• Msg.looking_for_document = "Looking for document";
• Msg.small_area = "Move Camera closer to document";
• Msg.distorted = "Hold camera parallel to document";
• Msg.unstable = "Don\'t move camera";

Both components require Xamarin.Forms and Pixelnetica.DocScanSDK.Xamarin.Forms. See the Xamarin Forms Demo application source code for more information.

ImageSdk Modules

Processing

Processing module provides document detection, correction and binarization.

All methods of this module (including creation) must be called in one thread.

Module creation

ImageProcessing sdk = new ImageProcessing();

Load image metadata using MetaImage object

Most convenient method to load metadata is by using ContentResolver and image Uri

string imageUri = ... // basic Uri
MetaImage sourceImage = MetaImage.FromStream(stream,imageUri);

There are a lot of different methods to create MetaImage.

Document detection

Corners corners = sdk.DetectDocumentCorners(originImage);

After this, you can let users accept or modify document detection results.

Document cropping and correction

MetaImage croppedImage = sdk.CorrectDocument(sourceImage, corners);

Image processing and binarization

There are 4 available image processing methods.

//Binarize to **Black and White** image.
targetImage = sdk.ImageBWBinarization(croppedImage);

//Convert to **Grayscale** image.
targetImage = sdk.ImageGrayBinarization(croppedImage);

//Enhance image **Colors**.
targetImage = sdk.ImageColorBinarization(croppedImage);`

//Only rotate image to the right document orientation leaving __Original__ colors untouched.  
targetImage = sdk.ImageOriginal(croppedImage);

We recommend utilize using statement.

using (ImageProcessing ip = new ImageProcessing())
{
...
}

ImageWriter module

Creation

We recommend utilizing using statements to automatically free and destroy writer instances.

using (ImageWriter writer = new ImageWriter(ImageWriter.EImageFileType.Pdf))
{
...
}

Several writer types could be specified.

• ImageSdkLibrary.ImageWriterJpeg - to write color JPEG image.
• ImageSdkLibrary.ImageWriterPng - to write color PNG image.
• ImageSdkLibrary.ImageWriterWebM - to write WebM image.
• ImageSdkLibrary.ImageWriterPngExt - to write 1-bit black-and-white PNG image.
• ImageSdkLibrary.ImageWriterPdf - to write a PDF document.
• ImageSdkLibrary.ImageWriterTiff - to write 1-bit Black-and-White TIFF-G4 compressed images. Creates most compact black-and-white files.

Writing images

To write one or several images (or pages) image or document file path should be specified.

writer.Open(filePath);

Additional optional parameters specific for current writer type. (e.g. compression for JPEG or page size for PDF) could be provided.

writer.Configure(key,value);

Write one image or page. To write multiple pages should be called several times

writer.Write(image);

For more details, we strongly recommend taking a close look at our demo applications source codes.

Support

Still have Questions, need Free Trial or Quotation?

Feel free to contact us in case of any inquires at Pixelnetica DSSDK Support.