Plotting

Visualization utilities for tracking results.

Plotting utilities for tracking and estimation visualization.

This module provides comprehensive plotting functions for:

• Covariance ellipses: 2D/3D uncertainty visualization

• Tracks: Trajectory and multi-target track plotting

• Coordinates: Coordinate system and rotation visualization

• Metrics: Performance metric visualization (RMSE, NEES, OSPA)

All plotting functions use Plotly for interactive visualizations.

Examples

>>> from pytcl.plotting import covariance_ellipse_points, plot_tracking_result
>>> import numpy as np

>>> # Generate covariance ellipse points
>>> mean = [0, 0]
>>> cov = [[1, 0.5], [0.5, 2]]
>>> x, y = covariance_ellipse_points(mean, cov, n_std=2.0)

>>> # Plot tracking results
>>> true_states = np.random.randn(50, 4)
>>> estimates = true_states + 0.1 * np.random.randn(50, 4)
>>> fig = plot_tracking_result(true_states, estimates)

Notes

Plotly is required for all plotting functions. Install with:

pip install plotly

pytcl.plotting.covariance_ellipse_points(mean, cov, n_std=2.0, n_points=100)

Generate points for a 2D covariance ellipse.

Parameters:

• mean (array_like) – Center of the ellipse [x, y].

• cov (array_like) – 2x2 covariance matrix.

• n_std (float, optional) – Number of standard deviations for ellipse size. Default is 2.0.

• n_points (int, optional) – Number of points to generate. Default is 100.

Returns:

• x (ndarray) – X coordinates of ellipse points.

• y (ndarray) – Y coordinates of ellipse points.

Return type:

Tuple[ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]]]

Examples

>>> mean = [0, 0]
>>> cov = [[1, 0.5], [0.5, 2]]
>>> x, y = covariance_ellipse_points(mean, cov, n_std=2.0)
>>> len(x) == 100
True

pytcl.plotting.covariance_ellipsoid_points(mean, cov, n_std=2.0, n_points=20)

Generate points for a 3D covariance ellipsoid surface.

Parameters:

• mean (array_like) – Center of the ellipsoid [x, y, z].

• cov (array_like) – 3x3 covariance matrix.

• n_std (float, optional) – Number of standard deviations for ellipsoid size. Default is 2.0.

• n_points (int, optional) – Number of points along each angular dimension. Default is 20.

Returns:

• x (ndarray) – X coordinates of surface points (n_points x n_points).

• y (ndarray) – Y coordinates of surface points (n_points x n_points).

• z (ndarray) – Z coordinates of surface points (n_points x n_points).

Return type:

Tuple[ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]]]

Examples

>>> mean = [0, 0, 0]
>>> cov = np.diag([1, 2, 3])
>>> x, y, z = covariance_ellipsoid_points(mean, cov)
>>> x.shape == (20, 20)
True

pytcl.plotting.ellipse_parameters(cov)

Extract ellipse parameters from a 2x2 covariance matrix.

Parameters:

cov (array_like) – 2x2 covariance matrix.

Returns:

• semi_major (float) – Semi-major axis length (1-sigma).

• semi_minor (float) – Semi-minor axis length (1-sigma).

• angle (float) – Rotation angle in radians (counter-clockwise from x-axis).

Return type:

Tuple[float, float, float]

Examples

>>> cov = [[4, 0], [0, 1]]
>>> a, b, theta = ellipse_parameters(cov)
>>> np.isclose(a, 2.0)
True
>>> np.isclose(b, 1.0)
True

pytcl.plotting.confidence_region_radius(n_dims, confidence=0.95)

Compute the chi-squared radius for a confidence region.

For a multivariate Gaussian, the squared Mahalanobis distance follows a chi-squared distribution with n_dims degrees of freedom.

Parameters:

• n_dims (int) – Number of dimensions.

• confidence (float, optional) – Confidence level (0 to 1). Default is 0.95.

Returns:

radius – The chi-squared radius (number of standard deviations).

Return type:

float

Examples

>>> r = confidence_region_radius(2, 0.95)
>>> np.isclose(r, np.sqrt(5.991), rtol=0.01)
True

pytcl.plotting.plot_covariance_ellipse(mean, cov, n_std=2.0, fill=True, color='blue', opacity=0.3, name=None, showlegend=True)

Create a Plotly trace for a covariance ellipse.

Parameters:

• mean (array_like) – Center of the ellipse [x, y].

• cov (array_like) – 2x2 covariance matrix.

• n_std (float, optional) – Number of standard deviations. Default is 2.0.

• fill (bool, optional) – Whether to fill the ellipse. Default is True.

• color (str, optional) – Color for the ellipse. Default is “blue”.

• opacity (float, optional) – Opacity for the fill (0 to 1). Default is 0.3.

• name (str, optional) – Name for the trace. Default is None.

• showlegend (bool, optional) – Whether to show in legend. Default is True.

Returns:

trace – Plotly scatter trace for the ellipse.

Return type:

go.Scatter

Raises:

DependencyError – If plotly is not installed.

pytcl.plotting.plot_covariance_ellipses(means, covariances, n_std=2.0, colors=None, opacity=0.3, show_centers=True)

Create a figure with multiple covariance ellipses.

Parameters:

