angles package

Module contents

angles.normalize_angle(angle)

Normalizes the angle to be -pi to +pi It takes and returns radians.

angles.normalize_angle_positive(angle)

Normalizes the angle to be 0 to 2*pi It takes and returns radians.

angles.shortest_angular_distance(from_angle, to_angle)

Given 2 angles, this returns the shortest angular difference. The inputs and ouputs are of course radians.

The result would always be -pi <= result <= pi. Adding the result to “from” will always get you an equivelent angle to “to”.

angles.shortest_angular_distance_with_large_limits(from_angle, to_angle, left_limit, right_limit)

Returns the delta from from_angle to to_angle, making sure it does not violate limits specified by left_limit and right_limit.

This function is similar to shortest_angular_distance_with_limits(), with the main difference that it accepts limits outside the [-M_PI, M_PI] range. Even if this is quite uncommon, one could indeed consider revolute joints with large rotation limits, e.g., in the range [-2*M_PI, 2*M_PI].

In this case, a strict requirement is to have left_limit smaller than right_limit. Note also that from_angle must lie inside the valid range, while to_angle does not need to. In fact, this function will evaluate the shortest (valid) angle shortest_angle so that from_angle+shortest_angle equals to_angle up to an integer multiple of 2*M_PI. As an example, a call to shortest_angular_distance_with_large_limits(0, 10.5*M_PI, -2*M_PI, 2*M_PI) will return true, with shortest_angle=0.5*M_PI. This is because from_angle and from_angle+shortest_angle are both inside the limits, and fmod(to_angle+shortest_angle, 2*M_PI) equals fmod(to_angle, 2*M_PI). On the other hand, shortest_angular_distance_with_large_limits(10.5*M_PI, 0, -2*M_PI, 2*M_PI) will return false, since from_angle is not in the valid range. Finally, note that the call shortest_angular_distance_with_large_limits(0, 10.5*M_PI, -2*M_PI, 0.1*M_PI) will also return true. However, shortest_angle in this case will be -1.5*M_PI.

eturn valid_flag, shortest_angle - valid_flag will be true if left_limit < right_limit and if “from_angle” and “from_angle+shortest_angle” positions are within the valid interval, false otherwise.

param left_limit - left limit of valid interval, must be smaller than right_limit. param right_limit - right limit of valid interval, must be greater than left_limit.

angles.shortest_angular_distance_with_limits(from_angle, to_angle, left_limit, right_limit)

Returns the delta from “from_angle” to “to_angle” making sure it does not violate limits specified by left_limit and right_limit.

The valid interval of angular positions is [left_limit,right_limit]. E.g., [-0.25,0.25] is a 0.5 radians wide interval that contains 0. But [0.25,-0.25] is a 2*pi-0.5 wide interval that contains pi (but not 0). The value of shortest_angle is the angular difference between “from” and “to” that lies within the defined valid interval.

E.g. shortest_angular_distance_with_limits(-0.5,0.5,0.25,-0.25) returns 2*pi-1.0

shortest_angular_distance_with_limits(-0.5,0.5,-0.25,0.25) returns None since -0.5 and 0.5 do not lie in the interval [-0.25,0.25]

param left_limit - left limit of valid interval for angular position

• must lie in [-pi, pi], left and right limits are specified on the unit circle w.r.t to a reference pointing inwards

param right_limit - right limit of valid interval for angular position

• must lie in [-pi, pi], left and right limits are specified on the unit circle w.r.t to a reference pointing inwards

eturns valid_flag, shortest_angle

angles.two_pi_complement(angle)

returns the angle in [-2*pi, 2*pi] going the other way along the unit circle. param angle The angle to which you want to turn in the range [-2*pi, 2*pi]

E.g. two_pi_complement(-pi/4) returns 7_pi/4

two_pi_complement(pi/4) returns -7*pi/4