Modules.UncertaintyTube package

Submodules

Modules.UncertaintyTube.uncertainty_tubes module

Modules.UncertaintyTube.uncertainty_tubes.uncertainty_tubes_2D(trajectories, axis=None)

Generate and plot 2D uncertainty tubes from trajectories.

Parameters:

trajectoriesnp.ndarray

Array of shape (n_trajectories, n_time_steps, n_ensemble_members, 2) representing the 2D trajectories.

axismatplotlib.axes.Axes, optional

Axis to plot on. If None, creates a new figure and axis.

Returns:

axismatplotlib.axes.Axes

Axis with the plotted uncertainty tubes.

Modules.UncertaintyTube.uncertainty_tubes.uncertainty_tubes_3D(trajectories, axis=None)

Generate and plot 3D uncertainty tubes from trajectories.

Parameters:

• trajectories (np.ndarray) – Array of shape (n_trajectories, n_time_steps, n_ensemble_members, 3) representing the 3D trajectories.

• axis (matplotlib.axes.Axes, optional) – Axis to plot on. If None, creates a new figure and axis.

Returns:

axis – Axis with the plotted uncertainty tubes.

Return type:

matplotlib.axes.Axes

Modules.UncertaintyTube.uncertainty_tubes_mesh module

Modules.UncertaintyTube.uncertainty_tubes_mesh.add_seed_vertices(vertices, seed_ellipsoids, vertex_idx, n_steps, resolution)

Add all vertices for a seed to the vertices array.

Modules.UncertaintyTube.uncertainty_tubes_mesh.add_segment_triangles(faces, seed_idx, face_offset, first_cross_section_start, second_cross_section_start, res_indices, resolution)

Add triangles connecting two consecutive cross-sections.

Modules.UncertaintyTube.uncertainty_tubes_mesh.align_cross_sections(ellipsoids, seed_idx, n_steps, resolution)

Align cross-sections to minimize twisting for a given seed.

Modules.UncertaintyTube.uncertainty_tubes_mesh.apply_circular_alignment(points, best_shift, best_is_reversed)

Apply circular alignment transformation to a set of points based on the calculated shift and orientation.

Parameters:

points (np.ndarray):

Points to transform (shape: n_points × num_dims)

best_shift (int):

Number of positions to shift

best_is_reversed (bool):

Whether to reverse point order

Returns:

aligned (np.ndarray):

Transformed points

point_correspondence_map (np.ndarray):

Index mapping from original to transformed points

Modules.UncertaintyTube.uncertainty_tubes_mesh.calculate_mesh_dimensions(n_steps, n_seeds, resolution)

Calculate dimensions needed for mesh arrays.

Modules.UncertaintyTube.uncertainty_tubes_mesh.circular_align_min_twist(points_ref, points_target, stride=1)

Aligns two sets of points forming closed loops with minimal twist.

Parameters:

points_ref (np.ndarray):

Reference point set (shape: n_points × num_dims)

points_target (np.ndarray):

Target point set to align (shape: n_points × num_dims)

stride (int):

Stride for sampling subset of points (for efficiency)

Returns:

aligned_points (np.ndarray):

Aligned target points

correspondence_map (np.ndarray):

Index mapping from original to aligned points

Modules.UncertaintyTube.uncertainty_tubes_mesh.compute_alignment_scores(reference, target, shifts)

Compute alignment scores for all possible shifts of target relative to reference.

Parameters:

• reference (np.ndarray) – Reference point set (shape: n_points × num_dims)

• target (np.ndarray) – Target point set to align (shape: n_points × num_dims)

• shifts (np.ndarray) – Array of shift values to try

Returns:

Scores for each shift (lower is better)

Return type:

np.ndarray

Modules.UncertaintyTube.uncertainty_tubes_mesh.generate_seed_faces(faces, seed_idx, seed_vertex_start, n_steps, resolution)

Generate triangle faces between consecutive cross-sections.

Modules.UncertaintyTube.uncertainty_tubes_mesh.generate_tube_mesh(trajectories, ellipsoids, n_jobs=1)

Generate triangle mesh for uncertainty tubes with sequential or parallel alignment.

Parameters:

trajectories (np.ndarray):

Ensemble trajectories with shape (n_steps, n_seeds, n_samples, num_dims)

ellipsoids (np.ndarray):

Cross-section boundary points with shape (n_steps, n_seeds, resolution, num_dims)

n_jobs (int, optional):

Number of parallel jobs to use. If n_jobs=1, uses sequential processing. If joblib is not available, falls back to sequential processing. Defaults to 1.