• means (list of array_like) – Centers of the ellipses.

• covariances (list of array_like) – 2x2 covariance matrices.

• n_std (float, optional) – Number of standard deviations. Default is 2.0.

• colors (list of str, optional) – Colors for each ellipse. Default cycles through a palette.

• opacity (float, optional) – Opacity for the fills. Default is 0.3.

• show_centers (bool, optional) – Whether to show center points. Default is True.

Returns:

fig – Plotly figure with the ellipses.

Return type:

go.Figure

pytcl.plotting.plot_covariance_ellipsoid(mean, cov, n_std=2.0, color='blue', opacity=0.5, name=None)

Create a Plotly surface trace for a 3D covariance ellipsoid.

Parameters:

• mean (array_like) – Center of the ellipsoid [x, y, z].

• cov (array_like) – 3x3 covariance matrix.

• n_std (float, optional) – Number of standard deviations. Default is 2.0.

• color (str, optional) – Color for the surface. Default is “blue”.

• opacity (float, optional) – Opacity (0 to 1). Default is 0.5.

• name (str, optional) – Name for the trace.

Returns:

trace – Plotly surface trace for the ellipsoid.

Return type:

go.Surface

pytcl.plotting.plot_trajectory_2d(states, x_idx=0, y_idx=1, mode='lines+markers', color='blue', name=None, marker_size=4, line_width=2, showlegend=True)

Create a Plotly trace for a 2D trajectory.

Parameters:

• states (array_like) – State trajectory of shape (n_steps, n_dims).

• x_idx (int, optional) – Index of x coordinate in state vector. Default is 0.

• y_idx (int, optional) – Index of y coordinate in state vector. Default is 1.

• mode (str, optional) – Plotly mode string. Default is “lines+markers”.

• color (str, optional) – Color for the trajectory. Default is “blue”.

• name (str, optional) – Name for the trace.

• marker_size (int, optional) – Size of markers. Default is 4.

• line_width (int, optional) – Width of lines. Default is 2.

• showlegend (bool, optional) – Whether to show in legend. Default is True.

Returns:

trace – Plotly scatter trace.

Return type:

go.Scatter

pytcl.plotting.plot_trajectory_3d(states, x_idx=0, y_idx=1, z_idx=2, mode='lines+markers', color='blue', name=None, marker_size=3, line_width=2, showlegend=True)

Create a Plotly trace for a 3D trajectory.

Parameters:

• states (array_like) – State trajectory of shape (n_steps, n_dims).

• x_idx (int, optional) – Index of x coordinate in state vector. Default is 0.

• y_idx (int, optional) – Index of y coordinate in state vector. Default is 1.

• z_idx (int, optional) – Index of z coordinate in state vector. Default is 2.

• mode (str, optional) – Plotly mode string. Default is “lines+markers”.

• color (str, optional) – Color for the trajectory. Default is “blue”.

• name (str, optional) – Name for the trace.

• marker_size (int, optional) – Size of markers. Default is 3.

• line_width (int, optional) – Width of lines. Default is 2.

• showlegend (bool, optional) – Whether to show in legend. Default is True.

Returns:

trace – Plotly 3D scatter trace.

Return type:

go.Scatter3d

pytcl.plotting.plot_measurements_2d(measurements, x_idx=0, y_idx=1, color='black', symbol='x', size=6, name=None, showlegend=True)

Create a Plotly trace for 2D measurements.

Parameters:

• measurements (array_like) – Measurements of shape (n_meas, n_dims).

• x_idx (int, optional) – Index of x coordinate. Default is 0.

• y_idx (int, optional) – Index of y coordinate. Default is 1.

• color (str, optional) – Color for markers. Default is “black”.

• symbol (str, optional) – Marker symbol. Default is “x”.

• size (int, optional) – Marker size. Default is 6.

• name (str, optional) – Name for the trace.

• showlegend (bool, optional) – Whether to show in legend. Default is True.

Returns:

trace – Plotly scatter trace.

Return type:

go.Scatter

pytcl.plotting.plot_tracking_result(true_states=None, estimates=None, measurements=None, covariances=None, x_idx=0, y_idx=2, cov_xy_idx=(0, 2), ellipse_interval=5, n_std=2.0, title='Tracking Result')

Create a comprehensive tracking result visualization.

Parameters:

• true_states (array_like, optional) – True state trajectory of shape (n_steps, n_dims).

• estimates (array_like, optional) – Estimated states of shape (n_steps, n_dims).

• measurements (array_like, optional) – Measurements of shape (n_steps, n_meas_dims).

• covariances (list of array_like, optional) – List of covariance matrices.

• x_idx (int, optional) – Index of x position in state. Default is 0.

• y_idx (int, optional) – Index of y position in state. Default is 2.

• cov_xy_idx (tuple, optional) – Indices for extracting position covariance. Default is (0, 2).

• ellipse_interval (int, optional) – Show ellipse every N steps. Default is 5.

• n_std (float, optional) – Number of standard deviations for ellipses. Default is 2.0.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure with the tracking result.

Return type:

go.Figure

pytcl.plotting.plot_multi_target_tracks(tracks, x_idx=0, y_idx=1, colors=None, title='Multi-Target Tracks', show_ids=True)

Plot multiple target tracks with different colors.

Parameters:

• tracks (dict) – Dictionary mapping track ID to state trajectory.

• x_idx (int, optional) – Index of x position in state. Default is 0.

• y_idx (int, optional) – Index of y position in state. Default is 1.

• colors (dict, optional) – Dictionary mapping track ID to color.

• title (str, optional) – Figure title.

• show_ids (bool, optional) – Whether to show track IDs at endpoints. Default is True.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.plot_state_time_series(states, time=None, state_names=None, title='State Time Series', ncols=2)

Plot state components as time series in subplots.

Parameters:

• states (array_like) – State trajectory of shape (n_steps, n_dims).

• time (array_like, optional) – Time vector. If None, uses step indices.

• state_names (list of str, optional) – Names for each state component.

• title (str, optional) – Figure title.

• ncols (int, optional) – Number of columns in subplot grid. Default is 2.

Returns:

fig – Plotly figure with subplots.

Return type:

go.Figure

pytcl.plotting.plot_estimation_comparison(true_states, estimates, covariances=None, time=None, state_indices=None, state_names=None, n_std=2.0, title='Estimation Comparison')

Plot true states vs estimates with error bounds.

Parameters:

• true_states (array_like) – True state trajectory of shape (n_steps, n_dims).

• estimates (array_like) – Estimated states of shape (n_steps, n_dims).

• covariances (list of array_like, optional) – List of covariance matrices for error bounds.

• time (array_like, optional) – Time vector.

• state_indices (list of int, optional) – Indices of states to plot. Default plots all.

• state_names (list of str, optional) – Names for each state component.

• n_std (float, optional) – Number of standard deviations for bounds. Default is 2.0.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.create_animated_tracking(true_states, estimates, measurements, covariances=None, x_idx=0, y_idx=2, cov_xy_idx=(0, 2), n_std=2.0, frame_duration=100, title='Animated Tracking')

Create an animated tracking visualization.

Parameters:

• true_states (array_like) – True state trajectory of shape (n_steps, n_dims).

• estimates (array_like) – Estimated states of shape (n_steps, n_dims).

• measurements (array_like) – Measurements of shape (n_steps, n_meas_dims).

• covariances (list of array_like, optional) – List of covariance matrices.

• x_idx (int, optional) – Index of x position in state. Default is 0.

• y_idx (int, optional) – Index of y position in state. Default is 2.

• cov_xy_idx (tuple, optional) – Indices for position covariance. Default is (0, 2).

• n_std (float, optional) – Standard deviations for ellipse. Default is 2.0.

• frame_duration (int, optional) – Duration per frame in ms. Default is 100.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure with animation.

Return type:

go.Figure

pytcl.plotting.plot_coordinate_axes_3d(origin=(0, 0, 0), rotation_matrix=None, scale=1.0, colors=('red', 'green', 'blue'), names=('X', 'Y', 'Z'), line_width=4, showlegend=True, name_prefix='')

Create Plotly traces for 3D coordinate axes.

Parameters:

• origin (array_like, optional) – Origin point [x, y, z]. Default is (0, 0, 0).

• rotation_matrix (array_like, optional) – 3x3 rotation matrix to apply to axes. Default is identity.

• scale (float, optional) – Length of axes. Default is 1.0.

• colors (tuple of str, optional) – Colors for X, Y, Z axes. Default is (“red”, “green”, “blue”).

• names (tuple of str, optional) – Names for X, Y, Z axes. Default is (“X”, “Y”, “Z”).

• line_width (int, optional) – Line width. Default is 4.

• showlegend (bool, optional) – Whether to show in legend. Default is True.

• name_prefix (str, optional) – Prefix for axis names in legend.

Returns:

traces – List of three Plotly traces for the axes.

Return type:

list of go.Scatter3d

pytcl.plotting.plot_rotation_comparison(R1, R2, labels=('Original', 'Rotated'), title='Rotation Comparison')

Compare two rotation matrices by visualizing their coordinate frames.

Parameters:

• R1 (array_like) – First 3x3 rotation matrix.

• R2 (array_like) – Second 3x3 rotation matrix.

• labels (tuple of str, optional) – Labels for the two frames.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.plot_euler_angles(angles, sequence='ZYX', title=None)

Visualize Euler angle rotations step by step.

Parameters:

• angles (array_like) – Three Euler angles in radians.

• sequence (str, optional) – Euler angle sequence. Default is “ZYX”.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure with subplots showing each rotation step.

Return type:

go.Figure

pytcl.plotting.plot_quaternion_interpolation(q_start, q_end, n_steps=10, title='Quaternion SLERP Interpolation')

Visualize quaternion interpolation (SLERP) between two orientations.

Parameters:

• q_start (array_like) – Starting quaternion [w, x, y, z].

• q_end (array_like) – Ending quaternion [w, x, y, z].

• n_steps (int, optional) – Number of interpolation steps. Default is 10.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure with animation.

Return type:

go.Figure

pytcl.plotting.plot_spherical_grid(r=1.0, n_lat=10, n_lon=20, color='lightblue', opacity=0.5, title='Spherical Coordinate Grid')

Plot a spherical coordinate grid.

Parameters:

• r (float, optional) – Radius of the sphere. Default is 1.0.

• n_lat (int, optional) – Number of latitude lines. Default is 10.

• n_lon (int, optional) – Number of longitude lines. Default is 20.

• color (str, optional) – Color for the grid. Default is “lightblue”.

• opacity (float, optional) – Opacity of the surface. Default is 0.5.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.plot_points_spherical(points_spherical, r_idx=0, theta_idx=1, phi_idx=2, color='red', size=5, name='Points', title='Points in Spherical Coordinates')

Plot points given in spherical coordinates.

Parameters:

• points_spherical (array_like) – Points in spherical coordinates (r, theta, phi) of shape (n_points, 3).

• r_idx (int, optional) – Index of radial coordinate. Default is 0.

• theta_idx (int, optional) – Index of azimuthal angle (from x-axis in xy-plane). Default is 1.

• phi_idx (int, optional) – Index of polar angle (from z-axis). Default is 2.

• color (str, optional) – Color for the points. Default is “red”.

• size (int, optional) – Marker size. Default is 5.

• name (str, optional) – Name for the trace.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.plot_coordinate_transform(points_original, points_transformed, transform_name='Transform', title=None)

Visualize a coordinate transformation between two point sets.

Parameters:

• points_original (array_like) – Original points of shape (n_points, 3).

• points_transformed (array_like) – Transformed points of shape (n_points, 3).

• transform_name (str, optional) – Name of the transformation.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure with two subplots.

Return type:

go.Figure

pytcl.plotting.plot_rmse_over_time(errors, time=None, component_names=None, title='RMSE Over Time', ylabel='RMSE')

Plot Root Mean Square Error over time.

Parameters:

• errors (array_like) – Error trajectory of shape (n_steps, n_dims) or (n_steps,).

• time (array_like, optional) – Time vector. If None, uses step indices.

• component_names (list of str, optional) – Names for each error component.

• title (str, optional) – Figure title.

• ylabel (str, optional) – Y-axis label.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.plot_nees_sequence(nees_values, time=None, n_dims=2, confidence=0.95, title='NEES Over Time')

Plot Normalized Estimation Error Squared with confidence bounds.

Parameters:

• nees_values (array_like) – NEES values over time.

• time (array_like, optional) – Time vector.

• n_dims (int, optional) – Number of dimensions for chi-squared bounds. Default is 2.

• confidence (float, optional) – Confidence level for bounds. Default is 0.95.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.plot_nis_sequence(nis_values, time=None, n_meas=2, confidence=0.95, title='NIS Over Time')

Plot Normalized Innovation Squared with confidence bounds.

Parameters:

• nis_values (array_like) – NIS values over time.

• time (array_like, optional) – Time vector.

• n_meas (int, optional) – Measurement dimension for chi-squared bounds. Default is 2.

• confidence (float, optional) – Confidence level for bounds. Default is 0.95.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.plot_ospa_over_time(ospa_values, time=None, localization=None, cardinality=None, title='OSPA Metric Over Time')

Plot OSPA (Optimal SubPattern Assignment) metric over time.

Parameters:

• ospa_values (array_like) – Total OSPA values over time.

• time (array_like, optional) – Time vector.

• localization (array_like, optional) – Localization component of OSPA.

• cardinality (array_like, optional) – Cardinality component of OSPA.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.plot_cardinality_over_time(true_cardinality, estimated_cardinality, time=None, title='Cardinality Over Time')

Plot true vs estimated number of targets over time.

Parameters:

• true_cardinality (array_like) – True number of targets at each time step.

• estimated_cardinality (array_like) – Estimated number of targets at each time step.

• time (array_like, optional) – Time vector.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.plot_error_histogram(errors, n_bins=50, component_names=None, title='Error Distribution', show_gaussian_fit=True)

Plot histogram of estimation errors.

Parameters:

• errors (array_like) – Errors of shape (n_samples, n_dims) or (n_samples,).

• n_bins (int, optional) – Number of histogram bins. Default is 50.

• component_names (list of str, optional) – Names for each error component.

• title (str, optional) – Figure title.

• show_gaussian_fit (bool, optional) – Whether to overlay Gaussian fit. Default is True.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.plot_consistency_summary(nees_values, nis_values=None, n_state_dims=4, n_meas_dims=2, confidence=0.95, title='Filter Consistency Summary')

Create a summary plot of filter consistency metrics.

Parameters:

• nees_values (array_like) – NEES values over time.

• nis_values (array_like, optional) – NIS values over time.

• n_state_dims (int, optional) – State dimension for NEES bounds. Default is 4.

• n_meas_dims (int, optional) – Measurement dimension for NIS bounds. Default is 2.

• confidence (float, optional) – Confidence level. Default is 0.95.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.plot_monte_carlo_rmse(monte_carlo_errors, time=None, component_names=None, show_individual=False, title='Monte Carlo RMSE')

Plot RMSE from Monte Carlo simulations.

Parameters:

• monte_carlo_errors (array_like) – Errors of shape (n_runs, n_steps, n_dims).

• time (array_like, optional) – Time vector.

• component_names (list of str, optional) – Names for each error component.

• show_individual (bool, optional) – Whether to show individual run traces. Default is False.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

Track Plotting

Track visualization functions.

Trajectory and track plotting utilities.

