irsim.util#

Utility functions for IR-SIM simulation.

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

Submodules#

Functions#

file_check(file_name[, root_path])

Check whether a file exists and return its absolute path.

find_file(root_path, target_filename)

WrapToPi(rad[, positive])

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

WrapToRegion(rad, range)

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

relative_position(position1, position2[, topi])

Calculate the relative position and angle between two points.

transform_point_with_state(point, state)

Transform a point using a state.

geometry_transform(geometry, state)

Transform geometry using a state.

vertices_transform(vertices, state)

Transform vertices using a state.

omni_to_diff(state_ori, vel_omni[, w_max, ...])

Convert omnidirectional velocity to differential velocity.

diff_to_omni(state_ori, vel_diff)

Convert differential velocity to omnidirectional velocity.

time_it([name])

Decorator to measure function execution time.

time_it2([name])

Decorator to measure function execution time with instance attribute check.

cross_product(o, a, b)

Compute the cross product of vectors OA and OB.

is_convex_and_ordered(points)

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

gen_inequal_from_vertex(vertex)

Generate inequality constraints for a convex polygon.

distance(point1, point2)

Compute the distance between two points.

dist_hypot(x1, y1, x2, y2)

random_point_range([range_low, range_high])

Generate a random point within a range.

is_2d_list(→ bool)

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

Package Contents#

irsim.util.file_check(file_name, root_path=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, target_filename)[source]#
irsim.util.WrapToPi(rad, positive=False)[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)

  • wrapping (π]. The function ensures that the angle is within this range by)

  • bounds. (it around if it exceeds the)

  • 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, range)[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.relative_position(position1, position2, topi=True)[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.transform_point_with_state(point, state)[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.geometry_transform(geometry, state)[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.vertices_transform(vertices, state)[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

irsim.util.omni_to_diff(state_ori, vel_omni, w_max=1.5, guarantee_time=0.2, tolerance=0.1, mini_speed=0.02)[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.diff_to_omni(state_ori, vel_diff)[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.time_it(name='Function')[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='Function')[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.cross_product(o, a, b)[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.is_convex_and_ordered(points)[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.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.distance(point1, point2)[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.dist_hypot(x1, y1, x2, y2)[source]#
irsim.util.random_point_range(range_low=[0, 0, -pi], range_high=[10, 10, pi])[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.is_2d_list(data: list) → 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