04Physics and features
floodlight
A typed data model for team-sport tracking: positions, events, pitch and per-frame codes as first-class objects, with kinematics and spatial analysis on top.
- Tracking + events
- Library
- No training
- MIT
- Modality
- Tracking and event data
- Output
- Kinematic and spatial features
- Evidence
- Journal of Open Source Software paper (2022)
- Code and weights
- Installable Python package; nothing to train
- Licence
- MIT
floodlight is a Python framework for team-sport data. Its core is a small set of data objects: an XY object for positions over time, Events, a Pitch that knows its dimensions and coordinate system, and Code objects for per-frame state such as ball status or possession. Parsers fill these objects from provider files, and models consume them.
On top sit the standard computations: distance covered, velocity and acceleration, plus geometric and spatial analyses.
Its design choice is strictness. A frame rate, a direction of play and a unit are properties of the object, not conventions in someone’s head.
Where it wins
- Kinematics done once, correctly. Differentiation and units are library code.
- The Code object is a ready container for an H/A/D signal: one state per frame, with definitions attached.
- Peer-reviewed, documented and MIT.
What it costs
- It carries data and computes features. It does not decide possession.
- It is one more data model to convert to and from if the rest of a stack runs on kloppy or plain arrays.
- Semantics stay with the user. The library stores a possession code; what counts as possession is still a definition someone must write.
How it plugs into possession
As the feature layer. Speeds of players and ball, accelerations and distances are the raw material of possession evidence. A collective-stillness cue for dead balls, for instance, is a velocity computation over all players.
Its per-frame codes also suit both ends of validation: the decoder’s output, and provider labels such as the possession and ball-status streams in the open DFL matches. Those matches are described under DFL IDSSE open data.
Our read
Solid plumbing for kinematics and per-frame state. It will not find possession. It will stop you fumbling the units on the way.