Home

Awesome

<h1 align="center"> <a href="http://ivg.au.tsinghua.edu.cn/"> <img alt="Logo" src=".docsrc/assets/readme/header.jpg"> </a> </h1> <p align="center"> <a href="https://badge.fury.io/py/gedml"> <img alt="PyPi version" src="https://badge.fury.io/py/gedml.svg"> </a> <a href="https://github.com/zbr17/GeDML/blob/master/.github/workflows/sphinx_pages.yml"> <img alt="Documentation build" src="https://github.com/zbr17/GeDML/workflows/Documentation/badge.svg"> </a> </p>

News

Introduction

GeDML is an easy-to-use generalized deep metric learning library, which contains:

Installation

Pip

pip install gedml

Quickstart

Demo 1: deep metric learning

CUDA_VISIBLE_DEVICES=0 python demo.py \
--data_path <path_to_data> \
--save_path <path_to_save> \
--eval_exclude f1_score NMI AMI \
--device 0 --batch_size 128 --test_batch_size 128 \
--setting proxy_anchor --splits_to_eval test --embeddings_dim 128 \
--lr_trunk 0.0001 --lr_embedder 0.0001 --lr_collector 0.01 \
--dataset cub200 --delete_old \

Demo 2: contrastive representation learning

CUDA_VISIBLE_DEVICES=0 python demo.py \
--data_path <path_to_data> \
--save_path <path_to_save> \
--eval_exclude f1_score NMI AMI \
--device 0 --batch_size 128 --test_batch_size 128 \
--setting mocov2 --splits_to_eval test --embeddings_dim 128 \
--lr_trunk 0.015 --lr_embedder 0.015 \
--dataset imagenet --delete_old \

If you want to use our code to conduct DML or CRL experiments, please refer to the up-to-date and most detailed configurations below: :point_down:

API

Initialization

Use ParserWithConvert to get parameters

>>> from gedml.launcher.misc import ParserWithConvert
>>> csv_path = ...
>>> parser = ParserWithConvert(csv_path=csv_path, name="...")
>>> opt, convert_dict = parser.render()

Use ConfigHandler to create all objects.

>>> from gedml.launcher.creators import ConfigHandler
>>> link_path = ...
>>> assert_path = ...
>>> param_path = ...
>>> config_handler = ConfigHandler(
    convert_dict=convert_dict,
    link_path=link_path,
    assert_path=assert_path,
    params_path=param_path,
    is_confirm_first=True
)
>>> config_handler.get_params_dict()
>>> objects_dict = config_handler.create_all()

Start

Use manager to automatically call trainer and tester.

>>> from gedml.launcher.misc import utils
>>> manager = utils.get_default(objects_dict, "managers")
>>> manager.run()

Or directly use trainer and tester.

>>> from gedml.launcher.misc import utils
>>> trainer = utils.get_default(objects_dict, "trainers")
>>> tester = utils.get_default(objects_dict, "testers")
>>> recorder = utils.get_default(objects_dict, "recorders")
# start to train
>>> utils.func_params_mediator(
    [objects_dict],
    trainer.__call__
)
# start to test
>>> metrics = utils.func_params_mediator(
    [
        {"recorders": recorder},
        objects_dict,
    ],
    tester.__call__
)

Document

For more information, please refer to: :point_right: Docs :book:

Some specific guidances:

Configs

We will continually update the optimal parameters of different configs in TsinghuaCloud

Framework

This project is modular in design. The pipeline diagram is as follows:

<h1 align="center"> <img alt="Pipeline" src=".docsrc/assets/readme/structure.png"> </h1>

Code structure

<!-- - [.docsrc](.docsrc): Code for documentation generation. - [.github](.github): CI/CD. -->

Method

Collectors

methoddescription
BaseCollectorBase class
DefaultCollectorDo nothing
ProxyCollectorMaintain a set of proxies
MoCoCollectorpaper: Momentum Contrast for Unsupervised Visual Representation Learning
SimSiamCollectorpaper: Exploring Simple Siamese Representation Learning
HDMLCollectorpaper: Hardness-Aware Deep Metric Learning
DAMLCollectorpaper: Deep Adversarial Metric Learning
DVMLCollectorpaper: Deep Variational Metric Learning

Losses

classifier-based

methoddescription
CrossEntropyLossCross entropy loss for unsupervised methods
LargeMarginSoftmaxLosspaper: Large-Margin Softmax Loss for Convolutional Neural Networks
ArcFaceLosspaper: ArcFace: Additive Angular Margin Loss for Deep Face Recognition
CosFaceLosspaper: CosFace: Large Margin Cosine Loss for Deep Face Recognition

pair-based

methoddescription
ContrastiveLosspaper: Learning a Similarity Metric Discriminatively, with Application to Face Verification
MarginLosspaper: Sampling Matters in Deep Embedding Learning
TripletLosspaper: Learning local feature descriptors with triplets and shallow convolutional neural networks
AngularLosspaper: Deep Metric Learning with Angular Loss
CircleLosspaper: Circle Loss: A Unified Perspective of Pair Similarity Optimization
FastAPLosspaper: Deep Metric Learning to Rank
LiftedStructureLosspaper: Deep Metric Learning via Lifted Structured Feature Embedding
MultiSimilarityLosspaper: Multi-Similarity Loss With General Pair Weighting for Deep Metric Learning
NPairLosspaper: Improved Deep Metric Learning with Multi-class N-pair Loss Objective
SignalToNoiseRatioLosspaper: Signal-To-Noise Ratio: A Robust Distance Metric for Deep Metric Learning
PosPairLosspaper: Exploring Simple Siamese Representation Learning

proxy-based

methoddescription
ProxyLosspaper: No Fuss Distance Metric Learning Using Proxies
ProxyAnchorLosspaper: Proxy Anchor Loss for Deep Metric Learning
SoftTripleLosspaper: SoftTriple Loss: Deep Metric Learning Without Triplet Sampling

Selectors

methoddescription
BaseSelectorBase class
DefaultSelectorDo nothing
DenseTripletSelectorSelect all triples
DensePairSelectorSelect all pairs

Code Reference

TODO:

IMPORTANT TODO: