Gallery Filter Network for Person Search

This repository implements the models described in the paper, "Gallery Filter Network for Person Search". The Object Search Research (OSR) package implements data prep, training, and inference for the CUHK-SYSU and PRW datasets. The package is easily extensible to other datasets.

We achieve state-of-the-art results on the benchmark CUHK-SYSU and PRW datasets, shown below, with downloadable model checkpoints. Metrics are computed with and without the Gallery Filter Network (GFN).

Dataset	Backbone	mAP	Top-1	mAP (GFN)	Top-1 (GFN)	Model
PRW	ConvNeXt Base	57.6	89.5	58.3	92.4	model
PRW	ResNet50	50.8	86.0	51.3	90.6	---
CUHK-SYSU	ConvNeXt Base	96.1	96.5	96.4	97.0	model
CUHK-SYSU	ResNet50	94.1	94.7	94.7	95.3	---

Installation

The OSR package can be installed with docker or conda. We provide example install instructions below, so the user can use the commands in setup.py "out of the box".

docker

host$ docker build --no-cache -t osr:v1.0.0 -f Dockerfile .

host$ docker run -it --rm \
        --ulimit core=0 \
        --name=osr_$(date +%F_%H-%M-%S) \
        --runtime=nvidia \
        --net=host \
        -v /dev/shm:/dev/shm \
        -v <PRW_PATH>:/datasets/prw \
        -v <CUHK_PATH>:/datasets/cuhk \
        -v $(pwd)/weights:/weights/hub \
        -v $(pwd):/home/username \
        -w /home/username \
        osr:v1.0.0 bash -c \
                "chown -R $(id -u):$(id -g) /home/username;\
                 groupadd -g $(id -g) groupname;\
                 useradd -u $(id -u) -g $(id -g) -d /home/username username;\
                 su username -s /bin/bash;"

container$ export PATH=${PATH}:/opt/conda/bin

You can also re-install in the container with:

container$ python3 setup.py install --user

conda

(base)$ conda env create -f conda.yaml

(base)$ conda activate osr

(osr)$ python3 setup.py install --user

Data Download

Optionally install gdown python package for easy download of the datasets from google drive.

pip install --user gdown

PRW

cd $DATASET_DIR
gdown https://drive.google.com/uc?id=0B6tjyrV1YrHeYnlhNnhEYTh5MUU
unzip PRW-v16.04.20.zip -d prw

CUHK-SYSU

cd $DATASET_DIR 
gdown https://drive.google.com/uc?id=1z3LsFrJTUeEX3-XjSEJMOBrslxD2T5af 
tar -xzvf cuhk_sysu.tar.gz -C cuhk

Data Prep

After docker or conda installation of the package above, simply run:

osr_prep_cuhk --dataset_dir ${DATASET_DIR}/cuhk
osr_prep_prw --dataset_dir ${DATASET_DIR}/prw

Config

For training and inference, we use .yaml files for the config format, with examples in the ./configs dir. Config files inherit from ./configs/default.yaml, which has all possible parameters, with documentation.

To train or test, make sure to first modify the dataset_dir in the target config .yaml.

We include config files for all the experiments in the main paper:

- baseline model
- final model
- augmentation ablation
- crop size ablation
- GFN objective ablation

Some configs group params together for easy running with ray tune grid_search. Additional config files, e.g., from supplementary experiments, are available upon request.

Training

To train the final models:

osr_run --trial_config=./configs/cuhk_train_final.yaml
osr_run --trial_config=./configs/prw_train_final.yaml

Inference

Trained model checkpoints are available upon request, but are too large to come with this export. To test, you will need to run the training script, then modify the checkpoint path in the test .yaml files to the resulting training checkpoint.

To test the final models:

osr_run --trial_config=./configs/cuhk_test_final.yaml
osr_run --trial_config=./configs/prw_test_final.yaml

Acknowledgment

Thanks to the authors of the following repos for their code, which was integral in this project:

Citation

@article{jaffe2022gfn,
  title={Gallery Filter Network for Person Search},
  author={Jaffe, Lucas and Zakhor, Avideh},
  journal={arXiv preprint arXiv:2210.12903}, 
  year={2022}
}

dustasa / GFN