.. SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 .. .. Licensed under the Apache License, Version 2.0 (the "License"); .. you may not use this file except in compliance with the License. .. You may obtain a copy of the License at .. .. http://www.apache.org/licenses/LICENSE-2.0 .. .. Unless required by applicable law or agreed to in writing, software .. distributed under the License is distributed on an "AS IS" BASIS, .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. .. See the License for the specific language governing permissions and .. limitations under the License. Search URLs =========== Wheel encodes the full search state in the URL hash. Copying the browser URL captures every active search mode, filter, and parameter, which makes it possible to bookmark a slice, share it with a colleague, or paste it into a tracker as a reproducible reference. The same encoding is also useful when constructing a link to Wheel programmatically, for example from a notebook, a script, or the :doc:`agent`. This page documents the URL structure and lists the parameters that correspond to each search mode in :doc:`search/index`. Every parameter described here can also be set through the UI controls; the URL is just the serialised form of the same configuration. URL Structure ------------- A Wheel search URL has the form:: http://sil-wheel.nvidia.com:8000/#&page=0&=&=... The fragment starts with ``#&`` (the leading ``&`` is intentional and is part of how Wheel parses the hash) and is followed by ``key=value`` pairs joined by ``&``. ``page=0`` selects the first page of results and is usually included when sharing a URL. Encoding rules: * Values are URL-encoded. Spaces are encoded as ``%20`` (not ``+``), and symbols such as ``>`` or ``&`` inside a value are percent-encoded. * Multi-value filters are joined with the literal token ``||`` (encoded as ``%7C%7C``). The exceptions are ``cluster_ids`` and ``wm_angle_range``, which use a single comma. * Boolean values are serialised as the strings ``true`` and ``false``. * Omitted parameters fall back to their defaults. ``project_source`` defaults to ``Alpamayo`` and is the only field that has a meaningful implicit default; everything else is simply unset when absent. Common Parameters ----------------- These parameters apply across all search modes and define which project, which datasets, and how results are ordered. .. list-table:: :header-rows: 1 :widths: 25 50 25 * - Parameter - Description - Notes * - ``page`` - Result page index, starting at 0. - Integer. * - ``project_source`` - One or more project names whose annotations and labels are loaded. - ``||`` separated. Defaults to ``Alpamayo``. * - ``data_source`` - One or more datasets to restrict the search to. Examples currently documented include ``MADS``, ``MADS-1M``, ``AV V1 train``, ``AV V1 validation``, ``AV V2 train``, ``AV V2 validation``, ``Nexar``, ``ncore-lidar-model-static-full``, and ``vipe-dynpose100kpp``. The full list is deployment-specific and is shown in the **Data Source** dropdown of the search panel. - ``||`` separated. See :doc:`search/metadata_search`. * - ``data_source_mode`` - Combination rule when multiple data sources are selected: ``any`` (clip belongs to at least one) or ``all`` (clip belongs to every listed source). - Defaults to ``any``. * - ``rank_mode`` - Ordering strategy when multiple ranked search modes are active. ``priority`` (default) uses the fixed priority order described in :doc:`search/index`. ``rrf`` merges the active ranked modes with reciprocal rank fusion, giving each mode comparable influence on the final order. - Defaults to ``priority``. Caption Search -------------- Parameters that drive :doc:`search/caption_search` and :doc:`search/caption_embed_search`. .. list-table:: :header-rows: 1 :widths: 30 70 * - Parameter - Description * - ``search`` - Caption keyword query. Supports quoted phrases and the boolean operators ``AND``, ``OR``, ``NOT``, as described in :doc:`search/caption_search`. * - ``caption_extra_queries`` - ``||``-separated list of rewritten variants generated by the **Rewrite** action. Each variant is OR-ed with the original ``search`` query. * - ``query_rewrite`` - ``true`` enables LLM-driven query rewriting at search time. * - ``caption_embed_search`` - Free-form text used as the query for caption embedding search (Qwen3 embeddings). * - ``caption_embed_extra_queries`` - ``||``-separated list of additional caption embedding queries merged into the same ranked retrieval. Semantic and Visual Search -------------------------- Parameters that drive :doc:`search/semantic_search` and :doc:`search/visual_search`. .. list-table:: :header-rows: 1 :widths: 30 70 * - Parameter - Description * - ``semantic_search_text`` - Text query for semantic text-to-video retrieval (CosmosEmbed1). * - ``semantic_search_clipid`` - Reference clip ID for semantic video-to-video retrieval. * - ``semantic_extra_queries`` - ``||``-separated list of additional semantic queries merged with ``semantic_search_text``. * - ``visual_search_text`` - Text query for frame-level visual search (CLIP). * - ``visual_search_image_id`` - Image ID used as the visual query for image-conditioned search. * - ``visual_extra_queries`` - ``||``-separated list of additional visual queries merged with ``visual_search_text``. Trajectory Search ----------------- Parameters that drive :doc:`search/trajectory_search`. Both shape search and pattern search require ego trajectory data, so ``with_ego_data=true`` is implied. .. list-table:: :header-rows: 1 :widths: 35 65 * - Parameter - Description * - ``trajectory_pattern`` - Named pattern (e.g. ``hard_braking``, ``high_curvature``, ``stop_go``) or a custom motion expression over the variables documented in :doc:`search/trajectory_search`. * - ``trajectory_shape_clipid`` - Reference clip ID whose ego path is used as the shape target. * - ``trajectory_shape_start_t`` - Start time, in seconds, of the sub-segment of the reference clip used for shape comparison. * - ``trajectory_shape_end_t`` - End time, in seconds, of the sub-segment of the reference clip. * - ``search_speed`` - Speed-based pattern shortcut. * - ``with_ego_data`` - ``true`` restricts results to clips with ego trajectory data attached. Perception-based Search ----------------------- Parameters that drive :doc:`search/perception_search`. Note that the URL parameter names use the ``wm_`` (world model) prefix. .. list-table:: :header-rows: 1 :widths: 30 70 * - Parameter - Description * - ``wm_class_name`` - Object class to filter on, from ``VEHICLE_CAR``, ``VEHICLE_TRUCK``, ``VEHICLE_BUS``, ``BIKE_WITH_RIDER``, ``BIKE_TRICYCLE``, ``PEDESTRIAN_UNKNOWN``. * - ``wm_min_count`` / ``wm_max_count`` - Lower and upper bounds on the total detection count of the selected class across the clip. * - ``wm_max_dist`` - Maximum distance, in metres, between the object and the ego vehicle for the range filter. * - ``wm_min_time`` - Minimum continuous duration, in seconds, that the object must remain in the configured spatial window. * - ``wm_angle_range`` - Comma-separated list of sectors from ``FRONT``, ``FRONT_RIGHT``, ``BACK_RIGHT``, ``BACK``, ``BACK_LEFT``, ``FRONT_LEFT``. Note the comma delimiter, which differs from the ``||`` used elsewhere. Classifier Search ----------------- Parameters that drive :doc:`search/classifier_search`. .. list-table:: :header-rows: 1 :widths: 30 70 * - Parameter - Description * - ``classifier_run_id`` - Identifier of the trained classifier run to apply. * - ``probability_expression`` - Expression on the classifier probability ``p``, for example ``p > 0.95``. Comparison and logical operators are supported. Cluster Search -------------- Parameters that drive :doc:`search/cluster_search`. .. list-table:: :header-rows: 1 :widths: 35 65 * - Parameter - Description * - ``cluster_run_id`` - Identifier of the clustering run to browse. * - ``cluster_ids`` - Comma-separated list of cluster indices to include. Note the comma delimiter, which differs from the ``||`` used elsewhere. * - ``cluster_distance_min`` / ``cluster_distance_max`` - Lower and upper bounds on centroid distance, used to focus on central or peripheral cluster members. * - ``cluster_zoom`` - ``1`` indicates that a single cluster is currently zoomed in the UMAP view. Included automatically when sharing a URL from a zoomed cluster so the recipient lands on the same view. Metadata and Annotation Filters ------------------------------- Parameters that drive :doc:`search/metadata_search`. .. list-table:: :header-rows: 1 :widths: 30 70 * - Parameter - Description * - ``filter`` - ``||``-separated list of annotation labels that clips must match. * - ``filter_mode`` - ``any`` (default) or ``all``. Combination rule for the values in ``filter``. * - ``labels_to_exclude`` - ``||``-separated list of annotation labels that clips must not carry. * - ``labels_to_exclude_mode`` - ``any`` (default) or ``all``. Combination rule for ``labels_to_exclude``. * - ``label_types`` - ``||``-separated list of label types to scope ``filter`` and ``labels_to_exclude`` to. * - ``without_ann`` - ``true`` restricts to clips with no annotations of the active project, useful for prioritising labelling work. * - ``search_clipid`` - Exact clip identifier. Surfaces a single clip by ID. * - ``search_country`` - Filter clips by the recorded country using official two-letter country codes only. Format: ISO 3166-1 alpha-2 (e.g., Switzerland = CH, USA = US, Germany = DE). * - ``left_hand_driving`` - ``true`` restricts to left-hand-drive recordings. * - ``numeric_filter`` - ``||``-separated list of numeric metric filters. Each filter has the form ``,,,``. Setting ``ordering`` to ``asc`` or ``desc`` makes the metric the active ranked mode. Display Toggles --------------- These parameters do not change which clips are returned, only how they are displayed in the result grid. .. list-table:: :header-rows: 1 :widths: 25 75 * - Parameter - Description * - ``times`` - ``true`` shows time-range badges on each clip card when annotations are time-scoped. * - ``with_metrics`` - ``true`` overlays per-clip model evaluation metrics on each card. * - ``with_bev`` - ``true`` adds the bird's-eye-view visualisation to each card. * - ``n`` - Number of clips per result page. Defaults to ``6`` and is included in the URL only when changed from the default. Worked Examples --------------- The examples below show how a natural-language description of a slice maps to the corresponding URL. **Caption keyword search restricted to a dataset** "Find ambulance footage in MADS-1M." ``http://sil-wheel.nvidia.com:8000/#&page=0&search=ambulance&data_source=MADS-1M&project_source=Alpamayo`` **Caption keyword combined with semantic retrieval and query rewriting** "Show me clips mentioning ``officer`` while semantically related to a construction zone, with rewriting on, in AV V1." ``http://sil-wheel.nvidia.com:8000/#&page=0&search=officer&semantic_search_text=construction%20zone&semantic_extra_queries=road%20work%7C%7Cconstruction%20cones%7C%7Corange%20barrels&data_source=AV%20V1%20train%7C%7CAV%20V1%20validation&project_source=Alpamayo`` **Classifier filter with a probability threshold** "All clips that the ``Barrier gate`` classifier scores above 0.95." ``http://sil-wheel.nvidia.com:8000/#&page=0&classifier_run_id=&probability_expression=p%20%3E%200.95&project_source=Alpamayo`` Replace ```` with the id of a trained classifier run (set automatically when you select a classifier in the UI). Common Patterns --------------- Working with URLs directly is most useful for: * **Sharing and bookmarking**: paste the current URL into a tracker, a message, or a doc to give a colleague the exact slice you are looking at. * **Programmatic links**: build a URL from a notebook or script when presenting a slice for review, for example after running a custom query through ``WheelClient`` and wanting to surface the same results in the browser. * **Adjusting filters by hand**: tweaking a single parameter in the URL bar is sometimes faster than navigating the UI, especially when iterating on a long composed query. For most interactive use, configuring the search through the UI panels is the natural path; the URL is the serialisation, not the primary interface.