.. 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.

Trajectory Search
=================

**Search mode: retrieval by how the ego vehicle moved, either the shape of its
path or statistics over that motion.**

Trajectory search retrieves clips using ego-vehicle motion. It supports two
modes: **shape search**, which finds clips whose ego path is geometrically similar
to a reference clip, and **pattern search**, which filters clips by evaluating
expressions over motion statistics such as speed, acceleration, and curvature.
Shape search is a ranked mode; pattern search is filter-only. Both require ego
trajectory data.

**Reach for it when** the manoeuvre matters more than the scenery. Use shape
search when you have a reference clip with an interesting manoeuvre and want
geometrically similar paths. Matching is speed-invariant, so the same curve
driven slowly still qualifies. Use pattern search to filter by a named
behaviour such as hard braking, swerving, or a prolonged stop.

**Reach for something else when** what you care about is in the scene rather
than the ego motion, or when the dataset carries no ego trajectories, since
neither mode returns anything without them.

.. figure:: /_static/images/trajectory_search.png
   :alt: Trajectory shape search results, each clip card showing its shape score and a plotted X-Y ego path beneath the video

   Trajectory shape search: clips with similar geometric path to a
   reference clip.

Shape Search
------------

Finds clips whose ego path has a similar geometric shape to a reference
clip. Trajectories are normalised to their starting position, so the
comparison is purely about shape: the same curve driven at different speeds
will match. A time window can be specified to restrict the match to a
sub-segment, allowing search for a specific manoeuvre without requiring the
full path to match. Shape search is a ranked mode.

Pattern Search
--------------

Pattern search filters clips by evaluating expressions over per-clip motion
statistics. For each clip, the following scalar arrays are precomputed from
the ego trajectory, with one value per timestep sampled at 10 Hz:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Variable
     - Description
   * - ``speed``
     - Ego speed in m/s
   * - ``speed_kph``
     - Ego speed in km/h
   * - ``acceleration``
     - Longitudinal acceleration in m/s² (negative = braking)
   * - ``jerk``
     - Rate of change of acceleration in m/s³
   * - ``curvature``
     - Path curvature at each timestep (higher = sharper turn)

Expressions can reference any of these arrays using standard mathematical
and logical operations. This is equivalent to writing a Python expression
in an interactive notebook: the expression is evaluated against each clip's
arrays and the clip is included in results if the expression evaluates to
``True``. Aggregate functions such as ``sum()``, ``mean()``, ``max()``,
``min()``, and ``any()`` are available, as are element-wise comparisons.

Examples:

.. code-block:: text

   mean(speed) > 20
   max(curvature) > 0.2 and mean(speed) > 10
   sum(acceleration < -3.0) > 10
   any(speed < 0.5) and any(speed_kph > 50)

Predefined Patterns
~~~~~~~~~~~~~~~~~~~

The following named patterns are available as shortcuts in the UI.
Selecting one is equivalent to entering the corresponding expression:

.. list-table::
   :header-rows: 1
   :widths: 25 35 40

   * - Pattern name
     - Expression
     - Description
   * - ``high_curvature``
     - ``sum(curvature > 0.15) > 10``
     - Sharp turning sustained over at least 1 second
   * - ``stop_go``
     - ``any(speed < 0.5) and any(speed > 3.0) and min(where(speed > 3.0)[0]) > min(where(speed < 0.5)[0])``
     - Speed transitions from near-stop to moving (stop precedes go)
   * - ``hard_braking``
     - ``sum(acceleration < -3.0) > 10``
     - Strong deceleration sustained over at least 1 second
   * - ``prolonged_stop``
     - ``sum(speed < 0.5) > 150``
     - Stationary for more than 15 seconds
   * - ``idle_to_cruise``
     - ``any(speed < 0.5) and any(speed > 10.0) and min(where(speed > 10.0)[0]) > min(where(speed < 0.5)[0])``
     - Clip starts stationary and reaches open-road speed (idle precedes cruise)
   * - ``high_speed_swerve``
     - ``sum(curvature > 0.2) > 10 and sum(speed_kph > 50) > 10``
     - Sharp lateral movement at highway speed
   * - ``moving_ego``
     - ``sum(speed_kph > 5) > 10``
     - Ego vehicle is in motion for at least 1 second

Custom expressions can be entered directly in the **Custom motion filter**
field and support the same syntax and variables as the predefined patterns.