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¶
A billiards ball |
|
Holds a ball’s state |
|
A circular pocket |
|
Enum where members are also (and must be) strings |
|
Ball-pocket collision models must satisfy this protocol |
|
An Enum for different ball-pocket collision models |
|
Returns a ball-pocket collision model |
Classes¶
- class pooltool.physics.resolve.ball_pocket.Ball(id: str, state: BallState = BallState.default, params: BallParams = BallParams.default, ballset: BallSet | None = None, initial_orientation: BallOrientation = BallOrientation.random, history: BallHistory = BallHistory.factory, history_cts: BallHistory = BallHistory.factory)[source]¶
A billiards ball
This class represents a billiards ball. It stores its parameters (mass, radius, etc.), it’s state (coordinates, velocity, spin, etc), its history (a time-resolved trajectory of its state), amongst other things.
- state¶
The ball’s state.
This is the current state of the ball.
See also
See the Important section in
Ball
for a description of the role ofstates
during simulation.
- params¶
The ball’s physical parameters.
The physical parameters of the ball.
- ballset¶
The ball set that the ball belongs to.
Important if rendering the ball in a scene.
See also
See
Ball.set_ballset()
for details
- Type:
- initial_orientation¶
The initial rendered orientation of the ball.
Important if rendering the ball in a scene.
This is the orientation of the ball at \(t = 0\).
- history¶
The ball’s state history
The historical states of the ball from \(t_{initial}\) to \(t_{final}\).
See also
See the Important section in
Ball
for a description of the role ofhistory
during simulation.
- history_cts¶
The ball’s continuous state history
The historical states of the ball from \(t_{initial}\) to \(t_{final}\) densely sampled with respect to time.
See also
See
pooltool.evolution.event_based.continuize.continuize()
for a details about continuizing a simulated system.See the Important section in
Ball
for a description of the role ofhistory_cts
during simulation.
Important
To instantiate this class, consider using the
create()
constructor. Or, use functions withinpooltool.layouts
to generate entire collection of balls. Or, of course, construct as normal with__init__
.Important
The following explains how a
Ball
object is modified when its parent system is simulated (pooltool.evolution.event_based.simulate.simulate()
).At the start of the simulation process,
state
represents the ball state at \(t = 0\). A copy ofstate
is appended tohistory
.For each timestep of the simulation,
state
is used to inform how the system should advance forward in time. Once determined,state
is updated to reflect the ball’s new state. A copy ofstate
is appended tohistory
.When the simulation is finished,
state
represents the final resting state of the ball. So too doeshistory[-1]
.Finally, if the system is continuized (see
pooltool.evolution.continuize.continuize()
),history_cts
is populated. Otherwise it remains empty.- property xyz¶
The displacement (from origin) vector of the ball.
A shortcut for
self.state.rvw[0]
.
- property vel¶
The velocity vector of the ball.
A shortcut for
self.state.rvw[1]
.
- property avel¶
The angular velocity vector of the ball.
A shortcut for
self.state.rvw[2]
.
Methods:
- set_ballset(ballset: pooltool.objects.ball.sets.BallSet) None [source]¶
Update the ballset
- Raises:
ValueError -- If the ball ID doesn’t match to a model name of the ballset.
See also
See
pooltool.objects.ball.sets
for details about ball sets.See
pooltool.system.datatypes.System.set_ballset()
for setting the ballset for all the balls in a system.
- copy(drop_history: bool = False) Ball [source]¶
Create a copy
- Parameters:
drop_history (bool) -- If True, the returned copy
history
andhistory_cts
attributes are both set to emptyBallHistory
objects.- Return type:
- static create(id: str, *, xy: Sequence[float] | None = None, ballset: pooltool.objects.ball.sets.BallSet | None = None, **kwargs) Ball [source]¶
Create a ball using keyword arguments.
This constructor flattens the tunable parameter space, allowing one to construct a
Ball
without directly instancing objects like likepooltool.objects.balls.params.BallParams
andBallState
.- Parameters:
xy (Optional[Sequence[float]]) -- The x and y coordinates of the ball position.
ballset (Optional[pooltool.objects.ball.sets.BallSet]) -- A ballset.
**kwargs -- Arguments accepted by
pooltool.objects.balls.params.BallParams
- Return type:
- class pooltool.physics.resolve.ball_pocket.BallState(rvw: ndarray[Any, dtype[float64]], s, t=0)[source]¶
Holds a ball’s state
The ball’s state is defined (1) the kinematic state of the ball, (2) a label specifying the ball’s motion state, and (3) the point in time that the ball exists in.
- rvw¶
The kinematic state of the ball.
rvw
is a \(3\times3\) matrix that stores the 3 vectors that characterize a ball’s kinematic state:\(r\): The displacement (from origin) vector (accessed with
rvw[0]
)\(v\): The velocity vector (accessed with
rvw[1]
)\(w\): The angular velocity vector (accessed with
rvw[2]
)
- Type:
numpy.ndarray[Any, numpy.dtype[numpy.float64]]
- s¶
The motion state label of the ball.
s
is an integer corresponding to the following motion state labels:0 = stationary 1 = spinning 2 = sliding 3 = rolling 4 = pocketed
- Type:
Methods:
- class pooltool.physics.resolve.ball_pocket.Pocket(id: str, center: ndarray[Any, dtype[float64]], radius: float, depth: float = 0.08, contains: set = UNKNOWN)[source]¶
A circular pocket
- center¶
A length-3 array specifying the pocket’s position.
center[0]
is the x-coordinate of the pocket’s centercenter[1]
is the y-coordinate of the pocket’s centercenter[2]
must be 0.0
- Type:
numpy.ndarray[Any, numpy.dtype[numpy.float64]]
Methods:
- a() float ¶
The x-coordinate of the pocket’s center
Cached Property Note
This is a cached property, and should be accessed as an attribute, not as a method call.
- Return type:
- b() float ¶
The y-coordinate of the pocket’s center
Cached Property Note
This is a cached property, and should be accessed as an attribute, not as a method call.
- Return type:
- class pooltool.physics.resolve.ball_pocket.StrEnum(value)[source]¶
Enum where members are also (and must be) strings
- class pooltool.physics.resolve.ball_pocket.BallPocketStrategy(*args, **kwargs)[source]¶
Ball-pocket collision models must satisfy this protocol
Bases:
Protocol
Methods:
- 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] [source]¶
This method resolves a ball-circular cushion collision
- Return type:
Tuple[pooltool.objects.ball.datatypes.Ball, pooltool.objects.table.components.Pocket]
Functions¶
- pooltool.physics.resolve.ball_pocket.get_ball_pocket_model(model: BallPocketModel | None = None, params: pooltool.physics.resolve.types.ModelArgs = {}) BallPocketStrategy [source]¶
Returns a ball-pocket collision model
- Parameters:
model (Optional[BallPocketModel]) -- An Enum specifying the desired model. If not passed,
CanonicalBallPocket
is passed with empty params.params (pooltool.physics.resolve.types.ModelArgs) -- A mapping of parameters accepted by the model.
- Returns:
An instantiated model that satisfies the
BallPocketStrategy
protocol.- Return type:
Attributes¶
- pooltool.physics.resolve.ball_pocket.ModelArgs¶
A mapping of argument names to argument values