Hello World¶

The Interface can be accessed not just from the command line, but also programmatically. In this section, you’ll create a script that creates a billiards system, simulates it, and then visualizes it with the interface.

Consider this hello world for pooltool.

Script¶

For those that want to jump straight in, here is the script:

#! /usr/bin/env python

import pooltool as pt

# We need a table, some balls, and a cue stick
table = pt.Table.default()
balls = pt.get_rack(pt.GameType.NINEBALL, table)
cue = pt.Cue(cue_ball_id="cue")

# Wrap it up as a System
shot = pt.System(table=table, balls=balls, cue=cue)

# Aim at the head ball with a strong impact
shot.cue.set_state(V0=8, phi=pt.aim.at_ball(shot, "1"))

# Evolve the shot.
pt.simulate(shot, inplace=True)

# Open up the shot in the GUI
interface = pt.ShotViewer()
interface.show(shot)

For those interested in some exposition, below is a line-by-line explanation.

Explanation¶

First thing first, the pootool package is imported which gives you access to the top-level API:

import pooltool as pt

Then a table, a cue stick, and a collection of balls are created and wrapped up into a pooltool.system.datatypes.System:

# We need a table, some balls, and a cue stick
table = pt.Table.default()
balls = pt.get_rack(pt.GameType.NINEBALL, table)
cue = pt.Cue(cue_ball_id="cue")

# Wrap it up as a System
shot = pt.System(table=table, balls=balls, cue=cue)

The cue stick parameters are then set with pooltool.objects.cue.datatypes.Cue.set_state. A large impact speed of V0=8 (m/s) is chosen, and an aiming utility function is used to aim the cue ball directly at the one-ball.

# Aim at the head ball with a strong impact
shot.cue.set_state(V0=8, phi=pt.aim.at_ball(shot, "1"))

Cue Signature

A description of the cue’s parameters can be found in the API docs:

class pooltool.objects.cue.datatypes.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 = CueSpecs.default)[source]

A cue stick

id

An ID for the cue.

Type:: str

V0

The impact speed.

Units are m/s.

Warning: 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

The cue parameters have been set, but the system still hasn’t been simulated. This is done with a call to pooltool.evolution.event_based.simulate.simulate:

# Evolve the shot.
pt.simulate(shot, inplace=True)

The system has now been evolved from its initial to its final state.

To visualize the shot, open the GUI with pooltool.interact.ShotViewer:

# Open up the shot in the GUI
interface = pt.ShotViewer()
interface.show(shot)

Next¶

Obviously this script is just the beginning. Pooltool offers much more than this, which means you have much more to learn. From here, I suggest you check out the Resources page and dive into whatever topic interests you.