pooltool.objects.table.components#

Houses all components that make up a table (pockets, cushions, etc)#

Overview#

Classes#
`CushionDirection`	An Enum for the direction of a cushion
`LinearCushionSegment`	A linear cushion segment defined by the line between points p1 and p2
`CircularCushionSegment`	A circular cushion segment defined by a circle center and radius
`CushionSegments`	A collection of cushion segments
`Pocket`	A circular pocket

Classes#

class pooltool.objects.table.components.CushionDirection[source]#

An Enum for the direction of a cushion

Important for constructing cushions if simulation performance speed is required.

For most table geometries, the playing surface only exists on one side of the cushion, so collisions only need to be checked for one direction. This direction can be specified with this class’s attributes.

SIDE1#: Use side 1.

SIDE2#: Use side 2.

BOTH#: Use sides 1 and 2.

Unfortunately, the rule governing whether to use SIDE1 or SIDE2 is not clear and instead requires experimentation.

If BOTH is used, both collision checks are performed which makes collision checks twice as slow.

Note

This used to inherit from Enum, but accessing the cushion direction in get_next_ball_linear_cushion_collision somehow took up 20% of the functions runtime so I removed it.

class pooltool.objects.table.components.LinearCushionSegment(id: str, p1: ndarray[Any, dtype[float64]], p2: ndarray[Any, dtype[float64]], direction: int = 2)[source]#

A linear cushion segment defined by the line between points p1 and p2

id#

The ID of the cushion segment.

Type:: str

p1#

The 3D coordinate where the cushion segment starts.

Note

p1 and p2 must share the same height (p1[2] == p2[2]).

Type:: numpy.ndarray[Any, numpy.dtype[numpy.float64]]

p2#

The 3D coordinate where the cushion segment ends.

Note

p1 and p2 must share the same height (p1[2] == p2[2]).

Type:: numpy.ndarray[Any, numpy.dtype[numpy.float64]]

direction#

The cushion direction (default = CushionDirection.BOTH).

See CushionDirection for explanation.

Type:: int

Methods:

height() → float#

The height of the cushion

Cached Property Note

This is a cached property, and should be accessed as an attribute, not as a method call.

Return type:: float

lx() → float#

The x-coefficient (\(l_x\)) of the cushion’s 2D general form line equation

Cached Property Note

This is a cached property, and should be accessed as an attribute, not as a method call.

The cushion’s general form line equation in the \(XY\) plane (i.e. dismissing the z-component) is

\[l_x x + l_y y + l_0 = 0\]

where

\[\begin{split}\begin{align*} l_x &= -\frac{p_{2y} - p_{1y}}{p_{2x} - p_{1x}} \\ l_y &= 1 \\ l_0 &= \frac{p_{2y} - p_{1y}}{p_{2x} - p_{1x}} p_{1x} - p_{1y} \\ \end{align*}\end{split}\]

Return type:: float

ly() → float#

The x-coefficient (\(l_y\)) of the cushion’s 2D general form line equation

See lx() for definition.

Cached Property Note

This is a cached property, and should be accessed as an attribute, not as a method call.

Return type:: float

l0() → float#

The constant term (\(l_0\)) of the cushion’s 2D general form line equation

See lx() for definition.

Cached Property Note

This is a cached property, and should be accessed as an attribute, not as a method call.

Return type:: float

normal() → numpy.typing.NDArray[numpy.float64]#

The line’s normal vector, with the z-component set to 0.

Warning

The returned normal vector is arbitrarily directed, meaning it may point away from the table surface, rather than towards it. This nonideality is properly handled in downstream simulation logic, however if you’re using this method for custom purposes, you may want to reverse the direction of this vector by negating it.

Return type:: numpy.typing.NDArray[numpy.float64]

get_normal(rvw: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64][source]#

Calculates the normal vector

Warning

Parameters:

rvw (numpy.typing.NDArray[numpy.float64]) --

The kinematic state vectors of the contacting balls.

See rvw parameter of pooltool.objects.ball.datatypes.BallState.

Returns:

The line’s normal vector, with the z-component set to 0.

