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 |
|---|---|---|
|
|
The most results the search popup lists. It is also VSS’s |
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 |
|---|---|---|
|
|
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. |
|
|
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 |
|---|---|
|
Drop crops labelled as another object; whole-frame hits stay. |
|
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). |
|
Rank by image-text similarity alone. |
How footage is indexed#
Setting |
Default |
Effect |
|---|---|---|
|
|
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. |
|
|
How long live footage and embeddings are kept ( |
|
|
Live streams indexed at once, one per UAV camera. Feeds beyond it show as |
|
|
Devices for frame embedding, object crops and query embedding; |
|
|
Also embed detected-object crops, which improves queries for small objects at extra indexing cost. |
|
|
Embedding model for both indexing and queries; changing it invalidates the existing index ( |
Playback#
Setting |
Default |
Effect |
|---|---|---|
|
|
Serve a cached low-bitrate preview ( |
|
|
Preview resolution and bitrate for slow links. |
|
|
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.