pooltool.ptmath

Math functions

Subpackages

Submodules

Functions

angle(v2: NDArray[float64], v1: NDArray[float64] = np.array([1, 0])) → float[source]

Returns counter-clockwise angle of projections of v1 and v2 onto the x-y plane

(just-in-time compiled)

Return type:

float

angle_between_vectors(a: NDArray[float64], b: NDArray[float64]) → float[source]

Compute the angle between two 3D vectors in radians.

Returns:

The angle between vectors a and b in radians. Can take on values within [0, pi].

Return type:

float

are_points_on_same_side(p1, p2, p3, p4) → bool[source]

Are points p3, p4 are on the same side of the line formed by points p1 and p2?

Accepts indexable objects. This is a 2D function, but if higher dimensions are provided, that’s ok (only the first two dimensions will be used).

Return type:

bool

convert_2D_to_3D(array: NDArray[float64]) → NDArray[float64][source]

Convert a 2D vector to a 3D vector, setting z=0

Return type:

NDArray[float64]

coordinate_rotation(v: NDArray[float64], phi: float) → NDArray[float64][source]

Rotate vector/matrix from one frame of reference to another (3D FIXME)

(just-in-time compiled)

Return type:

NDArray[float64]

cross(u: NDArray[float64], v: NDArray[float64]) → NDArray[float64][source]

Compute cross product u x v, where u and v are 3-dimensional vectors

(just-in-time compiled)

Return type:

NDArray[float64]

decompose_normal_tangent(v: NDArray[float64], n: NDArray[float64], flip_tangent_direction: bool = False) → tuple[float, float, NDArray[float64]][source]

Decomposes a vector into normal and tangent components given the unit normal direction

Returns:

Tuple of decomposed components and directions, (v_n, v_t, t). v_n is the signed component in the normal direction, v_t is the signed component in the tangent component, and t is the unit tangent direction. The unit normal direction isn’t returned, since it’s passed as an argument.

Return type:

tuple[float, float, NDArray[float64]]

find_intersection_2D(l1x: float, l1y: float, l10: float, l2x: float, l2y: float, l20: float) → tuple[float, float][source]

Find the intersection point of two lines in 2D space

The lines are defined by their linear equations in the general form: (l1x)x + (l1y)y + l10 = 0 and (l2x)x + (l2y)y + l20 = 0.

Parameters:

  • l1x : float

    The coefficient of x in the first line equation.

  • l1y : float

    The coefficient of y in the first line equation.

  • l10 : float

    The constant term in the first line equation.

  • l2x : float

    The coefficient of x in the second line equation.

  • l2y : float

    The coefficient of y in the second line equation.

  • l20 : float

    The constant term in the second line equation.

Returns:

A tuple (x, y) representing the intersection point if the lines intersect at a single point. Returns None if the lines are parallel or coincident (no unique intersection).

Return type:

tuple[float, float]

get_ball_energy(rvw: NDArray[float64], R: float, m: float) → float[source]

Get the energy of a ball

Currently calculating linear and rotational kinetic energy. Need to add potential energy if z-axis is freed

Return type:

float

get_roll_time(rvw: NDArray[float64], u_r: float, g: float) → float[source]
Return type:

float

get_slide_time(rvw: NDArray[float64], R: float, u_s: float, g: float) → float[source]
Return type:

float

get_spin_time(rvw: NDArray[float64], R: float, u_sp: float, g: float) → float[source]
Return type:

float

get_u_vec(rvw: NDArray[float64], phi: float, R: float, s: int) → NDArray[float64][source]
Return type:

NDArray[float64]

is_overlapping(rvw1: NDArray[float64], rvw2: NDArray[float64], R1: float, R2: float, min_spacer: float = 0.0) → bool[source]
Return type:

bool

norm2d(vec: NDArray[float64]) → float[source]

Calculate the norm of a 2D vector

This is faster than np.linalg.norm

Return type:

float

