Need better scanning performance?

Get a FREE customized reading template.

Overview of DCV parameters

Dynamsoft Capture Vision (DCV) is designed for high scalability and flexibility, and its parameter system plays a crucial role in achieving that. The parameter system can drive the behaviour of the SDK through its many varied configurations. In this article, we will provide an overview of the parametric architecture design of Dynamsoft Capture Vision.

Key Terms

In order to eliminate ambiguity, we first define several key terms.

• Parameter - A parameter is designed to represent a particular aspect of the behavior of the SDK, and each parameter has its own name. For instance, the ExpectedBarcodesCount parameter is used to control the expected number of recognized barcodes in the image or frame. Parameters can be configured with specific values or a range of values, which can be adjusted as required.

• Parameter template - A parameter template is a collection of parameters organized in a structured manner, expressed in JSON format. The name of the CaptureVisionTemplate object is also called “template name”, which is a unique identifier assigned to each parameter template. In the DCV SDK, this name is used to load the relevant configurations and control runtime behavior.

• Parameter template file - A parameter template file is a JSON file that contains one or multiple parameter templates.

Organization of a Parameter Template File

With the exception of GlobalParameter, all top-level keys in the parameter template file are arrays of the corresponding object. For example,CaptureVisionTemplates is an array of CaptureVisionTemplate objects, and TargetROIDefOptions is an array of TargetROIDef objects, and so on.

For Dynamsoft Barcode Reader SDK Users:

When using Dynamsoft Barcode Reader SDK standalone (without other DCV functional products), the following objects and their parameters are not applicable:

• LabelRecognizerTaskSettingOptions
• DocumentNormalizerTaskSettingOptions
• CodeParserTaskSettingOptions
• OutputTaskSettingOptions
• TextLineSpecificationOptions
• SemanticProcessingOptions

The following table list all the top-level keys.

Full JSON Structure

The following example shows the full JSON structure used by Dynamsoft Capture Vision.

{
    "CaptureVisionTemplates": [
        {
            "Name" : "CV_0",
            "ImageSourceName": "ISA_0",
            "ImageROIProcessingNameArray": ["TA_0" ],
            "SemanticProcessingNameArray": ["SP_0"]
            // ...other optional parameters
        },
        {
            // another CaptureVisionTemplate object
        }
    ],
    "ImageSourceOptions": [ 
        {
            "Name": "ISA_0"
            // ...other optional parameters
        },
        {
            // another ImageSource object
        }
    ],
    "TargetROIDefOptions" : [
        {
            "Name" : "TA_0",
            "TaskSettingNameArray": [ "LR_0", "BR_0", "DN_0" ]
            // ...other optional parameters
        },
        {
            // another TargetROIDef object
        }
    ],
    "ImageParameterOptions": [
        {
            "Name": "IP_0"
            // ...other optional parameters
        },
        {
            // another ImageParameter object
        }
    ], 
    "BarcodeReaderTaskSettingOptions": [
        {
            "Name" : "BR_0",
            "BarcodeFormatSpecificationNameArray" : ["FS_0"]
            // ...other optional parameters
        },
        {
            // another BarcodeReaderTaskSetting object
        }
    ],
    "BarcodeFormatSpecificationOptions": [
        {
            "Name": "FS_0"
            // ...other optional parameters
        },
        {
            // another BarcodeFormatSpecification object
        }
    ],
    "LabelRecognizerTaskSettingOptions": [
        {
            "Name" : "LR_0",
            "TextLineSpecificationNameArray" : [ "LS_0" ]
            // ...other optional parameters
        },
        {
            // another LabelRecognizerTaskSetting object
        }
    ],
    "TextLineSpecificationOptions" : [
        {
            "Name" : "LS_0",
            "CharacterModelName" : "NumberLetterCharRecognition"
            // ...other optional parameters
        },
        {
            // another TextLineSpecification object
        }
    ],
    "CaptureVisionModelOptions" : [
        {
            "Name" : "NumberLetterCharRecognition"
            // ...other optional parameters
        },
        {
            // another CaptureVisionModel object
        }
    ],
    "DocumentNormalizerTaskSettingOptions": [
        {
            "Name" : "DN_0"
            // ...other optional parameters
        },
        {
            // another DocumentNormalizerTaskSetting object
        }
    ],
    "SemanticProcessingOptions": [
        {
            "Name": "SP_0",
            "TaskSettingNameArray": [
                "CP_0"
            ]
            // ...other optional parameters
        },
        {
            // another SemanticProcessing object
        }
    ],
    "CodeParserTaskSettingOptions": [
        {
            "Name": "CP_0"
            // ...other optional parameters
        },
        {
            // another CodeParserTaskSetting object
        }
    ],
    "GlobalParameter":{
        "MaxTotalImageDimension": 0
        // ...other optional parameters
    },
    "OutputTaskSettingOptions":[
        {
            "Name" : "output_task"
            // ...other optional parameters
        },
        {
            // another OutputTaskSetting object
        }
    ]
}

