pooltool.events¶

Event, detection, and filtration¶

See here to learn about events and why they matter.

Submodules¶

pooltool.events.factory

Overview¶

Classes¶
`Agent`	An event agent.
`AgentType`	An Enum of event agents
`Event`	Represents an event.
`EventType`	An Enum of event types

Function¶
`ball_ball_collision`(ball1, ball2, time, set_initial)	Create a ball-ball collision.
`ball_circular_cushion_collision`(ball, cushion, time, set_initial)	Create a ball-circular-cushion collision.
`ball_linear_cushion_collision`(ball, cushion, time, set_initial)	Create a ball-linear-cushion collision.
`ball_pocket_collision`(ball, pocket, time, set_initial)	Create a ball-pocket collision.
`null_event`(time, set_initial)	Create a null event.
`rolling_spinning_transition`(ball, time, set_initial)	Create a rolling-spinning transition.
`rolling_stationary_transition`(ball, time, set_initial)	Create a rolling-stationary transition.
`sliding_rolling_transition`(ball, time, set_initial)	Create a sliding-rolling transition.
`spinning_stationary_transition`(ball, time, set_initial)	Create a spinning-stationary transition.
`stick_ball_collision`(stick, ball, time, set_initial)	Create a cue stick-ball collision.
`by_ball`(ball_ids, keep_nonevent)	Returns a function that filters events based on ball IDs.
`by_time`(t, after)	Returns a function that filter events with respect to a time cutoff.
`by_type`(types)	Returns a function that filters events based on event type.
`filter_ball`(events, ball_ids, keep_nonevent)	Filter events based on ball IDs.
`filter_events`(events, *funcs)	Filter events using multiple criteria.
`filter_time`(events, t, after)	Filter events with respect to a time cutoff.
`filter_type`(events, types)	Filter events based on event type.

Classes¶

An event agent.

This class represents an agent involved in events. The agent can be in different states before and after an event, represented by initial and final states.

id¶

ID for the agent.

Type:: str

agent_type¶

The type of the agent.

Type:: pooltool.events.datatypes.AgentType

initial¶

The state of the agent before an event.

Type:: pooltool.objects.datatypes.NullObject | pooltool.objects.cue.datatypes.Cue | pooltool.objects.ball.datatypes.Ball | pooltool.objects.table.components.Pocket | pooltool.objects.table.components.LinearCushionSegment | pooltool.objects.table.components.CircularCushionSegment | None

final¶

The state of the agent after an event.

Type:: pooltool.objects.datatypes.NullObject | pooltool.objects.cue.datatypes.Cue | pooltool.objects.ball.datatypes.Ball | pooltool.objects.table.components.Pocket | pooltool.objects.table.components.LinearCushionSegment | pooltool.objects.table.components.CircularCushionSegment | None

Methods:

set_initial(obj: Object) → None[source]¶

Sets the initial state of the agent (before event resolution).

This makes a copy of the passed object and sets it to initial.

In the case of a AgentType.BALL agent type, it drops history fields before copying to save time and memory.

Parameters:: obj (Object) -- The object from which initial will be set.

set_final(obj: Object) → None[source]¶

Sets the final state of the agent (after event resolution).

This makes a copy of the passed object and sets it to final.

In the case of a AgentType.BALL agent type, it drops history fields before copying to save time and memory.

Parameters:: obj (Object) -- The object from which final will be set.

matches(obj: Object) → bool[source]¶

Determines if the given object matches the agent.

It checks if the object is of the correct class type and if the IDs match.

Parameters:: obj (Object) -- The object to compare with the agent.
Returns:: True if the object’s class type and ID match the agent’s type and ID, False otherwise.
Return type:: bool

static from_object(obj: Object, set_initial: bool = False) → Agent[source]¶

Creates an agent instance from an object.

Optionally sets the initial state of the agent based on the provided object. The final state is not set.

Parameters:

obj (Object) -- The object to create the agent from.
set_initial (bool) -- If True, sets the initial state of the agent to the object’s state.

Returns:

A new instance of Agent.

Return type:

Agent

copy() → Agent[source]¶

Create a copy.

Return type:: Agent

class pooltool.events.AgentType(value)[source]¶

An Enum of event agents

NULL¶: A null agent.

CUE¶: A cue stick agent.

BALL¶: A ball agent.

POCKET¶: A pocket agent.

LINEAR_CUSHION_SEGMENT¶: A linear cushion segment agent.

CIRCULAR_CUSHION_SEGMENT¶: A circular cushion segment agent.

Bases: pooltool.utils.strenum.StrEnum

class pooltool.events.Event(event_type: EventType, agents: Tuple[Agent, ...], time: float)[source]¶

Represents an event.

This class models an event characterized by its type, the agents involved, and the time at which the event occurs.

Agent states before and after event resolution are stored in the Agent.initial and Agent.final attributes of agents within agents.

event_type¶

The type of the event, indicating the nature of the event.

Type:: pooltool.events.datatypes.EventType

agents¶

A tuple containing one or two agents involved in the event.

