diff --git a/README.md b/README.md index 4c26508e..489b3f0a 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ # NBA Player Movements -This is a script for visualization of NBA games from raw SportVU logs. +This is a script for visualization of NBA games using raw logs from the NBA SportVU dataset, which contains player and ball movement throughout NBA games. By running only a single command from the command line, you are able to view the entirety of players positioning throughout any NBA SportVU json file. -If you admire both Spurs' and Warriors' ball movement, Brad Stevens' playbook, or just miss KD in OKC you'll find this entertaining. +Whether you admire both the Spurs' and Warriors' ball movement, Erik Spoelstra's playbook, or just miss KD and Russ in OKC, you'll find this entertaining. + +As each game progresses, you can track the movement of each player currently on the court, with the names of all players printed on the screen. You can also see the location of the ball and both the game and shot clocks. This low-CPU visualization helps everyone simply study ball and player movements, and where your favorite team's potential weaknesses lie. ## Examples @@ -13,28 +15,30 @@ If you admire both Spurs' and Warriors' ball movement, Brad Stevens' playbook, o ## Usage -1. Clone this repo: +1. Clone this repo using the following link: ```bash $ git clone https://github.com/linouk23/NBA-Player-Movements ``` -2. Choose any NBA game from ```data/2016.NBA.Raw.SportVU.Game.Logs``` directory. - -3. Generate an animation for the play by running the following script: - - ```bash - $ python3 main.py --path=Celtics@Lakers.json --event=140 - ``` - - ``` - required arguments: - --path PATH a path to json file to read the events from - - optional arguments: - --event EVENT an index of the event to create the animation to - (the indexing start with zero, if you index goes beyond out - the total number of events (plays), it will show you the last - one of the game) - -h, --help show the help message and exit - ``` +2. Choose any NBA game from ```data/2016.NBA.Raw.SportVU.Game.Logs``` directory. Note: At the moment, only games from 2016 are included, but more seasons can be added as needed. (If any contributors would be willing to add games from 2017-present, it would be greatly appreciated.) + +3. The program takes two parameters: + required arguments: + --path PATH + a path any json file leading to a SportVU file. You can find examples in the "data/2016.NBA.Raw.SportVU.Game.Logs" directory, or you import them yourself. + ex. + ```bash + --path=Celtics@Lakers.json + ``` + optional arguments: + --event EVENT + This flag allows you to choose which play to start on. This allows you to skip to different portions of the game, or allows you to see a genius inbounds play drawn up by Steve Kerr. For example, if you wanted to skip to the 10th play of the game, you would enter 9, as in the following example: + ```bash + $ python3 main.py --path=Celtics@Lakers.json --event=9 + ``` + -h, --help + This flag prints information displays a general help menu of how to operate the program, and is also where you go to exit the program (although you can use Ctrl+C to terminate the program as well). + +## Contributions +This project has not been updated recently, and as software has changed regarding more advanced ways to track player movement and more advanced techniques have been created, additional contributions are highly encouraged. If anyone interested in AI visualizations would be interested in adding more advanced graphics, that would be greatly appreciated as well.