This module provides functions for visualizing trajectories, tracks, measurements, and estimation results in 2D and 3D.

pytcl.plotting.tracks.plot_trajectory_2d(states, x_idx=0, y_idx=1, mode='lines+markers', color='blue', name=None, marker_size=4, line_width=2, showlegend=True)

Create a Plotly trace for a 2D trajectory.

Parameters:

• states (array_like) – State trajectory of shape (n_steps, n_dims).

• x_idx (int, optional) – Index of x coordinate in state vector. Default is 0.

• y_idx (int, optional) – Index of y coordinate in state vector. Default is 1.

• mode (str, optional) – Plotly mode string. Default is “lines+markers”.

• color (str, optional) – Color for the trajectory. Default is “blue”.

• name (str, optional) – Name for the trace.

• marker_size (int, optional) – Size of markers. Default is 4.

• line_width (int, optional) – Width of lines. Default is 2.

• showlegend (bool, optional) – Whether to show in legend. Default is True.

Returns:

trace – Plotly scatter trace.

Return type:

go.Scatter

pytcl.plotting.tracks.plot_trajectory_3d(states, x_idx=0, y_idx=1, z_idx=2, mode='lines+markers', color='blue', name=None, marker_size=3, line_width=2, showlegend=True)

Create a Plotly trace for a 3D trajectory.

Parameters:

• states (array_like) – State trajectory of shape (n_steps, n_dims).

• x_idx (int, optional) – Index of x coordinate in state vector. Default is 0.

• y_idx (int, optional) – Index of y coordinate in state vector. Default is 1.

• z_idx (int, optional) – Index of z coordinate in state vector. Default is 2.

• mode (str, optional) – Plotly mode string. Default is “lines+markers”.

• color (str, optional) – Color for the trajectory. Default is “blue”.

• name (str, optional) – Name for the trace.

• marker_size (int, optional) – Size of markers. Default is 3.

• line_width (int, optional) – Width of lines. Default is 2.

• showlegend (bool, optional) – Whether to show in legend. Default is True.

Returns:

trace – Plotly 3D scatter trace.

Return type:

go.Scatter3d

pytcl.plotting.tracks.plot_measurements_2d(measurements, x_idx=0, y_idx=1, color='black', symbol='x', size=6, name=None, showlegend=True)

Create a Plotly trace for 2D measurements.

Parameters:

• measurements (array_like) – Measurements of shape (n_meas, n_dims).

• x_idx (int, optional) – Index of x coordinate. Default is 0.

• y_idx (int, optional) – Index of y coordinate. Default is 1.

• color (str, optional) – Color for markers. Default is “black”.

• symbol (str, optional) – Marker symbol. Default is “x”.

• size (int, optional) – Marker size. Default is 6.

• name (str, optional) – Name for the trace.

• showlegend (bool, optional) – Whether to show in legend. Default is True.

Returns:

trace – Plotly scatter trace.

Return type:

go.Scatter

pytcl.plotting.tracks.plot_tracking_result(true_states=None, estimates=None, measurements=None, covariances=None, x_idx=0, y_idx=2, cov_xy_idx=(0, 2), ellipse_interval=5, n_std=2.0, title='Tracking Result')

Create a comprehensive tracking result visualization.

Parameters:

• true_states (array_like, optional) – True state trajectory of shape (n_steps, n_dims).

• estimates (array_like, optional) – Estimated states of shape (n_steps, n_dims).

• measurements (array_like, optional) – Measurements of shape (n_steps, n_meas_dims).

• covariances (list of array_like, optional) – List of covariance matrices.

• x_idx (int, optional) – Index of x position in state. Default is 0.

• y_idx (int, optional) – Index of y position in state. Default is 2.

• cov_xy_idx (tuple, optional) – Indices for extracting position covariance. Default is (0, 2).

• ellipse_interval (int, optional) – Show ellipse every N steps. Default is 5.

• n_std (float, optional) – Number of standard deviations for ellipses. Default is 2.0.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure with the tracking result.

Return type:

go.Figure

pytcl.plotting.tracks.plot_multi_target_tracks(tracks, x_idx=0, y_idx=1, colors=None, title='Multi-Target Tracks', show_ids=True)

Plot multiple target tracks with different colors.

Parameters:

• tracks (dict) – Dictionary mapping track ID to state trajectory.

• x_idx (int, optional) – Index of x position in state. Default is 0.

• y_idx (int, optional) – Index of y position in state. Default is 1.

• colors (dict, optional) – Dictionary mapping track ID to color.

• title (str, optional) – Figure title.

• show_ids (bool, optional) – Whether to show track IDs at endpoints. Default is True.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.tracks.plot_state_time_series(states, time=None, state_names=None, title='State Time Series', ncols=2)

Plot state components as time series in subplots.

Parameters:

• states (array_like) – State trajectory of shape (n_steps, n_dims).

• time (array_like, optional) – Time vector. If None, uses step indices.

• state_names (list of str, optional) – Names for each state component.

• title (str, optional) – Figure title.

• ncols (int, optional) – Number of columns in subplot grid. Default is 2.

Returns:

fig – Plotly figure with subplots.

Return type:

go.Figure

