# Utility Functions¶

This module contains a collection of helper functions for math, obtaining shape dimensions, and manipulating contact lists.

Functions

 `getWidth`(element) Returns the width of an element. `getHeight`(element) Returns the height of an element. `fuzzyCompare`(a, b[, tol]) Tests whether two floats are equal within a certain tolerance. `getAngleSides`(a, b, c) Given three sides of a triangle, returns the angle. `getAngleVector`(x, y) Given a vector (x, y), calculates the angle of that vector. `toGrad`(rad) Converts radians to degrees. `clipInformed`(value, minValue, maxValue) Clips a value to a certain range. `quadFormula`(a, b, c) Implementation of the quadratic formula for solving quadratic equations. `moveDelta`(eX, eY, sX, sY[, minDist, speed]) Calculates the values to move from one position to another at fixed speed. `curvedShape`(origin, radius, startAngle, ...) Quick and dirty function for drawing convex and convave curves. `curvedShape2`(origin, radius, startAngle, ...) Function for drawing convex and convave curves. `makeList`(objectOrList) Ensures that the returned object is a list. `dist`(a, b) Calculates the euclidean distance between point a and point b. `mag`(v) Calculates the length of a vector. `norm`(v) Normalizes vector v. `moveToLocBlock`(shape, end[, speed]) Function that moves shape from start to end at a certain speed. `printContactList`(contactList) Prints all contacts in the contact list. `disableContactList`(contactList) Call on robot.frame.body.ContactList to invalidate all contacts after moving the robot to prevent unwanted rotations. `cleanContactList`(contactList) Cleans the contact list by throwing away all contacts that are no longer touching.

Details

`getWidth`(element)[source]

Returns the width of an element.

This function exists because the width and height of different Calico shapes has to be calculated differently. For example, Rectangles do not have a width attribute, but the width as to be calculated by taking the absolute difference between the two point of the Rectangle.

Parameters: element (`Shape`) – The element for which to get the width. The width of the provided element.
`getHeight`(element)[source]

Returns the height of an element.

This function exists because the width and height of different Calico shapes has to be calculated differently. For example, Rectangles do not have a width attribute, but the width as to be calculated by taking the absolute difference between the two point of the Rectangle.

Parameters: element (`Shape`) – The element for which to get the height. The height of the provided element.
`fuzzyCompare`(a, b, tol=1e-09)[source]

Tests whether two floats are equal within a certain tolerance.

Parameters: a (float) – The first float. b (float) – The second float. tol (float) – The tolerance. True if a and b are within tol of eachother, False otherwise.
`getAngleSides`(a, b, c)[source]

Given three sides of a triangle, returns the angle.

Parameters: a (float) – Length of side a. b (float) – Length of side b. c (float) – Length of side c. The angle between sides a and b.
`getAngleVector`(x, y)[source]

Given a vector (x, y), calculates the angle of that vector.

Parameters: x (float) – The x component of the vector. y (float) – The y component of the vector. The angle of the vector.
`toGrad`(rad)[source]

`clipInformed`(value, minValue, maxValue)[source]

Clips a value to a certain range.

The clipped value will remain unchanged if it fell within the range, it will be equal to the minValue if it was smaller than the minValue, and it will be equal to the maxValue if it was larger than the maxValue.

Parameters: value (float) – The value to clip. minValue (float) – The lower bound of the range. maxValue (float) – The upper bound of the range. Tuple containing the clipped value, and a Boolean that is True if the value was clipped, and false otherwise.
`quadFormula`(a, b, c)[source]

Solves equations of the form ax^2 + bx + c, and returns the value of x.

Parameters: a (float) – Value of a. b (float) – Value of b. c (float) – Value of c. List [n, s] where n is the number of solutions, and s is a list of length n containing the solutions.
`moveDelta`(eX, eY, sX, sY, minDist=10, speed=10)[source]

Calculates the values to move from one position to another at fixed speed.

Returns the dx and dy needed to move from (startX,startY) to (endX,endY) at some small increment. Returns (None,None) if the minDist is reached.

