Python SDK /fastsim.utils

fastsim.utils

6 classes

Utility classes for pose math, asset resolution, structured logging, visualization, and kinematics helpers used throughout the framework.

Pose Asset Log PoseUtil Visualizer KinematicsSolver
class

Pose

7 methods
fastsim.utils.pose.Pose

Immutable 6-DOF pose: 3D position + quaternion orientation (wxyz convention).

Pose supports composition via the * operator and inversion, making it convenient for frame transformations. Quaternion convention is w-first (wxyz).

__init__constructor
def __init__(self, position: list, quaternion: list)

Construct a Pose from position and wxyz quaternion.

Parameters
NameTypeDefaultDescription
positionlist—List [x, y, z] in metres.
quaternionlist—List [qw, qx, qy, qz] (w-first).
from_datastaticmethod
@staticmethod def from_data(data: dict) → Pose

Deserialize a Pose from a dict with position and quaternion keys.

Parameters
NameTypeDefaultDescription
datadict—Dict with 'position' and 'quaternion' (wxyz) entries.
Returns
Pose
from_quat_wxyzstaticmethod
@staticmethod def from_quat_wxyz(position: list, quaternion: list) → Pose

Construct a Pose explicitly from position and wxyz quaternion arrays.

Parameters
NameTypeDefaultDescription
positionlist—[x, y, z].
quaternionlist—[qw, qx, qy, qz].
Returns
Pose
inversemethod
def inverse(self) → Pose

Compute the inverse of this pose (i.e. the transform from world to this frame).

Returns
Pose — Inverted pose.
__mul__method
def __mul__(self, other: Pose) → Pose

Compose two poses: self * other applies other in the frame of self.

Parameters
NameTypeDefaultDescription
otherPose—The pose to compose with.
Returns
Pose — Composed pose.
positionproperty
@property def position(self) → list

The [x, y, z] position in metres.

Returns
list — List of 3 floats.
quaternionproperty
@property def quaternion(self) → list

The [qw, qx, qy, qz] orientation quaternion.

Returns
list — List of 4 floats, w-first.
class

Asset

static-only2 methods
fastsim.utils.asset.Asset

Static helpers for resolving URL-scheme asset paths and loading config dicts from files.

resolve_url_pathstaticmethod
@staticmethod def resolve_url_path(url: str, root_paths: dict) → str

Resolve a URL-scheme asset path to an absolute filesystem path.

Parameters
NameTypeDefaultDescription
urlstr—URL-scheme path, e.g. 'assets://meshes/table.usd'.
root_pathsdict—Mapping of URL schemes to root directories, e.g. {'assets': '/data/assets'}.
Returns
str — Resolved absolute path.
load_dict_from_filestaticmethod
@staticmethod def load_dict_from_file(path: str) → dict

Load a YAML or JSON file and return it as a Python dict.

Parameters
NameTypeDefaultDescription
pathstr—Path to a YAML or JSON file.
Returns
dict — Parsed file contents.
class

Log

static-only5 methods
fastsim.utils.log.Log

Structured logger with level-colored console output.

infostaticmethod
@staticmethod def info(msg: str) → None

Log an informational message.

Parameters
NameTypeDefaultDescription
msgstr—Message text.
Returns
None
warningstaticmethod
@staticmethod def warning(msg: str) → None

Log a warning message.

Parameters
NameTypeDefaultDescription
msgstr—Message text.
Returns
None
errorstaticmethod
@staticmethod def error(msg: str) → None

Log an error message.

Parameters
NameTypeDefaultDescription
msgstr—Message text.
Returns
None
successstaticmethod
@staticmethod def success(msg: str) → None

Log a success message.

Parameters
NameTypeDefaultDescription
msgstr—Message text.
Returns
None
debugstaticmethod
@staticmethod def debug(msg: str) → None

Log a debug message (shown only when debug logging is enabled).

Parameters
NameTypeDefaultDescription
msgstr—Message text.
Returns
None
class

PoseUtil

static-only7 methods
fastsim.utils.pose_util.PoseUtil

Static quaternion and rotation math helpers (wxyz convention throughout).

normalize_quat_wxyzstaticmethod
@staticmethod def normalize_quat_wxyz(q: list) → list

