traj-dist-rs 1.0.0-rc.5

# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401

import builtins
import typing

import numpy
import numpy.typing

@typing.final
class DpResult:
    r"""
    Python wrapper for the Rust DpResult struct

    This class wraps the Rust DpResult and provides Python-friendly access
    to the distance and optional matrix.
    """

    @property
    def distance(self) -> builtins.float:
        r"""
        Get the distance value
        """

    @property
    def matrix(self) -> typing.Optional[numpy.typing.NDArray[numpy.float64]]:
        r"""
        Get the matrix (or None if not computed)

        Returns a numpy array if use_full_matrix was True, otherwise None
        """

    def __repr__(self) -> builtins.str:
        r"""
        String representation
        """

    def __str__(self) -> builtins.str:
        r"""
        String representation
        """

    def __reduce__(self) -> tuple[typing.Any, typing.Any, typing.Any]:
        r"""
        Pickle serialization support using __reduce__

        Uses bincode to serialize the entire DpResult::inner as bytes for better performance.
        Returns a tuple (callable, args) that pickle can use to reconstruct the object.
        """

@typing.final
class Metric:
    r"""
    A metric configuration object for distance calculations.

    This class encapsulates the distance algorithm, its parameters, and the
    underlying point-to-point distance type (e.g., Euclidean or Spherical).

    Do not instantiate this class directly. Use the provided static factory
    methods instead (e.g., `Metric.sspd()`, `Metric.lcss(...)`).
    """

    def __new__(cls) -> Metric: ...
    @staticmethod
    def sspd(type_d: builtins.str = "euclidean") -> Metric:
        r"""
        Symmetric Segment-Path Distance.
        """

    @staticmethod
    def dtw(type_d: builtins.str = "euclidean") -> Metric:
        r"""
        Dynamic Time Warping.
        """

    @staticmethod
    def hausdorff(type_d: builtins.str = "euclidean") -> Metric:
        r"""
        Hausdorff Distance.
        """

    @staticmethod
    def discret_frechet(type_d: builtins.str = "euclidean") -> Metric:
        r"""
        Discrete Frechet Distance.
        """

    @staticmethod
    def lcss(eps: builtins.float, type_d: builtins.str = "euclidean") -> Metric:
        r"""
        Longest Common Subsequence.
        """

    @staticmethod
    def edr(eps: builtins.float, type_d: builtins.str = "euclidean") -> Metric:
        r"""
        Edit Distance on Real sequence.
        """

    @staticmethod
    def erp(
        g: typing.Sequence[builtins.float], type_d: builtins.str = "euclidean"
    ) -> Metric:
        r"""
        Edit distance with Real Penalty.
        """

    @staticmethod
    def edwp() -> Metric:
        r"""
        Edit Distance with Projections.

        EDwP is designed for trajectories with inconsistent sampling rates.
        Note: EDwP only supports Euclidean distance (not spherical distance).
        """

    @staticmethod
    def frechet() -> Metric:
        r"""
        Frechet Distance (continuous).

        Unlike Discrete Frechet, this considers all continuous points along
        the curve segments, providing an exact solution.
        Note: Frechet only supports Euclidean distance (not spherical distance).
        """

def __dp_result_from_pickle(data: bytes) -> DpResult:
    r"""
    Helper function to create DpResult from pickle data

    Deserializes the DpResult from bincode-encoded bytes.
    """

