irsim.util#

Utility functions for IR-SIM simulation.

This package contains helper functions for: - Mathematical operations - Coordinate transformations - File operations - Geometry utilities

Submodules#

Functions#

WrapToPi(→ float)

The function WrapToPi transforms an angle in radians to the range [-pi, pi].

WrapToRegion(→ float)

Transform an angle to a defined range, with length of 2*pi.

cross_product(→ float)

Compute the cross product of vectors OA and OB.

diff_to_omni(→ numpy.ndarray)

Convert differential velocity to omnidirectional velocity.

dist_hypot(→ float)

distance(→ float)

Compute the distance between two points.

file_check(→ str | None)

Check whether a file exists and return its absolute path.

find_file(→ str | None)

Recursively search for a file under root_path.

gen_inequal_from_vertex(vertex)

Generate inequality constraints for a convex polygon.

geometry_transform(→ Any)

Transform geometry using a state.

is_2d_list(→ bool)

Returns True if 'data' is a non-empty list of lists (or tuples), indicating a 2D structure.

is_convex_and_ordered(→ tuple[bool, str | None])

Determine if the polygon is convex and return the order (CW or CCW).

omni_to_diff(→ numpy.ndarray)

Convert omnidirectional velocity to differential velocity.

random_point_range(→ list[float])

Generate a random point within a range.

relative_position(→ tuple[float, float])

Calculate the relative position and angle between two points.

time_it(→ Any)

Decorator to measure function execution time.

time_it2(→ Any)

Decorator to measure function execution time with instance attribute check.

transform_point_with_state(→ numpy.ndarray)

Transform a point using a state.

vertices_transform(→ numpy.ndarray | None)

Transform vertices using a state.

Package Contents#

irsim.util.WrapToPi(rad: float, positive: bool = False) → float[源代码]#

The function WrapToPi transforms an angle in radians to the range [-pi, pi].

参数:

  • rad (float) -- Angle in radians. The rad parameter in the WrapToPi function represents an angle in radians that you want to transform to the range [-π, π]. The function ensures that the angle is within this range by wrapping it around if it exceeds the bounds.

  • positive (bool) -- Whether to return the positive value of the angle. Useful for angles difference.

返回:

The function WrapToPi(rad) returns the angle rad wrapped to the range [-pi, pi].

irsim.util.WrapToRegion(rad: float, range: list[float]) → float[源代码]#

Transform an angle to a defined range, with length of 2*pi.

参数:

  • rad (float) -- Angle in radians.

  • range (list) -- List defining the range [min, max].

返回:

Wrapped angle.

返回类型:

float

irsim.util.cross_product(o: list[float], a: list[float], b: list[float]) → float[源代码]#

Compute the cross product of vectors OA and OB.

参数:

  • o (array-like) -- Points representing vectors.

  • a (array-like) -- Points representing vectors.

  • b (array-like) -- Points representing vectors.

返回:

Cross product value.

返回类型:

float

irsim.util.diff_to_omni(state_ori: float, vel_diff: numpy.ndarray) → numpy.ndarray[源代码]#

Convert differential velocity to omnidirectional velocity.

参数:

  • state_ori (float) -- Orientation angle.

  • vel_diff (np.array) -- Differential velocity [linear, angular] (2x1).

返回:

Omnidirectional velocity [vx, vy] (2x1).

返回类型:

np.array

irsim.util.dist_hypot(x1: float, y1: float, x2: float, y2: float) → float[源代码]#
irsim.util.distance(point1: list[float] | numpy.ndarray, point2: list[float] | numpy.ndarray) → float[源代码]#

Compute the distance between two points.

参数:

  • point1 (np.array) -- First point [x, y] (2x1).

  • point2 (np.array) -- Second point [x, y] (2x1).

返回:

Distance between points.

返回类型:

float

irsim.util.file_check(file_name: str | None, root_path: str | None = None) → str | None[源代码]#

Check whether a file exists and return its absolute path.

Searches in the following order: 1. The given path directly 2. Relative to sys.path[0] 3. Relative to the current working directory 4. Relative to the script directory 5. Recursively under root_path (lazy fallback)

参数:

  • file_name (str | None) -- Name or relative path of the file to check. Returns None immediately if None.

  • root_path (str | None) -- Root directory for recursive search fallback.

返回:

Absolute path of the file if found, None otherwise.

返回类型:

str | None

irsim.util.find_file(root_path: str | None, target_filename: str) → str | None[源代码]#

