pooltool.layouts ================ .. py:module:: pooltool.layouts Functions and utilities for creating ball predetermined ball layouts -------------------------------------------------------------------- Overview -------- .. list-table:: Classes :header-rows: 0 :widths: auto :class: summarytable * - :py:obj:`Dir ` - Movement directions * - :py:obj:`Pos ` - Defines a position relative to another position, or a 2D table coordinate * - :py:obj:`BallPos ` - A subclass of Pos with ball id info .. list-table:: Function :header-rows: 0 :widths: auto :class: summarytable * - :py:obj:`ball_cluster_blueprint `\ (seed, jump_sequence) - Define a blueprint with a seed ball position and a sequence of quantized jumps * - :py:obj:`generate_layout `\ (blueprint, table, ballset, ball_params, spacing_factor, seed) - Generate Ball objects based on a given blueprint and table dimensions. * - :py:obj:`get_rack `\ (game_type, table, ball_params, ballset, spacing_factor) - Generate a ball rack. Classes ------- .. autoclass:: Dir Bases: :py:obj:`pooltool.utils.strenum.StrEnum` .. autoclass:: Pos .. autoclass:: BallPos Bases: :py:obj:`Pos` Functions --------- .. py:function:: ball_cluster_blueprint(seed: BallPos, jump_sequence: JumpSequence) -> List[BallPos] Define a blueprint with a seed ball position and a sequence of quantized jumps .. py:function:: generate_layout(blueprint: List[BallPos], table: pooltool.objects.table.datatypes.Table, ballset: Optional[pooltool.objects.ball.sets.BallSet] = None, ball_params: Optional[pooltool.objects.ball.datatypes.BallParams] = None, spacing_factor: float = 0.001, seed: Optional[int] = None) -> Dict[str, pooltool.objects.ball.datatypes.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. :param blueprint: A list of ball positions represented as BallPos objects, which describe their location relative to table anchors or other positions. :param table: A Table. This must exist so the rack can be created with respect to the table's dimensions. :param ball_params: A BallParams object, which all balls will be created with. This contains info like ball radius. :param spacing_factor: 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. :param seed: 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. :rtype: Dict[str, Ball] .. admonition:: 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). .. py:function:: get_rack(game_type: pooltool.game.datatypes.GameType, table: pooltool.objects.table.datatypes.Table, ball_params: Optional[pooltool.objects.ball.datatypes.BallParams] = None, ballset: Optional[pooltool.objects.ball.sets.BallSet] = None, spacing_factor: float = 0.001) -> Dict[str, pooltool.objects.ball.datatypes.Ball] Generate a ball rack. This function ultimately delegates to :func:`generate_layout`. :param game_type: The game type being played. This will determine what rack is returned. :param table: A table. This must exist so the rack can be created with respect to the table's dimensions. :param ball_params: Ball parameters that all balls will be created with. :param spacing_factor: 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. :rtype: Dict[str, Ball]