Skip to main content
Ctrl+K

Open Edge Platform

    • Open Edge Platform Overview
    • Metro
    • Manufacturing
    • Retail
    • Robotics
    • Education
    • Health and Life Sciences
    • Federal and Aerospace
    • Libraries, Tools, Services
    • DL Streamer
    • Scenescape
    • ViPPET
    • Geti
    • OpenVINO
    • OpenVINO Physical AI
    • Platform Software
  • Open Edge Platform Overview
  • Metro
  • Manufacturing
  • Retail
  • Robotics
  • Education
  • Health and Life Sciences
  • Federal and Aerospace
  • Libraries, Tools, Services
  • DL Streamer
  • Scenescape
  • ViPPET
  • Geti
  • OpenVINO
  • OpenVINO Physical AI
  • Platform Software

Section Navigation

  • Handheld (Soldier System) Blueprint
    • Infrastructure Setup
      • System Requirements
      • Advanced Image Customization
      • Build on macOS (x86 VM)
      • Infrastructure Capabilities
        • Container Device Interface Guide
        • GPU and NPU Device Plugins
        • Power Profiles User Guide
        • Thermal Profiles User Guide
        • Power and Thermal Profiles Co-working Guide
      • Troubleshooting
    • Install OEP SDKs
    • Install Handheld Multi-Modal Application
    • Access Application User Interface
    • Operator Guide
    • Application Operations
    • Benchmarks
      • Edge Workloads and Benchmarks Guide
    • AI Playground
    • AI Agent SKILLs
      • DL Streamer Pipelines Guide
        • DL Streamer Coding Agent Guide
      • Infrastructure AI Agent Integration
    • Release Notes
      • Release Notes 2026.1
  • UAV Blueprint
    • Infrastructure Setup
      • System Requirements
      • Advanced Image Customization
      • Build on macOS (x86 VM)
      • Infrastructure Capabilities
        • Container Device Interface Guide
        • GPU and NPU Device Plugins
        • Power Profiles User Guide
        • Thermal Profiles User Guide
        • Power and Thermal Profiles Co-working Guide
      • Troubleshooting
    • Install OEP SDK and Usage
    • Install UAV Vision Analytics Application
      • Standalone Mode
      • UAV Mission Compute SDK Mode
    • How-To Guides
      • QGroundControl
      • Multi-UAV Operations in the Ground Station
      • Search Live Video with VSS
      • Switch Deployment Modes
      • Enable NPU Inference
      • Simulate a Continuous Mission
      • View Detection Logs
      • Makefile Reference
      • Troubleshooting
    • How to Customize
      • Configure the Cameras
      • RealSense Camera
      • Manage the Detection Model
      • Modify the Detection Model
      • Change the Captioning (VLM) Model
      • Change the Video Source
      • Use Your Own Videos
      • Manage Pipelines
      • Modify Pipelines
      • Customize the Telemetry Overlay
      • Tune VSS Live Search
    • Benchmarks
      • UAV-specific Benchmarks Guide
      • Edge Workloads and Benchmarks Guide
    • Agent SKILLs
      • DL Streamer Pipelines Guide
        • DL Streamer Coding Agent Guide
      • Infrastructure AI Agent Integration
      • SDK Agent Commands and MCP Tools
    • Release Notes
  • Mission Systems Blueprint
    • Infrastructure Setup
      • System Requirements
    • Deterministic Threat Detection
      • System Requirements
      • First-Time Setup
      • Get Started
        • System Requirements
        • First-Time Setup
        • How-To Guides
          • Configure the Moxa Time-Sensitive Networking (TSN) Switch
          • Configure VLANs on the Moxa Switch
          • Create VLANs on All Machines
          • Configure Precision Time Protocol (PTP), IEEE 1588v2
          • Configure Precision Time Protocol (PTP), IEEE 802.1AS (gPTP)
          • Enable Time-Sensitive Networking (TSN) Traffic Shaping (IEEE 802.1Qbv)
          • Configure the Basler Camera to Use Precision Time Protocol (PTP) Timestamps
          • Integrate Basler Cameras with Scenescape
      • How-To Guides
        • Configure the Moxa Time-Sensitive Networking (TSN) Switch
        • Configure VLANs on the Moxa Switch
        • Create VLANs on All Machines
        • Configure Precision Time Protocol (PTP), IEEE 1588v2
        • Configure Precision Time Protocol (PTP), IEEE 802.1AS (gPTP)
        • Enable Time-Sensitive Networking (TSN) Traffic Shaping (IEEE 802.1Qbv)
        • Configure the Basler Camera to Use Precision Time Protocol (PTP) Timestamps
        • Integrate Basler Cameras with Scenescape
      • Release Notes
    • Benchmarks
      • Mission Systems Benchmarks Guide
      • Edge Workloads and Benchmarks Guide
    • Release Notes

---------------

  • Intel® Edge System Qualification
  • Get Help or Contribute
  • Federal And Aerospace AI Suite
  • Uncrewed Aerial Vehicle (UAV) Blueprint
  • How to Customize UAV Vision Analytics
  • Tune VSS Live Search

Tune VSS Live Search#