Recursively search for a file under root_path.

参数:

  • root_path (str | None) -- Directory to search under. Returns None if None.

  • target_filename (str) -- Name of the file to find.

返回:

Absolute path if found, None otherwise.

返回类型:

str | None

irsim.util.gen_inequal_from_vertex(vertex: numpy.ndarray)[源代码]#

Generate inequality constraints for a convex polygon.

参数:

vertex (np.array) -- Vertices of the polygon (2xN).

返回:

G matrix and h vector for the inequality Gx <= h.

返回类型:

tuple

irsim.util.geometry_transform(geometry: Any, state: numpy.ndarray) → Any[源代码]#

Transform geometry using a state.

参数:

  • geometry -- Shapely geometry to transform.

  • state (np.array or sequence of 3 floats) -- [xoff, yoff, theta]

返回:

Transformed geometry.

shapely expects [a, b, d, e, xoff, yoff] for: x' = a*x + b*y + xoff y' = d*x + e*y + yoff

irsim.util.is_2d_list(data: list | collections.deque) → bool[源代码]#

Returns True if 'data' is a non-empty list of lists (or tuples), indicating a 2D structure. Returns False if 'data' is a single list

irsim.util.is_convex_and_ordered(points: numpy.ndarray) → tuple[bool, str | None][源代码]#

Determine if the polygon is convex and return the order (CW or CCW).

参数:

points (np.ndarray) -- A 2xN NumPy array representing the vertices of the polygon.

返回:

A tuple where the first element is True if the polygon is convex,

and the second element is 'CW' or 'CCW' based on the order. If not convex, returns (False, None).

返回类型:

(bool, str)

irsim.util.omni_to_diff(state_ori: float, vel_omni: numpy.ndarray, w_max: float = 1.5, guarantee_time: float = 0.2, tolerance: float = 0.1, mini_speed: float = 0.02) → numpy.ndarray[源代码]#

Convert omnidirectional velocity to differential velocity.

参数:

  • state_ori (float) -- Orientation angle.

  • vel_omni (np.array) -- Omnidirectional velocity [vx, vy] (2x1).

  • w_max (float) -- Maximum angular velocity.

  • guarantee_time (float) -- Time to guarantee velocity.

  • tolerance (float) -- Angular tolerance.

  • mini_speed (float) -- Minimum speed threshold.

返回:

Differential velocity [linear, angular] (2x1).

返回类型:

np.array

irsim.util.random_point_range(range_low: list[float] | None = None, range_high: list[float] | None = None) → list[float][源代码]#

Generate a random point within a range.

参数:

  • range_low (list) -- Lower bound of the range.

  • range_high (list) -- Upper bound of the range.

返回:

Random point within the range.

返回类型:

np.array

irsim.util.relative_position(position1: numpy.ndarray, position2: numpy.ndarray, topi: bool = True) → tuple[float, float][源代码]#

Calculate the relative position and angle between two points.

参数:

  • position1 (np.array) -- First position [x, y] (2x1).

  • position2 (np.array) -- Second position [x, y] (2x1).

  • topi (bool) -- Whether to wrap angle to [-pi, pi] (default True).

返回:

Distance and angle (radians).

返回类型:

tuple

irsim.util.time_it(name: str = 'Function') → Any[源代码]#

Decorator to measure function execution time.

参数:

  • name (str) -- Function name for logging (default "Function").

  • print (bool) -- Whether to print execution time (default True).

返回:

Wrapped function with timing.

返回类型:

function

irsim.util.time_it2(name: str = 'Function') → Any[源代码]#

Decorator to measure function execution time with instance attribute check.

参数:

name (str) -- Function name for logging (default "Function").

返回:

Wrapped function with timing.

返回类型:

function

irsim.util.transform_point_with_state(point: numpy.ndarray, state: numpy.ndarray) → numpy.ndarray[源代码]#

Transform a point using a state.

参数:

  • point (np.array) -- Point [x, y, theta] (3x1).

  • state (np.array) -- State [x, y, theta] (3x1).

返回:

Transformed point (2x1).

返回类型:

np.array

irsim.util.vertices_transform(vertices: numpy.ndarray, state: numpy.ndarray) → numpy.ndarray | None[源代码]#

Transform vertices using a state.

参数:

  • vertices (np.array) -- Vertices of the object. (2xN)

  • state (np.array) -- State [x, y, theta] (3x1).

返回:

Transformed vertices.

返回类型:

np.array