treble_tsdk.core.trajectory

Classes

Trajectory

TrajectoryGenerator

TrajectoryOrientation

class treble_tsdk.core.trajectory.Trajectory
__init__(trajectory_type: str, points: list[Point3d])
concat(trajectories: list[Trajectory]) → Trajectory

Concatenate multiple trajectories.

If the gap between trajectories exceeds the default spatial step, a bridge is inserted.

Bridge rule: - regular spacing follows the default spatial step - endpoint always included - final segment may be shorter

fixed_orientation(orientation: Rotation) → TrajectoryOrientation

Create an orientation that is fixed to a single value for the entire trajectory.

Parameters:

orientation – The orientation to use.

Returns:

TrajectoryOrientation with the fixed orientation.

static from_object(obj: Source | Receiver) → Trajectory

Create a trajectory from a moving source or receiver. The returned trajectory will remember whether it came from a receiver, which is used by plot() to determine the display color.

get_at_distance(distance: float) → Point3d

Get the nearest point at a specific distance traveled along the trajectory.

Parameters:

distance – Distance in meters from the start of the trajectory.

Returns:

The nearest Point3d.

Raises:

ValueError – If the trajectory has no points or distance is negative.

get_at_percentage(t: float) → Point3d

Get the nearest point at a percentage along the trajectory.

Parameters:

t – Percentage along the trajectory (0.0 = start, 1.0 = end).

Returns:

The nearest Point3d.

Raises:

ValueError – If the trajectory has no points or t is outside [0, 1].

get_observer_orientation(observer_point: Point3d) → TrajectoryOrientation

Compute an orientation so that an observer at observer_point faces the trajectory at each point.

Parameters:

observer_point – The observer’s position.

Returns:

TrajectoryOrientation with computed orientations.

look_ahead() → TrajectoryOrientation

Create an orientation where each trajectory point faces the direction of travel. Each point looks toward the next point in the trajectory. The last point inherits the orientation from the second-to-last point.

Returns:

TrajectoryOrientation with computed orientations.

look_at(target: Point3d) → TrajectoryOrientation

Create an orientation where all trajectory points look at a target point.

Parameters:

target – The point to look at.

Returns:

TrajectoryOrientation with computed orientations.

look_at_keyframes(keyframes: dict[float, Point3d]) → TrajectoryOrientation

Create an orientation with look-at targets at specific percentages along the trajectory. Orientations are linearly interpolated between keyframes.

Parameters:

keyframes – {percentage (0.0-1.0): Point3d target} mappings.

Returns:

TrajectoryOrientation with computed orientations.

plot(model: ModelObj, orientation: TrajectoryOrientation | Rotation | None = None, is_receiver: bool | None = None)

Plot the trajectory within a 3D model visualization.

Parameters:

  • model – ModelObj to use as background for the trajectory visualization

  • orientation – Optional TrajectoryOrientation to display orientation arrows.

  • is_receiver – If True, display as a receiver trajectory (blue). If False, display as a source trajectory (green). If None (default), uses the trajectory’s origin if extracted via from_object(), otherwise defaults to source (green).

validate(model: ModelObj)
property total_length: float

Get the total arc-length of the trajectory in meters.

Returns:

Total length of the trajectory.

class treble_tsdk.core.trajectory.TrajectoryGenerator
static L_shape(start: Point3d, corner: Point3d, end: Point3d) → Trajectory

Generate an L-shaped trajectory composed of two straight segments.

Parameters:

  • start – Starting XYZ coordinate of the first segment.

  • corner – Intermediate point where the path turns.

  • end – Ending XYZ coordinate of the second segment.

Returns:

Trajectory containing the L-shaped points.

static Z_shape(start: Point3d, mid1: Point3d, mid2: Point3d, end: Point3d) → Trajectory

Generate a Z-shaped trajectory composed of three linear segments.

Parameters:

  • start – Starting XYZ coordinate.

  • mid1 – First intermediate point.

  • mid2 – Second intermediate point.

  • end – Ending XYZ coordinate.

Returns:

Trajectory containing the Z-shaped points.

static circle(center: Point3d, radius: float, normal: Point3d = Point3d(x=0.0, y=0.0, z=1.0)) → Trajectory

Generate a circular trajectory in 3D space oriented by a given normal vector.

Parameters:

  • center (Point3d) – XYZ coordinates of the circle’s center.

  • radius (float) – Radius of the circle.

  • normal (Point3d) – Normal vector defining the plane of the circle (default: +Z axis).

Returns:

np.ndarray of XYZ points forming a circle sampled according to self.spatial_step, validated against the model and ruleset.

static custom(points: list[Point3d]) → Trajectory

Generate a trajectory from a user-provided list of points, resampled so that consecutive points are separated by the default spatial step.

Parameters:

points – List of at least 2 Point3d coordinates defining the path.

Returns:

Trajectory containing the resampled points.

static figure8(center: Point3d = Point3d(x=0.0, y=0.0, z=0.0), a: float = 1.0) → Trajectory

Generate a 3D figure-eight (lemniscate-style) trajectory centered at a given point.

