pooltool.layouts

Functions and utilities for creating ball predetermined ball layouts

Overview

Classes

Dir

Movement directions

Pos

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

BallPos

A subclass of Pos with ball id info
Function

ball_cluster_blueprint(seed, jump_sequence)

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

generate_layout(blueprint, table, ballset, ball_params, spacing_factor, seed)

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

get_rack(game_type, table, ball_params, ballset, spacing_factor)

Generate a ball rack.

Classes

class pooltool.layouts.Dir(value)[source]

Movement directions

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

Bases: pooltool.utils.strenum.StrEnum

class pooltool.layouts.Pos(loc: List[Dir], relative_to: Pos | Tuple[float, float])[source]

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

loc

A sequence of translations.

Type:

List[pooltool.layouts.Dir]

relative_to

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.

Type:

pooltool.layouts.Pos | Tuple[float, float]

class pooltool.layouts.BallPos(loc: List[Dir], relative_to: Pos | Tuple[float, float], ids: Set[str])[source]

A subclass of Pos with ball id info

ids

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

Type:

Set[str]

Bases: Pos

Functions

pooltool.layouts.ball_cluster_blueprint(seed: BallPos, jump_sequence: JumpSequence) → List[BallPos][source]

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

Return type:

List[BallPos]

pooltool.layouts.generate_layout(blueprint: List[BallPos], table: pooltool.objects.table.datatypes.Table, ballset: pooltool.objects.ball.sets.BallSet | None = None, ball_params: pooltool.objects.ball.datatypes.BallParams | None = None, spacing_factor: float = 0.001, seed: int | None = None) → Dict[str, pooltool.objects.ball.datatypes.Ball][source]

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 (pooltool.objects.table.datatypes.Table) -- A Table. This must exist so the rack can be created with respect to the table’s dimensions.

  • ball_params (Optional[pooltool.objects.ball.datatypes.BallParams]) -- 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 (Optional[int]) -- 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).

pooltool.layouts.get_rack(game_type: pooltool.game.datatypes.GameType, table: pooltool.objects.table.datatypes.Table, ball_params: pooltool.objects.ball.datatypes.BallParams | None = None, ballset: pooltool.objects.ball.sets.BallSet | None = None, spacing_factor: float = 0.001) → Dict[str, pooltool.objects.ball.datatypes.Ball][source]

Generate a ball rack.

This function ultimately delegates to generate_layout().

Parameters:

  • game_type (pooltool.game.datatypes.GameType) -- The game type being played. This will determine what rack is returned.

  • table (pooltool.objects.table.datatypes.Table) -- A table. This must exist so the rack can be created with respect to the table’s dimensions.

  • ball_params (Optional[pooltool.objects.ball.datatypes.BallParams]) -- 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]