norm3d(vec: NDArray[float64]) → float[source]

Calculate the norm of a 3D vector

This is ~10x faster than np.linalg.norm

>>> import numpy as np
>>> from pooltool.ptmath import *
>>> vec = np.random.rand(3)
>>> norm3d(vec)
>>> %timeit np.linalg.norm(vec)
>>> %timeit norm3d(vec)
2.65 µs ± 63 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)
241 ns ± 2.57 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
Return type:

float

point_on_line_closest_to_point(p1: NDArray[float64], p2: NDArray[float64], p0: NDArray[float64]) → NDArray[float64][source]

Returns point on line defined by points p1 and p2 closest to the point p0

Equations from https://mathworld.wolfram.com/Point-LineDistance3-Dimensional.html

Return type:

NDArray[float64]

quaternion_from_vector_to_vector(a: NDArray[float64], b: NDArray[float64]) → Any[source]

Compute the quaternion representing the rotation from vector a to vector b

Parameters:
Returns:

A quaternion representing the rotation from a to b.

Return type:

Any

rel_velocity(rvw: NDArray[float64], R: float) → NDArray[float64][source]

Compute velocity of ball’s point of contact with the cloth relative to the cloth

This vector is non-zero whenever the ball is sliding

Return type:

NDArray[float64]

rotation_from_vector_to_vector(a: NDArray[float64], b: NDArray[float64]) → scipy.spatial.transform.Rotation[source]

Compute the rotation that transforms vector a to vector b.

Returns:

A scipy Rotation object representing the rotation from a to b.

Return type:

scipy.spatial.transform.Rotation

solve_transcendental(f: Callable[[float], float], a: float, b: float, tol: float = 1e-05, max_iter: int = 100) → float[source]

Solve transcendental equation f(x) = 0 in interval [a, b] using bisection method

Parameters:

  • f : Callable[[float], float]

    A function representing the transcendental equation.

  • a : float

    The lower bound of the interval.

  • b : float

    The upper bound of the interval.

  • tol : float

    The tolerance level for the solution. The function stops when the absolute difference between the upper and lower bounds is less than tol.

  • max_iter : int

    The maximum number of iterations to perform.

Returns:

The approximate root of f within the interval [a, b].

Raises:

  • ValueError -- If f(a) and f(b) have the same sign, indicating no root within the interval.

  • RuntimeError -- If the maximum number of iterations is reached without convergence.

Return type:

float

squared_norm2d(vec: NDArray[float64]) → float[source]

Calculate the squared norm of a 2D vector

Return type:

float

squared_norm3d(vec: NDArray[float64]) → float[source]

Calculate the squared norm of a 3D vector

Return type:

float

surface_velocity(rvw: NDArray[float64], d: NDArray[float64], R: float) → NDArray[float64][source]

Compute velocity of a point on ball’s surface (specified by unit direction vector)

Return type:

NDArray[float64]

tangent_surface_velocity(rvw: NDArray[float64], d: NDArray[float64], R: float) → NDArray[float64][source]

Compute velocity tangent to surface at a point on ball’s surface (specified by unit direction vector)

Return type:

NDArray[float64]

unit_vector(vector: NDArray[float64], handle_zero: bool = False) → NDArray[float64][source]

Returns the unit vector of the vector (just-in-time compiled)

Parameters:

handle_zero : bool

If True and vector = <0,0,0>, <0,0,0> is returned.

Return type:

NDArray[float64]

Notes

  • Only supports 3D (for 2D see unit_vector_slow)

unit_vector_slow(vector: NDArray[float64], handle_zero: bool = False) → NDArray[float64][source]

Returns the unit vector of the vector.

“Slow”, but supports more than just 3D.

Parameters:

handle_zero : bool

If True and vector = <0,0,0>, <0,0,0> is returned.

Return type:

NDArray[float64]

wiggle(x: float, val: float)[source]

Vary a float or int x by +- val according to a uniform distribution