pytcl.plotting.tracks.plot_estimation_comparison(true_states, estimates, covariances=None, time=None, state_indices=None, state_names=None, n_std=2.0, title='Estimation Comparison')

Plot true states vs estimates with error bounds.

Parameters:

• true_states (array_like) – True state trajectory of shape (n_steps, n_dims).

• estimates (array_like) – Estimated states of shape (n_steps, n_dims).

• covariances (list of array_like, optional) – List of covariance matrices for error bounds.

• time (array_like, optional) – Time vector.

• state_indices (list of int, optional) – Indices of states to plot. Default plots all.

• state_names (list of str, optional) – Names for each state component.

• n_std (float, optional) – Number of standard deviations for bounds. Default is 2.0.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.tracks.create_animated_tracking(true_states, estimates, measurements, covariances=None, x_idx=0, y_idx=2, cov_xy_idx=(0, 2), n_std=2.0, frame_duration=100, title='Animated Tracking')

Create an animated tracking visualization.

Parameters:

• true_states (array_like) – True state trajectory of shape (n_steps, n_dims).

• estimates (array_like) – Estimated states of shape (n_steps, n_dims).

• measurements (array_like) – Measurements of shape (n_steps, n_meas_dims).

• covariances (list of array_like, optional) – List of covariance matrices.

• x_idx (int, optional) – Index of x position in state. Default is 0.

• y_idx (int, optional) – Index of y position in state. Default is 2.

• cov_xy_idx (tuple, optional) – Indices for position covariance. Default is (0, 2).

• n_std (float, optional) – Standard deviations for ellipse. Default is 2.0.

• frame_duration (int, optional) – Duration per frame in ms. Default is 100.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure with animation.

Return type:

go.Figure

Ellipse Plotting

Covariance ellipse visualization.

Covariance ellipse plotting utilities.

This module provides functions for visualizing uncertainty as ellipses in 2D and 3D spaces, commonly used in tracking and estimation applications.

pytcl.plotting.ellipses.covariance_ellipse_points(mean, cov, n_std=2.0, n_points=100)

Generate points for a 2D covariance ellipse.

Parameters:

• mean (array_like) – Center of the ellipse [x, y].

• cov (array_like) – 2x2 covariance matrix.

• n_std (float, optional) – Number of standard deviations for ellipse size. Default is 2.0.

• n_points (int, optional) – Number of points to generate. Default is 100.

Returns:

• x (ndarray) – X coordinates of ellipse points.

• y (ndarray) – Y coordinates of ellipse points.

Return type:

Tuple[ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]]]

Examples

>>> mean = [0, 0]
>>> cov = [[1, 0.5], [0.5, 2]]
>>> x, y = covariance_ellipse_points(mean, cov, n_std=2.0)
>>> len(x) == 100
True

pytcl.plotting.ellipses.covariance_ellipsoid_points(mean, cov, n_std=2.0, n_points=20)

Generate points for a 3D covariance ellipsoid surface.

Parameters:

• mean (array_like) – Center of the ellipsoid [x, y, z].

• cov (array_like) – 3x3 covariance matrix.

• n_std (float, optional) – Number of standard deviations for ellipsoid size. Default is 2.0.

• n_points (int, optional) – Number of points along each angular dimension. Default is 20.

Returns:

• x (ndarray) – X coordinates of surface points (n_points x n_points).

• y (ndarray) – Y coordinates of surface points (n_points x n_points).

• z (ndarray) – Z coordinates of surface points (n_points x n_points).

Return type:

Tuple[ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]]]

Examples

>>> mean = [0, 0, 0]
>>> cov = np.diag([1, 2, 3])
>>> x, y, z = covariance_ellipsoid_points(mean, cov)
>>> x.shape == (20, 20)
True

pytcl.plotting.ellipses.ellipse_parameters(cov)

Extract ellipse parameters from a 2x2 covariance matrix.

Parameters:

cov (array_like) – 2x2 covariance matrix.

Returns:

• semi_major (float) – Semi-major axis length (1-sigma).

• semi_minor (float) – Semi-minor axis length (1-sigma).

• angle (float) – Rotation angle in radians (counter-clockwise from x-axis).

Return type:

Tuple[float, float, float]

Examples

>>> cov = [[4, 0], [0, 1]]
>>> a, b, theta = ellipse_parameters(cov)
>>> np.isclose(a, 2.0)
True
>>> np.isclose(b, 1.0)
True

pytcl.plotting.ellipses.confidence_region_radius(n_dims, confidence=0.95)

Compute the chi-squared radius for a confidence region.

For a multivariate Gaussian, the squared Mahalanobis distance follows a chi-squared distribution with n_dims degrees of freedom.

Parameters:

• n_dims (int) – Number of dimensions.

• confidence (float, optional) – Confidence level (0 to 1). Default is 0.95.

Returns:

radius – The chi-squared radius (number of standard deviations).

Return type:

float

Examples

>>> r = confidence_region_radius(2, 0.95)
>>> np.isclose(r, np.sqrt(5.991), rtol=0.01)
True

pytcl.plotting.ellipses.plot_covariance_ellipse(mean, cov, n_std=2.0, fill=True, color='blue', opacity=0.3, name=None, showlegend=True)

Create a Plotly trace for a covariance ellipse.

Parameters:

• mean (array_like) – Center of the ellipse [x, y].

