Presets

Overview

The presets feature in the Obstacle Detection System (ODS) allows the users to define and manage up to 128 predefined zone configurations. This feature facilitates quick switching between different configurations by loading a preset definition through a single command. This is especially useful in dynamic environments requiring frequent zone setup changes.

Key features

  1. Predefined configurations: users can define up to 128 presets.

  2. Quick activation: presets can be activated using the load command with a specific definition identifier.

  3. Customizable definitions: each preset includes:

    1. A set of active camera ports.

    2. Zone configurations with a unique

      1. Zone configuration ID

      2. Zone type

      3. Zone coordinates.

Note

Currently, it is not possible to configure the presets using the ifmVisionAssistant. The presets are only configured using the Python or C++ ifm3d API.

Parameter description

Within the ODS application parameters, the presets follow the structure below. All presets are contained under the presets/definitions parameter.

{
  "applications": {
    "instances": {
      "app0": {
        "class": "ods",
        "presets": {
          "definitions":{
            "0": {
              "description": "description of the preset",
              "preset": {
                "activePorts": [/* List of active camera ports */],
                "zones": {
                  "zoneConfigID":/* Unique identifier for zone configuration */,
                  "zoneType":/* Type of zone (e.g., convexHull, Polygon) */,
                  "zoneCoordinates": [/* Coordinates defining the zone */]
                }
              }
            }
          },
          "load": {"identifier": 0},
          "location": "/applications/instances/app0/configuration",
          "command": "nop"
        }
      }
    }
  }
}

All the parameters can be found in the applications/instances/appX/presets section of the JSON configuration.

Parameter

Description

/presets/definition/X

The identifier of the first preset, the first identifier must start with value "0" (string). A maximum of 128 presets can be configured.

/presets/definition/X/preset/activePorts

The ports that are used by this preset

/presets/definition/X/preset/zones

Define the used protection zones - See ods zone definition for a complete description. A maximum of three zones can be configured in one preset.

/presets/load/identifier

Value of the identifier of the preset that will be loaded when a load command is triggered

/presets/location

A read-only parameter specifying the JSON path to the ODS configuration, where the preset will be loaded when the load command is triggered.

/presets/command

Specifies the command to be executed. It can have the value nop (do nothing) or load (trigger loading preset).

/presets/definitions/X/description

String specifying a description for the preset

Note

  • The preset identifier is a string parameter.

  • The command parameter is per default nop and will return to this default again once the operation is completed.

Load command

To load a preset we use the load command, which will set the preset having the identifier matching the value of /presets/load/identifier. The load command is located under /presets/command and can have the following values:

  • nop: Default value, meaning do nothing.

  • load: Triggers loading the preset.

The load command execution time mainly depends on the activePorts in the preset. If we load a preset with different activePorts, the newly added ports need to change from IDLE to RUN. Changing only the zones while keeping the same activePorts is completed within one to two ODS frames, which corresponds to 50 to 100 ms with the default framerate of 20Hz.

The following table documents the approximate load runtime:

Change

Time to update result

Changing only the zone: activePorts: ["port2"] → ["port2"], zones: [zones_i] → [zones_j]

50 to 100 ms

Adding another port: activePorts: ["port2"] → ["port2", "port3"], zones: [zones_i] → [zones_j]

~600 ms

Mutually exclusive ports: activePorts: ["port2"] → ["port3"], zones: [zones_i] → [zones_j]

~600 ms

Configuration procedure

Please follow these steps to configure the ODS presets system:

  1. Create an ODS application instance and set up the ODS parameters. Please ensure that you list all the ports used across all presets in the ODS /appX/ports parameter. Refer to the port configuration documentation for detailed instructions.

  2. Currently, the presets can only be configured via the ifm3d API. Set a JSON configuration which contains the requested presets. Ensure each preset has a unique identifier (presets/definition/X) matching the zoneConfigID values.

    Note

    JSON validation is only performed during the configuration of presets and not when they are loaded using the load command. Each preset identifier should have a unique value starting from 0 up to 999, with a maximum of 128 presets. To avoid confusion, set the zoneConfigID to match the identifier of each preset. This is especially important when using the PLC application, as the global value displayed to the PLC is the zoneConfigID, not the preset identifier.

  3. Set the ODS application to RUN state. This can be also done before setting the ODS presets.

    Note

    • At this step, no preset will be automatically loaded. The default value of applications/instances/appX/configuration/zones/zoneConfigID is 0. This does not mean that to the preset containing zoneConfigID 0 has been loaded. Only after manually executing a load command will the zoneConfigID parameter be overwritten.

    • When ODS is in RUN state and a preset is added to the configuration, the currently used preset will not change until a load command is issued.

  4. Set the desired preset via a load command. Make sure to use the identifier to load the appropriate preset.