def cdist(
    trajectories_a: typing.Sequence[typing.List[typing.List[float]] | numpy.ndarray],
    trajectories_b: typing.Sequence[typing.List[typing.List[float]] | numpy.ndarray],
    metric: Metric,
    parallel: builtins.bool = True,
    show_progress: builtins.bool = False,
) -> numpy.typing.NDArray[numpy.float64]:
    r"""
    Compute distances between two trajectory collections

    This function computes the distances between all pairs of trajectories
    from two collections. The result is a full distance matrix (2D array)
    with shape (n_a, n_b).

    When to Use `cdist` vs `pdist`

    - Use `cdist` when:
    1. Computing distances between two different trajectory collections
    2. Your distance metric is **asymmetric** (distance(A, B) != distance(B, A))
    3. You need the full distance matrix for both directions

    - Use `pdist` when:
    1. Computing distances within a single trajectory collection
    2. Your distance metric is **symmetric** (distance(A, B) == distance(B, A))
    3. You want to save memory by using the compressed distance matrix format

    # Arguments
    * `trajectories_a` - First collection of trajectories, where each trajectory is a
                         2D numpy array or list of [x, y] pairs
    * `trajectories_b` - Second collection of trajectories
    * `metric` - Metric configuration object (e.g., `Metric.sspd()`, `Metric.lcss(eps=5.0)`)
    * `parallel` - Whether to use parallel processing (default: True)
    * `show_progress` - Whether to display a progress bar during computation (default: False).
                        The progress bar is rendered to stderr so it does not interfere with stdout.

    # Returns
    * `distances` - 2D numpy array with shape (len(trajectories_a), len(trajectories_b))

    # Output Format

    For `n_a` trajectories in the first collection and `n_b` trajectories in the second,
    the result is a 2D array with shape `(n_a, n_b)`. The distance at index `[i, j]`
    represents the distance from `trajectories_a[i]` to `trajectories_b[j]`.

    # Examples
    ```python
    import traj_dist_rs
    import numpy as np

    # Create metric configuration
    metric = traj_dist_rs.Metric.sspd(type_d="euclidean")

    # Using numpy arrays (zero-copy)
    trajectories_a = [
        np.array([[0.0, 0.0], [1.0, 1.0]]),
        np.array([[0.0, 1.0], [1.0, 0.0]])
    ]
    trajectories_b = [
        np.array([[0.5, 0.5], [1.5, 1.5]]),
        np.array([[0.5, 1.5], [1.5, 0.5]])
    ]
    distances = traj_dist_rs.cdist(trajectories_a, trajectories_b, metric=metric)
    print(distances.shape)  # (2, 2)

    # Using lists (will be copied)
    trajectories_a = [
        [[0.0, 0.0], [1.0, 1.0]],
        [[0.0, 1.0], [1.0, 0.0]]
    ]
    trajectories_b = [
        [[0.5, 0.5], [1.5, 1.5]],
        [[0.5, 1.5], [1.5, 0.5]]
    ]
    distances = traj_dist_rs.cdist(trajectories_a, trajectories_b, metric=metric)

    # Using ERP with gap point parameter
    metric_erp = traj_dist_rs.Metric.erp(g=[0.0, 1.0], type_d="euclidean")
    distances = traj_dist_rs.cdist(trajectories_a, trajectories_b, metric=metric_erp)

    # With progress bar
    distances = traj_dist_rs.cdist(trajectories_a, trajectories_b, metric=metric, show_progress=True)
    ```
    """

def discret_frechet(
    t1: typing.List[typing.List[float]] | numpy.ndarray,
    t2: typing.List[typing.List[float]] | numpy.ndarray,
    dist_type: builtins.str,
    use_full_matrix: builtins.bool = False,
) -> DpResult:
    r"""
    Compute the Discret Frechet distance between two trajectories

    The discret Frechet distance is a measure of similarity between two curves
    that takes into account the location and ordering of the points along the curves.

    # Arguments
    * `t1` - First trajectory (list of [longitude, latitude] pairs)
    * `t2` - Second trajectory (list of [longitude, latitude] pairs)
    * `dist_type` - Distance type: "euclidean" (only Euclidean is supported for Discret Frechet)
    * `use_full_matrix` - If true, compute and return the full DP matrix;
                           if false (default), return None for the matrix to save space

    # Returns
    * A `DpResult` object with two properties:
      - `distance`: Discret Frechet distance as f64
      - `matrix`: numpy array of shape (n0+1, n1+1) if use_full_matrix=True, else None

    # Examples
    ```python
    import traj_dist_rs

    t1 = [[0.0, 0.0], [1.0, 1.0]]
    t2 = [[0.0, 1.0], [1.0, 0.0]]
    result = traj_dist_rs.discret_frechet(t1, t2, "euclidean")
    print(result.distance)  # Distance value
    print(result.matrix)  # None

    result = traj_dist_rs.discret_frechet(t1, t2, "euclidean", True)
    print(result.matrix)  # numpy array
    ```
    """

