diff --git a/README.rst b/README.rst deleted file mode 100755 index c85209c..0000000 --- a/README.rst +++ /dev/null @@ -1,310 +0,0 @@ -Torchreid -=========== -Torchreid is a library for deep-learning person re-identification, written in `PyTorch `_. - -It features: - -- multi-GPU training -- support both image- and video-reid -- end-to-end training and evaluation -- incredibly easy preparation of reid datasets -- multi-dataset training -- cross-dataset evaluation -- standard protocol used by most research papers -- highly extensible (easy to add models, datasets, training methods, etc.) -- implementations of state-of-the-art deep reid models -- access to pretrained reid models -- advanced training techniques -- visualization tools (tensorboard, ranks, etc.) - - -Code: https://github.com/KaiyangZhou/deep-person-reid. - -Documentation: https://kaiyangzhou.github.io/deep-person-reid/. - -How-to instructions: https://kaiyangzhou.github.io/deep-person-reid/user_guide. - -Model zoo: https://kaiyangzhou.github.io/deep-person-reid/MODEL_ZOO. - -Tech report: https://arxiv.org/abs/1910.10093. - -You can find some research projects that are built on top of Torchreid `here `_. - - -What's new ------------- -- [Feb 2021] ``v1.3.6`` Added `University-1652 `_, a new dataset for multi-view multi-source geo-localization (credit to `Zhedong Zheng `_). -- [Feb 2021] ``v1.3.5``: Now the `cython code `_ works on Windows (credit to `lablabla `_). -- [Jan 2021] Our recent work, `MixStyle `_ (mixing instance-level feature statistics of samples of different domains for improving domain generalization), has been accepted to ICLR'21. The code has been released at https://github.com/KaiyangZhou/mixstyle-release where the person re-ID part is based on Torchreid. -- [Jan 2021] A new evaluation metric called `mean Inverse Negative Penalty (mINP)` for person re-ID has been introduced in `Deep Learning for Person Re-identification: A Survey and Outlook (TPAMI 2021) `_. Their code can be accessed at ``_. -- [Aug 2020] ``v1.3.3``: Fixed bug in ``visrank`` (caused by not unpacking ``dsetid``). -- [Aug 2020] ``v1.3.2``: Added ``_junk_pids`` to ``grid`` and ``prid``. This avoids using mislabeled gallery images for training when setting ``combineall=True``. -- [Aug 2020] ``v1.3.0``: (1) Added ``dsetid`` to the existing 3-tuple data source, resulting in ``(impath, pid, camid, dsetid)``. This variable denotes the dataset ID and is useful when combining multiple datasets for training (as a dataset indicator). E.g., when combining ``market1501`` and ``cuhk03``, the former will be assigned ``dsetid=0`` while the latter will be assigned ``dsetid=1``. (2) Added ``RandomDatasetSampler``. Analogous to ``RandomDomainSampler``, ``RandomDatasetSampler`` samples a certain number of images (``batch_size // num_datasets``) from each of specified datasets (the amount is determined by ``num_datasets``). -- [Aug 2020] ``v1.2.6``: Added ``RandomDomainSampler`` (it samples ``num_cams`` cameras each with ``batch_size // num_cams`` images to form a mini-batch). -- [Jun 2020] ``v1.2.5``: (1) Dataloader's output from ``__getitem__`` has been changed from ``list`` to ``dict``. Previously, an element, e.g. image tensor, was fetched with ``imgs=data[0]``. Now it should be obtained by ``imgs=data['img']``. See this `commit `_ for detailed changes. (2) Added ``k_tfm`` as an option to image data loader, which allows data augmentation to be applied ``k_tfm`` times *independently* to an image. If ``k_tfm > 1``, ``imgs=data['img']`` returns a list with ``k_tfm`` image tensors. -- [May 2020] Added the person attribute recognition code used in `Omni-Scale Feature Learning for Person Re-Identification (ICCV'19) `_. See ``projects/attribute_recognition/``. -- [May 2020] ``v1.2.1``: Added a simple API for feature extraction (``torchreid/utils/feature_extractor.py``). See the `documentation `_ for the instruction. -- [Apr 2020] Code for reproducing the experiments of `deep mutual learning `_ in the `OSNet paper `__ (Supp. B) has been released at ``projects/DML``. -- [Apr 2020] Upgraded to ``v1.2.0``. The engine class has been made more model-agnostic to improve extensibility. See `Engine `_ and `ImageSoftmaxEngine `_ for more details. Credit to `Dassl.pytorch `_. -- [Dec 2019] Our `OSNet paper `_ has been updated, with additional experiments (in section B of the supplementary) showing some useful techniques for improving OSNet's performance in practice. -- [Nov 2019] ``ImageDataManager`` can load training data from target datasets by setting ``load_train_targets=True``, and the train-loader can be accessed with ``train_loader_t = datamanager.train_loader_t``. This feature is useful for domain adaptation research. - - -Installation ---------------- - -Make sure `conda `_ is installed. - - -.. code-block:: bash - - # cd to your preferred directory and clone this repo - git clone https://github.com/KaiyangZhou/deep-person-reid.git - - # create environment - cd deep-person-reid/ - conda create --name torchreid python=3.7 - conda activate torchreid - - # install dependencies - # make sure `which python` and `which pip` point to the correct path - pip install -r requirements.txt - - # install torch and torchvision (select the proper cuda version to suit your machine) - conda install pytorch torchvision cudatoolkit=9.0 -c pytorch - - # install torchreid (don't need to re-build it if you modify the source code) - python setup.py develop - - -Get started: 30 seconds to Torchreid -------------------------------------- -1. Import ``torchreid`` - -.. code-block:: python - - import torchreid - -2. Load data manager - -.. code-block:: python - - datamanager = torchreid.data.ImageDataManager( - root='reid-data', - sources='market1501', - targets='market1501', - height=256, - width=128, - batch_size_train=32, - batch_size_test=100, - transforms=['random_flip', 'random_crop'] - ) - -3 Build model, optimizer and lr_scheduler - -.. code-block:: python - - model = torchreid.models.build_model( - name='resnet50', - num_classes=datamanager.num_train_pids, - loss='softmax', - pretrained=True - ) - - model = model.cuda() - - optimizer = torchreid.optim.build_optimizer( - model, - optim='adam', - lr=0.0003 - ) - - scheduler = torchreid.optim.build_lr_scheduler( - optimizer, - lr_scheduler='single_step', - stepsize=20 - ) - -4. Build engine - -.. code-block:: python - - engine = torchreid.engine.ImageSoftmaxEngine( - datamanager, - model, - optimizer=optimizer, - scheduler=scheduler, - label_smooth=True - ) - -5. Run training and test - -.. code-block:: python - - engine.run( - save_dir='log/resnet50', - max_epoch=60, - eval_freq=10, - print_freq=10, - test_only=False - ) - - -A unified interface ------------------------ -In "deep-person-reid/scripts/", we provide a unified interface to train and test a model. See "scripts/main.py" and "scripts/default_config.py" for more details. The folder "configs/" contains some predefined configs which you can use as a starting point. - -Below we provide an example to train and test `OSNet (Zhou et al. ICCV'19) `_. Assume :code:`PATH_TO_DATA` is the directory containing reid datasets. The environmental variable :code:`CUDA_VISIBLE_DEVICES` is omitted, which you need to specify if you have a pool of gpus and want to use a specific set of them. - -Conventional setting -^^^^^^^^^^^^^^^^^^^^^ - -To train OSNet on Market1501, do - -.. code-block:: bash - - python scripts/main.py \ - --config-file configs/im_osnet_x1_0_softmax_256x128_amsgrad_cosine.yaml \ - --transforms random_flip random_erase \ - --root $PATH_TO_DATA - - -The config file sets Market1501 as the default dataset. If you wanna use DukeMTMC-reID, do - -.. code-block:: bash - - python scripts/main.py \ - --config-file configs/im_osnet_x1_0_softmax_256x128_amsgrad_cosine.yaml \ - -s dukemtmcreid \ - -t dukemtmcreid \ - --transforms random_flip random_erase \ - --root $PATH_TO_DATA \ - data.save_dir log/osnet_x1_0_dukemtmcreid_softmax_cosinelr - -The code will automatically (download and) load the ImageNet pretrained weights. After the training is done, the model will be saved as "log/osnet_x1_0_market1501_softmax_cosinelr/model.pth.tar-250". Under the same folder, you can find the `tensorboard `_ file. To visualize the learning curves using tensorboard, you can run :code:`tensorboard --logdir=log/osnet_x1_0_market1501_softmax_cosinelr` in the terminal and visit :code:`http://localhost:6006/` in your web browser. - -Evaluation is automatically performed at the end of training. To run the test again using the trained model, do - -.. code-block:: bash - - python scripts/main.py \ - --config-file configs/im_osnet_x1_0_softmax_256x128_amsgrad_cosine.yaml \ - --root $PATH_TO_DATA \ - model.load_weights log/osnet_x1_0_market1501_softmax_cosinelr/model.pth.tar-250 \ - test.evaluate True - - -Cross-domain setting -^^^^^^^^^^^^^^^^^^^^^ - -Suppose you wanna train OSNet on DukeMTMC-reID and test its performance on Market1501, you can do - -.. code-block:: bash - - python scripts/main.py \ - --config-file configs/im_osnet_x1_0_softmax_256x128_amsgrad.yaml \ - -s dukemtmcreid \ - -t market1501 \ - --transforms random_flip color_jitter \ - --root $PATH_TO_DATA - -Here we only test the cross-domain performance. However, if you also want to test the performance on the source dataset, i.e. DukeMTMC-reID, you can set :code:`-t dukemtmcreid market1501`, which will evaluate the model on the two datasets separately. - -Different from the same-domain setting, here we replace :code:`random_erase` with :code:`color_jitter`. This can improve the generalization performance on the unseen target dataset. - -Pretrained models are available in the `Model Zoo `_. - - -Datasets --------- - -Image-reid datasets -^^^^^^^^^^^^^^^^^^^^^ -- `Market1501 `_ -- `CUHK03 `_ -- `DukeMTMC-reID `_ -- `MSMT17 `_ -- `VIPeR `_ -- `GRID `_ -- `CUHK01 `_ -- `SenseReID `_ -- `QMUL-iLIDS `_ -- `PRID `_ - -Geo-localization datasets -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- `University-1652 `_ - -Video-reid datasets -^^^^^^^^^^^^^^^^^^^^^^^ -- `MARS `_ -- `iLIDS-VID `_ -- `PRID2011 `_ -- `DukeMTMC-VideoReID `_ - - -Models -------- - -ImageNet classification models -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- `ResNet `_ -- `ResNeXt `_ -- `SENet `_ -- `DenseNet `_ -- `Inception-ResNet-V2 `_ -- `Inception-V4 `_ -- `Xception `_ -- `IBN-Net `_ - -Lightweight models -^^^^^^^^^^^^^^^^^^^ -- `NASNet `_ -- `MobileNetV2 `_ -- `ShuffleNet `_ -- `ShuffleNetV2 `_ -- `SqueezeNet `_ - -ReID-specific models -^^^^^^^^^^^^^^^^^^^^^^ -- `MuDeep `_ -- `ResNet-mid `_ -- `HACNN `_ -- `PCB `_ -- `MLFN `_ -- `OSNet `_ -- `OSNet-AIN `_ - - -Useful links -------------- -- `OSNet-IBN1-Lite (test-only code with lite docker container) `_ -- `Deep Learning for Person Re-identification: A Survey and Outlook `_ - - -Citation ---------- -If you find this code useful to your research, please cite the following papers. - -.. code-block:: bash - - @article{torchreid, - title={Torchreid: A Library for Deep Learning Person Re-Identification in Pytorch}, - author={Zhou, Kaiyang and Xiang, Tao}, - journal={arXiv preprint arXiv:1910.10093}, - year={2019} - } - - @inproceedings{zhou2019osnet, - title={Omni-Scale Feature Learning for Person Re-Identification}, - author={Zhou, Kaiyang and Yang, Yongxin and Cavallaro, Andrea and Xiang, Tao}, - booktitle={ICCV}, - year={2019} - } - - @article{zhou2019learning, - title={Learning Generalisable Omni-Scale Representations for Person Re-Identification}, - author={Zhou, Kaiyang and Yang, Yongxin and Cavallaro, Andrea and Xiang, Tao}, - journal={arXiv preprint arXiv:1910.06827}, - year={2019} - }