Example Configuration

Below is an example of an ODS configuration including presets. This configuration includes three presets:

  1. Forward driving preset: optimized for detecting objects in front of the vehicle with three detection zones.

  2. Backward driving preset: designed for rear detection with two zones.

  3. Left turn preset: configured for detecting objects during left turns with three zones.

These presets are provided as examples and can be customized or extended based on the specific needs of the customer.

{
  "applications": {
    "instances": {
      "app0": {
        "class": "ods",
        "ports": [
          "port2",
          "port3",
          "port6"
        ],
        "state": "CONF",
        "presets": {
          "definitions":{
            "0": {
              "description": "Forward preset with three zones and one active camera",
              "preset": {
                "activePorts": [
                  "port2",
                ],
                "zones": {
                  "zoneConfigID": 0,
                  "zoneType":"convexHull",
                  "zoneCoordinates": [
                    [[0, -0.3], [2.5, -0.3], [2.5, 0.3], [0, 0.3]],
                    [[2.5, -0.3], [3.5, -0.3], [3.5, 0.3], [2.5, 0.3]],
                    [[3.5, -0.3], [4.5, -0.3], [4.5, 0.3], [3.5, 0.3]]
                  ]
                }
              }
            },
            "1": {
              "description": "Backward preset with two zones and one active camera",
              "preset": {
                "activePorts": [
                  "port3"
                ],
                "zones": {
                  "zoneConfigID": 1,
                  "zoneType":"polygon",
                  "zoneCoordinates": [
                    [[-0.5, -0.3], [-3.0, -0.3], [-3.0, 0.3], [-0.5, 0.3]]
                    [[-3.0, -0.3], [-4.0, -0.3], [-4.0, 0.3], [-3.0, 0.3]]
                  ]
                }
              }
            },
            "2": {
              "description": "Left turn preset with three zones and two active cameras",
              "preset": {
                "activePorts": [
                  "port2",
                  "port4"
                ],
                "zones": {
                  "zoneConfigID": 2,
                  "zoneType":"polygon",
                  "zoneCoordinates": [
                    [[0.5, 0.3], [1.5, 0.3], [1.5, 0.9], [0.5, 0.9]],
                    [[1.5, 0.3], [2.5, 0.3], [2.5, 0.9], [1.5, 0.9]],
                    [[2.5, 0.3], [3.5, 0.3], [3.5, 0.9], [2.5, 0.9]]
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}

Best practices

  • As a first configuration step, include all required cameras in the JSON ports parameter. You can only define activePorts for each preset that are included in the global ports parameter. For example, if using two cameras for forward driving and two cameras for backward driving, specify all four camera ports in the global ports parameter.

  • Ensure that each preset has a unique identifier to prevent one preset from being overwritten by another. Define a unique value for the identifier starting from 0 up to 999, with a maximum of 128 presets.

  • We highly recommend to set the zoneConfigID value matches the identifier of the preset to avoid confusion.

  • When loading a preset, the identifier of the preset is going to be used for the load command. The zoneConfigID displayed is the one defined in the loaded preset, at presets/definitions/X/zones/zoneConfigID.

Known issues:

  • The zoneConfigID is not enforced to be identical with the presets identifier.

  • If no preset is set, the zoneConfigID will be displayed as the default value 0, but this doesn’t mean that preset 0 is active.

  • IDLE state will be set for the application if a preset containing an empty activePorts is loaded. The ODS will not update the data and the output returned will be empty.

  • The default value of the output if no zones or presets are set is [0,0,0]. So please ensure that a preset is loaded before operation.

Code examples

Code examples are available in the ifm3d-examples repository: see the Python ODS preset example.