{"id":13627451,"url":"https://github.com/zhreshold/mxnet-ssd","last_synced_at":"2025-05-16T09:05:38.318Z","repository":{"id":46629910,"uuid":"69511580","full_name":"zhreshold/mxnet-ssd","owner":"zhreshold","description":"MXNet port of SSD: Single Shot MultiBox Object Detector.  Reimplementation of https://github.com/weiliu89/caffe/tree/ssd","archived":false,"fork":false,"pushed_at":"2024-05-16T18:17:10.000Z","size":6329,"stargazers_count":763,"open_issues_count":95,"forks_count":334,"subscribers_count":49,"default_branch":"master","last_synced_at":"2025-04-09T04:03:30.236Z","etag":null,"topics":["object-detection"],"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/zhreshold.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,"publiccode":null,"codemeta":null}},"created_at":"2016-09-28T23:20:20.000Z","updated_at":"2024-11-18T06:39:14.000Z","dependencies_parsed_at":"2024-06-11T20:38:55.549Z","dependency_job_id":"eac80e97-e973-4536-ae97-fc86692aaf7a","html_url":"https://github.com/zhreshold/mxnet-ssd","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhreshold%2Fmxnet-ssd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhreshold%2Fmxnet-ssd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhreshold%2Fmxnet-ssd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhreshold%2Fmxnet-ssd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhreshold","download_url":"https://codeload.github.com/zhreshold/mxnet-ssd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254501557,"owners_count":22081528,"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":["object-detection"],"created_at":"2024-08-01T22:00:34.237Z","updated_at":"2025-05-16T09:05:33.307Z","avatar_url":"https://github.com/zhreshold.png","language":"Python","funding_links":[],"categories":["\u003ca name=\"Vision\"\u003e\u003c/a\u003e2. Vision","Python","Model Deployment library"],"sub_categories":["2.2 Object Detection","MXNet \u003ca name=\"mxnet\"/\u003e"],"readme":"# SSD: Single Shot MultiBox Object Detector\n\nSSD is an unified framework for object detection with a single network.\n\nYou can use the code to train/evaluate/test for object detection task.\n\n### Disclaimer\nThis is a re-implementation of original SSD which is based on caffe. The official\nrepository is available [here](https://github.com/weiliu89/caffe/tree/ssd).\nThe arXiv paper is available [here](http://arxiv.org/abs/1512.02325).\n\nThis example is intended for reproducing the nice detector while fully utilize the\nremarkable traits of MXNet.\n* The model is fully compatible with caffe version.\n* Model [converter](#convert-caffemodel) from caffe is available now!\n* The result is almost identical to the original version. However, due to different implementation details, the results might differ slightly.\n\n### What's new\n* **This repo is now deprecated, I am migrating to the latest [Gluon-CV](https://github.com/dmlc/gluon-cv) which is more user friendly and has a lot more algorithms in development. This repo will not receive active development, however, you can continue use it with the mxnet 1.1.0(probably 1.2.0).**\n* Now this repo is internally synchronized up to data with offical mxnet backend. `pip install mxnet` will work for this repo as well in most cases.\n* MobileNet pretrained model now provided.\n* Added multiple trained models.\n* Added a much simpler way to compose network from mainstream classification networks (resnet, inception...) and [Guide](symbol/README.md).\n* Update to the latest version according to caffe version, with 5% mAP increase.\n* Use C++ record iterator based on back-end multi-thread engine to achieve huge speed up on multi-gpu environments.\n* Monitor validation mAP during training.\n* More network symbols under development and test.\n* Extra operators are now in `mxnet/src/operator/contrib`, symbols are modified. Please use [Release-v0.2-beta](https://github.com/zhreshold/mxnet-ssd/releases/tag/v0.2-beta) for old models.\n* added Docker support for this repository, prebuilt \u0026 including all packages and dependencies. (linux only)\n* added tensorboard support, allowing a more convenient way of research. (linux only)\n\n### Demo results\n![demo1](https://cloud.githubusercontent.com/assets/3307514/19171057/8e1a0cc4-8be0-11e6-9d8f-088c25353b40.png)\n![demo2](https://cloud.githubusercontent.com/assets/3307514/19171063/91ec2792-8be0-11e6-983c-773bd6868fa8.png)\n![demo3](https://cloud.githubusercontent.com/assets/3307514/19171086/a9346842-8be0-11e6-8011-c17716b22ad3.png)\n\n### mAP\n|        Model          | Training data    | Test data |  mAP | Note |\n|:-----------------:|:----------------:|:---------:|:----:|:-----|\n| [VGG16_reduced 300x300](https://github.com/zhreshold/mxnet-ssd/releases/download/v0.5-beta/vgg16_ssd_300_voc0712_trainval.zip) | VOC07+12 trainval| VOC07 test| 77.8| fast |\n| [VGG16_reduced 512x512](https://github.com/zhreshold/mxnet-ssd/releases/download/v0.5-beta/vgg16_ssd_512_voc0712_trainval.zip) | VOC07+12 trainval | VOC07 test| 79.9| slow |\n| [Inception-v3 512x512](https://github.com/zhreshold/mxnet-ssd/releases/download/v0.7-alpha/ssd_inceptionv3_512_voc0712trainval.zip) | VOC07+12 trainval| VOC07 test| 78.9 | fastest |\n| [Resnet-50 512x512](https://github.com/zhreshold/mxnet-ssd/releases/download/v0.7-alpha/ssd_resnet50_512_voc0712trainval.zip) | VOC07+12 trainval| VOC07 test| 79.1 | fast |\n| [MobileNet 512x512](https://github.com/zhreshold/mxnet-ssd/releases/download/v0.7-alpha/mobilenet-ssd-512.zip) | VOC07+12 trainval| VOC07 test| 72.5 | super fast |\n| [MobileNet 608x608](https://github.com/zhreshold/mxnet-ssd/releases/download/v0.7-alpha/mobilenet-ssd-608.zip) | VOC07+12 trainval| VOC07 test| 74.7 | super fast |\n\n\n*More to be added*\n\n### Speed\n|         Model         |   GPU            | CUDNN | Batch-size | FPS* |\n|:---------------------:|:----------------:|:-----:|:----------:|:----:|\n| VGG16_reduced 300x300 | TITAN X(Maxwell) | v5.1  |     16     | 95   |\n| VGG16_reduced 300x300 | TITAN X(Maxwell) | v5.1  |     8      | 95   |\n| VGG16_reduced 300x300 | TITAN X(Maxwell) | v5.1  |     1      | 64   |\n| VGG16_reduced 300x300 | TITAN X(Maxwell) |  N/A  |     8      | 36   |\n| VGG16_reduced 300x300 | TITAN X(Maxwell) |  N/A  |     1      | 28   |\n\n*Forward time only, data loading and drawing excluded.*\n\n### Getting started\n* Option #1 - install using 'Docker'. if you are not familiar with this technology, there is a 'Docker' section below.\nyou can get the latest image:\n```\ndocker pull daviddocker78/mxnet-ssd:gpu_0.12.0_cuda9\n```\n* You will need python modules: `cv2`, `matplotlib` and `numpy`.\nIf you use mxnet-python api, you probably have already got them.\nYou can install them via pip or package manegers, such as `apt-get`:\n```\nsudo apt-get install python-opencv python-matplotlib python-numpy\n```\n* Clone this repo:\n```\n# if you don't have git, install it via apt or homebrew/yum based on your system\nsudo apt-get install git\n# cd where you would like to clone this repo\ncd ~\ngit clone --recursive https://github.com/zhreshold/mxnet-ssd.git\n# make sure you clone this with --recursive\n# if not done correctly or you are using downloaded repo, pull them all via:\n# git submodule update --recursive --init\ncd mxnet-ssd/mxnet\n```\n* (Skip this step if you have offcial MXNet installed.) Build MXNet: `cd /path/to/mxnet-ssd/mxnet`. Follow the official instructions [here](http://mxnet.io/get_started/install.html).\n```\n# for Ubuntu/Debian\ncp make/config.mk ./config.mk\n# modify it if necessary\n```\nRemember to enable CUDA if you want to be able to train, since CPU training is\ninsanely slow. Using CUDNN is optional, but highly recommanded.\n\n### Try the demo\n* Download the pretrained model: [`ssd_resnet50_0712.zip`](https://github.com/zhreshold/mxnet-ssd/releases/download/v0.6/resnet50_ssd_512_voc0712_trainval.zip), and extract to `model/` directory.\n* Run\n```\n# cd /path/to/mxnet-ssd\npython demo.py --gpu 0\n# play with examples:\npython demo.py --epoch 0 --images ./data/demo/dog.jpg --thresh 0.5\npython demo.py --cpu --network resnet50 --data-shape 512\n# wait for library to load for the first time\n```\n* Check `python demo.py --help` for more options.\n\n### Train the model\nThis example only covers training on Pascal VOC dataset. Other datasets should\nbe easily supported by adding subclass derived from class `Imdb` in `dataset/imdb.py`.\nSee example of `dataset/pascal_voc.py` for details.\n* Download the converted pretrained `vgg16_reduced` model [here](https://github.com/zhreshold/mxnet-ssd/releases/download/v0.2-beta/vgg16_reduced.zip), unzip `.param` and `.json` files\ninto `model/` directory by default.\n* Download the PASCAL VOC dataset, skip this step if you already have one.\n```\ncd /path/to/where_you_store_datasets/\nwget http://host.robots.ox.ac.uk/pascal/VOC/voc2012/VOCtrainval_11-May-2012.tar\nwget http://host.robots.ox.ac.uk/pascal/VOC/voc2007/VOCtrainval_06-Nov-2007.tar\nwget http://host.robots.ox.ac.uk/pascal/VOC/voc2007/VOCtest_06-Nov-2007.tar\n# Extract the data.\ntar -xvf VOCtrainval_11-May-2012.tar\ntar -xvf VOCtrainval_06-Nov-2007.tar\ntar -xvf VOCtest_06-Nov-2007.tar\n```\n* We are going to use `trainval` set in VOC2007/2012 as a common strategy.\nThe suggested directory structure is to store `VOC2007` and `VOC2012` directories\nin the same `VOCdevkit` folder.\n* Then link `VOCdevkit` folder to `data/VOCdevkit` by default:\n```\nln -s /path/to/VOCdevkit /path/to/this_example/data/VOCdevkit\n```\nUse hard link instead of copy could save us a bit disk space.\n* Create packed binary file for faster training:\n```\n# cd /path/to/mxnet-ssd\nbash tools/prepare_pascal.sh\n# or if you are using windows\npython tools/prepare_dataset.py --dataset pascal --year 2007,2012 --set trainval --target ./data/train.lst\npython tools/prepare_dataset.py --dataset pascal --year 2007 --set test --target ./data/val.lst --shuffle False\n```\n* Start training:\n```\npython train.py\n```\n* By default, this example will use `batch-size=32` and `learning_rate=0.004`.\nYou might need to change the parameters a bit if you have different configurations.\nCheck `python train.py --help` for more training options. For example, if you have 4 GPUs, use:\n```\n# note that a perfect training parameter set is yet to be discovered for multi-gpu\npython train.py --gpus 0,1,2,3 --batch-size 128 --lr 0.001\n```\n* Memory usage: MXNet is very memory efficient, training on `VGG16_reduced` model with `batch-size` 32 takes around 4684MB without CUDNN(conv1_x and conv2_x fixed).\n\n### Evalute trained model\nUse:\n```\n# cd /path/to/mxnet-ssd\npython evaluate.py --gpus 0,1 --batch-size 128 --epoch 0\n```\n### Convert model to deploy mode\nThis simply removes all loss layers, and attach a layer for merging results and non-maximum suppression.\nUseful when loading python symbol is not available.\n```\n# cd /path/to/mxnet-ssd\npython deploy.py --num-class 20\n# then you can run demo with new model without loading python symbol\npython demo.py --prefix model/ssd_300_deploy --epoch 0 --deploy\n```\n\n### Convert caffemodel\nConverter from caffe is available at `/path/to/mxnet-ssd/tools/caffe_converter`\n\nThis is specifically modified to handle custom layer in caffe-ssd. Usage:\n```\ncd /path/to/mxnet-ssd/tools/caffe_converter\nmake\npython convert_model.py deploy.prototxt name_of_pretrained_caffe_model.caffemodel ssd_converted\n# you will use this model in deploy mode without loading from python symbol\npython demo.py --prefix ssd_converted --epoch 1 --deploy\n```\nThere is no guarantee that conversion will always work, but at least it's good for now.\n\n### Legacy models\nSince the new interface for composing network is introduced, the old models have inconsistent names for weights.\nYou can still load the previous model by rename the symbol to `legacy_xxx.py`\nand call with `python train/demo.py --network legacy_xxx `\nFor example:\n```\npython demo.py --network 'legacy_vgg16_ssd_300.py' --prefix model/ssd_300 --epoch 0\n```\n\n### Docker \nFirst make sure [docker](https://docs.docker.com/engine/installation/) is\ninstalled. The docker plugin\n[nvidia-docker](https://github.com/NVIDIA/nvidia-docker) is required to run on\nNvidia GPUs.\n\n* pre-built docker images are available at https://hub.docker.com/r/daviddocker78/mxnet-ssd/\nto download a pre-built image, run:\n```\ndocker pull daviddocker78/mxnet-ssd:gpu_0.12.0_cuda9\n```\nOtherwise, if you wish to build it yourself, you have the Dockerfiles available in this repo, under the 'docker' folder.\n* to run a container instance:\n```\nnvidia-docker run -it --rm myImageName:tag\n```\nnow you can execute commands the same way as you would, if you'd install mxnet on your own computer.\nfor more information, see the [Guide](docker/README.md).\n\n### Tensorboard\n* There has been some great effort to bring tensorboard to mxnet.\nIf you chose to work with dockers, you have it installed in the pre-built image you've downloaded. otherwise, follow [here](https://github.com/dmlc/tensorboard) for installation steps.\n* To save training loss graphs, validation AP per class, and validation ROC graphs to tensorboard while training, you can specify:\n```\npython train.py --gpus 0,1,2,3 --batch-size 128 --lr 0.001 --tensorboard True\n```\n* To save also the distributions of layers (actually, the variance of them), you can specify:\n```\npython train.py --gpus 0,1,2,3 --batch-size 128 --lr 0.001 --tensorboard True --monitor 40\n```\n* Visualization with Docker: the UI of tensorboard has changed over time. to get the best experience, download the new tensorflow docker-image:\n```\n# download the built image from Dockerhub\ndocker pull tensorflow/tensorflow:1.4.0-devel-gpu\n# run a container and open a port using '-p' flag. \n# attach a volume from where you stored your logs, to a directory inside the container\nnvidia-docker run -it --rm -p 0.0.0.0:6006:6006 -v /my/full/experiment/path:/res tensorflow/tensorflow:1.4.0-devel-gpu\ncd /res\ntensorboard --logdir=.\n```\nTo launch tensorboard without docker, simply run the last command\nNow tensorboard is loading the tensorEvents of your experiment. open your browser under '0.0.0.0:6006' and you will have tensorboard!\n\n### Tensorboard visualizations\n![loss](https://user-images.githubusercontent.com/12379769/32689844-5e26ca0c-c6f4-11e7-9a09-a63da1a53b43.PNG)\n![AP](https://user-images.githubusercontent.com/12379769/32689857-89aa967c-c6f4-11e7-8c2b-6ebce88467b4.PNG)\n![ROC](https://user-images.githubusercontent.com/12379769/32689860-ada24e44-c6f4-11e7-99b7-75c78db4025d.PNG)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhreshold%2Fmxnet-ssd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhreshold%2Fmxnet-ssd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhreshold%2Fmxnet-ssd/lists"}