Normalize a wxyz quaternion to unit length.

Parameters
NameTypeDefaultDescription
qlist—[qw, qx, qy, qz] quaternion.
Returns
list — Normalized [qw, qx, qy, qz].
multiply_quat_wxyzstaticmethod
@staticmethod def multiply_quat_wxyz(q1: list, q2: list) → list

Multiply two wxyz quaternions: q1 ⊗ q2.

Parameters
NameTypeDefaultDescription
q1list—First quaternion [qw, qx, qy, qz].
q2list—Second quaternion [qw, qx, qy, qz].
Returns
list — Product quaternion [qw, qx, qy, qz].
inverse_quat_wxyzstaticmethod
@staticmethod def inverse_quat_wxyz(q: list) → list

Compute the inverse (conjugate) of a unit wxyz quaternion.

Parameters
NameTypeDefaultDescription
qlist—[qw, qx, qy, qz] quaternion.
Returns
list — Inverse quaternion [qw, qx, qy, qz].
quat_to_matrix_wxyzstaticmethod
@staticmethod def quat_to_matrix_wxyz(q: list) → np.ndarray

Convert a wxyz quaternion to a 3×3 rotation matrix.

Parameters
NameTypeDefaultDescription
qlist—[qw, qx, qy, qz] quaternion.
Returns
np.ndarray — 3×3 rotation matrix.
matrix_to_quat_wxyzstaticmethod
@staticmethod def matrix_to_quat_wxyz(matrix: np.ndarray) → list

Convert a 3×3 rotation matrix to a wxyz quaternion.

Parameters
NameTypeDefaultDescription
matrixnp.ndarray—3×3 rotation matrix.
Returns
list — [qw, qx, qy, qz] quaternion.
quat_to_euler_xyzstaticmethod
@staticmethod def quat_to_euler_xyz(q: list) → list

Convert a wxyz quaternion to XYZ Euler angles (intrinsic, radians).

Parameters
NameTypeDefaultDescription
qlist—[qw, qx, qy, qz] quaternion.
Returns
list — [rx, ry, rz] Euler angles in radians.
euler_to_quat_xyzstaticmethod
@staticmethod def euler_to_quat_xyz(euler: list) → list

Convert XYZ Euler angles (intrinsic, radians) to a wxyz quaternion.

Parameters
NameTypeDefaultDescription
eulerlist—[rx, ry, rz] Euler angles in radians.
Returns
list — [qw, qx, qy, qz] quaternion.
class

Visualizer

static-only2 methods
fastsim.utils.visualizer.Visualizer

Static scene visualization helpers for debug rendering of poses and bounding boxes.

visualize_posestaticmethod
@staticmethod def visualize_pose(pose: Pose, scale: float = 0.1, label: str | None = None) → None

Draw an XYZ axis triad at the given pose in the simulation viewport.

Parameters
NameTypeDefaultDescription
posePose—Pose at which to render the triad.
scaleoptfloat0.1Length of each axis arrow in metres.
labeloptstr|NoneNoneOptional text label to render beside the triad.
Returns
None
visualize_bounding_box_with_cornersstaticmethod
@staticmethod def visualize_bounding_box_with_corners(corners: np.ndarray, color: list | None = None) → None

Draw a wireframe bounding box defined by its 8 corner points.

Parameters
NameTypeDefaultDescription
cornersnp.ndarray—(8, 3) array of corner positions in world frame.
coloroptlist|NoneNoneOptional [r, g, b] color in [0, 1] range.
Returns
None
class

KinematicsSolver

static-only1 method
fastsim.utils.kinematics_solver.KinematicsSolver

Lightweight IK/FK solver that works without a full planner instance.

KinematicsSolver is suitable for quick one-off IK queries outside the normal motion planning pipeline. It does not perform collision checking.

solvestaticmethod
@staticmethod def solve(robot_name: str, target_pose: Pose) → dict

Solve IK for a named robot and target EE pose without collision checking.

Parameters
NameTypeDefaultDescription
robot_namestr—Name of the robot to solve for.
target_posePose—Target EE pose in world frame.
Returns
dict — Dict mapping joint names to solved position values.