Math

arcade.math.clamp(a: SupportsRichComparisonT, low: SupportsRichComparisonT, high: SupportsRichComparisonT) SupportsRichComparisonT[source]

Clamp a number between a range.

Parameters:
  • a (float) – The number to clamp

  • low (float) – The lower bound

  • high (float) – The upper bound

arcade.math.lerp(v1: L, v2: L, u: float) L[source]

Linearly interpolate two values which support arithmetic operators.

Both v1 and v2 must be of compatible types and support the following operators:

This means that in certain cases, you may want to use another function:

Parameters:
  • v1 (HasAddSubMul) – The first value

  • v2 (HasAddSubMul) – The second value

  • u – The interpolation value (0.0 to 1.0)

arcade.math.lerp_2d(v1: tuple[float | int, float | int] | Vec2, v2: tuple[float | int, float | int] | Vec2, u: float) Vec2[source]

Linearly interpolate between two 2D points passed as sequences.

Tip

This function returns a Vec2 you can use with :py:func`lerp` .

Parameters:
  • v1 – The first point as a sequence of 2 values.

  • v2 – The second point as a sequence of 2 values.

  • u (float) – The interpolation value (0.0 to 1.0)

arcade.math.lerp_3d(v1: tuple[float | int, float | int, float | int] | Vec3, v2: tuple[float | int, float | int, float | int] | Vec3, u: float) Vec3[source]

Linearly interpolate between two 3D points passed as sequences.

Tip

This function returns a Vec3 you can use with :py:func`lerp`.

Parameters:
  • v1 – The first point as a sequence of 3 values.

  • v2 – The second point as a sequence of 3 values.

  • u (float) – The interpolation value (0.0 to 1.0)

arcade.math.smerp(v1: L, v2: L, dt: float, h: float) L[source]

Smoothly interpolate between two values indepentdant of time. use as a = smerp(a, b, delta_time, 16).

Tip

To find the ideal decay constant (half-life) you can use: h = -t / math.log2(p) where p is how close (percentage) you’d like to be to the target value in t seconds. i.e if in 1 second you’d like to be within 1% then h ~= 0.15051

Parameters:
  • v1 – The first value to interpolate from.

  • v2 – The second value to interpolate to.

  • dt – The time in seconds that has passed since v1 was interpolated last

  • h – The decay constant. The higher the faster v1 reaches v2. 0.1-25.0 is a good range.

arcade.math.smerp_2d(v1: tuple[float | int, float | int] | Vec2, v2: tuple[float | int, float | int] | Vec2, dt: float, h: float) Vec2[source]

Smoothly interpolate between two sequences of length 2 indepentdant of time. use as a = smerp_2d(a, b, delta_time, 16).

Tip

To find the ideal decay constant (half-life) you can use: h = -t / math.log2(p) where p is how close (percentage) you’d like to be to the target value in t seconds. i.e if in 1 second you’d like to be within 1% then h ~= 0.15051

Tip

This function returns a Vec2 you can use with :py:func`smerp`.

Parameters:
  • v1 – The first value to interpolate from.

  • v2 – The second value to interpolate to.

  • dt – The time in seconds that has passed since v1 was interpolated last

  • h – The decay constant. The lower the faster v1 reaches v2. 0.1-25.0 is a good range.

arcade.math.smerp_3d(v1: tuple[float | int, float | int, float | int] | Vec3, v2: tuple[float | int, float | int, float | int] | Vec3, dt: float, h: float) Vec3[source]

Smoothly interpolate between two sequences of length 3 indepentdant of time. use as a = smerp_3d(a, b, delta_time, 16).

Tip

To find the ideal decay constant (half-life) you can use: h = -t / math.log2(p) where p is how close (percentage) you’d like to be to the target value in t seconds. i.e if in 1 second you’d like to be within 1% then h ~= 0.15051

Tip

This function returns a Vec3 you can use with :py:func`smerp`.

Parameters:
  • v1 – The first value to interpolate from.

  • v2 – The second value to interpolate to.

  • dt – The time in seconds that has passed since v1 was interpolated last

  • h – The decay constant. The higher the faster v1 reaches v2. 0.1-25.0 is a good range.

arcade.math.lerp_angle(start_angle: float, end_angle: float, u: float) float[source]

Linearly interpolate between two angles in degrees, following the shortest path.

Parameters:
  • start_angle (float) – The starting angle

  • end_angle (float) – The ending angle

  • u (float) – The interpolation value (0.0 to 1.0)

arcade.math.rand_in_rect(rect: Rect) tuple[float | int, float | int] | Vec2[source]

Calculate a random point in a rectangle.

Parameters:

rect (Rect) – The rectangle to calculate the point in.

arcade.math.rand_in_circle(center: tuple[float | int, float | int] | Vec2, radius: float) tuple[float | int, float | int] | Vec2[source]

Generate a point in a circle, or can think of it as a vector pointing a random direction with a random magnitude <= radius.