Returns:

vertices (np.ndarray):

Tube mesh vertices with shape (total_vertices, num_dims)

faces (np.ndarray):

Triangle indices with shape (n_seeds, triangles_per_seed, 3)

mean_trajectories (np.ndarray):

Mean trajectory paths

Modules.UncertaintyTube.uncertainty_tubes_mesh.generate_uncertainty_tube_mesh_2D(mean_trajectories, cross_sections)

Generate uncertainty tube mesh from mean trajectories and cross-sections.

Parameters:

• mean_trajectories (np.ndarray) – Array of shape (n_trajectories, n_time_steps, 2) representing the mean trajectory.

• cross_sections (np.ndarray) – Array of shape (n_trajectories, n_time_steps, 2, 2) representing the cross-sections.

Returns:

• points (np.ndarray) – Array of shape (n_trajectories*n_time_steps*2, 2) representing the tube mesh vertices.

• tube_mesh (np.ndarray) – Array of shape (n_trajectories*n_time_steps*2, 3) representing the tube mesh faces.

Modules.UncertaintyTube.uncertainty_tubes_stats module

Modules.UncertaintyTube.uncertainty_tubes_stats.build_2d_superellipse(eigvals, resolution=16, e_proj=1, sym=False)

Build a 2D superellipse given the eigenvalues.

Parameters:

• eigvals (np.ndarray) – Eigenvalues for the 2D projection.

• resolution (int, optional) – Number of points to sample on the superellipse boundary. Defaults to 16.

• e_proj (float, optional) – Exponent controlling the superellipse shape. e_proj=1 creates a standard ellipse, higher values approach a rectangle. Defaults to 1.

• sym (bool, optional) – If True, forces the superellipse to be symmetric by setting both axes to the same length. Defaults to False.

Returns:

A 2D array (shape: resolution × 2) representing the boundary points of the superellipse.

Return type:

np.ndarray

Modules.UncertaintyTube.uncertainty_tubes_stats.compute_eigen_2d(points)

Modules.UncertaintyTube.uncertainty_tubes_stats.expcos(x, e)

Modules.UncertaintyTube.uncertainty_tubes_stats.expsin(x, e)

Modules.UncertaintyTube.uncertainty_tubes_stats.generate_cross_sections(trajectories, major_trajectory=None, resolution=20, e_proj=1, sym=False, n_jobs=1)

Compute 3D uncertainty cross-sections along trajectory paths.

For each time step and starting location, this function calculates a cross-sectional uncertainty profile by projecting the ensemble trajectories onto a plane perpendicular to the major trajectory direction, performing principal component analysis, and constructing a superellipse boundary representing the uncertainty distribution.

Parameters:

• trajectories (np.ndarray) – Ensemble trajectories with shape (n_steps, n_starting_locations, n_samples, num_dims).

• major_trajectory (np.ndarray, optional) – The main trajectory to use for cross-section orientation, with shape (n_steps, n_starting_locations, num_dims). If None, uses the mean of trajectories.

• resolution (int, optional) – Number of points to sample on each cross-section boundary. Defaults to 20.

• e_proj (float, optional) – Exponent controlling the superellipse shape. e_proj=1 creates a standard ellipse, higher values approach a rectangle. Defaults to 1.

• sym (bool, optional) – If True, forces the superellipse to be symmetric by setting both axes to the same length. Defaults to False.

• n_jobs (int, optional) – Number of parallel jobs to use. If n_jobs=1, uses sequential processing. Defaults to 1.

Returns:

• uncertainty_tube (np.ndarray): Cross-section boundary points with shape (n_steps, n_starting_locations, resolution, num_dims).

• eigen_values (np.ndarray): Eigenvalues for each cross-section boundary point with shape (n_steps, n_starting_locations, resolution, 2).

Return type:

tuple

Notes

• The function computes a 2D superellipse embedded in 3D space for each trajectory segment.

• The cross-section is oriented perpendicular to the trajectory direction at each time step.

• The initial positions (t=0) are set to the starting points of the major trajectory.

Modules.UncertaintyTube.uncertainty_tubes_stats.generate_cross_sections_2D(trajectories)

Compute cross-sections of 2D trajectories.

Parameters:

trajectories (np.ndarray) – Array of shape (n_trajectories, n_time_steps, n_ensemble_members, 2) representing the 2D trajectories.

Returns:

cross_sections –

mean_trajectorynp.ndarray

Array of shape (n_trajectories, n_time_steps, 2) representing the mean trajectory.