• cov (array_like) – 2x2 covariance matrix.

• n_std (float, optional) – Number of standard deviations. Default is 2.0.

• fill (bool, optional) – Whether to fill the ellipse. Default is True.

• color (str, optional) – Color for the ellipse. Default is “blue”.

• opacity (float, optional) – Opacity for the fill (0 to 1). Default is 0.3.

• name (str, optional) – Name for the trace. Default is None.

• showlegend (bool, optional) – Whether to show in legend. Default is True.

Returns:

trace – Plotly scatter trace for the ellipse.

Return type:

go.Scatter

Raises:

DependencyError – If plotly is not installed.

pytcl.plotting.ellipses.plot_covariance_ellipses(means, covariances, n_std=2.0, colors=None, opacity=0.3, show_centers=True)

Create a figure with multiple covariance ellipses.

Parameters:

• means (list of array_like) – Centers of the ellipses.

• covariances (list of array_like) – 2x2 covariance matrices.

• n_std (float, optional) – Number of standard deviations. Default is 2.0.

• colors (list of str, optional) – Colors for each ellipse. Default cycles through a palette.

• opacity (float, optional) – Opacity for the fills. Default is 0.3.

• show_centers (bool, optional) – Whether to show center points. Default is True.

Returns:

fig – Plotly figure with the ellipses.

Return type:

go.Figure

pytcl.plotting.ellipses.plot_covariance_ellipsoid(mean, cov, n_std=2.0, color='blue', opacity=0.5, name=None)

Create a Plotly surface trace for a 3D covariance ellipsoid.

Parameters:

• mean (array_like) – Center of the ellipsoid [x, y, z].

• cov (array_like) – 3x3 covariance matrix.

• n_std (float, optional) – Number of standard deviations. Default is 2.0.

• color (str, optional) – Color for the surface. Default is “blue”.

• opacity (float, optional) – Opacity (0 to 1). Default is 0.5.

• name (str, optional) – Name for the trace.

Returns:

trace – Plotly surface trace for the ellipsoid.

Return type:

go.Surface

Metrics Plotting

Performance metrics visualization.

Performance metric visualization utilities.

This module provides functions for visualizing tracking and estimation performance metrics such as RMSE, NEES, NIS, and OSPA.

pytcl.plotting.metrics.plot_rmse_over_time(errors, time=None, component_names=None, title='RMSE Over Time', ylabel='RMSE')

Plot Root Mean Square Error over time.

Parameters:

• errors (array_like) – Error trajectory of shape (n_steps, n_dims) or (n_steps,).

• time (array_like, optional) – Time vector. If None, uses step indices.

• component_names (list of str, optional) – Names for each error component.

• title (str, optional) – Figure title.

• ylabel (str, optional) – Y-axis label.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.metrics.plot_nees_sequence(nees_values, time=None, n_dims=2, confidence=0.95, title='NEES Over Time')

Plot Normalized Estimation Error Squared with confidence bounds.

Parameters:

• nees_values (array_like) – NEES values over time.

• time (array_like, optional) – Time vector.

• n_dims (int, optional) – Number of dimensions for chi-squared bounds. Default is 2.

• confidence (float, optional) – Confidence level for bounds. Default is 0.95.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.metrics.plot_nis_sequence(nis_values, time=None, n_meas=2, confidence=0.95, title='NIS Over Time')

Plot Normalized Innovation Squared with confidence bounds.

Parameters:

• nis_values (array_like) – NIS values over time.

• time (array_like, optional) – Time vector.

• n_meas (int, optional) – Measurement dimension for chi-squared bounds. Default is 2.

• confidence (float, optional) – Confidence level for bounds. Default is 0.95.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.metrics.plot_ospa_over_time(ospa_values, time=None, localization=None, cardinality=None, title='OSPA Metric Over Time')

Plot OSPA (Optimal SubPattern Assignment) metric over time.

Parameters:

• ospa_values (array_like) – Total OSPA values over time.

• time (array_like, optional) – Time vector.

• localization (array_like, optional) – Localization component of OSPA.

• cardinality (array_like, optional) – Cardinality component of OSPA.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.metrics.plot_cardinality_over_time(true_cardinality, estimated_cardinality, time=None, title='Cardinality Over Time')

Plot true vs estimated number of targets over time.

Parameters:

• true_cardinality (array_like) – True number of targets at each time step.

• estimated_cardinality (array_like) – Estimated number of targets at each time step.

• time (array_like, optional) – Time vector.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.metrics.plot_error_histogram(errors, n_bins=50, component_names=None, title='Error Distribution', show_gaussian_fit=True)

Plot histogram of estimation errors.

Parameters:

• errors (array_like) – Errors of shape (n_samples, n_dims) or (n_samples,).

• n_bins (int, optional) – Number of histogram bins. Default is 50.

• component_names (list of str, optional) – Names for each error component.

• title (str, optional) – Figure title.

• show_gaussian_fit (bool, optional) – Whether to overlay Gaussian fit. Default is True.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.metrics.plot_consistency_summary(nees_values, nis_values=None, n_state_dims=4, n_meas_dims=2, confidence=0.95, title='Filter Consistency Summary')

Create a summary plot of filter consistency metrics.

Parameters:

