pooltool.objects.table#

Submodules#

Overview#

Classes#
`CircularCushionSegment`	A circular cushion segment defined by a circle center and radius
`CushionDirection`	An Enum for the direction of a cushion
`CushionSegments`	A collection of cushion segments
`LinearCushionSegment`	A linear cushion segment defined by the line between points p1 and p2
`Pocket`	A circular pocket
`Table`	A table.
`BilliardTableSpecs`	Parameter specifications for a billiards (pocketless) table.
`PocketTableSpecs`	Parameter specifications for a pocket table.
`SnookerTableSpecs`	Parameter specifications for a snooker table.
`TableModelDescr`	A table model specifier
`TableType`	An Enum describing the table type

Classes#

class pooltool.objects.table.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.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.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.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.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

class pooltool.objects.table.Table(cushion_segments: CushionSegments, pockets: Dict[str, Pocket], table_type: TableType, model_descr: TableModelDescr | None = None, height: float = 0.708, lights_height: float = 1.99)[source]#

A table.

While a table can be constructed by passing all of the following initialization parameters, there are many easier ways, all of which are detailed in the Table Specification </resources/table_specs> resource.

cushion_segments#

The table’s linear and circular cushion segments.

Type:: pooltool.objects.table.components.CushionSegments

pockets#

The table’s pockets.

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

table_type#

An Enum specifying the type of table.

Type:: pooltool.objects.table.specs.TableType

height#

The height of the playing surface (measured from the ground).

This is just used for visualization.

Type:: float

lights_height#

The height of the table lights (measured from the playing surface).

This is just used for visualization.

Type:: float

property w: float#

The width of the table.

Warning

This assumes the table follows the layout similar to this diagram. Specifically, it must have the linear cushion segments with IDs "3"` and "12".

Return type:: float

property l: float#

The length of the table.

Warning

This assumes the table follows the layout similar to this diagram. Specifically, it must have the linear cushion segments with IDs "9"` and "18".

Return type:: float

property center: Tuple[float, float]#

Return the 2D coordinates of the table’s center

Warning

This assumes l() and w() are defined.

Return type:: Tuple[float, float]

Methods:

copy() → Table[source]#

Create a copy.

Return type:: Table

static from_table_specs(specs: pooltool.objects.table.specs.TableSpecs) → Table[source]#

Build a table from a table specifications object

Parameters:

specs (pooltool.objects.table.specs.TableSpecs) --

A valid table specification.

Accepted objects:

Returns:

A table matching the specifications of the input.

pooltool.objects.table.specs.PocketTableSpecs has table_type set to pooltool.objects.table.specs.TableType.POCKET
pooltool.objects.table.specs.BilliardTableSpecs has table_type set to pooltool.objects.table.specs.TableType.BILLIARD
pooltool.objects.table.specs.SnookerTableSpecs has table_type set to pooltool.objects.table.specs.TableType.SNOOKER

Return type:

Table

classmethod prebuilt(name: pooltool.objects.table.collection.TableName) → Table[source]#

Create a default table based on name

Parameters:: name (pooltool.objects.table.collection.TableName) -- The name of the prebuilt table specs.
Returns:: A prebuilt table.
Return type:: Table

classmethod default(table_type: pooltool.objects.table.specs.TableType = TableType.POCKET) → Table[source]#

Create a default table based on table type

A default table is associated to each table type.

Parameters:: table_type (pooltool.objects.table.specs.TableType) -- The type of table.
Returns:: The default table for the given table type.
Return type:: Table

classmethod from_game_type(game_type: pooltool.game.datatypes.GameType) → Table[source]#

Create a default table based on table type

A default table is associated with each game type.

Parameters:: game_type (pooltool.game.datatypes.GameType) -- The game type.
Returns:: The default table for the given game type.
Return type:: Table

class pooltool.objects.table.BilliardTableSpecs(l: float = 3.05, w: float = 1.525, cushion_width: float = 0.0508, cushion_height: float = 0.036576, height: float = 0.708, lights_height: float = 1.99, model_descr: TableModelDescr = TableModelDescr.null)[source]#

Parameter specifications for a billiards (pocketless) table.