def discret_frechet_with_matrix(
    distance_matrix: numpy.ndarray, use_full_matrix: builtins.bool = False
) -> DpResult:
    r"""
    Compute the Discret Frechet distance using a precomputed distance matrix

    This function allows you to use a precomputed distance matrix instead of computing
    distances between trajectory points on the fly.

    # Arguments
    * `distance_matrix` - A 2D numpy array where `matrix[i][j]` is the distance between
                          point i of trajectory 1 and point j of trajectory 2
    * `use_full_matrix` - If true, compute and return the full DP matrix;
                           if false (default), return None for the matrix to save space

    # Returns
    * A `DpResult` object with two properties:
      - `distance`: Discret Frechet distance as f64
      - `matrix`: numpy array of shape (n0+1, n1+1) if use_full_matrix=True, else None

    # Examples
    ```python
    import traj_dist_rs
    import numpy as np

    dist_matrix = np.array([
        [1.0, 1.0],
        [1.0, 1.0],
    ])

    # Without matrix
    result = traj_dist_rs.discret_frechet_with_matrix(dist_matrix)
    print(result.distance)  # Distance value
    print(result.matrix)  # None

    # With matrix
    result = traj_dist_rs.discret_frechet_with_matrix(dist_matrix, use_full_matrix=True)
    print(result.matrix)  # numpy array
    ```
    """

def dtw(
    t1: typing.List[typing.List[float]] | numpy.ndarray,
    t2: typing.List[typing.List[float]] | numpy.ndarray,
    dist_type: builtins.str,
    use_full_matrix: builtins.bool = False,
) -> DpResult:
    r"""
    Compute the DTW (Dynamic Time Warping) distance between two trajectories

    # Arguments
    * `t1` - First trajectory (list of [longitude, latitude] pairs)
    * `t2` - Second trajectory (list of [longitude, latitude] pairs)
    * `dist_type` - Distance type: "euclidean" or "spherical"
    * `use_full_matrix` - If true, compute and return the full DP matrix;
                           if false (default), return None for the matrix to save space

    # Returns
    * A `DpResult` object with two properties:
      - `distance`: DTW distance as f64
      - `matrix`: numpy array of shape (n0+1, n1+1) if use_full_matrix=True, else None

    # Examples
    ```python
    import traj_dist_rs

    t1 = [[0.0, 0.0], [1.0, 1.0]]
    t2 = [[0.0, 1.0], [1.0, 0.0]]

    # Without matrix
    result = traj_dist_rs.dtw(t1, t2, "euclidean")
    print(result.distance)  # Distance value
    print(result.matrix)  # None

    # With matrix
    result = traj_dist_rs.dtw(t1, t2, "euclidean", True)
    print(result.distance)  # Distance value
    print(result.matrix)  # numpy array
    ```
    """

def dtw_with_matrix(
    distance_matrix: numpy.ndarray, use_full_matrix: builtins.bool = False
) -> DpResult:
    r"""
    Compute the DTW (Dynamic Time Warping) distance using a precomputed distance matrix

    This function allows you to use a precomputed distance matrix instead of computing
    distances between trajectory points on the fly. This can be useful when:
    - You need to compute multiple distance measures on the same trajectory pair
    - You want to reuse the same distance matrix across different computations
    - You have custom distance calculations that don't fit the standard distance types

    # Arguments
    * `distance_matrix` - A 2D numpy array where `matrix[i][j]` is the distance between
                          point i of trajectory 1 and point j of trajectory 2
    * `use_full_matrix` - If true, compute and return the full DP matrix;
                           if false (default), return None for the matrix to save space

    # Returns
    * A `DpResult` object with two properties:
      - `distance`: DTW distance as f64
      - `matrix`: numpy array of shape (n0+1, n1+1) if use_full_matrix=True, else None

    # Examples
    ```python
    import traj_dist_rs
    import numpy as np

    t1 = [[0.0, 0.0], [1.0, 1.0]]
    t2 = [[0.0, 1.0], [1.0, 0.0]]

    # Precompute distance matrix
    dist_matrix = np.array([
        [1.0, 1.0],  # distance from t1[0] to t2[0], t2[1]
        [1.0, 1.0],  # distance from t1[1] to t2[0], t2[1]
    ])

    # Without matrix
    result = traj_dist_rs.dtw_with_matrix(dist_matrix)
    print(result.distance)  # Distance value
    print(result.matrix)  # None

    # With matrix
    result = traj_dist_rs.dtw_with_matrix(dist_matrix, True)
    print(result.distance)  # Distance value
    print(result.matrix)  # numpy array
    ```
    """

