pooltool.ptmath

Math functions

Overview

Function

angle(v2, v1)	Returns counter-clockwise angle of projections of v1 and v2 onto the x-y plane
angle_between_vectors(v1, v2)	Returns angles between [-180, 180]
are_points_on_same_side(p1, p2, p3, p4)	Are points p3, p4 are on the same side of the line formed by points p1 and p2?
convert_2D_to_3D(array)	Convert a 2D vector to a 3D vector, setting z=0
coordinate_rotation(v, phi)	Rotate vector/matrix from one frame of reference to another (3D FIXME)
cross(u, v)	Compute cross product u x v, where u and v are 3-dimensional vectors
find_intersection_2D(l1x, l1y, l10, l2x, l2y, l20)	Find the intersection point of two lines in 2D space
get_ball_energy(rvw, R, m)	Get the energy of a ball
norm2d(vec)	Calculate the norm of a 2D vector
norm3d(vec)	Calculate the norm of a 3D vector
point_on_line_closest_to_point(p1, p2, p0)	Returns point on line defined by points p1 and p2 closest to the point p0
rel_velocity(rvw, R)	Compute velocity of cloth with respect to ball’s point of contact
solve_transcendental(f, a, b, tol, max_iter)	Solve transcendental equation f(x) = 0 in interval [a, b] using bisection method
unit_vector(vector, handle_zero)	Returns the unit vector of the vector (just-in-time compiled)
unit_vector_slow(vector, handle_zero)	Returns the unit vector of the vector.
wiggle(x, val)	Vary a float or int x by +- val according to a uniform distribution

Functions

pooltool.ptmath.angle(v2: numpy.typing.NDArray[numpy.float64], v1: numpy.typing.NDArray[numpy.float64] = np.array([1, 0])) → float

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

(just-in-time compiled)

Return type:

float

pooltool.ptmath.angle_between_vectors(v1: numpy.typing.NDArray[numpy.float64], v2: numpy.typing.NDArray[numpy.float64]) → float

Returns angles between [-180, 180]

Return type:

float

pooltool.ptmath.are_points_on_same_side(p1, p2, p3, p4) → bool

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

pooltool.ptmath.convert_2D_to_3D(array: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

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

Return type:

numpy.typing.NDArray[numpy.float64]

pooltool.ptmath.coordinate_rotation(v: numpy.typing.NDArray[numpy.float64], phi: float) → numpy.typing.NDArray[numpy.float64]

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

(just-in-time compiled)

Return type:

numpy.typing.NDArray[numpy.float64]

pooltool.ptmath.cross(u: numpy.typing.NDArray[numpy.float64], v: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

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

(just-in-time compiled)

Return type:

numpy.typing.NDArray[numpy.float64]

pooltool.ptmath.find_intersection_2D(l1x: float, l1y: float, l10: float, l2x: float, l2y: float, l20: float) → Tuple[float, float]

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]

pooltool.ptmath.get_ball_energy(rvw: numpy.typing.NDArray[numpy.float64], R: float, m: float) → float

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

pooltool.ptmath.norm2d(vec: numpy.typing.NDArray[numpy.float64]) → float

Calculate the norm of a 2D vector

This is faster than np.linalg.norm

Return type:

float

pooltool.ptmath.norm3d(vec: numpy.typing.NDArray[numpy.float64]) → float

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

pooltool.ptmath.point_on_line_closest_to_point(p1: numpy.typing.NDArray[numpy.float64], p2: numpy.typing.NDArray[numpy.float64], p0: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]

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:

numpy.typing.NDArray[numpy.float64]

pooltool.ptmath.rel_velocity(rvw: numpy.typing.NDArray[numpy.float64], R: float) → numpy.typing.NDArray[numpy.float64]

Compute velocity of cloth with respect to ball’s point of contact

This vector is non-zero whenever the ball is sliding

Return type:

numpy.typing.NDArray[numpy.float64]

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

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

pooltool.ptmath.unit_vector(vector: numpy.typing.NDArray[numpy.float64], handle_zero: bool = False) → numpy.typing.NDArray[numpy.float64]

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

Parameters:

handle_zero (bool, False) -- If True and vector = <0,0,0>, <0,0,0> is returned.

Return type:

numpy.typing.NDArray[numpy.float64]

Notes

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

pooltool.ptmath.unit_vector_slow(vector: numpy.typing.NDArray[numpy.float64], handle_zero: bool = False) → numpy.typing.NDArray[numpy.float64]

Returns the unit vector of the vector.

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

Parameters:

handle_zero (bool, False) -- If True and vector = <0,0,0>, <0,0,0> is returned.

Return type:

numpy.typing.NDArray[numpy.float64]

pooltool.ptmath.wiggle(x: float, val: float)

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