pooltool.physics.resolve.ball_cushion
=====================================

.. py:module:: pooltool.physics.resolve.ball_cushion

    Models for ball-cushion collisions.
    -----------------------------------
    
    

Subpackages
-----------
.. toctree::
   :titlesonly:
   :maxdepth: 1

   unrealistic/index.rst


Overview
--------

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

   * - :py:obj:`Han2005Circular <pooltool.physics.resolve.ball_cushion.Han2005Circular>`
     - Operations used by every ball-linear cushion collision resolver
   * - :py:obj:`Han2005Linear <pooltool.physics.resolve.ball_cushion.Han2005Linear>`
     - Operations used by every ball-linear cushion collision resolver
   * - :py:obj:`Mathavan2010Circular <pooltool.physics.resolve.ball_cushion.Mathavan2010Circular>`
     - Ball-cushion collision resolver for the Mathavan et al. (2010) collision model.
   * - :py:obj:`Mathavan2010Linear <pooltool.physics.resolve.ball_cushion.Mathavan2010Linear>`
     - Ball-cushion collision resolver for the Mathavan et al. (2010) collision model.
   * - :py:obj:`UnrealisticCircular <pooltool.physics.resolve.ball_cushion.UnrealisticCircular>`
     - Operations used by every ball-linear cushion collision resolver
   * - :py:obj:`UnrealisticLinear <pooltool.physics.resolve.ball_cushion.UnrealisticLinear>`
     - Operations used by every ball-linear cushion collision resolver
   * - :py:obj:`BallCCushionModel <pooltool.physics.resolve.ball_cushion.BallCCushionModel>`
     - An Enum for different ball-circular cushion collision models
   * - :py:obj:`BallLCushionModel <pooltool.physics.resolve.ball_cushion.BallLCushionModel>`
     - An Enum for different ball-linear cushion collision models




Classes
-------
.. autoclass:: Han2005Circular


   Bases: :py:obj:`pooltool.physics.resolve.ball_cushion.core.CoreBallCCushionCollision`




.. autoclass:: Han2005Linear


   Bases: :py:obj:`pooltool.physics.resolve.ball_cushion.core.CoreBallLCushionCollision`




.. autoclass:: Mathavan2010Circular


   Bases: :py:obj:`pooltool.physics.resolve.ball_cushion.core.CoreBallCCushionCollision`



   .. rubric:: Methods:
   .. py:method:: solve(ball: pooltool.objects.ball.datatypes.Ball, cushion: pooltool.objects.table.components.CircularCushionSegment) -> Tuple[pooltool.objects.ball.datatypes.Ball, pooltool.objects.table.components.CircularCushionSegment]

      Resolve ball-cushion collision via Mathavan et al. (2010).

      This method computes the post-collision linear and angular velocities of a ball
      colliding with a cushion, taking into account both ball spin and frictional
      effects. The collision model is based on the theoretical analysis described by
      Mathavan et al., which considers 3D impact dynamics and the effects of topspin
      and sidespin on the rebound trajectory.

      The function analyzes the ball's incident velocity and spin components relative
      to the cushion's normal and tangential planes. It then applies the derived
      differential equations to calculate the collision dynamics through numerical
      integration, accounting for both the compression and restitution phases of
      impact. The model incorporates the sliding coefficient of friction between ball
      and cushion as well as between ball and table, along with the coefficient of
      restitution. Once the complete impulse exchange is calculated, the updated
      linear and angular velocities are determined and returned.

      The model assumes insignificant cushion deformation, which is reported to be
      valid for normal velocities up to 2.5 m/s, and accounts for transitions between
      sliding and rolling states during collision.



.. autoclass:: Mathavan2010Linear


   Bases: :py:obj:`pooltool.physics.resolve.ball_cushion.core.CoreBallLCushionCollision`



   .. rubric:: Methods:
   .. py:method:: solve(ball: pooltool.objects.ball.datatypes.Ball, cushion: pooltool.objects.table.components.LinearCushionSegment) -> Tuple[pooltool.objects.ball.datatypes.Ball, pooltool.objects.table.components.LinearCushionSegment]

      Resolve ball-cushion collision via Mathavan et al. (2010).

      This method computes the post-collision linear and angular velocities of a ball
      colliding with a cushion, taking into account both ball spin and frictional
      effects. The collision model is based on the theoretical analysis described by
      Mathavan et al., which considers 3D impact dynamics and the effects of topspin
      and sidespin on the rebound trajectory.

      The function analyzes the ball's incident velocity and spin components relative
      to the cushion's normal and tangential planes. It then applies the derived
      differential equations to calculate the collision dynamics through numerical
      integration, accounting for both the compression and restitution phases of
      impact. The model incorporates the sliding coefficient of friction between ball
      and cushion as well as between ball and table, along with the coefficient of
      restitution. Once the complete impulse exchange is calculated, the updated
      linear and angular velocities are determined and returned.

      The model assumes insignificant cushion deformation, which is reported to be
      valid for normal velocities up to 2.5 m/s, and accounts for transitions between
      sliding and rolling states during collision.



.. autoclass:: UnrealisticCircular


   Bases: :py:obj:`pooltool.physics.resolve.ball_cushion.core.CoreBallCCushionCollision`




.. autoclass:: UnrealisticLinear


   Bases: :py:obj:`pooltool.physics.resolve.ball_cushion.core.CoreBallLCushionCollision`




.. autoclass:: BallCCushionModel


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




.. autoclass:: BallLCushionModel


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