The ground station’s live search is tuned entirely through uav-ground-station/.env. The defaults suit one UAV or a small fleet with the bundled CLIP embedding model; this page lists the settings worth changing and what each one trades off. After any change:

cd uav-ground-station
make down-vss && make up-vss      # VSS_SEARCH_* only need: docker compose ... up -d --build viz-backend

How many candidates VSS keeps#

Setting

Default

Effect

VSS_MAX_RESULTS

50

The most results the search popup lists. It is also VSS’s AGGREGATION_MAX_RESULTS (the top non-overlapping time windows VSS keeps per query), so the ground station can fetch up to this many per UAV camera and always has enough to fill the list after you pick one camera.

VSS aggregates across all indexed streams, so a camera or UAV with far more indexed footage could take every slot. The ground station therefore also asks VSS for each UAV’s and each camera’s own best matches, merges the answers and interleaves them by (UAV, camera), so every camera with a match is represented in the list. The UAV and Camera filters narrow that merged set without searching again, and the list then shows the top VSS_MAX_RESULTS of what remains. Raising the value shows more results, at the cost of slower queries (more windows are scored).

Which results are shown#

VSS’s relevance_score is normalised per query (the best hit is always 1.0), so it ranks hits but cannot say whether the best one is a real match. The ground station filters on the raw frame similarity instead:

Setting

Default

Effect

VSS_SEARCH_MIN_PEAK_SCORE

0.23

Hits whose best frame scores below this are dropped. Turns “an elephant” over road footage into no results. Tuned for CLIP ViT-B/32 (on aerial footage an absent object peaks at 0.21-0.22 and a present one at 0.25 or more; single words such as “person” score lower than full descriptions); another embedding model needs a different value.

VSS_SEARCH_RELATIVE_CUTOFF

0.90

Of the remaining hits, keep those within this fraction of the best hit’s frame score for the same UAV, trimming the weak tail behind a strong match.

Set both to 0 to show everything VSS returns. Lower MIN_PEAK_SCORE (for example 0.22) if genuine matches are being hidden; raise it if unrelated clips appear for nonsense queries. The search popup’s filtered_out count (/api/search) shows how many hits the filters removed.

Queries that name an object#

VSS also indexes crops of the objects its detector finds, each with a label. When a query names a detectable object (person, car, truck, bus, …), crops labelled as another object are dropped and the label of a matching crop is shown as Matched object on the result. VSS_SEARCH_OBJECT_MATCH selects the behaviour:

Value

Effect

crops (default)

Drop crops labelled as another object; whole-frame hits stay.

strict

Return only crops labelled as the searched object. Every result shows the object, but nothing is returned when the detector misses it (small or low-resolution frames).

off

Rank by image-text similarity alone.

How footage is indexed#

Setting

Default

Effect

VSS_FRAME_INTERVAL

15

Embed one frame every N frames of each live stream. Lower = finer time resolution and more embeddings (more CPU/GPU, more storage, slower queries); higher = cheaper indexing.

VSS_LIVE_RETENTION_HOURS

24

How long live footage and embeddings are kept (0 = forever).

VSS_LIVE_STREAM_MAX_CONCURRENT

8

Live streams indexed at once, one per UAV camera. Feeds beyond it show as queued in the live-index panel, the tab being viewed first. Raise it to index more UAVs together (more CPU/GPU).

VSS_INGEST_EMBEDDING_DEVICE, VSS_DETECTION_DEVICE, VSS_QUERY_EMBEDDING_DEVICE

CPU

Devices for frame embedding, object crops and query embedding; GPU/NPU need the device entries in .env.

VSS_ENABLE_OBJECT_DETECTION

true

Also embed detected-object crops, which improves queries for small objects at extra indexing cost.

VSS_EMBEDDING_MODEL

CLIP/clip-vit-b-32

Embedding model for both indexing and queries; changing it invalidates the existing index (make clean-vss-index) and the MIN_PEAK_SCORE calibration.

Playback#

Setting

Default

Effect

VSS_PREVIEW_ENABLED / VSS_PLAYBACK_DEFAULT

true / sd

Serve a cached low-bitrate preview (sd) or the original clip (hd) first.

VSS_PREVIEW_HEIGHT / VSS_PREVIEW_MAX_KBPS

360 / 800

Preview resolution and bitrate for slow links.

VSS_PREVIEW_CACHE_MB / VSS_PREVIEW_PREWARM

1024 / 3

Preview cache size, and how many top results are transcoded as soon as a search returns.

Troubleshooting#

A query that returns the full VSS_MAX_RESULTS every time, one stream dominating the results, and footage that never becomes searchable are covered in Troubleshooting — VSS Live Search. If a matching query returns nothing, VSS_SEARCH_MIN_PEAK_SCORE is too high or the footage is not indexed yet (allow VSS_LIVE_SYNC_INTERVAL_SECONDS plus a few frame intervals); if search is slow, lower VSS_MAX_RESULTS, raise VSS_FRAME_INTERVAL or move embedding to the GPU.

On this page
  • How many candidates VSS keeps
  • Which results are shown
    • Queries that name an object
  • How footage is indexed
  • Playback
  • Troubleshooting
Show Source
Enable cookies to use AI chat
Chat is locked. Click the blue chat button, then enable Functional cookies to unlock it.