How to Enable Re-identification Using Visual Similarity Search#

This guide provides step-by-step instructions to enable or disable re-identification (ReID) using visual similarity search in a Intel® SceneScape deployment. By completing this guide, you will:

Enable re-identification using a visual database and feature-matching model.
Understand how to track and evaluate unique object identities across frames.
Learn how to tune performance for specific use cases.

This task is important for enabling persistent object tracking across different camera scenes or time intervals.

Prerequisites#

Before you begin, ensure the following:

Docker is installed and configured.
You have access to modify the docker-compose.yml file in your deployment.
You are familiar with scene and camera configuration in Intel® SceneScape.

Steps to Enable Reidentification (ReID) for Out of Box Experience#

Enable VDMS storage by uncomment the following section in docker-compose-dl-streamer-example.yml

vdms:
  image: intellabs/vdms:latest
  init: true
  networks:
    scenescape:
      aliases:
        - vdms.scenescape.intel.com
  environment:
    - OVERRIDE_ca_file=/run/secrets/certs/scenescape-ca.pem
    - OVERRIDE_cert_file=/run/secrets/certs/scenescape-vdms-s.crt
    - OVERRIDE_key_file=/run/secrets/certs/scenescape-vdms-s.key
  secrets:
    - source: root-cert
      target: certs/scenescape-ca.pem
    - source: vdms-server-cert
      target: certs/scenescape-vdms-s.crt
    - source: vdms-server-key
      target: certs/scenescape-vdms-s.key
  restart: always

For information on VDMS, visit the official documentation: https://intellabs.github.io/vdms/.

SceneScape leverages VDMS to store object vector embeddings for the purpose of reidentifying an object using visual features.

Uncomment VDMS dependency in scene config Uncomment the vdms dependency:

depends_on:
  web:
    condition: service_healthy
  broker:
    condition: service_started
  ntpserv:
    condition: service_started
  vdms:
    condition: service_started

Enable Visual Feature Extraction in Video Pipeline Edit the retail-config setting in Docker Compose as follows:

retail-config:
  file: ./dlstreamer-pipeline-server/retail-config-reid.json

This reidentification-specific configuration uses a vision pipeline that includes anonymous visual feature extraction (also called “visual embeddings”) using a person reidentification model:

"pipeline": "multifilesrc loop=TRUE location=/home/pipeline-server/videos/apriltag-cam2.ts name=source ! decodebin ! videoconvert ! video/x-raw,format=BGR ! gvapython class=PostDecodeTimestampCapture function=processFrame module=/home/pipeline-server/user_scripts/gvapython/sscape/sscape_adapter.py name=timesync ! gvadetect model=/home/pipeline-server/models/intel/person-detection-retail-0013/FP32/person-detection-retail-0013.xml model-proc=/home/pipeline-server/models/object_detection/person/person-detection-retail-0013.json name=detection ! gvainference model=/home/pipeline-server/models/intel/person-reidentification-retail-0277/FP32/person-reidentification-retail-0277.xml inference-region=roi-list ! gvametaconvert add-tensor-data=true name=metaconvert ! gvapython class=PostInferenceDataPublish function=processFrame module=/home/pipeline-server/user_scripts/gvapython/sscape/sscape_adapter.py name=datapublisher ! gvametapublish name=destination ! appsink sync=true",

Start the System Launch the updated stack:
```
docker compose up
```

Expected Result: Intel® SceneScape starts with ReID enabled and begins assigning UUIDs based on visual similarity.

Steps to Disable Re-identification#

Comment Out the Database Container Disable vdms by commenting it out in docker-compose.yml:
```
# vdms:
#   image: intellabs/vdms:latest
#   ...
```
Remove the Dependency from Scene Controller Comment or delete the vdms dependency:
```
depends_on:
  - broker
  - web
  - ntpserv
  # - vdms
```
Remove ReID from the Camera Pipeline Edit the retail-config setting in Docker Compose and revert to the config without re-id model:

retail-config:
  file: ./dlstreamer-pipeline-server/retail-config.json

Restart the System:
```
docker compose up --build
```

Expected Result: Intel® SceneScape runs without ReID and no visual feature matching is performed.

Evaluating Re-identification Performance#

Track Unique IDs:
Intel® SceneScape publishes unique_detection_count via MQTT under the scene category topic. Each object includes an id field (UUID) for tracking.
UI Support:
UUID display in the 3D UI is planned for future releases.

Note: The default ReID model is tuned for the ‘person’ category and may not generalize well to other object types.

How Re-identification Works#

When an object is first detected, it is assigned a UUID and no similarity score. If ReID is enabled, the system collects visual features over time. Once enough features are gathered, they are compared to those in the database:

Match Found: The object is reassigned a matching UUID and given a similarity score.
No Match: The object retains its original UUID.

Known Issue: Current VDMS implementation does not support feature expiration, leading to degraded performance over time. This will be addressed in a future release.

Configuration Options#

Parameter	Purpose	Expected Value/Range
`DEFAULT_SIMILARITY_THRESHOLD`	Controls match sensitivity. Higher values increase matches (and false positives).	Float (e.g., 0.7–0.95)
`DEFAULT_MINIMUM_BBOX_AREA`	Minimum bounding box size to consider a valid feature.	Pixel area (e.g., 400–1600)
`DEFAULT_MINIMUM_FEATURE_COUNT`	Minimum features needed before querying DB.	Integer (e.g., 5–20)
`DEFAULT_MAX_FEATURE_SLICE_SIZE`	Proportion of features stored to improve DB performance.	Float (e.g., 0.1–1.0)

To apply changes:

docker compose down
make -C docker
docker compose up --build

Troubleshooting#

Issue: ReID not working
- Cause: Database container is not running or not linked.
- Resolution:
```
docker ps | grep vdms
docker compose logs vdms
```
Issue: Objects not re-identifying across scenes
- Cause: Insufficient visual features collected or poor lighting.
- Resolution:
  - Lower DEFAULT_MINIMUM_FEATURE_COUNT.
  - Increase DEFAULT_MINIMUM_BBOX_AREA only if objects are large and visible.