Parameters:

  • center – XYZ coordinates of the figure-eight’s center.

  • a – Scaling parameter controlling the size of the figure-eight curve.

  • spatial_step – Spatial step for the trajectory.

Returns:

Trajectory containing the figure-eight points.

static line(start: Point3d, end: Point3d) → Trajectory

Generate a straight-line trajectory between two points.

Parameters:

  • start – Starting XYZ coordinate.

  • end – Ending XYZ coordinate.

  • spatial_step – Spatial step for the trajectory.

Returns:

Trajectory containing the line points.

static polyline(points: list[Point3d], corner_radius: float = 0.0) → Trajectory

Create a multi-segment trajectory by connecting multiple points with straight-line interpolation between each pair.

Parameters:

  • points – List of XYZ coordinates.

  • corner_radius – Round the corners with an aproximated radius in meters.

  • spatial_step – Spatial step for the trajectory.

Returns:

Trajectory containing the polyline points.

static quadratic_bezier(start: Point3d, control: Point3d, end: Point3d) → Trajectory

Generate a quadratic Bézier curve from three control points.

The curve is sampled at N uniformly spaced parameter values t ∈ [0, 1] and follows the standard quadratic Bézier formulation:

B(t) = (1 - t)^2 P0 + 2(1 - t)t P1 + t^2 P2

Parameters:

  • start – Start point of the curve.

  • control – Control point defining the curvature.

  • end – End point of the curve.

  • spatial_step – Distance between consecutive points along the curve.

Returns:

Sampled points along the quadratic Bézier curve.

static random(start: Point3d, end: Point3d, num_control_points: int = 3, deviation: float = 0.3, mode: str = '3D') → Trajectory

Generate a random spline-like trajectory between two points using intermediate perturbed control points.

Parameters:

  • start – Starting XYZ coordinate.

  • end – Ending XYZ coordinate.

  • num_control_points – Number of randomly perturbed intermediate control points.

  • deviation – Maximum fractional deviation relative to total distance between start and end.

  • mode – If “2D”, movement is constrained to the XY plane.

Returns:

Smooth spline trajectory passing through start, end, and random control points.

static round_corners(control_pts: numpy.ndarray, radius: float, spatial_step: float) → numpy.ndarray

Apply geometric corner rounding (“knee”) to a polyline or spline trajectory.

This function inserts smooth Bezier fillets at trajectory corners and resamples the resulting path so that consecutive points are approximately spaced by the given spatial step.

Parameters:

  • control_pts (np.ndarray) – Array of XYZ control points defining the original polyline or spline.

  • radius (float) – Knee amount in meters. If 0, no corner rounding is applied and the trajectory is resampled as-is.

  • spatial_step (float) – Target distance between consecutive trajectory points.

Returns:

np.ndarray of trajectory points after applying the knee and uniform resampling.

static semicircle(start_point: Point3d, radius: float, normal: Point3d = Point3d(x=0.0, y=0.0, z=1.0), direction: int = 1) → Trajectory

Create a semicircle whose FIRST POINT equals start_point. The center is computed automatically based on the given normal.

Parameters:

  • start_point – The exact point where the semicircle must begin.

  • radius – Radius of the semicircle.

  • normal – Normal vector defining the plane of the arc.

  • direction – Determines turning direction inside the plane.

  • spatial_step – float

Returns:

Trajectory containing the semicircle points.

static spiral(center: Point3d = Point3d(x=0.0, y=0.0, z=0.0), a: float = 0.1, b: float = 0.05, turns: int = 3) → Trajectory

Generate a uniformly sampled 2D spiral trajectory in the XY plane.

Parameters:

  • center – Point3d

  • a – float Initial radius parameter of the spiral (r = a + b*t).

  • b – float Growth rate of the spiral radius.

  • turns – int Number of full rotations of the spiral.

  • spatial_step – float

Returns:

Trajectory containing the spiral points.

static spline(points: list[Point3d]) → Trajectory

Generate a smooth spline trajectory through a sequence of control points using a Catmull–Rom style cubic interpolation.

Parameters:

points – list[Point3d] List of at least four control points through which the trajectory should pass.

Returns:

Trajectory containing the interpolated points.

class treble_tsdk.core.trajectory.TrajectoryOrientation
__init__(keyframes: dict[float, Rotation])

Stores orientation keyframes using percentages (0.0-1.0) along a trajectory.

Parameters:

keyframes – {percentage (0.0-1.0): Rotation} mappings.

static from_object(obj: Source | Receiver) → TrajectoryOrientation | None

Extract orientation from a source or receiver’s metadata.

First checks for the __treble_object_orientation key (new format). Falls back to reading orientations from the trajectory blob (old format).

Parameters:

obj – Source or Receiver with metadata.

Returns:

TrajectoryOrientation if orientation data exists, None otherwise.

resolve(trajectory: Trajectory) → list[Rotation]

Interpolates between keyframes to produce one Rotation per trajectory point.

Uses the trajectory’s cumulative distances to map points to percentages. Points before the first keyframe get the first keyframe’s rotation; points after the last get the last rotation.

Parameters:

trajectory – The trajectory to resolve orientations for.

Returns:

List of Rotation objects, one per trajectory point.