{"id":13444067,"url":"https://github.com/lufficc/SSD","last_synced_at":"2025-03-20T17:33:08.173Z","repository":{"id":224807289,"uuid":"160727251","full_name":"lufficc/SSD","owner":"lufficc","description":"High quality, fast, modular reference implementation of SSD in PyTorch","archived":false,"fork":false,"pushed_at":"2024-01-26T01:50:32.000Z","size":764,"stargazers_count":1550,"open_issues_count":40,"forks_count":382,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-03-16T22:03:01.232Z","etag":null,"topics":["computer-vision","deep-learning","object-detection","pytorch","ssd"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lufficc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2018-12-06T20:19:33.000Z","updated_at":"2025-03-15T13:09:31.000Z","dependencies_parsed_at":"2024-02-27T20:49:51.300Z","dependency_job_id":"5f660654-a738-44ea-92c7-fe4b9de04e8b","html_url":"https://github.com/lufficc/SSD","commit_stats":{"total_commits":126,"total_committers":11,"mean_commits":"11.454545454545455","dds":"0.23809523809523814","last_synced_commit":"68dc0a20efaf3997e58b616afaaaa21bf8ca3c05"},"previous_names":["lufficc/ssd"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lufficc%2FSSD","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lufficc%2FSSD/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lufficc%2FSSD/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lufficc%2FSSD/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lufficc","download_url":"https://codeload.github.com/lufficc/SSD/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244660995,"owners_count":20489444,"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":["computer-vision","deep-learning","object-detection","pytorch","ssd"],"created_at":"2024-07-31T03:02:18.173Z","updated_at":"2025-03-20T17:33:07.762Z","avatar_url":"https://github.com/lufficc.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# High quality, fast, modular reference implementation of SSD in PyTorch 1.0\n\n\nThis repository implements [SSD (Single Shot MultiBox Detector)](https://arxiv.org/abs/1512.02325). The implementation is heavily influenced by the projects [ssd.pytorch](https://github.com/amdegroot/ssd.pytorch), [pytorch-ssd](https://github.com/qfgaohao/pytorch-ssd) and [maskrcnn-benchmark](https://github.com/facebookresearch/maskrcnn-benchmark). This repository aims to be the code base for researches based on SSD.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"figures/004545.jpg\" width=\"500px\" /\u003e\n  \u003cp\u003eExample SSD output (vgg_ssd300_voc0712).\u003c/p\u003e\n\u003c/div\u003e\n\n| Losses        | Learning rate | Metrics |\n| :-----------: |:-------------:| :------:|\n| ![losses](figures/losses.png) | ![lr](figures/lr.png) | ![metric](figures/metrics.png) |\n\n## Highlights\n\n- **PyTorch 1.0**: Support PyTorch 1.0 or higher.\n- **Multi-GPU training and inference**: We use `DistributedDataParallel`, you can train or test with arbitrary GPU(s), the training schema will change accordingly.\n- **Modular**: Add your own modules without pain. We abstract `backbone`,`Detector`, `BoxHead`, `BoxPredictor`, etc. You can replace every component with your own code without change the code base. For example, You can add [EfficientNet](https://github.com/lukemelas/EfficientNet-PyTorch) as backbone, just add `efficient_net.py` (ALREADY ADDED) and register it, specific it in the config file, It's done!\n- **CPU support for inference**: runs on CPU in inference time.\n- **Smooth and enjoyable training procedure**: we save the state of model, optimizer, scheduler, training iter, you can stop your training and resume training exactly from the save point without change your training `CMD`.\n- **Batched inference**: can perform inference using multiple images per batch per GPU.\n- **Evaluating during training**: eval you model every `eval_step` to check performance improving or not.\n- **Metrics Visualization**: visualize metrics details in tensorboard, like AP, APl, APm and APs for COCO dataset or mAP and 20 categories' AP for VOC dataset.\n- **Auto download**: load pre-trained weights from URL and cache it.\n## Installation\n### Requirements\n\n1. Python3\n1. PyTorch 1.0 or higher\n1. yacs\n1. [Vizer](https://github.com/lufficc/Vizer)\n1. GCC \u003e= 4.9\n1. OpenCV\n\n\n### Step-by-step installation\n\n```bash\ngit clone https://github.com/lufficc/SSD.git\ncd SSD\n# Required packages: torch torchvision yacs tqdm opencv-python vizer\npip install -r requirements.txt\n\n# Done! That's ALL! No BUILD! No bothering SETUP!\n\n# It's recommended to install the latest release of torch and torchvision.\n```\n\n\n## Train\n\n### Setting Up Datasets\n#### Pascal VOC\n\nFor Pascal VOC dataset, make the folder structure like this:\n```\nVOC_ROOT\n|__ VOC2007\n    |_ JPEGImages\n    |_ Annotations\n    |_ ImageSets\n    |_ SegmentationClass\n|__ VOC2012\n    |_ JPEGImages\n    |_ Annotations\n    |_ ImageSets\n    |_ SegmentationClass\n|__ ...\n```\nWhere `VOC_ROOT` default is `datasets` folder in current project, you can create symlinks to `datasets` or `export VOC_ROOT=\"/path/to/voc_root\"`.\n\n#### COCO\n\nFor COCO dataset, make the folder structure like this:\n```\nCOCO_ROOT\n|__ annotations\n    |_ instances_valminusminival2014.json\n    |_ instances_minival2014.json\n    |_ instances_train2014.json\n    |_ instances_val2014.json\n    |_ ...\n|__ train2014\n    |_ \u003cim-1-name\u003e.jpg\n    |_ ...\n    |_ \u003cim-N-name\u003e.jpg\n|__ val2014\n    |_ \u003cim-1-name\u003e.jpg\n    |_ ...\n    |_ \u003cim-N-name\u003e.jpg\n|__ ...\n```\nWhere `COCO_ROOT` default is `datasets` folder in current project, you can create symlinks to `datasets` or `export COCO_ROOT=\"/path/to/coco_root\"`.\n\n### Single GPU training\n\n```bash\n# for example, train SSD300:\npython train.py --config-file configs/vgg_ssd300_voc0712.yaml\n```\n### Multi-GPU training\n\n```bash\n# for example, train SSD300 with 4 GPUs:\nexport NGPUS=4\npython -m torch.distributed.launch --nproc_per_node=$NGPUS train.py --config-file configs/vgg_ssd300_voc0712.yaml SOLVER.WARMUP_FACTOR 0.03333 SOLVER.WARMUP_ITERS 1000\n```\nThe configuration files that I provide assume that we are running on single GPU. When changing number of GPUs, hyper-parameter (lr, max_iter, ...) will also changed according to this paper: [Accurate, Large Minibatch SGD: Training ImageNet in 1 Hour](https://arxiv.org/abs/1706.02677).\n\n## Evaluate\n\n### Single GPU evaluating\n\n```bash\n# for example, evaluate SSD300:\npython test.py --config-file configs/vgg_ssd300_voc0712.yaml\n```\n\n### Multi-GPU evaluating\n\n```bash\n# for example, evaluate SSD300 with 4 GPUs:\nexport NGPUS=4\npython -m torch.distributed.launch --nproc_per_node=$NGPUS test.py --config-file configs/vgg_ssd300_voc0712.yaml\n```\n\n## Demo\n\nPredicting image in a folder is simple:\n```bash\npython demo.py --config-file configs/vgg_ssd300_voc0712.yaml --images_dir demo --ckpt https://github.com/lufficc/SSD/releases/download/1.2/vgg_ssd300_voc0712.pth\n```\nThen it will download and cache `vgg_ssd300_voc0712.pth` automatically and predicted images with boxes, scores and label names will saved to `demo/result` folder by default.\n\nYou will see a similar output:\n```text\n(0001/0005) 004101.jpg: objects 01 | load 010ms | inference 033ms | FPS 31\n(0002/0005) 003123.jpg: objects 05 | load 009ms | inference 019ms | FPS 53\n(0003/0005) 000342.jpg: objects 02 | load 009ms | inference 019ms | FPS 51\n(0004/0005) 008591.jpg: objects 02 | load 008ms | inference 020ms | FPS 50\n(0005/0005) 000542.jpg: objects 01 | load 011ms | inference 019ms | FPS 53\n```\n\n## MODEL ZOO\n### Origin Paper:\n\n|         | VOC2007 test | coco test-dev2015 |\n| :-----: | :----------: |   :----------:    |\n| SSD300* |     77.2     |      25.1         |\n| SSD512* |     79.8     |      28.8         |\n\n### COCO:\n\n| Backbone       | Input Size  |          box AP                  | Model Size |  Download |\n| :------------: | :----------:|   :--------------------------:   | :--------: | :-------: |\n|  VGG16         |     300     |          25.2                    |  262MB     | [model](https://github.com/lufficc/SSD/releases/download/1.2/vgg_ssd300_coco_trainval35k.pth)   |\n|  VGG16         |     512     |          29.0                    |  275MB     | [model](https://github.com/lufficc/SSD/releases/download/1.2/vgg_ssd512_coco_trainval35k.pth)   |\n\n### PASCAL VOC:\n\n| Backbone         | Input Size  |          mAP                     | Model Size | Download  |\n| :--------------: | :----------:|   :--------------------------:   | :--------: | :-------: |\n|  VGG16           |     300     |          77.7                    |   201MB    | [model](https://github.com/lufficc/SSD/releases/download/1.2/vgg_ssd300_voc0712.pth)  |\n|  VGG16           |     512     |          80.7                    |   207MB    | [model](https://github.com/lufficc/SSD/releases/download/1.2/vgg_ssd512_voc0712.pth)  |\n|  Mobilenet V2    |     320     |          68.9                    |   25.5MB   | [model](https://github.com/lufficc/SSD/releases/download/1.2/mobilenet_v2_ssd320_voc0712_v2.pth) |\n|  Mobilenet V3    |     320     |          69.5                    |   29.9MB   | [model](https://github.com/lufficc/SSD/releases/download/1.2/mobilenet_v3_ssd320_voc0712.pth) |\n|  EfficientNet-B3 |     300     |          73.9                    |   97.1MB   | [model](https://github.com/lufficc/SSD/releases/download/1.2/efficient_net_b3_ssd300_voc0712.pth) |\n\n## Develop Guide\n\nIf you want to add your custom components, please see [DEVELOP_GUIDE.md](DEVELOP_GUIDE.md) for more details.\n\n\n## Troubleshooting\nIf you have issues running or compiling this code, we have compiled a list of common issues in [TROUBLESHOOTING.md](TROUBLESHOOTING.md). If your issue is not present there, please feel free to open a new issue.\n\n## Citations\nIf you use this project in your research, please cite this project.\n```text\n@misc{lufficc2018ssd,\n    author = {Congcong Li},\n    title = {{High quality, fast, modular reference implementation of SSD in PyTorch}},\n    year = {2018},\n    howpublished = {\\url{https://github.com/lufficc/SSD}}\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flufficc%2FSSD","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flufficc%2FSSD","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flufficc%2FSSD/lists"}