a.k.a. Modern Fast Image REtrieval

ModFire is a training, testing, deploying toolkit for modern fast image retrieval.

• Motivation
• Quick Start
  • Requirements
• Usage
  • Data
  • Training
• Contribute to this Repository
• To-do List
• References and License
  • References
  • Citation
  • Copyright

Motivation

Evaluating performance of a hashing / quantization based retrieval model is tricky. You may meet various evaluation protocols (3 kinds of CIFAR-10, 2 kinds of NUS-WIDE, the randomness in splits also matters a lot), you may handle different backbones (what should I use? AlexNet, VGG, ResNet?), you may even fight with some legacy codes (lots of troubles with Caffe, MXNet, TensorFlow). These just mess things up.

A comprehensive benchmark is needed for all methods --- with the latest deep learning tricks. Therefore, this repo issues the whole pipeline for it, with the extensible and customizable training and evaluation configs.

Quick Start

Requirements

• Hardware
  • A CUDA-enabled GPU (≥ 16GiB VRAM)
  • ≥ 32GiB RAM
• OS
  • All features are tested on Ubuntu 20.04, other platforms should also work. If not, please file bugs.
• Software
  • A conda environment is highly recommended.
  • Python should be < 3.9 due to package dependencies. The following packages would be installed if missed, but it's still recommended to install them manually to choose your preferred version.
  • PyTorch >= 11.3 with torchdata, torchvision.
  • faiss-cpu >= 1.7

To use ModFire, a direct way is to use the PyPI package:

pip install modfire
modfire -v

That will prints:

                      _  __ _
  _ __ ___   ___   __| |/ _(_)_ __ ___
 | '_ ` _ \ / _ \ / _` | |_| | '__/ _ \
 | | | | | | (_) | (_| |  _| | | |  __/
 |_| |_| |_|\___/ \__,_|_| |_|_|  \___|

0.1.0

Usage

Data

Common retrieval datasets are included in the repo.

modfire dataset

Available datasets are:
      CIFAR10     : modfire.dataset.easy.cifar.CIFAR10
      CIFAR100    : modfire.dataset.easy.cifar.CIFAR100
      COCO        : modfire.dataset.easy.coco.COCO
      ImageNet100 : modfire.dataset.easy.imagenet100.ImageNet100
      MIRFlickr25k: modfire.dataset.easy.mirflickr25k.MIRFlickr25k
      NUS_WIDE    : modfire.dataset.easy.nuswide.NUS_WIDE

You could download them by just a command.

modfire dataset --root [TARGET_DIR] [DATASET_NAME]

Training

modfire train [CONFIG_PATH]

Contribute to this Repository

Just like other git repos, before raising issues or pull requests, please take a thorough look at issue templates.

To-do List

• Benchmarking site

References and License

References

Citation

Copyright

Fonts:

• [Don Perry]

Pictures:

Third-party repos:

Repos	License
PyTorch	BSD-style
Torchvision	BSD-3-Clause
Apex	BSD-3-Clause
Tensorboard	Apache-2.0
Kornia	Apache-2.0
rich	MIT
python-lmdb	OpenLDAP Version 2.8
PyYAML	MIT
marshmallow	MIT
click	BSD-3-Clause
vlutils	Apache-2.0
MessagePack	Apache-2.0
marshmallow-jsonschema	MIT
json-schema-for-humans	Apache-2.0
CyclicLR	MIT
Streamlit	Apache-2.0
conda	BSD 3-Clause

This repo is licensed under

Apache License
Version 2.0