Model Configuration File Format#

Overview#

Model configuration files (JSON) define the AI models available for use in camera pipelines within SceneScape, specifying model parameters, element types, and adapter configurations needed to generate proper GStreamer pipelines with DLStreamer elements.

File Structure#

Model configuration files are JSON documents stored in the Models/models/model_configs folder and managed through the SceneScape Models page, which is accessible in the top menu of the SceneScape UI. Each file contains model definitions with unique identifiers that can be referenced in the Camera Chain field.

Basic Structure#

{
  "model_identifier": {
    "type": "detect|classify",
    "params": {
      "model": "path/to/model.xml",
      "model_proc": "path/to/model-proc.json"
      // other DLStreamer element parameters
    },
    "input-format": {
      "color-space": "BGR|RGB"
    },
    "adapter-params": {
      "metadatagenpolicy": "detectionPolicy|reidPolicy|classificationPolicy"
    }
  }
}

Example Configuration#

{
  "retail": {
    "type": "detect",
    "params": {
      "model": "intel/person-detection-retail-0013/FP32/person-detection-retail-0013.xml",
      "model_proc": "object_detection/person/person-detection-retail-0013.json",
      "scheduling-policy": "latency",
      "threshold": "0.75"
    },
    "input-format": {
      "color-space": "BGR"
    },
    "adapter-params": {
      "metadatagenpolicy": "detectionPolicy"
    }
  }
}

Field Descriptions#

Model Identifier#

The top-level key (e.g., “retail”) serves as the short identifier referenced in the Camera Chain field. It should be unique within the configuration file, descriptive of the model’s purpose, and easy to reference in the camera configuration page.

Type Field#

Specifies the DLStreamer element type for the model:

  • detect: maps to gvadetect element for object detection models.

  • classify: maps to gvaclassify element for classification models.

Parameters Section#

Contains the model-specific parameters passed to the DLStreamer element.

Path Resolution#

  • model: path to the model file (typically .xml for OpenVINO models).

  • model_proc: path to the model processing configuration file (.json).

Note: Model proc file is deprecated. Avoid using it to prevent dealing with a legacy solution. It will be maintained for some time to ensure backwards compatibility, but you should not use it in modern applications. The new method of model preparation is described in Model Info Section. See the Model proc file documentation page for more details.

Important: Paths are automatically resolved relative to the /home/pipeline-server/models directory in the DLStreamer container. Use relative paths from this base directory.

Additional Parameters#

Any additional parameters specified in the params section are passed directly to the DLStreamer element with proper formatting and quoting for GStreamer pipeline syntax.

Input Format#

Defines the expected input format for the model:

  • color-space: Specifies the color space format (BGR, RGB) required by the model

Adapter Parameters#

Configuration for the Python adapter that transforms DLStreamer metadata to the SceneScape format:

  • metadatagenpolicy: defines how metadata is generated and formatted.

    • detectionPolicy: for standard object detection results with 2D bounding boxes.

    • detection3DPolicy: for 3D object detection results with spatial coordinates, rotation, and dimensions.

    • reidPolicy: for re-identification tracking with detection data plus encoded feature vectors.

    • classificationPolicy: for classification results combined with detection bounding boxes.

    • ocrPolicy: for optical character recognition results with 3D detection data plus extracted text.

Usage in Pipeline Generation#

When generating a camera pipeline:

  1. The Camera Chain field references a model by its identifier (e.g., “retail”).

  2. The pipeline generator looks up the model configuration.

  3. The type field determines which DLStreamer element to use (gvadetect or gvaclassify).

  4. The params section provides the element parameters with resolved paths.

  5. The adapter-params configure the metadata transformation adapter.

Best Practices#

  • Descriptive Identifiers: use meaningful names for model identifiers.

  • Relative Paths: always use paths relative to the models directory.

  • Consistent Naming: follow consistent naming conventions across configurations.

  • Validation: test model configurations before deployment.

Troubleshooting#

When adding a new model config file through the Models page UI, if you encounter the following error:

Error uploading file: [Errno 13] Permission denied

use below instructions as a workaround.

Copying a model config into models PVC#

Use the cluster PVC mount that holds SceneScape models to make a config available at runtime.

  1. Find the models PVC and pod:

kubectl get pvc -n <namespace> | grep models
kubectl get pods -n <namespace>

  1. Identify mount path of the models PVC

kubectl describe pod scenescape-release-1-web-dep-584dbc6c5d-vtcwl -n scenescape | grep -A 10 -B 10 models

  1. Copy the config file: The default mount path is /home/scenescape/SceneScape/models.

kubectl cp /path/to/local/config.json <namespace>/<pod>:/home/scenescape/SceneScape/models/models/model_configs/config.json

  1. Verify and restart (if needed):

kubectl exec -n <namespace> <pod> -- ls -la /home/scenescape/SceneScape/models/models/model_configs/
kubectl rollout restart deployment/<deployment-name> -n <namespace>

If you encounter the same permissions error uploading model files, copy the files using above instructions into the models folder such that they can be referenced from the new model config file.