pooltool.layouts

Functions and utilities for creating ball predetermined ball layouts

Classes

class Dir

Movement directions

The diagonal positions are not true diagonals (45 degrees), but rather the diagonals seen when creating a triangular rack pattern (60 degrees).

property translation_map: dict[Dir, tuple[float, float]]

Return type:

dict[Dir, tuple[float, float]]

Base Classes:

pooltool.utils.strenum.StrEnum

class Jump

Methods:

static LEFT(quantity: int = 1) → list[Translation]

Return type:

list[Translation]

static RIGHT(quantity: int = 1) → list[Translation]

Return type:

list[Translation]

static UP(quantity: int = 1) → list[Translation]

Return type:

list[Translation]

static DOWN(quantity: int = 1) → list[Translation]

Return type:

list[Translation]

static UPLEFT(quantity: int = 1) → list[Translation]

Return type:

list[Translation]

static UPRIGHT(quantity: int = 1) → list[Translation]

Return type:

list[Translation]

static DOWNRIGHT(quantity: int = 1) → list[Translation]

Return type:

list[Translation]

static DOWNLEFT(quantity: int = 1) → list[Translation]

Return type:

list[Translation]

static ANGLE(degrees: float, quantity: int = 1) → list[Translation]

Return type:

list[Translation]

static eval(translations: list[Translation], radius: float) → tuple[float, float]

Return type:

tuple[float, float]

class Pos(loc: list[Translation], relative_to: Pos | tuple[float, float])

Defines a position relative to another position, or a 2D table coordinate

Attributes:

loc : list[Dir | float]

A sequence of translations. Each translation is either a Dir enum for discrete directions, or a float representing an angle in radians (0 = right, pi/2 = up). Use Jump.ANGLE(degrees) for convenience.

relative_to : Pos | tuple[float, float]

This defines what the translation is with respect to. This can either be another Pos, or a 2D coordinate, normalized by the table’s width and height. The origin is the bottom-left corner of the table, so (0.0, 0.0) is bottom-left and (1.0, 1.0) is top right.

class BallPos(loc: list[Dir | float], relative_to: Pos | tuple[float, float], ids: set[str])

A subclass of Pos with ball id info

Base Classes:

Pos

Attributes:

ids : set[str]

This set says which ball ids can exist at the given position.

Functions

ball_cluster_blueprint(seed: BallPos, jump_sequence: JumpSequence) → list[BallPos]

Define a blueprint with a seed ball position and a sequence of quantized jumps

Return type:

list[BallPos]

generate_layout(blueprint: list[BallPos], table: Table, ballset: BallSet | None = None, ball_params: BallParams | None = None, spacing_factor: float = 0.001, seed: int | None = None) → dict[str, Ball]

Generate Ball objects based on a given blueprint and table dimensions.

The function calculates the absolute position of each ball on the table using the translations provided in the blueprint relative to table anchors. It then randomly assigns ball IDs to each position, ensuring no ball ID is used more than once.

Parameters:

• blueprint : list[BallPos]

  A list of ball positions represented as BallPos objects, which describe their location relative to table anchors or other positions.

• table : Table

  A Table. This must exist so the rack can be created with respect to the table’s dimensions.

• ball_params : BallParams | None

  A BallParams object, which all balls will be created with. This contains info like ball radius.

• spacing_factor : float

  This factor adjusts the spacing between balls to ensure they do not touch each other directly. Instead of being in direct contact, each ball is allocated within a larger, virtual radius defined as (1 + spacing_factor) * R, where R represents the actual radius of the ball. Within this expanded radius, the ball’s position is determined randomly, allowing for a controlled separation between each ball. The spacing_factor therefore dictates the degree of this separation, with higher values resulting in greater distances between adjacent balls. Setting this to 0 is not recommended.

• seed : int | None

  Set a seed for reproducibility. That’s because getting a rack involves two random procedures. First, some ball positions can be satisfied with many different ball IDs. For example, in 9 ball, only the 1 ball and 9 ball are predetermined, the positions of the other balls are random. The second source of randomnness is from spacing_factor.

Returns:

A dictionary mapping ball IDs to their respective Ball objects, with their absolute positions on the table.

Return type:

Dict[str, Ball]

Notes

• The table dimensions are normalized such that the bottom-left corner is (0.0, 0.0) and the top-right corner is (1.0, 1.0).

get_rack(game_type: GameType, table: Table, ball_params: BallParams | None = None, ballset: BallSet | None = None, spacing_factor: float = 0.001) → dict[str, Ball]

Generate a ball rack.

This function ultimately delegates to pooltool.layouts.generate_layout().

Parameters:

• game_type : GameType

  The game type being played. This will determine what rack is returned.

• table : Table

  A table. This must exist so the rack can be created with respect to the table’s dimensions.

• ball_params : BallParams | None

  Ball parameters that all balls will be created with.

• spacing_factor : float

  This factor adjusts the spacing between balls to ensure they do not touch each other directly. Instead of being in direct contact, each ball is allocated within a larger, virtual radius defined as (1 + spacing_factor) * R, where R represents the actual radius of the ball. Within this expanded radius, the ball’s position is determined randomly, allowing for a controlled separation between each ball. The spacing_factor therefore dictates the degree of this separation, with higher values resulting in greater distances between adjacent balls. Setting this to 0 is not recommended.

Returns:

A dictionary mapping ball IDs to their respective Ball objects, with their absolute positions on the table.

Return type:

Dict[str, Ball]

Attributes

DEFAULT_STANDARD_BALLSET

DEFAULT_SNOOKER_BALLSET

DEFAULT_THREECUSH_BALLSET

DEFAULT_SUMTOTHREE_BALLSET = 'None'

Translation