What is the NBA Hawkeye Importer?
The NBA Hawkeye Importer allows users to import player positional tracking data collected via Hawkeye Optical tracking systems during NBA games, into OpenField.
The NBA Hawkeye Importer will import:
- Player positional data to generate velocity-based metrics in OpenField (such as Total Distance, Meters per Minutes, Max Velocity etc.).
- Activity and Periods related to the game.
- Athlete rotations that reflect 'Ball in Play' times.
- Athletes will be rotated on whenever the Game Clock was running AND the athlete was on court, according to information provided in the NBA API.
Walkthrough
How to Use the NBA Hawkeye Importer
The NBA Hawkeye Importer tool will be provided to you by Catapult Support or your Customer Success Representative.
The Importer tool runs independently of OpenField Console to download game data from the NBA API, and then convert the data into our existing Catapult Portable File (CPF) format, which can then be imported into OpenField Console.
- Extract the supplied NBA Hawkeye Importer.zip folder by right-clicking the folder and select Extract All.
- Open the extracted folder and navigate to the 'Publish' folder.
- If desired, update the config.json file to filter the tool to only show games for your team or to filter for a particular season.
More information on how to update the config.json file is detailed in How to configure default team and season for the NBA Hawkeye Importer. - Run the tool by opening nba_download.exe.
- Select the season for the game you wish to import. Use the arrows to move the selector up and down and hit Enter to confirm selection.
- Select the team for which you want to find the game to import. Use the arrows to move the selector up and down and hit Enter to confirm selection.
- Once a team has been selected the list of that team's games for the season will be displayed, with the latest games being displayed first. Use the arrow keys to move the selector up and down and hit Enter to confirm selection and to begin the download of game data from the NBA API.
If required select Next Page to view more games.
- The download of game data from the NBA API will commence. A typical game will have up to 500,000 'payloads' to download.
- Once the import is completed you can press the Enter key to close the importer tool.
- The NBA Hawkeye Importer tool will create a data folder in the NBA Hawkeye Importer\publish directory, and then create a folder per game downloaded that will contain the downloaded data to be imported into OpenField.
- Open OpenField Console.
-
Follow the steps to import a CPF file via the Data Importer tile. To select the right files to import for your desired game, during the CPF import process choose the desired game folder created in the data folder in the NBA Hawkeye Importer directory.
- As part of the CPF import process, the CPFs will automatically 'name match' to athletes in your OpenField account. Alternatively CPF files can be resolved manually to your athletes. Note that both team's data will be downloaded and converted into CPFs for the selected game.
- Once the CPF import is complete the activity can be loaded in Console and synced to cloud.
How to Configure Default Team and Season for the NBA Hawkeye Importer
It may be desirable to configure the NBA Hawkeye Importer tool to only display your team or a specific season, to prevent the number of button presses required to find the game you wish to import.
- Navigate to the NBA Hawkeye Importer folder > Publish > Open the config.json file in a text editor.
- To filter games to a particular season, edit the "AVAILABLE SEASONS" array to include just the desired season(s). For example to filter just the 2024 season, edit the file to "AVAILABLE_SEASONS": ["2024"].
- To filter the list of teams that will appear for selection in the tool, edit the "HARDCODED_TEAMS" array so that just the desired team(s) have a "display" value of true, and the teams you wish to filter out to have a "display" value of false. For example to filter the list of teams to just Boston:
Alternatively, delete the teams from the "HARDCODED_TEAMS" array that you do not wish to see in the Importer tool. For example to filter the list of teams to just Boston:
- Save the config.json file.
How is the Hawkeye data downsampled and filtered?
In order for the Hawkeye source data to be compatible with OpenField it needs to be downsampled from Hawkeye's 60Hz data capture rate, to 10Hz.
In addition, the NBA Hawkeye Importer tool performs some filtering and smoothing of data to reduce the chance of erroneous distance, velocity or acceleration values being calculated when importing the source data.
The NBA Hawkeye Importer tool applies the following logic when importing the Hawkeye data:
- The source data is downloaded at 60Hz
- Any missing data points for a specific athlete is 'padded' with the previous valid data point.
Only athletes that are on court for a particular timestamp contain data from Hawkeye, so we need to pad out data for time periods for any athletes that are on the bench
- The Padded source data is then down sampled from 60Hz to 10Hz.
This is performed by grouping every 6 data samples, and picking the last data point in each group to achieve a downsampled data source at 10Hz.
-
Velocity is derived by:
- Comparing two sequential x and y values from the padded source data to determine the rate in change of distance
- If a velocity value of >10 m/s is derived, it is filtered out and instead the last valid velocity value is used
- The derived velocity value is added to a 'velocity buffer' which contains the last 5 valid velocity values
- The 'velocity buffer' values are averaged to calculated a smoothed velocity value, which is then used to derive acceleration and add distance to the odometer
- Comparing two sequential x and y values from the padded source data to determine the rate in change of distance
-
Acceleration is derived by:
- Comparing two sequential smoothed velocity values to determine the rate in change of velocity
- If an acceleration value of >8m/s/s is derived, it is filtered out and instead a capped value of 8 m/s/s is used
- The derived acceleration value is added to a 'acceleration buffer' which contains the last 5 acceleration values
- The 'acceleration buffer' values are averaged to calculated a smoothed acceleration value, which is then used to derive acceleration based parameters
- Comparing two sequential smoothed velocity values to determine the rate in change of velocity