This example shows the complete JSON structure template. Most fields are optional and should be included only when needed. Do NOT copy this whole structure directly. For real usage, start with the Minimal Valid JSON example and add only the necessary sections.

Minimal Valid JSON Example

The following example includes only the minimum required fields needed to create a functional configuration. You can use it as a starting point and expand it based on your scenario.

{
    "CaptureVisionTemplates": [
        {
            "Name" : "CV_0",
            "ImageROIProcessingNameArray": ["TA_0" ],
        }
    ],
    "TargetROIDefOptions" : [
        {
            "Name" : "TA_0",
            "TaskSettingNameArray": [ "BR_0" ]
        }
    ],
    "BarcodeReaderTaskSettingOptions": [
        {
            "Name" : "BR_0",
            "BarcodeFormatIds": ["BF_DEFAULT"]
        }
    ]
}

This minimal example is intentionally simple. In real-world scenarios, additional sections such as ImageParameter, LabelRecognizerTaskSetting, or SemanticProcessing options may be required depending on the features you use.

How to Apply DCV Parameters

To use custom parameters in Dynamsoft Capture Vision, follow these steps:

1. Load Parameter Template

   Use one of the following APIs to load your parameter template:

   • InitSettings(jsonString) - Load parameter template from a JSON string
   • InitSettingsFromFile(filePath) - Load parameter template from a JSON file

   These APIs will replace all existing parameter templates with the ones from the loaded content.

2. Start Capturing

   Pass the template name to one of the capturing APIs:

   • Capture(..., templateName) - Processes a single-page image.
   • CaptureMultiPages(..., templateName) - Processes a multiple-page image.
   • StartCapturing(..., templateName) - Starts continuous capturing to process multiple images.

   The templateName parameter should match the Name field in your CaptureVisionTemplate object.

3. Reset to Default (Optional)

   If you need to discard custom settings and restore factory defaults:

   • ResetSettings() - Resets all parameter templates to their original factory state

   This is useful when you want to start fresh or switch between different configuration modes.

Special Rules for DCV Parameter Configuration

In this section, we will discuss some special rules for configuring the DCV parameter templates. Understanding these rules will help you efficiently configure a simple and user-friendly parameter template.

Default Value of Parameters

Generally, the DCV parameter templates have been designed with many common scenarios in mind, so the default values of many parameters do not need to be modified. When configuring a custom template, you only need to configure required parameters and fine-tuning parameters related to business scenarios. Other optional parameters are automatically filled with default values. This simplifies your configuration and makes your templates easier to read.

Inherited Parameters

Sometimes, we need to configure multiple templates to adapt to different scenarios, but only a few parameter values differ between each template. DCV provides a parameter configuration inheritance mechanism that further reduces the amount of configuration work. For example, when configuring IP_A and IP_B objects in ImageParameterOptions, you can define a BaseImageParameterName parameter in the IP_B object with a value of IP_A. Then IP_B object will inherit all the parameter definitions of IP_A, and if IP_B defines a parameter with the same name but a different value, that parameter will adopt the value of IP_B.

This allows you to create a new parameter template that inherits most of its configuration from an existing template, reducing the amount of repetitive configuration work needed.