def edr(
    t1: typing.List[typing.List[float]] | numpy.ndarray,
    t2: typing.List[typing.List[float]] | numpy.ndarray,
    dist_type: builtins.str,
    eps: builtins.float,
    use_full_matrix: builtins.bool = False,
) -> DpResult:
    r"""
    Compute the EDR (Edit Distance on Real sequence) distance between two trajectories

    EDR is a distance measure for trajectories that allows for gaps in the matching.
    It uses a threshold `eps` to determine if two points match.
    The distance is normalized by the maximum length of the two trajectories.

    # Arguments
    * `t1` - First trajectory (list of [longitude, latitude] pairs)
    * `t2` - Second trajectory (list of [longitude, latitude] pairs)
    * `dist_type` - Distance type: "euclidean" or "spherical"
    * `eps` - Epsilon threshold for matching points
    * `use_full_matrix` - If true, compute and return the full DP matrix;
                           if false (default), return None for the matrix to save space

    # Returns
    * A `DpResult` object with two properties:
      - `distance`: EDR distance as f64 (normalized to [0, 1])
      - `matrix`: numpy array of shape (n0+1, n1+1) if use_full_matrix=True, else None

    # Examples
    ```python
    import traj_dist_rs

    t1 = [[0.0, 0.0], [1.0, 1.0]]
    t2 = [[0.0, 1.0], [1.0, 0.0]]
    result = traj_dist_rs.edr(t1, t2, "euclidean", eps=0.5)
    print(result.distance)  # Distance value
    print(result.matrix)  # None

    result = traj_dist_rs.edr(t1, t2, "euclidean", eps=0.5, use_full_matrix=True)
    print(result.matrix)  # numpy array
    ```
    """

def edr_with_matrix(
    distance_matrix: numpy.ndarray,
    eps: builtins.float,
    use_full_matrix: builtins.bool = False,
) -> DpResult:
    r"""
    Compute the EDR (Edit Distance on Real sequence) distance using a precomputed distance matrix

    This function allows you to use a precomputed distance matrix instead of computing
    distances between trajectory points on the fly.

    # Arguments
    * `distance_matrix` - A 2D numpy array where `matrix[i][j]` is the distance between
                          point i of trajectory 1 and point j of trajectory 2
    * `eps` - Epsilon threshold for matching points
    * `use_full_matrix` - If true, compute and return the full DP matrix;
                           if false (default), return None for the matrix to save space

    # Returns
    * A `DpResult` object with two properties:
      - `distance`: EDR distance as f64 (normalized to [0, 1])
      - `matrix`: numpy array of shape (n0+1, n1+1) if use_full_matrix=True, else None

    # Examples
    ```python
    import traj_dist_rs
    import numpy as np

    dist_matrix = np.array([
        [1.0, 1.0],
        [1.0, 1.0],
    ])

    # Without matrix
    result = traj_dist_rs.edr_with_matrix(dist_matrix, eps=0.5)
    print(result.distance)  # Distance value
    print(result.matrix)  # None

    # With matrix
    result = traj_dist_rs.edr_with_matrix(dist_matrix, eps=0.5, use_full_matrix=True)
    print(result.matrix)  # numpy array
    ```
    """

def edwp(
    t1: typing.List[typing.List[float]] | numpy.ndarray,
    t2: typing.List[typing.List[float]] | numpy.ndarray,
    use_full_matrix: builtins.bool = False,
) -> DpResult:
    r"""
    Compute the EDwP (Edit Distance with Projections) distance between two trajectories

    EDwP is designed for trajectories with inconsistent sampling rates. It uses
    point-to-segment projections to handle different sampling densities.

    # Arguments
    * `t1` - First trajectory (list of [x, y] pairs)
    * `t2` - Second trajectory (list of [x, y] pairs)
    * `use_full_matrix` - If true, compute and return the full DP matrix;
                           if false (default), return None for the matrix to save space

    # Returns
    * A `DpResult` object with two properties:
      - `distance`: EDwP distance as f64
      - `matrix`: numpy array of shape (n0, n1) if use_full_matrix=True, else None

    # Notes
    - EDwP only supports Euclidean distance (not spherical distance)
    - Passing "spherical" as distance type will result in an error

    # Examples
    ```python
    import traj_dist_rs

    t1 = [[0.0, 0.0], [1.0, 1.0], [2.0, 2.0]]
    t2 = [[0.1, 0.1], [1.1, 1.1], [2.1, 2.1]]

    # Without matrix
    result = traj_dist_rs.edwp(t1, t2, False)
    print(result.distance)  # Distance value
    print(result.matrix)  # None

    # With matrix
    result = traj_dist_rs.edwp(t1, t2, True)
    print(result.distance)  # Distance value
    print(result.matrix)  # numpy array
    ```
    """

