pooltool.ptmath.utils

Functions

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

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

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

Return type:

NDArray[float64]

wiggle(x: float, val: float)

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

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

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]

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

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

(just-in-time compiled)

Return type:

NDArray[float64]

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

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]

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

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)

angle(v2: NDArray[float64], v1: NDArray[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

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

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

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

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

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

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

Parameters:

• a : NDArray[float64]

  Initial 3D vector

• b : NDArray[float64]

  Target 3D vector

Returns:

A quaternion representing the rotation from a to b.

Return type:

Any

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

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

(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]]

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]]

point_on_line_closest_to_point(p1: NDArray[float64], p2: NDArray[float64], p0: NDArray[float64]) → NDArray[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:

NDArray[float64]

squared_norm3d(vec: NDArray[float64]) → float

Calculate the squared norm of a 3D vector

Return type:

float

norm3d(vec: NDArray[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

squared_norm2d(vec: NDArray[float64]) → float

Calculate the squared norm of a 2D vector

Return type:

float

norm2d(vec: NDArray[float64]) → float

Calculate the norm of a 2D vector

This is faster than np.linalg.norm

Return type:

float

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

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]

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

Return type:

NDArray[float64]

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

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]

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

Return type:

NDArray[float64]

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

Return type:

float

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

Return type:

float

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

Return type:

float

get_ball_energy(rvw: NDArray[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

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

Return type:

bool

tip_contact_offset(cue_center_offset: NDArray[float64], tip_radius: float, ball_radius: float) → NDArray[float64]

Calculate the ball contact point offset from the cue tip center offset.

This function converts the offset of the cue tip’s center (relative to the ball’s center, and normalized by the ball’s radius) into the offset of the contact point on the ball’s surface.

The conversion is based on the geometry of two circles in contact. Since the distance from the ball’s center to the cue tip’s center is (ball_radius + tip_radius) while the ball’s surface is at a distance ball_radius, the contact point lies along the same line scaled by the factor

1 / (1 + tip_radius/ball_radius).

In other words, if (a, b) represent the cue tip center offset, then the ball is struck at

(a, b) / (1 + tip_radius/ball_radius).

Parameters:

• cue_center_offset : NDArray[float64]

  A 2D vector (e.g., [a, b]) representing the offset of the cue tip center relative to the ball center (normalized by the ball’s radius).

• tip_radius : float

  The radius of the cue tip.

• ball_radius : float

  The radius of the ball.

Returns:

A 2D vector representing the offset of the contact point on the ball’s surface, normalized by the ball’s radius.

Return type:

NDArray[np.float64]

tip_center_offset(tip_center_offset: NDArray[float64], tip_radius: float, ball_radius: float) → NDArray[float64]

Calculate the cue tip center offset from a given contact point offset on the ball.

This function performs the inverse transformation of tip_contact_offset. Given a 2D contact point offset on the ball’s surface (normalized by the ball’s radius), it computes the corresponding cue tip center offset. Since the cue tip’s center is located an extra tip_radius beyond the ball’s surface, the transformation scales the contact offset by

1 + tip_radius/ball_radius.

Parameters:

• cue_center_offset

  A 2D vector (e.g., [a, b]) representing the offset of the cue tip center relative to the ball center (normalized by the ball’s radius).

• tip_radius : float

  The radius of the cue tip.

• ball_radius : float

  The radius of the ball.

Returns:

A 2D vector representing the offset of the cue tip’s center relative to the

ball’s center (normalized by the ball’s radius).

Return type:

NDArray[np.float64]