pooltool.physics.resolve.ball_cushion

Models for ball-cushion collisions.

Subpackages

• pooltool.physics.resolve.ball_cushion.unrealistic

Overview

Classes

Han2005Circular	Operations used by every ball-linear cushion collision resolver
Han2005Linear	Operations used by every ball-linear cushion collision resolver
Mathavan2010Circular	Ball-cushion collision resolver for the Mathavan et al. (2010) collision model.
Mathavan2010Linear	Ball-cushion collision resolver for the Mathavan et al. (2010) collision model.
UnrealisticCircular	Operations used by every ball-linear cushion collision resolver
UnrealisticLinear	Operations used by every ball-linear cushion collision resolver
BallCCushionModel	An Enum for different ball-circular cushion collision models
BallLCushionModel	An Enum for different ball-linear cushion collision models

Classes

class pooltool.physics.resolve.ball_cushion.Han2005Circular

Bases: pooltool.physics.resolve.ball_cushion.core.CoreBallCCushionCollision

class pooltool.physics.resolve.ball_cushion.Han2005Linear

Bases: pooltool.physics.resolve.ball_cushion.core.CoreBallLCushionCollision

class pooltool.physics.resolve.ball_cushion.Mathavan2010Circular(max_steps: int = 1000, delta_p: float = 0.001)

Ball-cushion collision resolver for the Mathavan et al. (2010) collision model.

This work predicts ball bounce angles and bounce speeds for the ball’s collisions with a cushion, under the assumption of insignificant cushion deformation. Differential equations are derived for the ball dynamics during the impact and these these equations are solved numerically.

References

Mathavan S, Jackson MR, Parkin RM. A theoretical analysis of billiard ball-cushion dynamics under cushion impacts. Proceedings of the Institution of Mechanical Engineers, Part C. 2010;224(9):1863-1873. doi:10.1243/09544062JMES1964

Available at https://drdavepoolinfo.com//physics_articles/Mathavan_IMechE_2010.pdf

Bases: pooltool.physics.resolve.ball_cushion.core.CoreBallCCushionCollision

Methods:

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.

Return type:

Tuple[pooltool.objects.ball.datatypes.Ball, pooltool.objects.table.components.CircularCushionSegment]

class pooltool.physics.resolve.ball_cushion.Mathavan2010Linear(max_steps: int = 1000, delta_p: float = 0.001)

Ball-cushion collision resolver for the Mathavan et al. (2010) collision model.

This work predicts ball bounce angles and bounce speeds for the ball’s collisions with a cushion, under the assumption of insignificant cushion deformation. Differential equations are derived for the ball dynamics during the impact and these these equations are solved numerically.

References

Mathavan S, Jackson MR, Parkin RM. A theoretical analysis of billiard ball-cushion dynamics under cushion impacts. Proceedings of the Institution of Mechanical Engineers, Part C. 2010;224(9):1863-1873. doi:10.1243/09544062JMES1964

Available at https://drdavepoolinfo.com//physics_articles/Mathavan_IMechE_2010.pdf

Bases: pooltool.physics.resolve.ball_cushion.core.CoreBallLCushionCollision

Methods:

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.

Return type:

Tuple[pooltool.objects.ball.datatypes.Ball, pooltool.objects.table.components.LinearCushionSegment]

class pooltool.physics.resolve.ball_cushion.UnrealisticCircular(restitution: bool = False)

Bases: pooltool.physics.resolve.ball_cushion.core.CoreBallCCushionCollision

class pooltool.physics.resolve.ball_cushion.UnrealisticLinear(restitution: bool = False)

Bases: pooltool.physics.resolve.ball_cushion.core.CoreBallLCushionCollision

class pooltool.physics.resolve.ball_cushion.BallCCushionModel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

An Enum for different ball-circular cushion collision models

HAN_2005

https://ekiefl.github.io/2020/04/24/pooltool-theory/#3-han-2005

UNREALISTIC

An unrealistic model in which balls are perfectly reflected. Spin is left untouched by the interaction.

Bases: pooltool.utils.strenum.StrEnum

class pooltool.physics.resolve.ball_cushion.BallLCushionModel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

An Enum for different ball-linear cushion collision models

HAN_2005

https://ekiefl.github.io/2020/04/24/pooltool-theory/#3-han-2005.

UNREALISTIC

An unrealistic model in which balls are perfectly reflected. Spin is left untouched by the interaction.

Bases: pooltool.utils.strenum.StrEnum