# deep-person-reid **Repository Path**: james9/deep-person-reid ## Basic Information - **Project Name**: deep-person-reid - **Description**: Torchreid: Deep learning person re-identification in PyTorch. - **Primary Language**: Python - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2021-10-27 - **Last Updated**: 2021-10-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README Torchreid =========== Torchreid is a library for deep-learning person re-identification, written in `PyTorch `_ and developed for our ICCV'19 project, `Omni-Scale Feature Learning for Person Re-Identification `_. Torchreid 是一个用于深度学习人员重新识别的库，用 PyTorch 编写并为我们的 ICCV'19 项目“人员重新识别的全方位特征学习”开发。 It features（它的特点是）: - multi-GPU training 多GPU训练 - support both image- and video-reid 支持图像和视频reid - end-to-end training and evaluation 端到端的训练和评估 - incredibly easy preparation of reid datasets （非常容易地准备 reid 数据集） - 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 （访问预训练的 reid 模型） - 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（您可以找到一些建立在 Torchreid 之上的研究项目 ） `here `_. What's new ------------ - [Aug 2021] We have released the ImageNet-pretrained models of ``osnet_ain_x0_75``, ``osnet_ain_x0_5`` and ``osnet_ain_x0_25``. The pretraining setup follows `pycls `_. 我们已经发布了 osnet_ain_x0_75、osnet_ain_x0_5 和 osnet_ain_x0_25 的 ImageNet 预训练模型。 预训练设置如下。 - [Apr 2021] We have updated the appendix in the `TPAMI version of OSNet `_ to include results in the multi-source domain generalization setting. The trained models can be found in the `Model Zoo `_. 我们已更新 OSNet `_ 的`TPAMI 版本中的附录，以将结果包含在多源域泛化设置中。 训练好的模型可以在`Model Zoo `_中找到。 - [Apr 2021] We have added a script to automate the process of calculating average results over multiple splits. For more details please see ``tools/parse_test_res.py``. 我们添加了一个脚本来自动化计算多个分割的平均结果的过程。 有关更多详细信息，请参阅“tools/parse_test_res.py”。 - [Apr 2021] ``v1.4.0``: We added the person search dataset, `CUHK-SYSU `_. Please see the `documentation `_ regarding how to download the dataset (it contains cropped person images). ``v1.4.0``：我们添加了人物搜索数据集，`CUHK-SYSU `_。 关于如何下载数据集（它包含裁剪的人物图像），请参阅`文档`_。 - [Apr 2021] All models in the model zoo have been moved to google drive. Please raise an issue if any model's performance is inconsistent with the numbers shown in the model zoo page (could be caused by wrong links). 模型动物园中的所有模型都已移至谷歌驱动器。 如果任何模型的性能与模型动物园页面中显示的数字不一致（可能由错误链接引起），请提出问题。 - [Mar 2021] `OSNet `_ will appear in the TPAMI journal! Compared with the conference version, which focuses on discriminative feature learning using the omni-scale building block, this journal extension further considers generalizable feature learning by integrating `instance normalization layers `_ with the OSNet architecture. We hope this journal paper can motivate more future work to taclke the generalization issue in cross-dataset re-ID. [2021 年 3 月] `OSNet `_ 将出现在 TPAMI 期刊中！与专注于使用全方位构建块的判别特征学习的会议版本相比，本期刊扩展进一步考虑了通过将`实例归一化层`_与OSNet 架构。我们希望这篇期刊论文能够激发更多未来的工作来解决跨数据集 re-ID 中的泛化问题。 - [Mar 2021] Generalization across domains (datasets) in person re-ID is crucial in real-world applications, which is closely related to the topic of *domain generalization*. Interested in learning how the field of domain generalization has developed over the last decade? Check our recent survey in this topic at https://arxiv.org/abs/2103.02503, with coverage on the history, datasets, related problems, methodologies, potential directions, and so on (*methods designed for generalizable re-ID are also covered*!). [2021 年 3 月] 个人 re-ID 中跨域（数据集）的泛化在实际应用中至关重要，这与 *域泛化* 主题密切相关。有兴趣了解领域泛化领域在过去十年中是如何发展的？在 https://arxiv.org/abs/2103.02503 上查看我们最近关于该主题的调查，涵盖了历史、数据集、相关问题、方法论、潜在方向等（*为可泛化 re-ID 设计的方法也是覆盖*！）。 - [Feb 2021] ``v1.3.6`` Added `University-1652 `_, a new dataset for multi-view multi-source geo-localization (credit to `Zhedong Zheng `_). [2021 年 2 月] ``v1.3.6`` 添加了 `University-1652 `_，一个用于多视图多源地理的新数据集- 本地化（归功于`郑哲东`_）。 - [Feb 2021] ``v1.3.5``: Now the `cython code `_ works on Windows (credit to `lablabla `_). [2021 年 2 月] ``v1.3.5``：现在 `cython 代码 `_ 可在 Windows 上运行（归功于 `lablabla < https://github.com/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. [2021 年 1 月] 我们最近的工作，`MixStyle `_（混合不同域样本的实例级特征统计以提高域泛化），已被接受ICLR'21。代码已在 https://github.com/KaiyangZhou/mixstyle-release 发布，其中人员重新识别部分基于 Torchreid。 [2021 年 1 月] 在“用于人员重新识别的深度学习：调查和展望”(TPAMI 2021) `_。他们的代码可以在 ``_ 访问。 - [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``). ``v1.3.3``：修复了 ``visrank`` 中的错误（由未解压 ``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``. ``v1.3.2``：将 ``_junk_pids`` 添加到 ``grid`` 和 ``prid``。这可以避免在设置“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``). ``v1.3.0``：(1) 将 ``dsetid`` 添加到现有的 3 元组数据源，从而产生 ``(impath, pid, camid, dsetid)``。此变量表示数据集 ID，在组合多个数据集进行训练时很有用（作为数据集指标）。例如，当结合 ``market1501`` 和 ``cuhk03`` 时，前者将被分配 ``dsetid=0`` 而后者将被分配 ``dsetid=1``。 (2) 添加了“RandomDatasetSampler”。类似于“RandomDomainSampler”，“RandomDatasetSampler”从每个指定的数据集中抽取一定数量的图像（“batch_size // num_datasets”）（数量由“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). ``v1.2.6``：添加了 ``RandomDomainSampler``（它使用 ``batch_size // num_cams`` 图像对 ``num_cams`` 摄像头进行采样以形成小批量）。 - [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. ``v1.2.5``：(1) ``__getitem__`` 的 Dataloader 输出已从 ``list`` 更改为 ``dict``。以前，一个元素，例如图像张量，使用 ``imgs=data[0]`` 获取。现在它应该通过``imgs=data['img']`` 获得。有关详细更改，请参阅此 `commit `_。 (2) 添加 ``k_tfm`` 作为图像数据加载器的选项，它允许将数据增强应用 ``k_tfm`` 次*独立*到图像。如果 ``k_tfm > 1`` ， ``imgs=data['img']`` 返回一个包含 ``k_tfm`` 图像张量的列表。 - [May 2020] Added the person attribute recognition code used in `Omni-Scale Feature Learning for Person Re-Identification (ICCV'19) `_. See ``projects/attribute_recognition/``. 添加了用于人员重新识别的全方位特征学习 (ICCV'19) `_ 中使用的人员属性识别代码。参见“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``. ``v1.2.1``：添加了一个用于特征提取的简单 API (``torchreid/utils/feature_extractor.py``)。指令见`文档`_。 - [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 `_. 用于重现 `OSNet 论文 `_ .pdf>`__ (Supp. B) 已经在``projects/DML`` 发布。 - [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. 升级到“v1.2.0”。引擎类已变得更加与模型无关，以提高可扩展性。有关更多详细信息，请参阅`Engine `_ 和`ImageSoftmaxEngine `_。归功于`Dassl.pytorch `_。 - [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. 我们的 `OSNet 论文 `_ 已更新，额外的实验（在补充的 B 部分中）展示了一些提高 OSNet 性能的有用技术在 Installation --------------- Make sure `conda `_ is installed. 确保安装了 conda。 .. 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 use this code or the models in your research, please give credit to 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{zhou2021osnet, title={Learning Generalisable Omni-Scale Representations for Person Re-Identification}, author={Zhou, Kaiyang and Yang, Yongxin and Cavallaro, Andrea and Xiang, Tao}, journal={TPAMI}, year={2021} }