Structure of Sequence Files

An acquisition sequence file is defined in JSON format but with the file ending ".seq". Each specific acquisition sequence that should be available for a configuration requires its own sequence file.

The acquisition sequence must be specified by an array of "lanes". A lane defines a sequence of "actions" for a specific image source. Thus, each image source is configured in its own lane in the acquisition sequence. MERLIC currently supports different types of actions: for acquiring an image, setting individual camera parameters, setting a delay, and setting a barrier for synchronization purposes.

Each lane also defines a parameter set for the camera or peripheral device which should be loaded into the device when the acquisition sequence is activated. This can be either the primary parameter set that is implicit for each image source, or an alternative parameter set that can be saved using the MERLIC RTE Setup. In the following, you can find more detailed information.

File Version

The acquisition sequence file format is versioned. The file version consists of a major and a minor version.

MERLIC 26.03 uses the major file version 2. If you have used acquisition sequence files in MERLIC 5.4 or 5.5, they have used the major version 1. When you start MERLIC 26.03 or newer for the first time, the existing sequence files defined with major file version 1 will be automatically upgraded to file version 2.

Upgraded files are not backwards-compatible, so you won't be able to use them with previous versions of MERLIC. Backups of the version 1 sequence files are automatically created with the file extension ".seq.1" in case you need to downgrade manually.

The minor file version will be used in future versions of MERLIC to facilitate extensions to the file format in a backwards-compatible manner.

JSON Schema and Editor Support

MVTec hosts JSON schema definitions for the acquisition sequence file format. Using a modern text editor with support for JSON schema can simplify the process of authoring sequence files in various ways:

• Keys and attributes in the JSON file can be auto-completed by the editor according to the schema definition.
• The editor can display descriptions which are given in the schema, for example when hovering over keys and attributes in the JSON file.
• Many common errors when authoring the sequence files can be caught early, for example, missing mandatory keys, invalid values, or wrong data types.

To benefit from the JSON schema, include the following key in the top-level object of sequence file:

"$schema": "http://download.mvtec.com/acquisition-sequence-v2.0.schema.json",

This tells the editor where to find the schema definition. Additionally, you may need to tell your editor to treat ".seq" files as JSON. For example, in Visual Studio Code, click on the file type in the editor window's status bar, usually "Plain Text", and select "JSON" instead.

Lanes

The acquisition sequence is defined by an array of "lanes" in the sequence file. You may configure one lane per image source. However, it is not mandatory to define a lane for each image source in the image source configuration. A lane contains a specific set of information:

Whenever the acquisition sequence is executed, the lanes are executed in parallel.

The basic structure of a sequence file might look as follows:

{
    "$schema": "http://download.mvtec.com/acquisition-sequence-v2.0.schema.json",
    "Version": "2.0",
    "Lanes": [
        {
            "DeviceType": "ImageSource",
            "DeviceId": "Cam1",
            "AlternativeParameterSet": null,
            "Actions": []
        },
        {
            "DeviceType": "ImageSource",
            "DeviceId": "Cam2",
            "AlternativeParameterSet": null,
            "Actions": []
        }
    ]
}

When creating or editing an acquisition sequence file, you can use the "$schema" keyword to reference the JSON schema defined for acquisition sequences:

{
    "$schema": "http://download.mvtec.com/acquisition-sequence-v2.0.schema.json",
    "Version": "2.0",
    "Lanes": [
        ...
    ]
}

The schema can be used to verify whether the format is valid and enables the use of auxiliary features such as code completion and displaying information on the parameters, provided these features are supported in the IDE or text editor of your choice.

Available "Actions"

AcquireImage

This action can be used to acquire an image from the image source. It contains only one attribute, "ImageName", which defines the name of the image. The name must be unique within the acquisition sequence. It also represents the name that will be shown in the Image Source tool in the MVApp when selecting the image to be used in the MVApp.

If you are configuring an acquisition sequence for an already existing MVApp, you have to keep in mind to either define the same name for the image as already set in the MVApp or to adjust the MVApp to the new name in the acquisition sequence. Otherwise, an error might occur.

An error also occurs when using this action for non-streaming devices. It can only be used for regular camera devices.

Example

{
    "Type": "AcquireImage",
    "Attributes": {
         "ImageName": "Image1"
    }
}  

SetParameter

This action can be used to set a parameter of a camera device. The name and the value of the parameter must be passed in the attributes "ParameterName" and "ParameterValue".

You can set the values for camera parameters as well as for MVTec EasyParams. For both types of parameters, the respective internal name of the parameter must be given in the "ParameterName" attribute. The internal name is defined by the manufacturer and might differ from the display name which is shown in the "Image Sources" tab of the MERLIC RTE Setup. For example, the internal name of a camera parameter might have an additional prefix or it might be the same as the display name but without spaces. They correspond to the parameter names that are used by HALCON in the operators get_framegrabber_param and set_framegrabber_param. However, you can also get the internal name via the MERLIC RTE Setup.

Getting the Internal Parameter Name

1. Open the MERLIC RTE Setup and go to the "Image Sources" tab.
2. Select the respective image source configuration and camera device. Make sure that the configuration is active.
3. Open the parameter tab on the right in which the desired camera parameter is provided:
   • For an EasyParam, open the "EasyParams" tab.
   • For any other camera parameter, open the "All Parameters" tab.
4. Look for the desired parameter in the parameter list.
5. Right-click on the parameter name and copy the internal name via the context-menu.
6. You can now past the name in the sequence file.

The internal names of the EasyParams are the following:

Example

{
    "Type": "SetParameter",
    "Attributes": {
        "ParameterName": "[Consumer]exposure",
        "ParameterValue": 200.0
    }
}

By default, the modified parameter is reset to its previous value after each execution of the sequence. This behavior can optionally be deactivated by setting the attribute "ExcludeFromRollback" to "true". However, this option should be used with care because it might lead to unexpected camera configurations, especially when setting camera parameters with dependencies to other values and when using multiple acquisition sequences.

Delay

This action can be used to delay the execution of the lane for a specified duration in milliseconds. The delay must be defined in the attribute "Milliseconds".

Example

{
    "Type": "Delay",
    "Attributes": {
        "Milliseconds": 2000
    }
}

Barrier

The lanes of different image sources are executed in parallel. This action can be used to synchronize the execution of two or more lanes. When the execution of a lane arrives at a barrier it waits until all other lanes have also arrived at their according barrier, that is, at the barrier with the same "BarrierName" attribute.

Example

{
    "Type": "Barrier",
    "Attributes": {
        "BarrierName": "barrier1"
    }
}