Events that are collisions (EventType.is_collision()) have two agents, while events that are transitions (EventType.is_transition()), or events with event type EventType.NONE, have one agent.

By convention, the order of the agents matches how the EventType attributes are named.

Type:: Tuple[pooltool.events.datatypes.Agent, …]

time¶

The time at which the event occurs.

Type:: float

property ids: Tuple[str, Ellipsis]¶

Retrieves the IDs of the agents involved in the event.

This property provides access to a tuple of agent IDs, allowing identification of the agents involved in the event.

Returns:: A tuple containing the IDs of the agents involved in the event.
Return type:: Tuple[str, …]

Methods:

copy() → Event[source]¶

Create a copy.

Return type:: Event

class pooltool.events.EventType(value)[source]¶

An Enum of event types

NONE¶: The null event.

BALL_BALL¶: A ball-ball collision.

BALL_LINEAR_CUSHION¶: A ball collision with a linear cushion segment.

BALL_CIRCULAR_CUSHION¶: A ball collision with a circular cushion segment.

BALL_POCKET¶: A ball pocket “collision”. This marks the point at which the ball crosses the point of no return.

STICK_BALL¶: A cue-stick ball collision.

SPINNING_STATIONARY¶: A ball transition from spinning to stationary.

ROLLING_STATIONARY¶: A ball transition from rolling to stationary.

ROLLING_SPINNING¶: A ball transition from rolling to spinning.

SLIDING_ROLLING¶: A ball transition from sliding to rolling.

Bases: pooltool.utils.strenum.StrEnum

Methods:

is_collision() → bool[source]¶

Returns whether the member is a collision

Return type:: bool

is_transition() → bool[source]¶

Returns whether the member is a transition

Return type:: bool

Functions¶

pooltool.events.ball_ball_collision(ball1: pooltool.objects.ball.datatypes.Ball, ball2: pooltool.objects.ball.datatypes.Ball, time: float, set_initial: bool = False) → pooltool.events.datatypes.Event[source]¶

Create a ball-ball collision.

Return type:: pooltool.events.datatypes.Event

pooltool.events.ball_circular_cushion_collision(ball: pooltool.objects.ball.datatypes.Ball, cushion: pooltool.objects.table.components.CircularCushionSegment, time: float, set_initial: bool = False) → pooltool.events.datatypes.Event[source]¶

Create a ball-circular-cushion collision.

Return type:: pooltool.events.datatypes.Event

pooltool.events.ball_linear_cushion_collision(ball: pooltool.objects.ball.datatypes.Ball, cushion: pooltool.objects.table.components.LinearCushionSegment, time: float, set_initial: bool = False) → pooltool.events.datatypes.Event[source]¶

Create a ball-linear-cushion collision.

Return type:: pooltool.events.datatypes.Event

pooltool.events.ball_pocket_collision(ball: pooltool.objects.ball.datatypes.Ball, pocket: pooltool.objects.table.components.Pocket, time: float, set_initial: bool = False) → pooltool.events.datatypes.Event[source]¶

Create a ball-pocket collision.

Return type:: pooltool.events.datatypes.Event

pooltool.events.null_event(time: float, set_initial: bool = False) → pooltool.events.datatypes.Event[source]¶

Create a null event.

Return type:: pooltool.events.datatypes.Event

pooltool.events.rolling_spinning_transition(ball: pooltool.objects.ball.datatypes.Ball, time: float, set_initial: bool = False) → pooltool.events.datatypes.Event[source]¶

Create a rolling-spinning transition.

Return type:: pooltool.events.datatypes.Event

pooltool.events.rolling_stationary_transition(ball: pooltool.objects.ball.datatypes.Ball, time: float, set_initial: bool = False) → pooltool.events.datatypes.Event[source]¶

Create a rolling-stationary transition.

Return type:: pooltool.events.datatypes.Event

pooltool.events.sliding_rolling_transition(ball: pooltool.objects.ball.datatypes.Ball, time: float, set_initial: bool = False) → pooltool.events.datatypes.Event[source]¶

Create a sliding-rolling transition.

Return type:: pooltool.events.datatypes.Event

pooltool.events.spinning_stationary_transition(ball: pooltool.objects.ball.datatypes.Ball, time: float, set_initial: bool = False) → pooltool.events.datatypes.Event[source]¶

Create a spinning-stationary transition.

Return type:: pooltool.events.datatypes.Event

pooltool.events.stick_ball_collision(stick: pooltool.objects.cue.datatypes.Cue, ball: pooltool.objects.ball.datatypes.Ball, time: float, set_initial: bool = False) → pooltool.events.datatypes.Event[source]¶

Create a cue stick-ball collision.

Return type:: pooltool.events.datatypes.Event

pooltool.events.by_ball(ball_ids: str | List[str], keep_nonevent: bool = False) → FilterFunc[source]¶

Returns a function that filters events based on ball IDs.

Parameters:

ball_ids (Union[str, List[str]]) -- A collection of ball IDs.
keep_nonevent (bool) -- Retain non-events (EventType.NONE).

Returns:

