GetPresets

The Ensenso SDK installation comes with a set of parameter presets for different purposes. These presets are located in the installation directory in the form of JSON files. With this command you can get one or more presets based on filter parameters you provide. The resulting presets are included in the command’s Result node as JSON.

To understand the provided command parameters, please first familiarize yourself with JSON schema and below with our NxLib specific preset schema and the given example. We also provide a preset guide with a short code snippet demonstrating how to load and apply a preset from within your application.

There are several parameters that can be used to filter the list of available presets. Providing none of the filter parameters makes the command list all available presets. The possible filter parameters are:

• Name: If known, you can specify the name of a particular preset. The other filters are still applied to the preset with the given name if they are enabled.

• Tags: Specify one or more tags the preset has to have. Only presets containing all the specified tags are returned.

• Condition: Provide a condition the preset’s Data object has to satisfy. Only presets satisfying the condition are returned.

• Data: As described in the schema, a preset file itself can also define a condition, which will be applied to the JSON data specified by this parameter. A preset is only returned if its condition is satisfied. Presets without a condition are considered valid. Not specifying a data node will simply skip filtering by the preset conditions.

When working with filters and especially conditions formulated as JSON schema, you might want to find out why a particular preset was filtered out. The ExcludedPresets subnode of the Result node contains an object for each preset that has been filtered out.

Additional preset files can either be put next to the preinstalled ones or in one or more local directories, which can be given to the command via the FolderPath parameter. In both cases make sure that the Name value is unique in all JSON preset files known by the command.

Preset example

The following example shows a user defined preset for the PatchMatch matching algorithm. It extends an already existing preset StereoMatchingBase and basically just changes the matching method to PatchMatch via the Data object. It will, however, contain all parameter presets defined in StereoMatchingBase. Furthermore, as the Name and Description values already imply, this preset requires a C-series camera (with the JSON schema defined in the Condition object).

Filtering based on this condition only works, however, if the Data parameter is provided. Only if that provided data contains a key ModelName with a value starting with “C57” and if it contains a subnode Parameters, which implies that the camera is currently opened, the preset is returned.

{
    "Name": "PatchMatch-C-Series",
    "Description": "An example parameter preset that extends the base stereo matching preset and only works with C-series cameras",
    "Tags": [
        "PatchMatch",
        "C",
        "Example"
    ],
    "Extends": "StereoMatchingBase",
    "Condition": {
        "properties": {
            "ModelName": {
                "type": "string",
                "pattern": "^C57.*$"
            }
        },
        "required": [
            "ModelName",
            "Parameters"
        ]
    },
    "Data": {
        "Parameters": {
            "DisparityMap": {
                "StereoMatching": {
                    "Method": "PatchMatch"
                }
            }
        }
    }
}

Preset schema

Name	String, required	The name of the preset. Must be unique among all loaded presets.
Description	String, required	An arbitrary description. Does not have to be unique.
Hidden	Boolean, optional	Presets that are only used as a base for other presets can be hidden with this flag.
Tags	Array, optional	One or more tags that can be used to filter the loaded presets.
Extends	String or Array, optional	The name of one or more presets on which this preset is based. If multiple presets are given, extension is performed in the same order as provided in the array. During extension the base values are loaded first and are then merged with the values stored in this preset. Subject of extension are the following fields: Tags Merged as sets. Condition Merged with an allOf JSON schema field. Data Merged on JSON level.
Condition	Object, optional	A condition as JSON schema that the Data parameter of this command must satisfy if given.
Data	Object, required	The NxLib parameters as JSON.

Structuring a complex condition

When writing complex conditions you can split the condition in smaller parts and reference them via the $ref keyword. A JSON file that is referenced by a preset is called a reference file. A reference file must specify a dialect via the $schema field, otherwise it is not recognized as such. We currently only support the dialect http://json-schema.org/draft-07/schema. Reference files are distinguished by their filenames, so make sure that each reference file has a unique filename and also consider the already installed reference files, which could lead to filename conflicts.

Alternatively, you can create a preset file that only contains a condition (leave the Data field empty) and include this pure condition preset in another preset via the Extends keyword.

In the following the above example has been restructured using a reference file. For more examples see the installed presets and reference files.

// Simplified condition referencing another file containing parts of the condition
"Condition": {
    "$ref": "./isCSeriesCamera.json"
    "required": [
        "ModelName",
        "Parameters"
    ]
}

// isCSeriesCamera.json
"$schema": "http://json-schema.org/draft-07/schema",
"properties": {
    "ModelName": {
        "type": "string",
        "pattern": "^C57.*$"
    }
}