JSON-based Domain-Specific Language for Data Capture

Feb 07, 2024

 Capture Vision

•  DSL
•  HTML5
•  JAVASCRIPT
•  DOCUMENT SCANNING
•  BARCODE
•  MRZ

A Domain-Specific Language (DSL) is a computer language that’s targeted to a particular kind of problem. Examples of DSLs are CSS, SQL, make, etc.

An important and useful distinction Martin Fowler makes is between internal and external DSLs. Internal DSLs are particular ways of using a host language to give the host language the feel of a particular language, like Jetpack Compose. External DSLs have their own custom syntax and you write a full parser to process them, like JSON and XML.

Dynamsoft Capture Vision is a Data Capture framework which is designed to make it easy to scan documents, read barcodes and recognize text. One of its key features is that we can use a JSON-based DSL to configure the data capture tasks. In this article, we are going to take a look at this DSL.

Not Using DSL and Using DSL

Let’s first talk about the usage of not using DSL and using DSL.

Suppose we want to scan the document and read the barcodes in the following image:

We can use Dynamsoft Document Normalizer and Dynamsoft Barcode Reader to do this. The two SDKs support various platforms like iOS, Android, Desktop and Web. Here, we use the JavaScript version for Web:

let documentNormalizer = await Dynamsoft.DDN.DocumentNormalizer.createInstance(); //requires Dynamsoft Document Normalizer version 1.x
let barcodeReader = await Dynamsoft.DBR.BarcodeReader.createInstance(); //requires Dynamsoft Barcode Reader version 9.x
let img = document.getElementById("image");
let quads = await documentNormalizer.detectQuad(img);
let normalizedImageResult = await documentNormalizer.normalize(img, {
  quad: quads[0].location
});
let normalizedImageAsCanvas = normalizedImageResult.image.toCanvas();
let barcodeResults = await barcodeReader.decode(normalizedImageAsCanvas);

Dynamsoft Capture Vision can work as a router to call Dynamsoft Document Normalizer and Dynamsoft Barcode Reader to achieve the same result.

First, we need to define the task in a JSON DSL.

1. Define a barcode reading task and a document scanning task.

   {
     "BarcodeReaderTaskSettingOptions": [
       {
         "Name": "task-read-barcodes"
       }
     ],
     "DocumentNormalizerTaskSettingOptions": [
       {
         "Name": "task-detect-and-normalize-document"
       }
     ]
   }
   

2. Define two target ROIs: a whole-image ROI for document scanning and an ROI for barcode reading which is based on the detected document image.

   {
     "TargetROIDefOptions": [
       {
         "Name": "roi-detect-and-normalize-document",
         "TaskSettingNameArray": ["task-detect-and-normalize-document"]
       },
       {
         "Name": "roi-read-barcodes",
         "TaskSettingNameArray": ["task-read-barcodes"],
         "Location":
         {
           "ReferenceObjectFilter" : {
             "ReferenceTargetROIDefNameArray": ["roi-detect-and-normalize-document"]
           }
         }
       }
     ]
   }
   

   Note: if the Location is not set, the ROI is the whole image.

3. Define a template named ScanDocumentAndReadBarcode which uses the two target ROIs for processing.

   {
     "CaptureVisionTemplates": [
       {
         "Name": "ScanDocumentAndReadBarcode",
         "ImageROIProcessingNameArray": [
           "roi-detect-and-normalize-document","roi-read-barcodes"
         ]
       }
     ]
   }
   

Save the JSON as template.json and then, we can do the same document scanning and barcode reading task with the following JavaScript code:

let router = await Dynamsoft.CVR.CaptureVisionRouter.createInstance();
let response = await fetch("./template.json");
let settings = await response.text();
await router.initSettings(settings);
let results = await router.capture(document.getElementById("image"),"ScanDocumentAndReadBarcode");

We can do a lot more using the JSON DSL, like setting the image processing parameters, specifying which barcode formats to use, etc. You can learn about this in the docs.

PS: Dynamsoft Capture Vision requires Dynamsoft Document Normalizer v2+ and Dynamsoft Barcode Reader v10+.

Advantages and Disadvantages

Using a JSON-based DSL in Dynamsoft Capture Vision has some advantages and disadvantages:

Advantages:

• The data capture logic can be shared between different platforms without the need to write platform-specific codes.
• Image processing results can be shared internally to improve performance. For example, we don’t need to read images into bytes or convert an image to grayscale twice.
• Domain experts can solve specific tasks more efficiently than using a general programming language.

Disadvantages:

• There is a learning curve.
• Designing and maintaining a DSL is an extra cost.
• Not easy to modify the settings using the host language. This is often needed in an interactive scenario, like modifying the boundaries of a scanned document before cropping.

To overcome the disadvantages, Dynamsoft Capture Vision has done the following work:

1. A programming interface to modify the settings: SimplifiedCaptureVisionSettings
2. Detailed documentation to help you learn it.

Source Code

You can find the source code of demos using Dynamsoft Capture Vision in the following repo: https://github.com/tony-xlh/dynamsoft-capture-vision-samples/