ATE Result

ate_result

AbsoluteTrajectoryDeviations dataclass

AbsoluteTrajectoryDeviations(
    pos_dev: ndarray,
    directed_pos_dev: ndarray,
    rot_dev: Rotations | None = None,
    rotations_used: bool = False,
)

Container holding absolute pose deviations between two trajectories.

The arrays stored in this dataclass represent per-epoch deviations after an optional temporal/spatial alignment of a reference (ground truth) and a test trajectory. They are later aggregated by ATEResult to derive metrics such as mean/median Absolute Trajectory Error (ATE), directional bias, and RMS statistics.

All deviations describe how far the evaluated (test) trajectory deviates from the reference, i.e. test minus reference: a positive x deviation means the test trajectory is further in x direction, a positive along-track deviation that it is ahead, a positive horizontal cross-track deviation that it is to the right and a positive vertical cross-track deviation that it is above.

Attributes:

• pos_dev (ndarray) –

  3D array of absolute position deviation vectors in meters. Shape is (N, 3) for N deviation vectors with x, y, z components. These deviations are directly depending on the definition of the coordinate frame of the trajectories.

• directed_pos_dev (ndarray) –

  3D array of directed position deviation vectors (e.g. along-track, horizontal/vertical cross-track) in meters. Shape is (N, 3). These deviations are independent of the global coordinate frame, as they are derived based on the along-track direction of the trajectory.

• rot_dev (Rotations | None) –

  Optional orientation deviations represented as a Rotations instance (radians), the rotation from the reference to the test orientation (test * reference^-1). None if rotational evaluation was not performed.

• rotations_used (bool) –

  Indicates whether trajectory rotation information was employed to derive the direction frame for directed_pos_dev. If False, directional decomposition has relied on positional differences only.

ATEResult

ATEResult(
    trajectory: Trajectory,
    abs_dev: AbsoluteTrajectoryDeviations,
    name: str = "",
)

This class represents a set of absolute trajectory deviations

Absolute trajectory deviations describe absolute pose deviations between two trajectories. The deviations are calculated by comparing pairs of positions and orientations in the test and reference trajectory.

Attributes:

• trajectory (Trajectory) –

  The trajectory the deviations are belonging to

• abs_dev (AbsoluteTrajectoryDeviations) –

  The absolute trajectory deviations

• name (str) –

  The name of the result

Source code in trajectopy\results\ate_result.py

def __init__(
    self,
    trajectory: Trajectory,
    abs_dev: AbsoluteTrajectoryDeviations,
    name: str = "",
) -> None:
    self.name = name or trajectory.name
    self.trajectory = trajectory
    self.abs_dev = abs_dev

correlation cached property

correlation: DeviationCorrelation

Temporal correlation of the deviations: autocorrelation, correlation time and number of independent deviations of each component (cached, see DeviationCorrelation).

is_spatially_sorted property

is_spatially_sorted: bool

True if the trajectory was sorted spatially, i.e. its path lengths do not follow the chronological order. Only then, ordering by path length differs from ordering by time.

index property

index: ndarray

Returns the variable that currently parametrizes the trajectory.

Depending on the sorting of the trajectory, this is either time or arc length.

Returns:

• ndarray –

  np.ndarray: Current independent variable array (time or path-length).

has_orientation property

has_orientation: bool

Returns True if orientation is available.

Returns:

• bool ( bool ) –

  True if rotation deviations are available, False otherwise.

pos_dev_x property

pos_dev_x: ndarray

Returns x deviations

pos_dev_y property

pos_dev_y: ndarray

Returns y deviations

pos_dev_z property

pos_dev_z: ndarray

Returns z deviations

pos_bias_x property

pos_bias_x: float

Returns x bias

pos_bias_y property

pos_bias_y: float

Returns y bias

pos_bias_z property

pos_bias_z: float

Returns z bias

pos_bias_cross_h property

pos_bias_cross_h: float

Returns horizontal cross track bias

pos_bias_cross_v property

pos_bias_cross_v: float

Returns vertical cross track bias

pos_bias_along property

pos_bias_along: float

Returns along track bias

rot_dev_x property

rot_dev_x: ndarray

Returns roll deviations

rot_dev_y property

rot_dev_y: ndarray

Returns pitch deviations

rot_dev_z property

rot_dev_z: ndarray

Returns yaw deviations

rot_bias_xyz cached property

rot_bias_xyz: ndarray

Returns roll, pitch and yaw bias

