The provided SDK enables accessing image results of a MERLIC Vision App, that is, images that have been specified as an "MVApp result" in MERLIC Creator. The following sections describe the concept of the image API that can be used to retrieve these image results.

If you are using the C++ support libray, the concept of the image API is the same. Therefore, you can also check the information on this page to learn about the general concept of the image API. For specific information in case of the support library, you may refer to the topic C++ Plug-in Support Library.

Data Container Descriptor and Data Component Descriptor

The image API is based on data container descriptors and data component descriptors which reference a specific data container and data component, respectively.

For each execution, a data container descriptor is provided which may contain multiple data component descriptors. The number of data component descriptors depend on the number of image results that have been defined in the respective MVApp. Each data component descriptor references a single data component which, in turn, represents a specific image result. The abstract term "data component" is used to allow for future generalization. Currently, MERLIC only supports image data for this purpose. However, this might change in future releases. A data component descriptor also contains meta data of the referenced data component, i.e., image, such as the default image format and the default image dimension. The data component descripter does not contain the actual image result but a descriptive representation of the image. Thus, each image result that is provided by an MVApp is represented by a data component and each data component is referenced by a data component descriptor which also contains the default meta data for the image.

For example, in the graphic below, three images have been specified as MVApp results. Therefore, the data container descriptor that results from an execution contains three data component descriptors and each of these data component descriptors references one of the three image results.

In case an MVApp is executed in which no image result has been defined as MVApp result, the data container descriptor will be empty.

Accessing the Data Container Descriptor

The data container descriptor of an iteration is provided to the communication plug-in as part of the ResultReady event and as part of the Result object that is queried from the result store of the vision system, that is, MERLIC. The plug-in may continue to submit the data container descriptor back to the vision system without any modification. However, the plug-in may also modify the meta data of the data component descriptors contained in the data container descriptor before submitting the data container descriptor back to the vision system. This might be useful if you want to query/use a specific image format or a predefined image dimension.

It is also possible to select only specific data component descriptors, for example, if you are not interested in all image results, or even create new data container descriptors combining the data component descriptors from different results. In the example graphic above, only two of the three data component descriptors are selected. In addition, the image dimension was changed in the data compoment descriptor that references the image depicted by the red circle.

Submitting the Data Container Descriptor to the Vision System

The final data container descriptor can be submitted back to the vision system as requested to retrieve the corresponding data container via MV_FetchDataContainer(). In response to MV_FetchDataContainer(), the communication plug-in receives a data container which contains the data components of the requested data component descriptors. The data components will contain the binary image data in the exact format and dimensions as specified in the corresponding data component descriptor. If an individual data component descriptor could not be serviced, a "data component error" takes its place as depicted in the graphic above. This might be the case if the image is no longer stored, if any meta data is not supported, or if the conversion failed.

After the communication plug-in received the data components, that is, the image results, it can do whatever it likes with the data. For example, the MQTT plug-in publishes the data to a dedicated MQTT topic whereas the example plug-in "save-images" stores the images on the file system.

Image Format

You have to define in which format the images are fetched. You could specify a fixed image format in the code of your plug-in or you can provide a user parameter to enable the user to choose the desired image format in the configuration of the plug-in. If you want to have a look at possible user parameters for image results, you can use the example plug-in "save-images" or the standard plug-ins MQTT and OPC UA, which also support the "Image Result" feature.

In general, all images of the types "byte", "int1", "uint2", "int2", int4", "int8", and "real" can be exported in the MVApp as an MVApp result. Using MERLIC RTE, it is possible to fetch them in one of three data formats: HALCON Serialized Item, JPEG, and PNG. The image type "real" forms an exception, because you can export it only as HALCON Serialized Item. To export images of the type "real" as JPEG or PNG, the image can first be convert in the MVApp to a "byte" image.

Availability of Image Results

Image results can only be accessed if the respective image data is still availalbe in the database of the vision system. Otherwise, an error will be returned. Whether the image data is still available depends on the size of the in-memory storage for results. It defines the maximum number of results that are stored for MERLIC RTE. If the number of results exceeds the defined buffer size, the oldest results will be removed including any image data of that result.

To keep the image data of those results that are removed from the result store, you can use the extended image storage of MERLIC. This way, the image results are still available. However, as soon as the size of the extended image storage is exceeded, it will also remove the oldest images from this storage.

The size of the in-memory storage and the settings for the extended image storage can be configured in the MERLIC preferences within the MERLIC Creator or in the MERLIC .ini file via the respective ini options. For more information, see MERLIC Preferences and The MERLIC .ini File in the MERLIC manual.