A function that when passed a list of events, returns a filtered list containing only events that involve balls matching the passed ball ID(s).

Return type:

FilterFunc

pooltool.events.by_time(t: float, after: bool = True) → FilterFunc[source]¶

Returns a function that filter events with respect to a time cutoff.

Parameters:

t (float) -- The cutoff time for filtering events.
after (bool) -- If True, return events after time t (non-inclusive). If False, return events before time t (non-inclusive).

Returns:

A function that when passed a list of events, returns a filtered list containing only events before or after the cutoff time, non-inclusive.

Return type:

FilterFunc

pooltool.events.by_type(types: pooltool.events.datatypes.EventType | List[pooltool.events.datatypes.EventType]) → FilterFunc[source]¶

Returns a function that filters events based on event type.

Parameters:: types (Union[pooltool.events.datatypes.EventType, List[pooltool.events.datatypes.EventType]]) -- Event type(s) you want to include in your result. All others will be filtered.
Returns:: A function that when passed a list of events, returns a filtered list containing only events matching the passed event type(s).
Return type:: FilterFunc

pooltool.events.filter_ball(events: List[pooltool.events.datatypes.Event], ball_ids: str | List[str], keep_nonevent: bool = False) → List[pooltool.events.datatypes.Event][source]¶

Filter events based on ball IDs.

Parameters:

events (List[pooltool.events.datatypes.Event]) -- A list of chronological events.
ball_ids (Union[str, List[str]]) -- A collection of ball IDs.
keep_nonevent (bool) -- Retain non-events (EventType.NONE).

Returns:

A filtered event list containing only events that involve balls matching the passed ball ID(s).

Return type:

List[Event]

See also

If you’re filtering based on multiple criteria, you can (and should!) use filter_events().

pooltool.events.filter_events(events: List[pooltool.events.datatypes.Event], *funcs: FilterFunc) → List[pooltool.events.datatypes.Event][source]¶

Filter events using multiple criteria.

A convenient way to filter based multiple filtering criteria.

Parameters:

events (List[pooltool.events.datatypes.Event]) -- A list of chronological events.
*funcs (FilterFunc) -- An arbitrary number of functions that take a list of events as input, and gives a subset of that list as input. It sounds laborious--it’s not. See Examples.

Returns:

A filtered event list containing only events passing the supplied criteria.

Return type:

List[Event]

Examples

Generate a list of events.

>>> import pooltool as pt
>>> system = pt.System.example()
>>> system.cue.set_state(a=0.68)
>>> pt.simulate(system, inplace=True)
>>> events = system.events

In this shot, both the cue-ball and the 1-ball are potted. We are interested in filtering for the cue-ball pocket event. Option 1 is to call filter_type() and then filter_ball():

>>> filtered_events = pt.events.filter_type(events, pt.EventType.BALL_POCKET)
>>> filtered_events = pt.events.filter_ball(filtered_events, "cue")
>>> event_of_interest = filtered_events[0]
>>> event_of_interest
<Event object at 0x7fa855e7e6c0>
 ├── type   : ball_pocket
 ├── time   : 3.231130101576186
 └── agents : ('cue', 'rt')

Option 2, the better option, is to use filter_events():

>>> filtered_events = pt.events.filter_events(
>>>     events,
>>>     pt.events.by_type(pt.EventType.BALL_POCKET),
>>>     pt.events.by_ball("cue"),
>>> )
>>> event_of_interest = filtered_events[0]
>>> event_of_interest
<Event object at 0x7fa855e7e6c0>
 ├── type   : ball_pocket
 ├── time   : 3.231130101576186
 └── agents : ('cue', 'rt')

See also

If you’re filtering based on a single criterion, you can consider using filter_type(), filter_ball(), filter_time(), etc.

pooltool.events.filter_time(events: List[pooltool.events.datatypes.Event], t: float, after: bool = True) → List[pooltool.events.datatypes.Event][source]¶

Filter events with respect to a time cutoff.

Parameters:

events (List[pooltool.events.datatypes.Event]) -- A list of chronological events.
t (float) -- The cutoff time for filtering events.
after (bool) -- If True, return events after time t (non-inclusive). If False, return events before time t (non-inclusive).

Returns:

A filtered event list containing only events before or after the cutoff time, non-inclusive.

Return type:

List[Event]

See also

If you’re filtering based on multiple criteria, you can (and should!) use filter_events().

pooltool.events.filter_type(events: List[pooltool.events.datatypes.Event], types: pooltool.events.datatypes.EventType | List[pooltool.events.datatypes.EventType]) → List[pooltool.events.datatypes.Event][source]¶

Filter events based on event type.

Parameters:

events (List[pooltool.events.datatypes.Event]) -- A list of chronological events.
types (Union[pooltool.events.datatypes.EventType, List[pooltool.events.datatypes.EventType]]) -- Event type(s) you want to include in your result. All others will be filtered.

Returns:

A filtered event list containing only events matching the passed event type(s).

Return type:

List[Event]

See also

If you’re filtering based on multiple criteria, you can (and should!) use filter_events().