rot_bias_x property

rot_bias_x: ndarray

Returns roll bias

rot_bias_y property

rot_bias_y: ndarray

Returns pitch bias

rot_bias_z property

rot_bias_z: ndarray

Returns yaw bias

pos_dev_along property

pos_dev_along: ndarray

Returns deviations of along track deviations

pos_dev_cross_h property

pos_dev_cross_h: ndarray

Returns deviations of horizontal cross track deviations

pos_dev_cross_v property

pos_dev_cross_v: ndarray

Returns deviations of vertical cross track deviations

rot_dev_xyz cached property

rot_dev_xyz: ndarray

Returns rpy deviations

pos_dev_comb cached property

pos_dev_comb: ndarray

Returns position deviations combined using the L2 norm (cached: the statistics use them several times)

rot_dev_comb cached property

rot_dev_comb: ndarray

Returns rotation deviations as single rotation angles (cached: the statistics use them several times)

pos_dev_rms property

pos_dev_rms: float

Returns RMS of 3d positions

pos_ate property

pos_ate: float

Returns mean of 3d position deviations

pos_dev_max property

pos_dev_max: float

Returns max of 3d position deviations

pos_dev_min property

pos_dev_min: float

Returns min of 3d position deviations

pos_dev_median property

pos_dev_median: float

Returns min of 3d position deviations

pos_dev_std property

pos_dev_std: float

Returns std of 3d position deviations

rot_dev_rms property

rot_dev_rms: float

Returns RMS of rotations

rot_dev_std property

rot_dev_std: float

Returns STD of rotations

rot_ate property

rot_ate: float

Returns mean of rotation deviations

rot_dev_median property

rot_dev_median: float

Returns median of rotations

rot_dev_min property

rot_dev_min: float

Returns min of rotations

rot_dev_max property

rot_dev_max: float

Returns max of rotations

pos_rms_along property

pos_rms_along: float

Returns RMS of along track deviations

pos_rms_cross_h property

pos_rms_cross_h: float

Returns RMS of horizontal cross track deviations

pos_rms_cross_v property

pos_rms_cross_v: float

Returns RMS of vertical cross track deviations

pos_rms_x property

pos_rms_x: float

Returns RMS of x deviations

pos_rms_y property

pos_rms_y: float

Returns RMS of y deviations

pos_rms_z property

pos_rms_z: float

Returns RMS of z deviations

rot_rms_x property

rot_rms_x: float

Returns RMS of roll deviations

rot_rms_y property

rot_rms_y: float

Returns RMS of pitch deviations

rot_rms_z property

rot_rms_z: float

Returns RMS of yaw deviations

columns property

columns: list[str]

Returns the column names of the dataframe

remove_ate_above

remove_ate_above(threshold: float) -> None

Clips the ATE at a given value.

This is useful to remove outliers from the ATE.

Parameters:

• threshold (float) –

  Maximum ATE value to keep.

Source code in trajectopy\results\ate_result.py

def remove_ate_above(self, threshold: float) -> None:
    """Clips the ATE at a given value.

    This is useful to remove outliers from the ATE.

    Args:
        threshold (float): Maximum ATE value to keep.
    """
    if threshold <= 0.0:
        return

    ate_below_idx = self.pos_dev_comb < threshold
    self.trajectory.mask(ate_below_idx)

    self.abs_dev.pos_dev = self.abs_dev.pos_dev[ate_below_idx]
    self.abs_dev.directed_pos_dev = self.abs_dev.directed_pos_dev[ate_below_idx]

    if self.abs_dev.rot_dev is not None:
        # selected as quaternions, a round trip through Euler angles is inexact near gimbal lock
        self.abs_dev.rot_dev = Rotations.from_quat(self.abs_dev.rot_dev.as_quat()[ate_below_idx])

    # the combined deviations and rotation statistics are cached and depend on the removed deviations
    for cached in ("rot_dev_xyz", "rot_bias_xyz", "rot_dev_comb", "pos_dev_comb", "correlation"):
        self.__dict__.pop(cached, None)

set_sorting

set_sorting(sorting: Sorting) -> None

Orders the trajectory and its deviations by time or path length.

Parameters:

• sorting (Sorting) –

  New sorting.

Source code in trajectopy\results\ate_result.py