def erp_compat_traj_dist(
    t1: typing.List[typing.List[float]] | numpy.ndarray,
    t2: typing.List[typing.List[float]] | numpy.ndarray,
    dist_type: builtins.str,
    g: typing.Optional[typing.List[float]],
    use_full_matrix: builtins.bool = False,
) -> DpResult:
    r"""
    Compute the ERP (Edit distance with Real Penalty) distance between two trajectories

    This is the **traj-dist compatible** implementation that matches the (buggy) implementation
    in traj-dist. This version should be used when compatibility with traj-dist is required.

    ERP is a distance measure for trajectories that uses a gap point `g` as a penalty
    for insertions and deletions. The distance is computed using dynamic programming.

    **Note**: This implementation has a bug in the DP matrix initialization where it uses
    the total sum of distances to g instead of cumulative sums. This matches the bug in
    traj-dist's Python implementation.

    # Arguments
    * `t1` - First trajectory (list of [longitude, latitude] pairs)
    * `t2` - Second trajectory (list of [longitude, latitude] pairs)
    * `dist_type` - Distance type: "euclidean" or "spherical"
    * `g` - Gap point for penalty (list of [longitude, latitude] or None for centroid)
    * `use_full_matrix` - If true, compute and return the full DP matrix;
                           if false (default), return None for the matrix to save space

    # Returns
    * A `DpResult` object with two properties:
      - `distance`: ERP distance as f64
      - `matrix`: numpy array of shape (n0+1, n1+1) if use_full_matrix=True, else None

    # Examples
    ```python
    import traj_dist_rs

    t1 = [[0.0, 0.0], [1.0, 1.0]]
    t2 = [[0.0, 1.0], [1.0, 0.0]]
    result = traj_dist_rs.erp_compat_traj_dist(t1, t2, "euclidean", g=[0.0, 0.0])
    print(result.distance)  # Distance value
    print(result.matrix)  # None

    result = traj_dist_rs.erp_compat_traj_dist(t1, t2, "euclidean", g=[0.0, 0.0], use_full_matrix=True)
    print(result.matrix)  # numpy array
    ```
    """

def erp_compat_traj_dist_with_matrix(
    distance_matrix: numpy.ndarray,
    seq0_gap_dists: numpy.ndarray,
    seq1_gap_dists: numpy.ndarray,
    use_full_matrix: builtins.bool = False,
) -> DpResult:
    r"""
    Compute the ERP (Edit distance with Real Penalty) distance using a precomputed distance matrix

    This is the **traj-dist compatible** implementation that matches the (buggy) implementation
    in traj-dist. This version should be used when compatibility with traj-dist is required.

    This function allows you to use a precomputed distance matrix and extra distance arrays
    instead of computing distances on the fly.

    # Arguments
    * `distance_matrix` - A 2D numpy array where `matrix[i][j]` is the distance between
                          point i of trajectory 1 and point j of trajectory 2
    * `seq0_gap_dists` - A 1D numpy array where `seq0_gap_dists[i]` is the distance between
                         point i of trajectory 1 and the gap point g
    * `seq1_gap_dists` - A 1D numpy array where `seq1_gap_dists[j]` is the distance between
                         point j of trajectory 2 and the gap point g
    * `use_full_matrix` - If true, compute and return the full DP matrix;
                           if false (default), return None for the matrix to save space

    # Returns
    * A `DpResult` object with two properties:
      - `distance`: ERP distance as f64
      - `matrix`: numpy array of shape (n0+1, n1+1) if use_full_matrix=True, else None

    # Examples
    ```python
    import traj_dist_rs
    import numpy as np

    dist_matrix = np.array([
        [1.0, 1.0],
        [1.0, 1.0],
    ])
    seq0_gap_dists = np.array([1.0, 1.0])
    seq1_gap_dists = np.array([1.0, 1.0])

    # Without matrix
    result = traj_dist_rs.erp_compat_traj_dist_with_matrix(dist_matrix, seq0_gap_dists, seq1_gap_dists)
    print(result.distance)  # Distance value
    print(result.matrix)  # None

    # With matrix
    result = traj_dist_rs.erp_compat_traj_dist_with_matrix(dist_matrix, seq0_gap_dists, seq1_gap_dists, use_full_matrix=True)
    print(result.matrix)  # numpy array
    ```
    """

