`fastsim.utils`

6 个类

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 个方法

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.

参数

参数名	类型	默认值	说明
`position`	list	—	List [x, y, z] in metres.
`quaternion`	list	—	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.

参数

参数名	类型	默认值	说明
`data`	dict	—	Dict with 'position' and 'quaternion' (wxyz) entries.

返回值

Pose

from_quat_wxyzstaticmethod

@staticmethod def from_quat_wxyz(position: list, quaternion: list) → Pose

Construct a Pose explicitly from position and wxyz quaternion arrays.

参数

参数名	类型	默认值	说明
`position`	list	—	[x, y, z].
`quaternion`	list	—	[qw, qx, qy, qz].

返回值

Pose

inversemethod

def inverse(self) → Pose

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

返回值

Pose — Inverted pose.

__mul__method

def __mul__(self, other: Pose) → Pose

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

参数

参数名	类型	默认值	说明
`other`	Pose	—	The pose to compose with.

返回值

Pose — Composed pose.

positionproperty

@property def position(self) → list

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

返回值

list — List of 3 floats.

quaternionproperty

@property def quaternion(self) → list

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

返回值

list — List of 4 floats, w-first.

class

Asset

静态类2 个方法

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.

参数

参数名	类型	默认值	说明
`url`	str	—	URL-scheme path, e.g. 'assets://meshes/table.usd'.
`root_paths`	dict	—	Mapping of URL schemes to root directories, e.g. {'assets': '/data/assets'}.

返回值

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.

参数

参数名	类型	默认值	说明
`path`	str	—	Path to a YAML or JSON file.

返回值

dict — Parsed file contents.

class

Log

静态类5 个方法

fastsim.utils.log.Log

Structured logger with level-colored console output.

infostaticmethod

@staticmethod def info(msg: str) → None

Log an informational message.

参数

参数名	类型	默认值	说明
`msg`	str	—	Message text.

返回值

None

warningstaticmethod

@staticmethod def warning(msg: str) → None

Log a warning message.

参数

参数名	类型	默认值	说明
`msg`	str	—	Message text.

返回值

None

errorstaticmethod

@staticmethod def error(msg: str) → None

Log an error message.

参数

参数名	类型	默认值	说明
`msg`	str	—	Message text.

返回值

None

successstaticmethod

@staticmethod def success(msg: str) → None

Log a success message.

参数

参数名	类型	默认值	说明
`msg`	str	—	Message text.

返回值

None

debugstaticmethod

@staticmethod def debug(msg: str) → None

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

参数

参数名	类型	默认值	说明
`msg`	str	—	Message text.

返回值

None

class

PoseUtil

静态类7 个方法

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.

参数

参数名	类型	默认值	说明
`q`	list	—	[qw, qx, qy, qz] quaternion.

返回值

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.

参数

参数名	类型	默认值	说明
`q1`	list	—	First quaternion [qw, qx, qy, qz].
`q2`	list	—	Second quaternion [qw, qx, qy, qz].

返回值

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.

参数

参数名	类型	默认值	说明
`q`	list	—	[qw, qx, qy, qz] quaternion.

返回值

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.

参数

参数名	类型	默认值	说明
`q`	list	—	[qw, qx, qy, qz] quaternion.

返回值

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.

参数

参数名	类型	默认值	说明
`matrix`	np.ndarray	—	3×3 rotation matrix.

返回值

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).

参数

参数名	类型	默认值	说明
`q`	list	—	[qw, qx, qy, qz] quaternion.

返回值

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.

参数

参数名	类型	默认值	说明
`euler`	list	—	[rx, ry, rz] Euler angles in radians.

返回值

list — [qw, qx, qy, qz] quaternion.

class

Visualizer

静态类2 个方法

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.

参数

参数名	类型	默认值	说明
`pose`	Pose	—	Pose at which to render the triad.
`scale`opt	float	`0.1`	Length of each axis arrow in metres.
`label`opt	str\|None	`None`	Optional text label to render beside the triad.

返回值

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.

参数

参数名	类型	默认值	说明
`corners`	np.ndarray	—	(8, 3) array of corner positions in world frame.
`color`opt	list\|None	`None`	Optional [r, g, b] color in [0, 1] range.

返回值

None

class

KinematicsSolver

静态类1 个方法

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.

参数

参数名	类型	默认值	说明
`robot_name`	str	—	Name of the robot to solve for.
`target_pose`	Pose	—	Target EE pose in world frame.

返回值

dict — Dict mapping joint names to solved position values.