def set_sorting(self, sorting: Sorting) -> None:
    """Orders the trajectory and its deviations by time or path length.

    Args:
        sorting (Sorting): New sorting.
    """
    if sorting == self.trajectory.sorting:
        return

    order = self.trajectory.sort_index(sorting)
    self.trajectory.set_sorting(sorting)

    self.abs_dev.pos_dev = self.abs_dev.pos_dev[order]
    self.abs_dev.directed_pos_dev = self.abs_dev.directed_pos_dev[order]
    if self.abs_dev.rot_dev is not None:
        self.abs_dev.rot_dev = Rotations.from_quat(self.abs_dev.rot_dev.as_quat()[order])

    # cached per-epoch deviations follow the old order
    for cached in ("rot_dev_xyz", "rot_bias_xyz", "rot_dev_comb", "pos_dev_comb", "correlation"):
        self.__dict__.pop(cached, None)

from_file classmethod

from_file(filename: str) -> ATEResult

Reads an ATE result from a file.

Source code in trajectopy\results\ate_result.py

@classmethod
def from_file(cls, filename: str) -> "ATEResult":
    """Reads an ATE result from a file."""
    from trajectopy.io import results_io

    return results_io.read_ate_result(filename)

to_dataframe

to_dataframe() -> DataFrame

Exports results as pandas dataframe

Source code in trajectopy\results\ate_result.py

def to_dataframe(self) -> pd.DataFrame:
    """
    Exports results as pandas dataframe
    """
    trajectory_data = np.c_[
        self.trajectory.timestamps,
        self.trajectory.path_lengths,
        self.trajectory.positions.xyz,
    ]

    if self.trajectory.rotations is not None:
        trajectory_data = np.c_[trajectory_data, self.trajectory.rotations.as_quat()]

    deviation_data = np.c_[self.abs_dev.pos_dev, self.abs_dev.directed_pos_dev]

    if self.abs_dev.rot_dev:
        deviation_data = np.c_[deviation_data, self.abs_dev.rot_dev.as_quat()]

    all_data = np.c_[trajectory_data, deviation_data]

    return pd.DataFrame(all_data, columns=self.columns)

to_kml

to_kml(
    filename: str,
    field: str = "position",
    max_std: float = 3.0,
    **options: Any,
) -> None

Exports the result to a Google Earth KML file: the trajectory colored by a deviation field, with playback in Google Earth's time slider. Requires a trajectory with a known EPSG code.

Parameters:

• filename (str) –

  The output filename (e.g., "ate.kml").

• field (str, default: 'position' ) –

  Deviation field that colors the trajectory, e.g. "position", "x", "along_track", "rotation" or "yaw" (see :func:trajectopy.io.kml.ate_kml_fields). Defaults to "position".

• max_std (float, default: 3.0 ) –

  The color scale is clipped to mean ± max_std standard deviations (0 = minimum to maximum). Defaults to 3.0.

• **options (Any, default: {} ) –

  Further options of :func:trajectopy.io.kml.write_ate_kml, e.g. colormap="viridis", value_range=(0.0, 0.5), heights="ellipsoidal" or extrude=True.

Source code in trajectopy\results\ate_result.py

def to_kml(self, filename: str, field: str = "position", max_std: float = 3.0, **options: Any) -> None:
    """Exports the result to a Google Earth KML file: the trajectory colored by a deviation field, with
    playback in Google Earth's time slider. Requires a trajectory with a known EPSG code.

    Args:
        filename (str): The output filename (e.g., "ate.kml").
        field (str, optional): Deviation field that colors the trajectory, e.g. "position", "x",
            "along_track", "rotation" or "yaw" (see :func:`trajectopy.io.kml.ate_kml_fields`).
            Defaults to "position".
        max_std (float, optional): The color scale is clipped to mean ± ``max_std`` standard deviations
            (0 = minimum to maximum). Defaults to 3.0.
        **options: Further options of :func:`trajectopy.io.kml.write_ate_kml`, e.g. ``colormap="viridis"``,
            ``value_range=(0.0, 0.5)``, ``heights="ellipsoidal"`` or ``extrude=True``.
    """
    from trajectopy.io.kml import write_ate_kml

    write_ate_kml(self, filename, field=field, max_std=max_std, **options)

to_file

to_file(filename: str, mode: str = 'a') -> None

Exports the result as CSV with a metadata header.

Source code in trajectopy\results\ate_result.py

def to_file(self, filename: str, mode: str = "a") -> None:
    """Exports the result as CSV with a metadata header."""
    from trajectopy.io import results_io

    results_io.write_ate_result(self, filename, mode=mode)