Module Variables

When initializing a module with the configuration file, Savant uses the OmegaConf package enabling not only immediate parameter values but also references to the values of other parameters, as well as options for interpolating configuration parameters from external sources.

Interpolation is useful in the following cases:

configure an option to set the value from an environment variable, with a default value given;
avoid duplication of the same value in several places, for example, in the case when objects of the same class are filtered at the output of the Detection Unit and also processed in the Python Function Unit;
use for the parameter a derivative of the value of another parameter if the values of these parameters are interrelated; for example, when the minimum allowed sizes for detected objects depend on the frame size.

Note

Interpolation happens only once, when the module is being initialized. Even when the dynamic parameters are used, their values interpolated only once.

OmegaConf value interpolation capabilities are described in OmegaConf interpolation manual. Savant supports all features of OmegaConf, for example:

parameters:
  object_min_size: 64
pipeline:
  elements:
    - element: nvinfer@detector
      # irrelevant configuration is omitted
      output:
        # irrelevant configuration is omitted
        objects:
          - class_id: 0
            label: person
            selector:
              kwargs:
                min_width: ${parameters.object_min_size}
                min_height: ${.min_width}

Environment Resolver

In Savant, there is a resolver used to retrieve variables from the system environment, such as a combination of oc.env and oc.decode to load a parameter value from the operating system environment:

parameters:
  frame:
    width: ${oc.decode:${oc.env:FRAME_WIDTH, 1280}}
    height: ${oc.decode:${oc.env:FRAME_HEIGHT, 720}}

In addition, Savant implements special resolvers.

Initializer Resolver

The initializer resolver makes it easy to get parameter values from any supported source (system environment, Etcd, default). When using the initializer, the resolution for value happens according to the priorities configured with the parameter_init_priority section. By default, the priorities are configured as follows:

# Etcd -> env -> default
#
parameter_init_priority:
  # higher number means lower priority
  environment: 20
  etcd: 10
  # default has the lowest priority

To use the initializer resolver, you need to specify the type name of the resolver initializer, the name of the parameter by which the value will be searched among the sources, and a default value. For example, using the initializer looks like this:

parameters:
  fps_period: ${initializer:FPS_PERIOD, 10000}
  # equivalent omega conf resolvers
  # fps_period: ${oc.decode:${oc.env:FPS_PERIOD, 10000}}

Calc Resolver

The calc resolver allows using arithmetic expressions to calculate the value of a configuration parameter, including based on the value of other configuration parameters. For example, the configuration that sets the filtering of detected objects according to the frame size in the pipeline looks like this:

parameters:
  frame:
    width: 1280
    height: 720
pipeline:
  elements:
    - element: nvinfer@detector
      # skip irrelevant configuration
      output:
      # skip irrelevant configuration
        objects:
          - class_id: 0
            label: person
            selector:
              kwargs:
                min_width: ${calc:"arg_0*arg_1", ${parameters.frame.width}, 0.15}
                min_height: ${calc:"arg_0*arg_1", ${parameters.frame.height}, 0.15}

The explanation of the calc resolver usage from the example above is as follows:

calc specifies resolver name;
arg_0 * arg_1 is the arithmetic expression to evaluate the value;
the list of values corresponding to the arguments of the expression, separated by commas.

The calc resolver relies on the simpleeval package, a list of supported operators can be seen at the Operators page.

JSON Resolver

The JSON resolver decodes a JSON string, resulting in the JSON object that will be placed into the YAML configuration under the node to which the expression belongs.

Such a resolver is useful if you want to pass a whole section through an environment variable or Etcd. For example, the default value of the parameters.output_frame parameter is internally defined as follows:

parameters:
  output_frame: ${json:${oc.env:OUTPUT_FRAME, null}}

As a result, when loading a configuration, Savant tries to fetch the value of the OUTPUT_FRAME environment variable and then decodes the resulting string as JSON. That is, by passing the following line to the module configuration through the OUTPUT_FRAME environment variable:

'{"codec": "h264", "encoder_params": {"bitrate": 4000000}}'

The resulting configuration is presented in the following snippet:

parameters:
  output_frame:
    codec: h264
    encoder_params:
      bitrate: 4000000