TrajectoryData

Represents a generic trajectory composed of metadata and multiple JointTrajectoryPoint instances.

Properties:

Property	Type	Description
meta	TrajectoryMeta	Trajectory metadata
points	list[JointTrajectoryPoint]	List of trajectory points

Read-only properties:

Property	Type	Description
id	str	Trajectory ID, equivalent to meta.id
joint_names	list[str]	Joint names in the trajectory, taken from the first point
duration	Duration	Total trajectory duration; seconds can be read via duration.seconds

TrajectoryData

Signature:

TrajectoryData(
    *,
    meta: TrajectoryMeta | None = None,
    points: list[JointTrajectoryPoint] | None = None,
)

Description:

Constructs a TrajectoryData instance. All parameters must be passed as keyword arguments.

Parameters:

Parameter	Type	Required	Description
meta	TrajectoryMeta | None	No	Trajectory metadata; defaults to empty metadata if not provided
points	list[JointTrajectoryPoint] | None	No	Trajectory point list; defaults to empty list if not provided

Returns:

TrajectoryData instance.

Raises:

None.

save

Signature:

TrajectoryData.save(path: str | PathLike[str]) -> None

Description:

Saves the trajectory as a .btraj trajectory package; the package contains only meta.json and data.json.

Parameters:

Parameter	Type	Required	Description
path	str | PathLike[str]	Yes	Output file path, must end with .btraj

Returns:

None.

Raises:

ValueError: Path suffix is not .btraj.

RuntimeError: File write failed.

load

Signature:

@classmethod
TrajectoryData.load(path: str | PathLike[str]) -> TrajectoryData

Description:

Loads from a .btraj trajectory package and validates, returning a new TrajectoryData instance.

Parameters:

Parameter	Type	Required	Description
path	str | PathLike[str]	Yes	Trajectory package path, must end with .btraj

Returns:

TrajectoryData instance.

Raises:

ValueError: Path suffix is not .btraj, or path is not a file.

FileNotFoundError: File does not exist.

RuntimeError: Package is not a valid .btraj, JSON parsing failed, metadata missing fields, or trajectory validation failed.

to_numpy

Signature:

TrajectoryData.to_numpy() -> dict[str, Any]

Description:

Exports the trajectory in numpy array format, convenient for analysis or editing. The returned dictionary contains:

• meta: original TrajectoryMeta
• joint_names: list[str]
• times: np.ndarray, time_from_start.seconds per frame
• positions: np.ndarray, shape (n_frames, n_joints), missing values filled with np.nan
• velocities / accelerations / efforts: optional, output when the corresponding field exists in any frame

Parameters:

No parameters.

Returns:

dict[str, Any].

Raises:

None.