pooltool.objects¶

Simulation object classes.¶

The three main simulation objects are pooltool.objects.Ball, pooltool.objects.Cue, and pooltool.objects.Table, however there are many more objects that either help create the primary objects or comprise the primary objects. Those are all kept in this module.

Overview¶

Classes¶
`Ball`	A billiards ball.
`BallHistory`	A container of BallState objects
`BallOrientation`	Stores a ball’s rendered BallOrientation
`BallState`	Holds a ball’s state
`BallParams`	Ball parameters and physical constants
`PrebuiltBallParams`	An Enum specifying prebuilt ball parameters.
`BallSet`	A ballset.
`Cue`	A cue stick.
`CueSpecs`	Cue stick specifications.
`TableName`	An Enum specifying table names.
`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.

Function¶
`get_ballset`(name)	Return the ballset with the given name.
`get_ballset_names`()	Returns a list of available ballset names

Classes¶

class pooltool.objects.Ball(id: str, state: BallState = NOTHING, params: BallParams = NOTHING, ballset: BallSet | None = None, initial_orientation: BallOrientation = NOTHING, history: BallHistory = NOTHING, history_cts: BallHistory = NOTHING)[source]¶

A billiards ball.

This class represents a billiards ball. It stores its parameters (mass, radius, etc.), it’s state (coordinates, velocity, spin, etc), its history (a time-resolved trajectory of its state), amongst other things.

id¶

An ID for the ball.

Use strings (e.g. “1” not 1).

Type:: str

state¶

The ball’s state.

This is the current state of the ball.

See also

See the Important section below for a description of the role of states during simulation.

Type:: pooltool.objects.ball.datatypes.BallState

params¶

The ball’s physical parameters.

The physical parameters of the ball.

Type:: pooltool.objects.ball.params.BallParams

ballset¶

The ball set that the ball belongs to.

Important if rendering the ball in a scene.

See also

See set_ballset() for details

Type:: pooltool.objects.ball.sets.BallSet | None

initial_orientation¶

The initial rendered orientation of the ball.

Important if rendering the ball in a scene.

This is the orientation of the ball at \(t = 0\).

Type:: pooltool.objects.ball.datatypes.BallOrientation

history¶

The ball’s state history

The historical states of the ball from \(t_{initial}\) to \(t_{final}\).

See also

See the Important section below for a description of the role of history during simulation.

Type:: pooltool.objects.ball.datatypes.BallHistory

history_cts¶

The ball’s continuous state history

The historical states of the ball from \(t_{initial}\) to \(t_{final}\) densely sampled with respect to time.

See also

See pooltool.evolution.continuize() for a details about continuizing a simulated system.
See the Important section below for a description of the role of history_cts during simulation.

Type:: pooltool.objects.ball.datatypes.BallHistory

Important

To instantiate this class, consider using the create() constructor. Or, use functions within pooltool.layouts to generate entire collection of balls. Or, of course, construct as normal with __init__.

Important

The following explains how a Ball object is modified when its parent system is simulated (pooltool.evolution.simulate()).

At the start of the simulation process, state represents the ball state at \(t = 0\). A copy of state is appended to history.

For each timestep of the simulation, state is used to inform how the system should advance forward in time. Once determined, state is updated to reflect the ball’s new state. A copy of state is appended to history.

When the simulation is finished, state represents the final resting state of the ball. So too does history[-1].

Finally, if the system is continuized (see pooltool.evolution.continuize()), history_cts is populated. Otherwise it remains empty.

property xyz¶

The displacement (from origin) vector of the ball.

A shortcut for self.state.rvw[0].

property vel¶

The velocity vector of the ball.

A shortcut for self.state.rvw[1].

property avel¶

The angular velocity vector of the ball.

A shortcut for self.state.rvw[2].

Methods:

set_ballset(ballset: pooltool.objects.ball.sets.BallSet) → None[source]¶

Update the ballset

Raises:: ValueError -- If the ball ID doesn’t match to a model name of the ballset.

See also

See pooltool.objects.BallSet for details about ball sets.
See pooltool.system.System.set_ballset() for setting the ballset for all the balls in a system.

copy(drop_history: bool = False) → Ball[source]¶

Create a copy

Parameters:: drop_history (bool) -- If True, the returned copy history and history_cts attributes are both set to empty pooltool.objects.BallHistory objects.
Return type:: Ball

static create(id: str, *, xy: collections.abc.Sequence[float] | None = None, ballset: pooltool.objects.ball.sets.BallSet | None = None, **kwargs) → Ball[source]¶

Create a ball using keyword arguments.

This constructor flattens the tunable parameter space, allowing one to construct a Ball without directly instancing objects like like pooltool.objects.BallParams and pooltool.objects.BallState.

Parameters:

xy (collections.abc.Sequence[float] | None) -- The x and y coordinates of the ball position.
ballset (pooltool.objects.ball.sets.BallSet | None) -- A ballset.
**kwargs -- Arguments accepted by pooltool.objects.BallParams

Return type:

Ball

static dummy(id: str = 'dummy') → Ball[source]¶

Return type:: Ball

class pooltool.objects.BallHistory(states: list[BallState] = NOTHING)[source]¶

A container of BallState objects

states¶

A list of time-increasing BallState objects (default = []).

Type:: list[pooltool.objects.ball.datatypes.BallState]

property empty: bool¶

Returns whether or not the ball history is empty

Returns:: True if states has no length else False
Return type:: bool

Methods:

add(state: BallState) → None[source]¶

Append a state to the history

Raises:: AssertionError -- If state.t < self.states[-1]

Notes

This appends state to states
state is not copied before appending to the history, so they share the same memory address.

copy() → BallHistory[source]¶

Create a copy

Return type:: BallHistory

vectorize() → tuple[numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64]][source]¶

Compile the attribute from each ball state into arrays

This method unzips each pooltool.objects.BallState in states, resulting in an array of pooltool.objects.BallState.rvw values, an array of pooltool.objects.BallState.s values, and an array of pooltool.objects.BallState.t values.

The vectors have the following properties:

>>> import pooltool as pt
>>> history = pt.simulate(pt.System.example(), continuous=True).balls["cue"].history_cts
>>> rvws, ss, ts = history.vectorize()
>>> # Their lengths are equal to the BallHistory
>>> len(rvws) == len(ss) == len(ts) == len(history)
True
>>> # The indices of the arrays match the values of the history
>>> pt.objects.BallState(rvws[26], ss[26], ts[26]) == history[26]
True

Returns:: A length 3 tuple (rvws, ss and ts).
Raises:: ValueError -- If the history is empty.
Return type:: tuple[numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64]]

Example

vectorize can be useful for plotting trajectories.

import pooltool as pt
import matplotlib.pyplot as plt

system = pt.System.example()
pt.simulate(system, continuous=True, inplace=True)

for ball in system.balls.values():
    rvw, ss, ts = ball.history_cts.vectorize()
    plt.plot(rvw[:, 0, 0], rvw[:, 0, 1], color=ss)

plt.show()

See also

from_vectorization()

static from_vectorization(vectorization: tuple[numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64]] | None) → BallHistory[source]¶

Zips a vectorization into a BallHistory

An inverse method of vectorize().

Returns:: A BallHistory constructed from the input vectors.
Return type:: BallHistory

Example

This illustrates a round-trip with vectorize() and from_vectorization().

First create history

>>> import pooltool as pt
>>> history = pt.simulate(pt.System.example(), continuous=True).balls["cue"].history_cts

Illustrate a lossless round trip:

>>> pt.objects.BallHistory.from_vectorization(history.vectorize()) == history
True

See also

vectorize()

static factory() → BallHistory[source]¶

Return type:: BallHistory

class pooltool.objects.BallOrientation(pos: tuple[float, float, float, float], sphere: tuple[float, float, float, float])[source]¶

Stores a ball’s rendered BallOrientation

From a practical standpoint, what needs to be understood about this class is that its attributes uniquely specify a ball’s rendered orientation. Less practically, but more specifically, these attributes correspond to the nodes, ‘pos’ and ‘sphere’, that make up a ball’s visual rendering.

pos¶

A quaternion.

Type:: tuple[float, float, float, float]

sphere¶

Another quaternion.

Type:: tuple[float, float, float, float]

Methods:

static random() → BallOrientation[source]¶

Generate a random BallOrientation

This generates a ball orientation from a uniform sampling of possible orientations.

Returns:: A randomized ball orientation.
Return type:: BallOrientation

copy() → BallOrientation[source]¶

Create a copy

Note

Since the class is frozen and its attributes are immutable, this just returns self.

Return type:: BallOrientation

class pooltool.objects.BallState(rvw: ndarray[tuple[int, ...], dtype[float64]], s, t=0)[source]¶

Holds a ball’s state

The ball’s state is defined (1) the kinematic state of the ball, (2) a label specifying the ball’s motion state, and (3) the point in time that the ball exists in.

rvw¶

The kinematic state of the ball.

rvw is a \(3\times3\) matrix that stores the 3 vectors that characterize a ball’s kinematic state:

\(r\): The displacement (from origin) vector (accessed with rvw[0])
\(v\): The velocity vector (accessed with rvw[1])
\(w\): The angular velocity vector (accessed with rvw[2])

Type:: numpy.ndarray[tuple[int, …], numpy.dtype[numpy.float64]]

s¶

The motion state label of the ball.

s is an integer corresponding to the following motion state labels:

= stationary
= spinning
= sliding
= rolling
= pocketed

Type:: int

t¶

The simulated time.

Type:: float

Methods:

copy() → BallState[source]¶

Create a copy

Return type:: BallState

static default() → BallState[source]¶

Construct a default BallState

Returns:

A valid yet undercooked state.

>>> import pooltool as pt
>>> pt.objects.BallState.default()
BallState(rvw=array([[nan, nan, nan],
       [ 0.,  0.,  0.],
       [ 0.,  0.,  0.]]), s=0, t=0.0)

Return type:

BallState

class pooltool.objects.BallParams(m: float = 0.170097, R: float = 0.028575, u_s: float = 0.2, u_r: float = 0.01, u_sp_proportionality: float = 0.4444444444444444, u_b: float = 0.05, e_b: float = 0.95, e_c: float = 0.85, f_c: float = 0.2, g: float = 9.81)[source]¶

Ball parameters and physical constants

Note

The presence of an attribute does not guarantee its usage by the physics engine. For example, if the frictionless elastic ball-ball collision model is used, then \(u_b\), the ball-ball sliding coefficient of friction, will have no affect on the simulation.

m¶

The mass of the ball.

Type:: float

R¶

The radius of the ball.

Type:: float

u_s¶

The sliding coefficient of friction.

References

https://ekiefl.github.io/2020/04/24/pooltool-theory/#case-4-sliding

Type:: float

u_r¶

The rolling coefficient of friction.

References

https://ekiefl.github.io/2020/04/24/pooltool-theory/#case-3-rolling

Type:: float

u_sp_proportionality¶

The spinning coefficient of friction, with \(R\) factored out.

See also

For the coefficient of spinning friction, use the property u_sp().

References

https://ekiefl.github.io/2020/04/24/pooltool-theory/#case-2-spinning

Type:: float

u_b¶

The ball-ball coefficient of sliding friction.

Type:: float

e_b¶

The ball-ball coefficient of restitution.

Type:: float

e_c¶

The cushion coefficient of restitution.

Note

This is a potentially model-dependent ball-cushion parameter and should be placed elsewhere, either as a model parameter or as a cushion segment parameter.

Type:: float

f_c¶

The cushion coefficient of friction.

Note

This is a potentially model-dependent ball-cushion parameter and should be placed elsewhere, either as a model parameter or as a cushion segment parameter.

Type:: float

g¶

The gravitational constant.

Type:: float

Most of the default values (SI units) are taken from or based off of https://billiards.colostate.edu/faq/physics/physical-properties/.

Some of the parameters aren’t truly ball parameters, e.g. the gravitational constant. However, it is nice to be able to tune such parameters on a ball-by-ball basis, so they are included here.

property u_sp: float¶

Coefficient of spinning friction

This is equal to u_sp_proportionality * R

Cached Property Note

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

Return type:: float

Methods:

copy() → BallParams[source]¶

Return a copy

Note

Since the class is frozen and its attributes are immutable, this just returns self.

Return type:: BallParams

classmethod default(game_type: pooltool.game.datatypes.GameType = GameType.EIGHTBALL) → BallParams[source]¶

Return prebuilt ball parameters based on game type

Parameters:: game_type (pooltool.game.datatypes.GameType) -- What type of game is being played?
Returns:: The prebuilt ball parameters associated with the passed game type.
Return type:: BallParams

classmethod prebuilt(name: PrebuiltBallParams) → BallParams[source]¶

Return prebuilt ball parameters based on name

Parameters:: name (PrebuiltBallParams) -- A pooltool.objects.PrebuiltBallParams member.
Return type:: BallParams

All prebuilt ball parameters are are members of the pooltool.objects.PrebuiltBallParams Enum. This constructor takes a prebuilt name and returns the corresponding ball parameters.

See also

pooltool.objects.PrebuiltBallParams

class pooltool.objects.PrebuiltBallParams(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

An Enum specifying prebuilt ball parameters.

POOL_GENERIC¶

SNOOKER_GENERIC¶

BILLIARD_GENERIC¶

Bases: pooltool.utils.strenum.StrEnum

class pooltool.objects.BallSet(name: str)[source]¶

A ballset.

What is a ballset?

A ballset specifies the set that a ball belongs to.

Why is it important?

Ballsets are important for properly rendering balls in a scene. By specifying a ballset for a ball, you declare the visual texture / skin that the ball should be wrapped in. If a ball’s ballset is not declared, it will be rendered with the default skin.

What ballsets are available?

See pooltool.objects.get_ballset_names().

Where are ballsets stored?

Each ballset is represented as a subdirectory within the following directory:

$ echo $(python -c "import pooltool; print(pooltool.__file__[:-12])")/models/balls

Each ball model is a .glb file. Its base name represents the model’s ID, and matching ball IDs will be textured by this model. To associate multiple ball IDs to the same model, a conversion.json file is used. For example, see how the generic_snooker ballset matches the red ball IDs to the same model ID:

$ cat $(python -c "import pooltool; print(pooltool.__file__[:-12])")/models/balls/generic_snooker/conversion.json
{
  "red_01": "red",
  "red_02": "red",
  "red_03": "red",
  "red_04": "red",
  "red_05": "red",
  "red_06": "red",
  "red_07": "red",
  "red_08": "red",
  "red_09": "red",
  "red_10": "red",
  "red_11": "red",
  "red_12": "red",
  "red_13": "red",
  "red_14": "red",
  "red_15": "red"
}

name¶

The name of the ballset.

During instantiation, the validity of this name will be checked, and a ValueError will be raised if the ballset doesn’t exist.

Type:: str

property path: pathlib.Path¶

The path of the ballset directory

This directory holds the ball models.

Return type:: pathlib.Path

property ids: list[str]¶

Return type:: list[str]

Methods:

ball_path(id: str) → pathlib.Path[source]¶

The model path used for a given ball ID

Parameters:: id (str) -- The ball ID.
Raises:: ValueError -- If Ball ID doesn’t match to the ballset.
Returns:: The model path.
Return type:: Path

class pooltool.objects.Cue(id: str = 'cue_stick', V0: float = 2.0, phi: float = 0.0, theta: float = 0.0, a: float = 0.0, b: float = 0.25, cue_ball_id: str = 'cue', specs: CueSpecs = NOTHING)[source]¶

A cue stick.

id¶

An ID for the cue.

Type:: str

V0¶

The impact speed.

Units are m/s.

Note

This is the speed of the cue stick upon impact, not the speed of the ball upon impact.

Type:: float

phi¶

The directional strike angle.

The horizontal direction of the cue’s orientation relative to the table layout. Specified in degrees.

If you imagine facing from the head rail (where the cue is positioned for a break shot) towards the foot rail (where the balls are racked),

\(\phi = 0\) corresponds to striking the cue ball to the right
\(\phi = 90\) corresponds to striking the cue ball towards the foot rail
\(\phi = 180\) corresponds to striking the cue ball to the left
\(\phi = 270\) corresponds to striking the cue ball towards the head rail
\(\phi = 360\) corresponds to striking the cue ball to the right

Type:: float

theta¶

The cue inclination angle.

The vertical angle of the cue stick relative to the table surface. Specified in degrees.

\(\theta = 0\) corresponds to striking the cue ball parallel with the table (no massé)
\(\theta = 90\) corresponds to striking the cue ball downwards into the table (max massé)

Type:: float

a¶

The amount and direction of side spin.

\(a = -1\) is the rightmost side of ball
\(a = +1\) is the leftmost side of the ball

Type:: float

b¶

The amount of top/bottom spin.

\(b = -1\) is the bottom-most side of the ball
\(b = +1\) is the top-most side of the ball

Type:: float

cue_ball_id¶

The ball ID of the ball being cued.

Type:: str

specs¶

The cue specs.

Type:: pooltool.objects.cue.datatypes.CueSpecs

Methods:

copy() → Cue[source]¶

Create a copy

Note

specs is shared between self and the copy, but that’s ok because it’s frozen and has no mutable attributes.

Return type:: Cue

reset_state() → None[source]¶

Resets V0, phi, theta, a and b to their defaults.

Set the cueing parameters

Parameters:

V0 (float | None) -- See V0
phi (float | None) -- See phi
theta (float | None) -- See theta
a (float | None) -- See a
b (float | None) -- See b
cue_ball_id (str | None) -- See cue_ball_id

If any arguments are None, they will be left untouched--they will not be set to None.

classmethod default() → Cue[source]¶

Construct a cue with defaults

Return type:: Cue

class pooltool.objects.CueSpecs(brand: str = 'Predator', M: float = 0.567, length: float = 1.4732, tip_radius: float = 0.0106045, shaft_radius_at_tip: float = 0.0065, shaft_radius_at_butt: float = 0.02, end_mass: float = 0.0056699)[source]¶

Cue stick specifications.

All units are SI.

brand¶

The brand.

Type:: str

M¶

The mass.

Type:: float

length¶

The cue length.

Type:: float

tip_radius¶

The cue tip radius.

Type:: float

shaft_radius_at_tip¶

The cue shaft radius near the tip of the cue.

Type:: float

shaft_radius_at_butt¶

The cue shaft radius near the butt of the cue.

Type:: float

end_mass¶

The mass of the of the cue’s end. This controls the amount of deflection (squirt) that occurs when using sidespin. Lower means less deflection. It is defined here: https://billiards.colostate.edu/technical_proofs/new/TP_A-31.pdf.

Type:: float

Methods:

static default() → CueSpecs[source]¶

Construct a default cue spec

Return type:: CueSpecs

abstract static snooker() → CueSpecs[source]¶

Return type:: CueSpecs

class pooltool.objects.TableName(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

An Enum specifying table names.

SEVEN_FOOT_SHOWOOD¶

SNOOKER_GENERIC¶

BILLIARD_WIP¶

SUMTOTHREE_WIP¶

Bases: pooltool.utils.strenum.StrEnum

class pooltool.objects.CircularCushionSegment(id: str, center: ndarray[tuple[int, ...], 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[tuple[int, …], numpy.dtype[numpy.float64]]

radius¶

The radius of the cushion segment.

Type:: float

property 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

property 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

property 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

Methods:

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

static dummy() → CircularCushionSegment[source]¶

Return type:: CircularCushionSegment

class pooltool.objects.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 took up 20% of the function’s runtime, so it was removed.

class pooltool.objects.CushionSegments(linear: dict[str, LinearCushionSegment], circular: dict[str, CircularCushionSegment])[source]¶

A collection of cushion segments

Cushion segments can be either linear (see pooltool.objects.LinearCushionSegment) or circular (see pooltool.objects.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.LinearCushionSegment(id: str, p1: ndarray[tuple[int, ...], dtype[float64]], p2: ndarray[tuple[int, ...], 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[tuple[int, …], 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[tuple[int, …], numpy.dtype[numpy.float64]]

direction¶

The cushion direction (default = pooltool.objects.CushionDirection.BOTH).

See pooltool.objects.CushionDirection for explanation.

Type:: int

property 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

property 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

property 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

property 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

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

Methods:

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.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 pooltool.objects.CircularCushionSegment.get_normal(). Consider using normal() instead.

copy() → LinearCushionSegment[source]¶

Create a copy

Return type:: LinearCushionSegment

static dummy() → LinearCushionSegment[source]¶

Return type:: LinearCushionSegment

class pooltool.objects.Pocket(id: str, center: ndarray[tuple[int, ...], dtype[float64]], radius: float, depth: float = 0.08, contains: set = NOTHING)[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[tuple[int, …], 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

property 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

property 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

Methods:

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

static dummy() → Pocket[source]¶

Return type:: Pocket

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

property has_linear_cushions: bool¶

Return type:: bool

property has_circular_cushions: bool¶

Return type:: bool

property has_pockets: bool¶

Return type:: bool

Methods:

set_cushion_height(height: float) → None[source]¶

Set the height of all cushion segments.

Parameters:: height (float) -- The new height to set for all cushion segments.

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:

pooltool.objects.PocketTableSpecs
pooltool.objects.BilliardTableSpecs
pooltool.objects.SnookerTableSpecs

Returns:

A table matching the specifications of the input.

pooltool.objects.PocketTableSpecs has table_type set to pooltool.objects.TableType.POCKET
pooltool.objects.BilliardTableSpecs has table_type set to pooltool.objects.TableType.BILLIARD
pooltool.objects.SnookerTableSpecs has table_type set to pooltool.objects.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.BilliardTableSpecs(l: float = 2.84, w: float = 1.42, cushion_width: float = 0.0508, cushion_height: float = 0.037, height: float = 0.708, lights_height: float = 1.99, model_descr: TableModelDescr = NOTHING)[source]¶

Parameter specifications for a billiards (pocketless) table.

See also

See the Table Specification resource for visualizations and descriptions of each attribute.
See pooltool.objects.PocketTableSpecs for billiard table specs.
See pooltool.objects.SnookerTableSpecs for snooker table specs.

class pooltool.objects.PocketTableSpecs(l: float = 1.9812, w: float = 0.9906, cushion_width: float = 0.0508, cushion_height: float = 0.036576, corner_pocket_width: float = 0.118, corner_pocket_angle: float = 5.3, corner_pocket_depth: float = 0.0417, corner_pocket_radius: float = 0.062, corner_jaw_radius: float = 0.02095, side_pocket_width: float = 0.137, side_pocket_angle: float = 7.14, side_pocket_depth: float = 0.0685, side_pocket_radius: float = 0.0645, side_jaw_radius: float = 0.00795, height: float = 0.708, lights_height: float = 1.99, model_descr: TableModelDescr = NOTHING)[source]¶

Parameter specifications for a pocket table.

See also

See the Table Specification resource for visualizations and descriptions of each attribute.
See pooltool.objects.BilliardTableSpecs for billiard table specs.
See pooltool.objects.SnookerTableSpecs for snooker table specs.

Default parameters match pooltool.objects.TableName.SEVEN_FOOT_SHOWOOD.

class pooltool.objects.SnookerTableSpecs(l: float = 3.5445, w: float = 1.7465, cushion_width: float = 0.039369999999999995, cushion_height: float = 0.028, corner_pocket_width: float = 0.083, corner_pocket_angle: float = 0, corner_pocket_depth: float = 0.036, corner_pocket_radius: float = 0.1016, corner_jaw_radius: float = 0.1016, side_pocket_width: float = 0.087, side_pocket_angle: float = 0, side_pocket_depth: float = 0.02413, side_pocket_radius: float = 0.042671999999999995, side_jaw_radius: float = 0.0635, height: float = 0.708, lights_height: float = 1.99, model_descr: TableModelDescr = NOTHING)[source]¶

Parameter specifications for a snooker table.

See also

See the Table Specification resource for visualizations and descriptions of each attribute.
See pooltool.objects.BilliardTableSpecs for billiard table specs.
See pooltool.objects.PocketTableSpecs for pocket table specs.

Note

Currently, this class is an identical clone of pooltool.objects.PocketTableSpecs, but with different defaults. That’s not very useful, but it’s likely that some time in the future, snooker tables may have some parameters distinct from standard pool tables (e.g. directional cloth), causing these classes to diverge.

class pooltool.objects.TableModelDescr(name: str)[source]¶

A table model specifier

name¶

The name of the table model.

Type:: str

Methods:

get_path(use_pbr: bool = False) → str[source]¶

Get the path of the model based on PBR preference

The path is searched for in pooltool/models/table/{name}/{name}[_pbr].glb.

Parameters:: use_pbr (bool) -- Whether to use physical based rendering variant
Raises:: ConfigError -- If model path cannot be found from name.
Returns:: A filename specified with Panda3D filename syntax (see https://docs.panda3d.org/1.10/python/programming/advanced-loading/filename-syntax).
Return type:: str

static null() → TableModelDescr[source]¶

Return type:: TableModelDescr

class pooltool.objects.TableType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

An Enum describing the table type.

POCKET¶

BILLIARD¶

SNOOKER¶

OTHER¶

Bases: pooltool.utils.strenum.StrEnum

Functions¶

pooltool.objects.get_ballset(name: str) → BallSet[source]¶

Return the ballset with the given name.

Parameters:: name (str) -- The name of the ballset. To list available ballset names, call pooltool.objects.get_ballset_names().
Raises:: ValueError -- If Ball ID doesn’t match to the ballset.
Returns:: A ballset.
Return type:: BallSet

pooltool.objects.get_ballset_names() → list[str][source]¶

Returns a list of available ballset names

Return type:: list[str]