Parameters: eX (float) – X coordinate of the end position. eY (float) – Y coordinate of the end position. sX (float) – X coordinate of the start position. sY (float) – Y coordinate of the start position. minDist (float) – Distance at which the function returns (None, None). speed (float) – The length of the returned vector. Tuple (dx, dy) describing a vector of length speed towards the end position. Returns the vector (None, None) when the start and end positions are within minDist from each other.
`curvedShape`(origin, radius, startAngle, stopAngle, convex=True, edgeThickness=10)[source]

Quick and dirty function for drawing convex and convave curves.

Warning: this function is a quick and dirty. It is prone to crashing Calico if ill-used. I encourage someone to make something a bit more robust. RV

```self.addObstacle(self.curvedShape([350,350],250,180,360,False,250))
```

Ways to crash the function:

1. Start and stop angles are not in the right order.

```self.addObstacle(self.curvedShape([350,350],250,180,90,False,250))
```

2. I think this crashes the function because of the point at angle = 360. Either the point is repeated or creates a backwards polygon

```self.addObstacle(self.curvedShape([350,350],150,0,360))
```
Parameters: origin (tuple) – The center point of the curve. radius (float) – The radius of the curve. startAngle (float) – The angle at which the curve starts. stopAngle (float) – The angle at which the curve terminates. convex (bool) – Whether or not this curve is convex or concave. edgeThickness (float) – The width of the curve if concave. `Polygon` object in the shape of the specified curve.
`curvedShape2`(origin, radius, startAngle, stopAngle, convex=True, edgeThickness=10)[source]

Function for drawing convex and convave curves.

Effectively the same as `curvedShape()`, but with some extra checks to avoid crashing calico.

```self.addObstacle(self.curvedShape([350,350],250,180,360,False,250))
```
Parameters: origin (tuple) – The center point of the curve. radius (float) – The radius of the curve. startAngle (float) – The angle at which the curve starts. stopAngle (float) – The angle at which the curve terminates. convex (bool) – Whether or not this curve is convex or concave. edgeThickness (float) – The width of the curve if concave. `Polygon` object in the shape of the specified curve.
`makeList`(objectOrList)[source]

Ensures that the returned object is a list.

If the passed object was already a list (or tuple), returns the object unmodified. If the object was not a list, this function will return a list of length one, containing that object.

Parameters: objectOrList (any) – The object that needs to be a list. The original list if the passed object was a list, or a list containing the passed object.
`dist`(a, b)[source]

Calculates the euclidean distance between point a and point b.

Parameters: a (tuple) – Point a. b (tuple) – Point b. The euclidean distance between points a and b.
`mag`(v)[source]

Calculates the length of a vector.

Parameters: v (tuple) – The vector for which to calculate the length. The length of vector v.
`norm`(v)[source]

Normalizes vector v.

Normalization simply means making the vector of length 1. Crashes if the original vector has lenght 0.

Parameters: v (tuple) – The vector to normalize. The normalized vector.
`moveToLocBlock`(shape, end, speed=10)[source]

Function that moves shape from start to end at a certain speed.

Blocks until the shape has reached the end location. Function relies on the physics simulator being active in the background, and it will never return if the phsyics simulator is not active (or blocked), or if the shape is unable to reach the end location because of intervening obstacles.

Parameters: shape (`Shape`) – The shape to move. end (tuple) – The position to move the shape to. speed (float) – The speed with which to move the shape.
`printContactList`(contactList)[source]

Prints all contacts in the contact list.

Parameters: contactList (`ContactList`) – The contact list to print.
`disableContactList`(contactList)[source]

Call on robot.frame.body.ContactList to invalidate all contacts after moving the robot to prevent unwanted rotations.

Used to stop robot from spinning after it has been stopped. Look up portal object for guide on how to use it.

Parameters: contactList (`ContactList`) – The contact list to disable.
`cleanContactList`(contactList)[source]

Cleans the contact list by throwing away all contacts that are no longer touching.

Parameters: contactList (`ContactList`) – The contact list to clean. Returns a contact list with all non-touching contacts removed.