def erp_standard(
    t1: typing.List[typing.List[float]] | numpy.ndarray,
    t2: typing.List[typing.List[float]] | numpy.ndarray,
    dist_type: builtins.str,
    g: typing.Optional[typing.List[float]],
    use_full_matrix: builtins.bool = False,
) -> DpResult:
    r"""
    Compute the ERP (Edit distance with Real Penalty) distance between two trajectories

    This is the **standard** ERP implementation with correct cumulative initialization.
    This version should be used for new applications where correctness is more important
    than compatibility with traj-dist.

    ERP is a distance measure for trajectories that uses a gap point `g` as a penalty
    for insertions and deletions. The distance is computed using dynamic programming.

    **Note**: This implementation correctly accumulates distances by index in the DP matrix
    initialization, unlike the buggy implementation in traj-dist.

    # Arguments
    * `t1` - First trajectory (list of [longitude, latitude] pairs)
    * `t2` - Second trajectory (list of [longitude, latitude] pairs)
    * `dist_type` - Distance type: "euclidean" or "spherical"
    * `g` - Gap point for penalty (list of [longitude, latitude] or None for centroid)
    * `use_full_matrix` - If true, compute and return the full DP matrix;
                           if false (default), return None for the matrix to save space

    # Returns
    * A `DpResult` object with two properties:
      - `distance`: ERP distance as f64
      - `matrix`: numpy array of shape (n0+1, n1+1) if use_full_matrix=True, else None

    # Examples
    ```python
    import traj_dist_rs

    t1 = [[0.0, 0.0], [1.0, 1.0]]
    t2 = [[0.0, 1.0], [1.0, 0.0]]
    result = traj_dist_rs.erp_standard(t1, t2, "euclidean", g=[0.0, 0.0])
    print(result.distance)  # Distance value
    print(result.matrix)  # None

    result = traj_dist_rs.erp_standard(t1, t2, "euclidean", g=[0.0, 0.0], use_full_matrix=True)
    print(result.matrix)  # numpy array
    ```
    """

def erp_standard_with_matrix(
    distance_matrix: numpy.ndarray,
    seq0_gap_dists: numpy.ndarray,
    seq1_gap_dists: numpy.ndarray,
    use_full_matrix: builtins.bool = False,
) -> DpResult:
    r"""
    Compute the ERP (Edit distance with Real Penalty) distance using a precomputed distance matrix

    This is the **standard** ERP implementation with correct cumulative initialization.
    This version should be used for new applications where correctness is more important
    than compatibility with traj-dist.

    This function allows you to use a precomputed distance matrix and extra distance arrays
    instead of computing distances on the fly.

    # Arguments
    * `distance_matrix` - A 2D numpy array where `matrix[i][j]` is the distance between
                          point i of trajectory 1 and point j of trajectory 2
    * `seq0_gap_dists` - A 1D numpy array where `seq0_gap_dists[i]` is the distance between
                         point i of trajectory 1 and the gap point g
    * `seq1_gap_dists` - A 1D numpy array where `seq1_gap_dists[j]` is the distance between
                         point j of trajectory 2 and the gap point g
    * `use_full_matrix` - If true, compute and return the full DP matrix;
                           if false (default), return None for the matrix to save space

    # Returns
    * A `DpResult` object with two properties:
      - `distance`: ERP distance as f64
      - `matrix`: numpy array of shape (n0+1, n1+1) if use_full_matrix=True, else None

    # Examples
    ```python
    import traj_dist_rs
    import numpy as np

    dist_matrix = np.array([
        [1.0, 1.0],
        [1.0, 1.0],
    ])
    seq0_gap_dists = np.array([1.0, 1.0])
    seq1_gap_dists = np.array([1.0, 1.0])

    # Without matrix
    result = traj_dist_rs.erp_standard_with_matrix(dist_matrix, seq0_gap_dists, seq1_gap_dists)
    print(result.distance)  # Distance value
    print(result.matrix)  # None

    # With matrix
    result = traj_dist_rs.erp_standard_with_matrix(dist_matrix, seq0_gap_dists, seq1_gap_dists, use_full_matrix=True)
    print(result.matrix)  # numpy array
    ```
    """

