pooltool.physics.resolve.ball_pocket
====================================

.. py:module:: pooltool.physics.resolve.ball_pocket

    Defining and handling ball pocket collisions
    --------------------------------------------
    
    
    .. note::
    
       If this module is ever extended to support multiple treatments for ball pocket
       collisions, expand this file into a file structure modelled after ../ball_ball or
       ../ball_cushion
    

Overview
--------

.. list-table:: Classes
   :header-rows: 0
   :widths: auto
   :class: summarytable

   * - :py:obj:`Ball <pooltool.physics.resolve.ball_pocket.Ball>`
     - A billiards ball
   * - :py:obj:`BallState <pooltool.physics.resolve.ball_pocket.BallState>`
     - Holds a ball's state
   * - :py:obj:`Pocket <pooltool.physics.resolve.ball_pocket.Pocket>`
     - A circular pocket
   * - :py:obj:`StrEnum <pooltool.physics.resolve.ball_pocket.StrEnum>`
     - Enum where members are also (and must be) strings
   * - :py:obj:`BallPocketStrategy <pooltool.physics.resolve.ball_pocket.BallPocketStrategy>`
     - Ball-pocket collision models must satisfy this protocol
   * - :py:obj:`BallPocketModel <pooltool.physics.resolve.ball_pocket.BallPocketModel>`
     - An Enum for different ball-pocket collision models


.. list-table:: Function
   :header-rows: 0
   :widths: auto
   :class: summarytable

   * - :py:obj:`get_ball_pocket_model <pooltool.physics.resolve.ball_pocket.get_ball_pocket_model>`\ (model, params)
     - Returns a ball-pocket collision model


.. list-table:: Attributes
   :header-rows: 0
   :widths: auto
   :class: summarytable

   * - :py:obj:`ModelArgs <pooltool.physics.resolve.ball_pocket.ModelArgs>`
     - A mapping of argument names to argument values


Classes
-------
.. autoclass:: Ball


   .. py:property:: xyz

      The displacement (from origin) vector of the ball.

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

   .. py:property:: vel

      The velocity vector of the ball.

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

   .. py:property:: avel

      The angular velocity vector of the ball.

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



   .. rubric:: Methods:
   .. py:method:: set_ballset(ballset: pooltool.objects.ball.sets.BallSet) -> None

      Update the ballset

      :raises ValueError: If the ball ID doesn't match to a model name of the ballset.

      .. seealso::

         - See :mod:`pooltool.objects.ball.sets` for details about ball sets.
         - See :meth:`pooltool.system.datatypes.System.set_ballset` for setting the
           ballset for all the balls in a system.


   .. py:method:: copy(drop_history: bool = False) -> Ball

      Create a copy

      :param drop_history: If True, the returned copy :attr:`history` and :attr:`history_cts`
                           attributes are both set to empty :class:`BallHistory` objects.


   .. py:method:: create(id: str, *, xy: Optional[Sequence[float]] = None, ballset: Optional[pooltool.objects.ball.sets.BallSet] = None, **kwargs) -> Ball
      :staticmethod:

      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
      :class:`pooltool.objects.balls.params.BallParams` and :class:`BallState`.

      :param xy: The x and y coordinates of the ball position.
      :param ballset: A ballset.
      :param \*\*kwargs: Arguments accepted by :class:`pooltool.objects.balls.params.BallParams`



.. autoclass:: BallState




   .. rubric:: Methods:
   .. py:method:: copy() -> BallState

      Create a copy


   .. py:method:: default() -> BallState
      :staticmethod:

      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)
      :rtype: BallState



.. autoclass:: Pocket


   .. py:property:: a
      :type: float

      The x-coordinate of the pocket's center

      .. cached_property_note::

   .. py:property:: b
      :type: float

      The y-coordinate of the pocket's center

      .. cached_property_note::



   .. rubric:: Methods:
   .. py:method:: add(ball_id: str) -> None

      Add a ball ID to :attr:`contains`


   .. py:method:: remove(ball_id: str) -> None

      Remove a ball ID from :attr:`contains`


   .. py:method:: copy() -> Pocket

      Create a copy



.. autoclass:: StrEnum


   Bases: :py:obj:`str`, :py:obj:`enum.Enum`




.. autoclass:: BallPocketStrategy


   Bases: :py:obj:`Protocol`



   .. rubric:: Methods:
   .. py:method:: resolve(ball: pooltool.objects.ball.datatypes.Ball, pocket: pooltool.objects.table.components.Pocket, inplace: bool = False) -> Tuple[pooltool.objects.ball.datatypes.Ball, pooltool.objects.table.components.Pocket]

      This method resolves a ball-circular cushion collision



.. autoclass:: BallPocketModel


   Bases: :py:obj:`pooltool.utils.strenum.StrEnum`





Functions
---------
.. py:function:: get_ball_pocket_model(model: Optional[BallPocketModel] = None, params: pooltool.physics.resolve.types.ModelArgs = {}) -> BallPocketStrategy

   Returns a ball-pocket collision model

   :param model: An Enum specifying the desired model. If not passed,
                 :class:`CanonicalBallPocket` is passed with empty params.
   :param params: A mapping of parameters accepted by the model.

   :returns: An instantiated model that satisfies the :class:`BallPocketStrategy` protocol.



Attributes
----------
.. py:data:: ModelArgs

   A mapping of argument names to argument values