• nees_values (array_like) – NEES values over time.

• nis_values (array_like, optional) – NIS values over time.

• n_state_dims (int, optional) – State dimension for NEES bounds. Default is 4.

• n_meas_dims (int, optional) – Measurement dimension for NIS bounds. Default is 2.

• confidence (float, optional) – Confidence level. Default is 0.95.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.metrics.plot_monte_carlo_rmse(monte_carlo_errors, time=None, component_names=None, show_individual=False, title='Monte Carlo RMSE')

Plot RMSE from Monte Carlo simulations.

Parameters:

• monte_carlo_errors (array_like) – Errors of shape (n_runs, n_steps, n_dims).

• time (array_like, optional) – Time vector.

• component_names (list of str, optional) – Names for each error component.

• show_individual (bool, optional) – Whether to show individual run traces. Default is False.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

Coordinate Plotting

Coordinate system visualization helpers.

Coordinate system visualization utilities.

This module provides functions for visualizing coordinate systems, rotations, and transformations in 2D and 3D.

pytcl.plotting.coordinates.plot_coordinate_axes_3d(origin=(0, 0, 0), rotation_matrix=None, scale=1.0, colors=('red', 'green', 'blue'), names=('X', 'Y', 'Z'), line_width=4, showlegend=True, name_prefix='')

Create Plotly traces for 3D coordinate axes.

Parameters:

• origin (array_like, optional) – Origin point [x, y, z]. Default is (0, 0, 0).

• rotation_matrix (array_like, optional) – 3x3 rotation matrix to apply to axes. Default is identity.

• scale (float, optional) – Length of axes. Default is 1.0.

• colors (tuple of str, optional) – Colors for X, Y, Z axes. Default is (“red”, “green”, “blue”).

• names (tuple of str, optional) – Names for X, Y, Z axes. Default is (“X”, “Y”, “Z”).

• line_width (int, optional) – Line width. Default is 4.

• showlegend (bool, optional) – Whether to show in legend. Default is True.

• name_prefix (str, optional) – Prefix for axis names in legend.

Returns:

traces – List of three Plotly traces for the axes.

Return type:

list of go.Scatter3d

pytcl.plotting.coordinates.plot_rotation_comparison(R1, R2, labels=('Original', 'Rotated'), title='Rotation Comparison')

Compare two rotation matrices by visualizing their coordinate frames.

Parameters:

• R1 (array_like) – First 3x3 rotation matrix.

• R2 (array_like) – Second 3x3 rotation matrix.

• labels (tuple of str, optional) – Labels for the two frames.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.coordinates.plot_euler_angles(angles, sequence='ZYX', title=None)

Visualize Euler angle rotations step by step.

Parameters:

• angles (array_like) – Three Euler angles in radians.

• sequence (str, optional) – Euler angle sequence. Default is “ZYX”.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure with subplots showing each rotation step.

Return type:

go.Figure

pytcl.plotting.coordinates.plot_quaternion_interpolation(q_start, q_end, n_steps=10, title='Quaternion SLERP Interpolation')

Visualize quaternion interpolation (SLERP) between two orientations.

Parameters:

• q_start (array_like) – Starting quaternion [w, x, y, z].

• q_end (array_like) – Ending quaternion [w, x, y, z].

• n_steps (int, optional) – Number of interpolation steps. Default is 10.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure with animation.

Return type:

go.Figure

pytcl.plotting.coordinates.plot_spherical_grid(r=1.0, n_lat=10, n_lon=20, color='lightblue', opacity=0.5, title='Spherical Coordinate Grid')

Plot a spherical coordinate grid.

Parameters:

• r (float, optional) – Radius of the sphere. Default is 1.0.

• n_lat (int, optional) – Number of latitude lines. Default is 10.

• n_lon (int, optional) – Number of longitude lines. Default is 20.

• color (str, optional) – Color for the grid. Default is “lightblue”.

• opacity (float, optional) – Opacity of the surface. Default is 0.5.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.coordinates.plot_points_spherical(points_spherical, r_idx=0, theta_idx=1, phi_idx=2, color='red', size=5, name='Points', title='Points in Spherical Coordinates')

Plot points given in spherical coordinates.

Parameters:

• points_spherical (array_like) – Points in spherical coordinates (r, theta, phi) of shape (n_points, 3).

• r_idx (int, optional) – Index of radial coordinate. Default is 0.

• theta_idx (int, optional) – Index of azimuthal angle (from x-axis in xy-plane). Default is 1.

• phi_idx (int, optional) – Index of polar angle (from z-axis). Default is 2.

• color (str, optional) – Color for the points. Default is “red”.

• size (int, optional) – Marker size. Default is 5.

• name (str, optional) – Name for the trace.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure.

Return type:

go.Figure

pytcl.plotting.coordinates.plot_coordinate_transform(points_original, points_transformed, transform_name='Transform', title=None)

Visualize a coordinate transformation between two point sets.

Parameters:

• points_original (array_like) – Original points of shape (n_points, 3).

• points_transformed (array_like) – Transformed points of shape (n_points, 3).

• transform_name (str, optional) – Name of the transformation.

• title (str, optional) – Figure title.

Returns:

fig – Plotly figure with two subplots.

Return type:

go.Figure