{"id":20038513,"url":"https://github.com/yahoo/spivak","last_synced_at":"2025-07-26T10:37:06.373Z","repository":{"id":143360185,"uuid":"608322299","full_name":"yahoo/spivak","owner":"yahoo","description":null,"archived":false,"fork":false,"pushed_at":"2024-09-20T14:16:48.000Z","size":326,"stargazers_count":31,"open_issues_count":3,"forks_count":3,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-08T18:51:37.219Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yahoo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"Contributing.md","funding":null,"license":"LICENSE","code_of_conduct":"Code_of_Conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-01T19:27:42.000Z","updated_at":"2025-01-13T13:07:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"86ec15cb-f336-4d04-b4c8-dc9a9817ec54","html_url":"https://github.com/yahoo/spivak","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":"yahoo/.github","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fspivak","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fspivak/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fspivak/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Fspivak/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yahoo","download_url":"https://codeload.github.com/yahoo/spivak/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252451771,"owners_count":21749978,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T10:29:39.297Z","updated_at":"2025-05-05T06:32:15.193Z","avatar_url":"https://github.com/yahoo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# spivak: \u003cins\u003esp\u003c/ins\u003eorts \u003cins\u003ei\u003c/ins\u003endeed \u003cins\u003ev\u003c/ins\u003eideo \u003cins\u003ea\u003c/ins\u003enalysis \u003cins\u003ek\u003c/ins\u003eit\n\u003e A toolkit for automatic analysis of sports videos.\n\n## Updates\n\n- [Sept 2024]: we have released pretrained models for action spotting on the SoccerNet dataset.\nPlease see [Reproducing-results-from-the-SoccerNet-action-spotting-challenge-2022.md](Reproducing-results-from-the-SoccerNet-action-spotting-challenge-2022.md).\n\n## Background\n\nThis package implements methods for action spotting and camera\nshot segmentation on the\n[SoccerNet dataset](https://www.soccer-net.org/). In addition,\nit provides a set of tools for visualizing results, and for\nvisualizing various metrics that are computed against the ground\ntruth annotations.\n\nMost of the code in this repository deals with implementing the\nfollowing two papers, which focus on the task of action spotting\non the SoccerNet dataset.\n- [Temporally Precise Action Spotting in Soccer Videos Using\nDense Detection Anchors](https://arxiv.org/abs/2205.10450).\nIn ICIP, 2022.\n- [Action Spotting using Dense Detection Anchors Revisited:\nSubmission to the SoccerNet Challenge 2022](https://arxiv.org/abs/2206.07846).\narXiv preprint, 2022.\n\nThe action spotting method that is implemented here\ncame in first place in the SoccerNet Challenge 2022. You can\nread more about the 2022 challenge and results in the following paper:\n- [SoccerNet 2022 Challenges Results](https://arxiv.org/abs/2210.02365).\nIn MMSports, 2022.\n\n## Setup\n\n### Requirements\n\nOur models depend on TensorFlow, though this package also includes\nsome evaluation and visualization code which does not. We've currently\nonly tested our code using TensorFlow 2.7.0, thus the\ncorresponding version is currently specified in the\n[setup.py](setup.py) file. Certain visualization\nscripts depend on ffmpeg via PyAV (`av` pip package). The rest of\nthe dependencies are specified in [setup.py](setup.py) and can\nlikely be directly installed using pip as described below.\n\nFor the heavier sets of features, our standard flow assumes that a good\namount of CPU RAM is available. We recommend having 256GB or more\nin order to make things simpler. Our input data pipeline is\nresponsible for consuming most of the CPU memory and can be tweaked to\nconsume less at the cost of speed. An example of how to do this is\npresented in\n[one of our guides](Reproducing-results-from-the-SoccerNet-action-spotting-challenge-2022.md#low-memory-setup).\nThe code implementing the input data pipeline is in\n[tf_dataset.py](spivak/models/tf_dataset.py), and is based on\n[tf.data](https://www.tensorflow.org/guide/data).\n\n### Install\n\nRun pip install in order to do a local development install, as follows.\nAfter successful installation, you should see the message\n`Successfully installed spivak`.\n\n```bash\nBASE_CODE_DIR=\"YOUR_BASE_CODE_DIR\"  # Wherever the spivak repo is located.\ncd $BASE_CODE_DIR/spivak  # The root folder, which contains setup.py.\npip install -e .\n```\n\nIf you have `ffmpeg` installed, you can also run the video visualization\nscripts from our package. In that case, you can run the installation with\nthe following command, which will also install the PyAV package:\n\n```bash\npip install -e .[av]\n```\n\n### Get the SoccerNet data\n\nYou will most likely want to download the following set of\nprecomputed features and labels using SoccerNet's pip package.\nPlease see detailed instructions at \u003chttps://www.soccer-net.org/data\u003e.\n- ResNet features\n(filenames used for downloading: `[\"1_ResNET_TF2.npy\", \"2_ResNET_TF2.npy\"]`).\n- ResNet features projected using PCA\n(filenames used for downloading: `[\"1_ResNET_TF2_PCA512.npy\", \"2_ResNET_TF2_PCA512.npy\"]`).\n- Baidu features\n(these were also denoted _Combination_ in our papers; filenames\nused for downloading:\n`[\"1_baidu_soccer_embeddings.npy\", \"2_baidu_soccer_embeddings.npy\"]`).\n- Action spotting labels\n(filename used for downloading: `[\"Labels-v2.json\"]`).\n- Camera shot segmentation labels\n(filename used for downloading: `[\"Labels-cameras.json\"]`).\n\nIf you would like to use our video-specific visualization functionality,\nyou will also need to get the\n[SoccerNet videos](https://www.soccer-net.org/data#h.ov9k48lcih5g).\nThe low-resolution version of the videos should be enough for\nvisualization purposes.\n\n### Set up some folders\n\nIn order to follow our guides, please create\nfolders to store your models and results, as follows.\n\n```bash\nMODELS_DIR=\"YOUR_MODELS_DIR\"\nmkdir -p $MODELS_DIR\nRESULTS_DIR=\"YOUR_RESULTS_DIR\"\nmkdir -p $RESULTS_DIR\nREPORTS_DIR=\"YOUR_REPORTS_DIR\"\nmkdir -p $REPORTS_DIR\nVISUALIZATIONS_DIR=\"YOUR_VISUALIZATIONS_DIR\"\nmkdir -p $VISUALIZATIONS_DIR\n# We recommend setting FEATURES_DIR to \"data/features\" as below, since many\n# commands in our guides use \"data/features\" directly.\nFEATURES_DIR=\"data/features\"\nmkdir -p $FEATURES_DIR\n```\n\nPlease also create the symbolic links described below, so\nthat you can easily access the downloaded SoccerNet data. The symbolic links\nwill point from the [data/](data) folder to the folders containing the actual\ndownloaded data.\n\n```bash\ncd data/  # This folder will initially just contain the splits/ folder.\nln -s YOUR_LABELS_FOLDER  labels  # For the Labels-v2.json and/or the Labels-cameras.json files.\nln -s YOUR_FEATURES_RESNET_FOLDER  features/resnet  # For the ResNet-based features.\nln -s YOUR_FEATURES_BAIDU_FOLDER  features/baidu  # For the Baidu Combination features.\nln -s YOUR_VIDEOS_224P_FOLDER  videos_224p  # For the low-resolution videos.\n```\n\n## Action spotting usage\n\nAfter completing the setup steps above, please see\n[Action-spotting-usage.md](Action-spotting-usage.md) for action spotting\nusage instructions. Additionally, to download our pretrained action\nspotting models and to reproduce results from our experiments, please see\n[Reproducing-results-from-the-SoccerNet-action-spotting-challenge-2022.md](Reproducing-results-from-the-SoccerNet-action-spotting-challenge-2022.md).\n\n## Citations\n\nIf you found our models and code useful, please consider citing our works:\n\n```\n@inproceedings{soares2022temporally,\n  author={Soares, Jo{\\~a}o~V.~B. and Shah, Avijit and Biswas, Topojoy},\n  booktitle={International Conference on Image Processing (ICIP)},\n  title={Temporally Precise Action Spotting in Soccer Videos Using Dense Detection Anchors},\n  year={2022},\n  pages={2796-2800},\n  doi={10.1109/ICIP46576.2022.9897256}\n}\n\n@article{soares2022action,\n  title={Action Spotting using Dense Detection Anchors Revisited: Submission to the {SoccerNet} {Challenge} 2022},\n  author={Soares, Jo{\\~a}o~V.~B. and Shah, Avijit},\n  journal={arXiv preprint arXiv:2206.07846},\n  year={2022}\n}\n```\n\n## Contribute\n\nPlease refer to [the Contributing.md file](Contributing.md) for information about how to\nget involved. We welcome  issues, questions, and pull requests.\n\nPlease be aware that we (the maintainers) are currently busy with other projects, so it\nmay take some days before we are able to get back to you. We do not foresee big changes\nto this repository going forward.\n\n## Maintainers\n\n- Joao Soares: jvbsoares@yahooinc.com\n- Avijit Shah: avijit.shah@yahooinc.com\n\n## License\n\nThis project is licensed under the terms of the\n[Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.html)\nopen source license. Please refer to [LICENSE](LICENSE) for\nthe full terms.\n\n## Acknowledgments\n\nWe thank the [SoccerNet team](https://www.soccer-net.org/team) for making their datasets\navailable and organizing the series of related challenges. We also thank them for\nmaking their code available under open source licenses.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyahoo%2Fspivak","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyahoo%2Fspivak","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyahoo%2Fspivak/lists"}