def frechet(
    t1: typing.List[typing.List[float]] | numpy.ndarray,
    t2: typing.List[typing.List[float]] | numpy.ndarray,
) -> builtins.float:
    r"""
    Compute the Frechet distance between two trajectories

    The Frechet distance considers all continuous points along the curve segments,
    providing an exact solution (unlike Discrete Frechet which only considers vertices).

    Intuitively, it represents the minimum leash length required for a person
    and their dog to walk along the two curves without backtracking.

    # Arguments
    * `t1` - First trajectory (list of [x, y] pairs or numpy array)
    * `t2` - Second trajectory (list of [x, y] pairs or numpy array)

    # Returns
    * The Frechet distance as a float

    # Notes
    - Frechet distance only supports Euclidean distance (not spherical distance)
    - Trajectories with fewer than 2 points return float('inf')
    - Result is always <= the Discrete Frechet distance for the same trajectories

    # Examples
    ```python
    import traj_dist_rs

    t1 = [[0.0, 0.0], [1.0, 1.0], [2.0, 0.0]]
    t2 = [[0.0, 0.5], [1.0, 1.5], [2.0, 0.5]]

    distance = traj_dist_rs.frechet(t1, t2)
    print(f"Frechet distance: {distance}")
    ```
    """

def hausdorff(
    t1: typing.List[typing.List[float]] | numpy.ndarray,
    t2: typing.List[typing.List[float]] | numpy.ndarray,
    dist_type: builtins.str,
) -> builtins.float:
    r"""
    Compute the Hausdorff distance between two trajectories

    # Arguments
    * `t1` - First trajectory (list of [longitude, latitude] pairs)
    * `t2` - Second trajectory (list of [longitude, latitude] pairs)
    * `dist_type` - Distance type: "euclidean" or "spherical"

    # Returns
    * Hausdorff distance as f64

    # Examples
    ```python
    import traj_dist_rs

    t1 = [[0.0, 0.0], [1.0, 1.0]]
    t2 = [[0.0, 1.0], [1.0, 0.0]]
    dist = traj_dist_rs.hausdorff(t1, t2, "euclidean")
    ```
    """

def lcss(
    t1: typing.List[typing.List[float]] | numpy.ndarray,
    t2: typing.List[typing.List[float]] | numpy.ndarray,
    dist_type: builtins.str,
    eps: builtins.float,
    use_full_matrix: builtins.bool = False,
) -> DpResult:
    r"""
    Compute the LCSS (Longest Common Subsequence) distance between two trajectories

    The LCSS distance is calculated as 1 - (length of longest common subsequence) / min(len(t0), len(t1))
    where two points are considered matching if their distance is less than eps.

    # Arguments
    * `t1` - First trajectory (list of [longitude, latitude] pairs)
    * `t2` - Second trajectory (list of [longitude, latitude] pairs)
    * `dist_type` - Distance type: "euclidean" or "spherical"
    * `eps` - Epsilon threshold for matching points
    * `use_full_matrix` - If true, compute and return the full DP matrix;
                           if false (default), return None for the matrix to save space

    # Returns
    * A `DpResult` object with two properties:
      - `distance`: LCSS distance as f64
      - `matrix`: numpy array of shape (n0+1, n1+1) if use_full_matrix=True, else None

    # Examples
    ```python
    import traj_dist_rs

    t1 = [[0.0, 0.0], [1.0, 1.0]]
    t2 = [[0.0, 1.0], [1.0, 0.0]]
    result = traj_dist_rs.lcss(t1, t2, "euclidean", eps=0.5)
    print(result.distance)  # Distance value
    print(result.matrix)  # None

    result = traj_dist_rs.lcss(t1, t2, "euclidean", eps=0.5, use_full_matrix=True)
    print(result.matrix)  # numpy array
    ```
    """

def lcss_with_matrix(
    distance_matrix: numpy.ndarray,
    eps: builtins.float,
    use_full_matrix: builtins.bool = False,
) -> DpResult:
    r"""
    Compute the LCSS (Longest Common Subsequence) distance using a precomputed distance matrix

    This function allows you to use a precomputed distance matrix instead of computing
    distances between trajectory points on the fly.

    # Arguments
    * `distance_matrix` - A 2D numpy array where `matrix[i][j]` is the distance between
                          point i of trajectory 1 and point j of trajectory 2
    * `eps` - Epsilon threshold for matching points
    * `use_full_matrix` - If true, compute and return the full DP matrix;
                           if false (default), return None for the matrix to save space

    # Returns
    * A `DpResult` object with two properties:
      - `distance`: LCSS distance as f64
      - `matrix`: numpy array of shape (n0+1, n1+1) if use_full_matrix=True, else None

    # Examples
    ```python
    import traj_dist_rs
    import numpy as np

    dist_matrix = np.array([
        [1.0, 1.0],
        [1.0, 1.0],
    ])

    # Without matrix
    result = traj_dist_rs.lcss_with_matrix(dist_matrix, eps=0.5)
    print(result.distance)  # Distance value
    print(result.matrix)  # None

    # With matrix
    result = traj_dist_rs.lcss_with_matrix(dist_matrix, eps=0.5, use_full_matrix=True)
    print(result.matrix)  # numpy array
    ```
    """

