{"id":21239205,"url":"https://github.com/cutupdev/table-tennis-ball-tracking-using-cnn","last_synced_at":"2025-07-10T19:32:15.537Z","repository":{"id":223270996,"uuid":"759466556","full_name":"cutupdev/Table-Tennis-Ball-Tracking-using-CNN","owner":"cutupdev","description":"This is real time table tennis ball tracking repository using CNN. It used python, pytorch, CNN. I build own deep CNN and reach enough accuracy.","archived":false,"fork":false,"pushed_at":"2024-04-05T09:44:01.000Z","size":22665,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-31T23:34:32.685Z","etag":null,"topics":["cnn","python","pytorch"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cutupdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-02-18T17:10:22.000Z","updated_at":"2024-08-06T12:31:33.000Z","dependencies_parsed_at":"2024-04-05T10:51:46.672Z","dependency_job_id":null,"html_url":"https://github.com/cutupdev/Table-Tennis-Ball-Tracking-using-CNN","commit_stats":null,"previous_names":["catlover75926/table-tennis-ball-tracking-using-cnn","harmonitech/table-tennis-ball-tracking-using-cnn","cutupdev/table-tennis-ball-tracking-using-cnn"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cutupdev%2FTable-Tennis-Ball-Tracking-using-CNN","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cutupdev%2FTable-Tennis-Ball-Tracking-using-CNN/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cutupdev%2FTable-Tennis-Ball-Tracking-using-CNN/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cutupdev%2FTable-Tennis-Ball-Tracking-using-CNN/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cutupdev","download_url":"https://codeload.github.com/cutupdev/Table-Tennis-Ball-Tracking-using-CNN/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225653865,"owners_count":17502940,"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":["cnn","python","pytorch"],"created_at":"2024-11-21T00:42:26.203Z","updated_at":"2024-11-21T00:42:26.882Z","avatar_url":"https://github.com/cutupdev.png","language":"Python","readme":"# Pytorch-CNN\n\n[![python-image]][python-url]\n[![pytorch-image]][pytorch-url]\n\n![demo](./docs/demo.gif)\n\n## 1. Features\n- [x] Ball detection global stage\n- [x] Ball detection local stage (refinement)\n- [x] Events Spotting detection (Bounce and Net hit)\n- [x] Semantic Segmentation (Human, table, and scoreboard)\n- [x] Multi-Task learning\n- [x] [Distributed Data Parallel Training](https://github.com/pytorch/examples/tree/master/distributed/ddp)\n- [x] Enable/Disable modules in the TTNet model\n- [x] Smooth labeling for event spotting\n- [x] TensorboardX\n  \n\n## 2. Getting Started\n### Requirement\n\n```shell script\npip install -U -r requirement.txt\n```\n\nYou will also need PyTurboJPEG:\n\n```shell script\n$ sudo apt-get install libturbojpeg\n...\n$ pip install PyTurboJPEG\n...\n```\n\n### 2.1. Preparing the dataset\nThe instruction for the dataset preparation is [here](./prepare_dataset/README.md)\n\n### 2.2. Model \u0026 Input tensors\n\n**TTNet model architecture**:\n\n![architecture](./docs/architecture.PNG)\n\n**Input tensor structure**\n\n![input tensor](./docs/input_tensor.PNG)\n\n### 2.3. How to run\n\n#### 2.3.1. Training\n##### 2.3.1.1. Single machine, single gpu\n\n```shell script\npython main.py --gpu_idx 0\n```\n\nBy default (as the above command), there are 4 modules in the TTNet model: *global stage, local stage, event spotting, segmentation*.\nYou can disable one of the modules, except the global stage module.\u003cbr\u003e\nAn important note is if you disable the local stage module, the event spotting module will be also disabled.\n\n- You can disable the _**segmentation stage**_:\n\n```shell script\npython main.py --gpu_idx 0 --no_seg\n```\n\n- You can disable the _**event spotting module**_:\n\n```shell script\npython main.py --gpu_idx 0 --no_event\n```\n\n- You can disable the _**local stage, event spotting, segmentation modules**_:\n\n```shell script\npython main.py --gpu_idx 0 --no_local --no_seg --no_event\n```\n\n##### 2.3.1.2. Multi-processing Distributed Data Parallel Training\nWe should always use the `nccl` backend for multi-processing distributed training since it currently provides the best \ndistributed training performance.\n\n- **Single machine (node), multiple GPUs**\n\n```shell script\npython main.py --dist-url 'tcp://127.0.0.1:29500' --dist-backend 'nccl' --multiprocessing-distributed --world-size 1 --rank 0\n```\n\n- **Two machines (two nodes), multiple GPUs**\n\n_**First machine**_\n\n```shell script\npython main.py --dist-url 'tcp://IP_OF_NODE1:FREEPORT' --dist-backend 'nccl' --multiprocessing-distributed --world-size 2 --rank 0\n```\n_**Second machine**_\n\n```shell script\npython main.py --dist-url 'tcp://IP_OF_NODE2:FREEPORT' --dist-backend 'nccl' --multiprocessing-distributed --world-size 2 --rank 1\n```\n\n#### 2.3.2. Training stratergy\n\nThe performance of the TTNet strongly depends on the global stage for ball detection. Hence, It's necessary to train the \n`global ball stage module` of the TTNet model first.\n\n- **1st phase**: Train the global and segmentation modules with 30 epochs\n \n```shell script\n./train_1st_phase.sh\n```  \n\n- **2nd phase**: Load the trained weights to the global and the segmentation part, initialize the weight of the local stage with the weights of\nthe global stage. In this phase, we train and just update weights of the local and the event modules. (30 epochs)\n\n```shell script\n./train_2nd_phase.sh\n```\n\n- **3rd phase**: Fine tune all modules. Train the network with only 30 epochs\n\n```shell script\n./train_3rd_phase.sh\n```\n\n  \n#### 2.3.3. Visualizing training progress\nThe Tensorboard was used to save loss values on the training set and the validation set.\nExecute the below command on the working terminal:\n```\n    cd logs/\u003ctask directory\u003e/tensorboard/\n    tensorboard --logdir=./\n```\n\nThen open the web browser and go to: [http://localhost:6006/](http://localhost:6006/)\n\n\n#### 2.3.4. Evaluation\n\nThe thresholds of the segmentation and event spotting tasks could be set in `test.sh` bash shell scripts.\n\n```shell script\n./test_3rd_phase.sh\n```\n\n#### 2.3.5. Demo:\n\nRun a demonstration with an input video:\n\n```shell script\n./demo.sh\n```\n\n## Citation\n\n```bash\n@article{TTNet,\n  author = {Roman Voeikov, Nikolay Falaleev, Ruslan Baikulov},\n  title = {TTNet: Real-time temporal and spatial video analysis of table tennis},\n  year = {2020},\n  conference = {CVPR 2020},\n}\n```\n\n## Usage\n```\nusage: main.py [-h] [--seed SEED] [--saved_fn FN] [-a ARCH] [--dropout_p P]\n               [--multitask_learning] [--no_local] [--no_event] [--no_seg]\n               [--pretrained_path PATH] [--overwrite_global_2_local]\n               [--no-val] [--no-test] [--val-size VAL_SIZE]\n               [--smooth-labelling] [--num_samples NUM_SAMPLES]\n               [--num_workers NUM_WORKERS] [--batch_size BATCH_SIZE]\n               [--print_freq N] [--checkpoint_freq N] [--sigma SIGMA]\n               [--thresh_ball_pos_mask THRESH] [--start_epoch N]\n               [--num_epochs N] [--lr LR] [--minimum_lr MIN_LR] [--momentum M]\n               [-wd WD] [--optimizer_type OPTIMIZER] [--lr_type SCHEDULER]\n               [--lr_factor FACTOR] [--lr_step_size STEP_SIZE]\n               [--lr_patience N] [--earlystop_patience N] [--freeze_global]\n               [--freeze_local] [--freeze_event] [--freeze_seg]\n               [--bce_weight BCE_WEIGHT] [--global_weight GLOBAL_WEIGHT]\n               [--local_weight LOCAL_WEIGHT] [--event_weight EVENT_WEIGHT]\n               [--seg_weight SEG_WEIGHT] [--world-size N] [--rank N]\n               [--dist-url DIST_URL] [--dist-backend DIST_BACKEND]\n               [--gpu_idx GPU_IDX] [--no_cuda] [--multiprocessing-distributed]\n               [--evaluate] [--resume_path PATH] [--use_best_checkpoint]\n               [--seg_thresh SEG_THRESH] [--event_thresh EVENT_THRESH]\n               [--save_test_output] [--video_path PATH] [--output_format PATH]\n               [--show_image] [--save_demo_output]\n\nTTNet Implementation\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --seed SEED           re-produce the results with seed random\n  --saved_fn FN         The name using for saving logs, models,...\n  -a ARCH, --arch ARCH  The name of the model architecture\n  --dropout_p P         The dropout probability of the model\n  --multitask_learning  If true, the weights of different losses will be\n                        learnt (train).If false, a regular sum of different\n                        losses will be applied\n  --no_local            If true, no local stage for ball detection.\n  --no_event            If true, no event spotting detection.\n  --no_seg              If true, no segmentation module.\n  --pretrained_path PATH\n                        the path of the pretrained checkpoint\n  --overwrite_global_2_local\n                        If true, the weights of the local stage will be\n                        overwritten by the global stage.\n  --no-val              If true, use all data for training, no validation set\n  --no-test             If true, dont evaluate the model on the test set\n  --val-size VAL_SIZE   The size of validation set\n  --smooth-labelling    If true, smoothly make the labels of event spotting\n  --num_samples NUM_SAMPLES\n                        Take a subset of the dataset to run and debug\n  --num_workers NUM_WORKERS\n                        Number of threads for loading data\n  --batch_size BATCH_SIZE\n                        mini-batch size (default: 16), this is the totalbatch\n                        size of all GPUs on the current node when usingData\n                        Parallel or Distributed Data Parallel\n  --print_freq N        print frequency (default: 10)\n  --checkpoint_freq N   frequency of saving checkpoints (default: 3)\n  --sigma SIGMA         standard deviation of the 1D Gaussian for the ball\n                        position target\n  --thresh_ball_pos_mask THRESH\n                        the lower thresh for the 1D Gaussian of the ball\n                        position target\n  --start_epoch N       the starting epoch\n  --num_epochs N        number of total epochs to run\n  --lr LR               initial learning rate\n  --minimum_lr MIN_LR   minimum learning rate during training\n  --momentum M          momentum\n  -wd WD, --weight_decay WD\n                        weight decay (default: 1e-6)\n  --optimizer_type OPTIMIZER\n                        the type of optimizer, it can be sgd or adam\n  --lr_type SCHEDULER   the type of the learning rate scheduler (steplr or\n                        ReduceonPlateau)\n  --lr_factor FACTOR    reduce the learning rate with this factor\n  --lr_step_size STEP_SIZE\n                        step_size of the learning rate when using steplr\n                        scheduler\n  --lr_patience N       patience of the learning rate when using\n                        ReduceoPlateau scheduler\n  --earlystop_patience N\n                        Early stopping the training process if performance is\n                        not improved within this value\n  --freeze_global       If true, no update/train weights for the global stage\n                        of ball detection.\n  --freeze_local        If true, no update/train weights for the local stage\n                        of ball detection.\n  --freeze_event        If true, no update/train weights for the event module.\n  --freeze_seg          If true, no update/train weights for the segmentation\n                        module.\n  --bce_weight BCE_WEIGHT\n                        The weight of BCE loss in segmentation module, the\n                        dice_loss weight = 1- bce_weight\n  --global_weight GLOBAL_WEIGHT\n                        The weight of loss of the global stage for ball\n                        detection\n  --local_weight LOCAL_WEIGHT\n                        The weight of loss of the local stage for ball\n                        detection\n  --event_weight EVENT_WEIGHT\n                        The weight of loss of the event spotting module\n  --seg_weight SEG_WEIGHT\n                        The weight of BCE loss in segmentation module\n  --world-size N        number of nodes for distributed training\n  --rank N              node rank for distributed training\n  --dist-url DIST_URL   url used to set up distributed training\n  --dist-backend DIST_BACKEND\n                        distributed backend\n  --gpu_idx GPU_IDX     GPU index to use.\n  --no_cuda             If true, cuda is not used.\n  --multiprocessing-distributed\n                        Use multi-processing distributed training to launch N\n                        processes per node, which has N GPUs. This is the\n                        fastest way to use PyTorch for either single node or\n                        multi node data parallel training\n  --evaluate            only evaluate the model, not training\n  --resume_path PATH    the path of the resumed checkpoint\n  --use_best_checkpoint\n                        If true, choose the best model on val set, otherwise\n                        choose the last model\n  --seg_thresh SEG_THRESH\n                        threshold of the segmentation output\n  --event_thresh EVENT_THRESH\n                        threshold of the event spotting output\n  --save_test_output    If true, the image of testing phase will be saved\n  --video_path PATH     the path of the video that needs to demo\n  --output_format PATH  the type of the demo output\n  --show_image          If true, show the image during demostration\n  --save_demo_output    If true, the image of demonstration phase will be\n                        saved\n```","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcutupdev%2Ftable-tennis-ball-tracking-using-cnn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcutupdev%2Ftable-tennis-ball-tracking-using-cnn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcutupdev%2Ftable-tennis-ball-tracking-using-cnn/lists"}