Reference: https://stackoverflow.com/a/50746409

Parameters:
  • center (Point2) – The center of the circle

  • radius (float) – The radius of the circle

arcade.math.rand_on_circle(center: tuple[float | int, float | int] | Vec2, radius: float) tuple[float | int, float | int] | Vec2[source]

Generate a point on a circle.

Parameters:
  • center (Point2) – The center of the circle

  • radius (float) – The radius of the circle

arcade.math.rand_on_line(pos1: tuple[float | int, float | int] | Vec2, pos2: tuple[float | int, float | int] | Vec2) tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3[source]

Given two points defining a line, return a random point on that line.

Parameters:
  • pos1 (Point2) – The first point

  • pos2 (Point2) – The second point

arcade.math.rand_angle_360_deg() float[source]

Returns a random angle in degrees between 0.0 and 360.0.

arcade.math.rand_angle_spread_deg(angle: float, half_angle_spread: float) float[source]

Returns a random angle in degrees, within a spread of the given angle.

Parameters:
  • angle (float) – The angle to spread from

  • half_angle_spread (float) – The half angle spread

arcade.math.rand_vec_spread_deg(angle: float, half_angle_spread: float, length: float) tuple[float | int, float | int] | Vec2[source]

Returns a random vector, within a spread of the given angle.

Parameters:
  • angle (float) – The angle to spread from

  • half_angle_spread (float) – The half angle spread

  • length (float) – The length of the vector

arcade.math.rand_vec_magnitude(angle: float, lo_magnitude: float, hi_magnitude: float) tuple[float | int, float | int] | Vec2[source]

Return a vector of randomized magnitude pointing in the given direction.

Parameters:
  • angle (float) – The vector angle in radians

  • lo_magnitude (float) – The lower magnitude

  • hi_magnitude (float) – The higher magnitude

arcade.math.get_distance(x1: float, y1: float, x2: float, y2: float) float[source]

Get the distance between two points.

Parameters:
  • x1 (float) – x coordinate of the first point

  • y1 (float) – y coordinate of the first point

  • x2 (float) – x coordinate of the second point

  • y2 (float) – y coordinate of the second point

arcade.math.rotate_point(x: float, y: float, cx: float, cy: float, angle_degrees: float) tuple[float | int, float | int] | Vec2[source]

Rotate a point around a center.

Parameters:
  • x (float) – x value of the point you want to rotate

  • y (float) – y value of the point you want to rotate

  • cx (float) – x value of the center point you want to rotate around

  • cy (float) – y value of the center point you want to rotate around

  • angle_degrees (float) – Angle, in degrees, to rotate

arcade.math.rescale_relative_to_point(source: tuple[float | int, float | int] | Vec2, target: tuple[float | int, float | int] | Vec2, factor: float | int | tuple[float | int, float | int] | Vec2) tuple[float | int, float | int] | Vec2[source]

Calculate where a point should be when scaled by the factor realtive to the source point.

Parameters:
  • source – Where to scaled from.

  • target – The point being scaled.

  • factor – How much to scale by. If factor is less than one, target approaches source. Otherwise it moves away. A factor of zero returns source.

Returns:

The rescaled point.

arcade.math.rotate_around_point(source: tuple[float | int, float | int] | Vec2, target: tuple[float | int, float | int] | Vec2, angle: float)[source]

Rotate a point around another point clockwise.

Parameters:
  • source – The point to rotate around

  • target – The point to rotate

  • angle – The degrees to rotate the target by.

arcade.math.get_angle_degrees(x1: float, y1: float, x2: float, y2: float) float[source]

Get the angle in degrees between two points.

Parameters:
  • x1 (float) – x coordinate of the first point

  • y1 (float) – y coordinate of the first point

  • x2 (float) – x coordinate of the second point

  • y2 (float) – y coordinate of the second point

arcade.math.get_angle_radians(x1: float, y1: float, x2: float, y2: float) float[source]

Get the angle in radians between two points.

Parameters:
  • x1 (float) – x coordinate of the first point

  • y1 (float) – y coordinate of the first point

  • x2 (float) – x coordinate of the second point

  • y2 (float) – y coordinate of the second point

arcade.math.quaternion_rotation(axis: tuple[float | int, float | int, float | int] | Vec3, vector: tuple[float | int, float | int, float | int] | Vec3, angle: float) tuple[float, float, float][source]

Rotate a 3-dimensional vector of any length clockwise around a 3-dimensional unit length vector.

This method of vector rotation is immune to rotation-lock, however it takes a little more effort to find the axis of rotation rather than 3 angles of rotation. Ref: https://danceswithcode.net/engineeringnotes/quaternions/quaternions.html.

Parameters:
  • axis (tuple[float, float, float]) – The unit length vector that will be rotated around

  • vector (tuple[float, float, float]) – The 3-dimensional vector to be rotated

  • angle (float) – The angle in degrees to rotate the vector clock-wise by