Return type:

NDArray[np.float64]

Note

This method only exists for call signature parity with CircularCushionSegment.get_normal(). Consider using normal() instead.

copy() → LinearCushionSegment[source]#

Create a copy

Return type:: LinearCushionSegment

class pooltool.objects.table.components.CircularCushionSegment(id: str, center: ndarray[Any, dtype[float64]], radius: float)[source]#

A circular cushion segment defined by a circle center and radius

id#

The ID of the cushion segment.

Type:: str

center#

A length-3 array specifying the circular cushion’s center.

center[0], center[1], and center[2] are the x-, y-, and z-coordinates of the cushion’s center. The circle is assumed to be parallel to the XY plane, which makes center[2] is the height of the cushion.

Type:: numpy.ndarray[Any, numpy.dtype[numpy.float64]]

radius#

The radius of the cushion segment.

Type:: float

Methods:

height() → float#

The height of the cushion

Cached Property Note

This is a cached property, and should be accessed as an attribute, not as a method call.

Return type:: float

a() → float#

The x-coordinate of the cushion’s center

Cached Property Note

This is a cached property, and should be accessed as an attribute, not as a method call.

Return type:: float

b() → float#

The y-coordinate of the cushion’s center

Cached Property Note

This is a cached property, and should be accessed as an attribute, not as a method call.

Return type:: float

get_normal(rvw: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64][source]#

Calculates the normal vector for a ball contacting the cushion

Assumes that the ball is in fact in contact with the cushion.

Parameters:: rvw (numpy.typing.NDArray[numpy.float64]) -- The kinematic state vectors of the contacting ball (see
Return type:: numpy.typing.NDArray[numpy.float64]

:param pooltool.objects.ball.datatypes.BallState.rvw).:

Returns:: The normal vector, with the z-component set to 0.
Return type:: NDArray[np.float64]

copy() → CircularCushionSegment[source]#

Create a copy

Return type:: CircularCushionSegment

class pooltool.objects.table.components.CushionSegments(linear: Dict[str, LinearCushionSegment], circular: Dict[str, CircularCushionSegment])[source]#

A collection of cushion segments

Cushion segments can be either linear (see LinearCushionSegment) or circular (see CircularCushionSegment). This class stores both.

linear#

A dictionary of linear cushion segments.

Warning

Keys must match the value IDs, e.g. {"2": LinearCushionSegment(id="2", ...)}

Type:: Dict[str, pooltool.objects.table.components.LinearCushionSegment]

circular#

A dictionary of circular cushion segments.

Warning

Keys must match the value IDs, e.g. {"2t": CircularCushionSegment(id="2t", ...)}

Type:: Dict[str, pooltool.objects.table.components.CircularCushionSegment]

Methods:

copy() → CushionSegments[source]#

Create a copy

Return type:: CushionSegments

class pooltool.objects.table.components.Pocket(id: str, center: ndarray[Any, dtype[float64]], radius: float, depth: float = 0.08, contains: set = UNKNOWN)[source]#

A circular pocket

id#

The ID of the pocket.

Type:: str

center#

A length-3 array specifying the pocket’s position.

center[0] is the x-coordinate of the pocket’s center
center[1] is the y-coordinate of the pocket’s center
center[2] must be 0.0

Type:: numpy.ndarray[Any, numpy.dtype[numpy.float64]]

radius#

The radius of the pocket.

Type:: float

depth#

How deep the pocket is.

Type:: float

contains#

Stores the ball IDs of pocketed balls (default = set()).

Type:: set

Methods:

a() → float#

The x-coordinate of the pocket’s center

Cached Property Note

This is a cached property, and should be accessed as an attribute, not as a method call.

Return type:: float

b() → float#

The y-coordinate of the pocket’s center

Cached Property Note

This is a cached property, and should be accessed as an attribute, not as a method call.

Return type:: float

add(ball_id: str) → None[source]#

Add a ball ID to contains

remove(ball_id: str) → None[source]#

Remove a ball ID from contains

copy() → Pocket[source]#

Create a copy

Return type:: Pocket