def pdist(
    trajectories: typing.Sequence[typing.List[typing.List[float]] | numpy.ndarray],
    metric: Metric,
    parallel: builtins.bool = True,
    show_progress: builtins.bool = False,
) -> numpy.typing.NDArray[numpy.float64]:
    r"""
    Compute pairwise distances between trajectories

    This function computes the distances between all unique pairs of trajectories
    in the input list. The result is a compressed distance matrix (1D array)
    containing distances for all pairs (i, j) where i < j.

    # Symmetry Assumption

    This function assumes that the distance metric is **symmetric**, i.e.,
    `distance(A, B) == distance(B, A)`. All standard distance algorithms
    in traj-dist-rs (SSPD, DTW, Hausdorff, LCSS, EDR, ERP, Discret Frechet)
    satisfy this property.

    **Important**: If your distance metric is **asymmetric**, use `cdist` instead
    to compute the full distance matrix. Using `pdist` with asymmetric distances
    will only compute half of the distances and may produce incorrect results.

    # Arguments
    * `trajectories` - List of trajectories, where each trajectory is a 2D numpy array
                       or list of [x, y] pairs
    * `metric` - Metric configuration object (e.g., `Metric.sspd()`, `Metric.lcss(eps=5.0)`)
    * `parallel` - Whether to use parallel processing (default: True)
    * `show_progress` - Whether to display a progress bar during computation (default: False).
                        The progress bar is rendered to stderr so it does not interfere with stdout.

    # Returns
    * `distances` - 1D numpy array containing distances for all unique pairs

    # Output Format

    For `n` trajectories, the result is a 1D array of length `n * (n - 1) / 2`.
    The distances are ordered as `d(0,1), d(0,2), ..., d(0,n-1), d(1,2), d(1,3), ..., d(n-2,n-1)`.

    # Examples
    ```python
    import traj_dist_rs
    import numpy as np

    # Create metric configuration
    metric = traj_dist_rs.Metric.sspd(type_d="euclidean")

    # Using numpy arrays (zero-copy)
    trajectories = [
        np.array([[0.0, 0.0], [1.0, 1.0]]),
        np.array([[0.0, 1.0], [1.0, 0.0]]),
        np.array([[0.5, 0.5], [1.5, 1.5]])
    ]
    distances = traj_dist_rs.pdist(trajectories, metric=metric)

    # Using lists (will be copied)
    trajectories = [
        [[0.0, 0.0], [1.0, 1.0]],
        [[0.0, 1.0], [1.0, 0.0]],
        [[0.5, 0.5], [1.5, 1.5]]
    ]
    distances = traj_dist_rs.pdist(trajectories, metric=metric)

    # Using LCSS with epsilon parameter
    metric_lcss = traj_dist_rs.Metric.lcss(eps=5.0, type_d="euclidean")
    distances = traj_dist_rs.pdist(trajectories, metric=metric_lcss)

    # With progress bar
    distances = traj_dist_rs.pdist(trajectories, metric=metric, show_progress=True)
    ```
    """

def sspd(
    t1: typing.List[typing.List[float]] | numpy.ndarray,
    t2: typing.List[typing.List[float]] | numpy.ndarray,
    dist_type: builtins.str,
) -> builtins.float:
    r"""
    Compute the SSPD distance between two trajectories

    # Arguments
    * `t1` - First trajectory (list of [longitude, latitude] pairs)
    * `t2` - Second trajectory (list of [longitude, latitude] pairs)
    * `dist_type` - Distance type: "euclidean" or "spherical"

    # Returns
    * SSPD distance as f64

    # Examples
    ```python
    import traj_dist_rs

    t1 = [[0.0, 0.0], [1.0, 1.0]]
    t2 = [[0.0, 1.0], [1.0, 0.0]]
    dist = traj_dist_rs.sspd(t1, t2, "euclidean")
    ```
    """