cross_sectionsnp.ndarray

Array of shape (n_trajectories, n_time_steps)

Return type:

list of np.ndarray

Modules.UncertaintyTube.uncertainty_tubes_stats.project_points_onto_line(point0, point1, points)

Project points onto a line defined by two points.

Parameters:

• point0 (np.ndarray) – Array of shape (2,) representing the first point on the line.

• point1 (np.ndarray) – Array of shape (2,) representing the second point on the line.

• points (np.ndarray) – Array of shape (n_points, 2) representing the points to be projected.

Returns:

projections – Array of shape (n_points, 2) representing the projected points on the line.

Return type:

np.ndarray

Modules.UncertaintyTube.uncertainty_tubes_stats.project_points_to_plane(point0, point1, points)

Projects points onto a plane perpendicular to the line segment from point0 to point1.

Parameters:

• point0 (np.ndarray) – Define the line segment direction

• point1 (np.ndarray) – Define the line segment direction

• points (np.ndarray) – Points to project (shape: (n_points, num_dims))

Returns:

Projected points on the orthogonal plane

Return type:

np.ndarray

Modules.UncertaintyTube.uncertainty_tubes_stats.uncertainty_cross_section(point0, point1, points, resolution=16, e_proj=1, sym=False)

Calculate a cross-sectional uncertainty profile using start, end, and point cloud.

This function generates a 2D superellipse embedded in 3D space that represents the uncertainty distribution around a trajectory segment. It projects points onto a plane perpendicular to the segment direction, performs principal component analysis to determine the main uncertainty directions, and creates a superellipse boundary.

Parameters:

• point0 (np.ndarray) – A 3D point representing the start of the segment.

• point1 (np.ndarray) – A 3D point representing the end of the segment.

• points (np.ndarray) – A 2D array of points (shape: n_samples × num_dims) representing the point cloud.

• resolution (int, optional) – Number of points to sample on the superellipse boundary. Defaults to 16.

• e_proj (float, optional) – Exponent controlling the superellipse shape. e_proj=1 creates a standard ellipse, higher values approach a rectangle. Defaults to 1.

• sym (bool, optional) – If True, forces the superellipse to be symmetric by setting both axes to the same length. Defaults to False.

Returns:

• cross_section_3d (np.ndarray): A 2D array (shape: resolution × num_dims) representing the boundary points of the 3D cross-sectional profile.

• eigen_values (np.ndarray): A 2D array (shape: resolution × 2) containing the two principal eigenvalues for each boundary point, representing the magnitudes of uncertainty in the primary directions.

Return type:

tuple

Notes

• The function creates a 2D superellipse in 3D space (not a true 3D ellipsoid)

• The cross-section is oriented perpendicular to the trajectory direction

• The function uses a 2-sigma confidence region (covering ~95% of variance)

• The superellipse shape can be controlled via the e_proj parameter

Modules.UncertaintyTube.uncertainty_tubes_vis module

Modules.UncertaintyTube.uncertainty_tubes_vis.matplotlib_uncertainty_tube_2D_vis(points, tube_mesh, mean_trajectories, axis=None)

Plot 2D uncertainty tubes from pre-generated mesh data.

Parameters:

pointsnp.ndarray

Array of shape (n_points, 2) representing the tube mesh vertices.

tube_meshnp.ndarray

Array of shape (n_faces, 3) representing the tube mesh faces.

mean_trajectoriesnp.ndarray

Array of shape (n_trajectories, n_time_steps, 2) representing the mean trajectory.

axismatplotlib.axes.Axes, optional

Axis to plot on. If None, creates a new figure and axis.

Returns:

None

Modules.UncertaintyTube.uncertainty_tubes_vis.matplotlib_uncertainty_tube_vis(vertices, faces, mean_trajectories, uv_coords, axis=None)

Plot 3D uncertainty tubes from pre-generated mesh data.

Parameters:

vertices (np.ndarray):

Global vertex array with shape (total_vertices, 3)

faces (np.ndarray):

Triangle face indices with shape (n_seeds, triangles_per_seed, 3)

mean_trajectories (np.ndarray):

Mean trajectory positions with shape (n_steps+1, n_seeds, 3)

uv_coords (np.ndarray):

UV coordinates for coloring, shape matching vertices.

axis (matplotlib.axes.Axes, optional):

3D axis to plot on. If None, creates a new figure and axis.

Returns:

None

Module contents

UncertaintyTube Module

This module provides uncertainty tube functionality for uncertainty visualization.