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)

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[source]#

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

Parameters:

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

Returns:

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

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

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

Parameters:

  • rad (float) – Angle in radians.

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

Returns:

Wrapped angle.

Return type:

float

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

Compute the cross product of vectors OA and OB.

Parameters:

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

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

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

Returns:

Cross product value.

Return type:

float

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

Convert differential velocity to omnidirectional velocity.

Parameters:

  • state_ori (float) – Orientation angle.

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

Returns:

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

Return type:

np.array

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

Compute the distance between two points.

Parameters:

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

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

Returns:

Distance between points.

Return type:

float

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

Check whether a file exists and return its absolute path.

Parameters:

  • file_name (str) – Name of the file to check.

  • root_path (str, optional) – Root path to use if the file is not found.

Returns:

Absolute path of the file if found.

Return type:

str

Raises:

FileNotFoundError – If the file is not found.

irsim.util.find_file(root_path: str, target_filename: str) → str[source]#
irsim.util.gen_inequal_from_vertex(vertex: numpy.ndarray)[source]#

Generate inequality constraints for a convex polygon.

Parameters:

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

Returns:

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

Return type:

tuple

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

Transform geometry using a state.

Parameters:

  • geometry – Shapely geometry to transform.

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

Returns:

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[source]#

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][source]#

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

Parameters:

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

Returns:

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

Return type:

(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[source]#

Convert omnidirectional velocity to differential velocity.

Parameters:

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

Returns:

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

Return type:

np.array

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

Generate a random point within a range.

Parameters:

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

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

Returns:

Random point within the range.

Return type:

np.array

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

Calculate the relative position and angle between two points.

Parameters:

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

Returns:

Distance and angle (radians).

Return type:

tuple

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

Decorator to measure function execution time.

Parameters:

  • name (str) – Function name for logging (default “Function”).

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

Returns:

Wrapped function with timing.

Return type:

function

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

Decorator to measure function execution time with instance attribute check.

Parameters:

name (str) – Function name for logging (default “Function”).

Returns:

Wrapped function with timing.

Return type:

function

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

Transform a point using a state.

Parameters:

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

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

Returns:

Transformed point (2x1).

Return type:

np.array

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

Transform vertices using a state.

Parameters:

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

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

Returns:

Transformed vertices.

Return type:

np.array