{"id":13737994,"url":"https://github.com/zbr17/GeDML","last_synced_at":"2025-05-08T15:32:11.161Z","repository":{"id":47188016,"uuid":"403631248","full_name":"zbr17/GeDML","owner":"zbr17","description":"Generalized Deep Metric Learning.","archived":false,"fork":false,"pushed_at":"2022-03-22T13:41:12.000Z","size":6443,"stargazers_count":35,"open_issues_count":1,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-10T20:55:56.747Z","etag":null,"topics":["computer-vision","contrastive-learning","deep-metric-learning","loss-functions","metric-learning","self-supervised-learning"],"latest_commit_sha":null,"homepage":"https://zbr17.github.io/GeDML/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zbr17.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-09-06T13:23:07.000Z","updated_at":"2024-07-07T02:31:01.000Z","dependencies_parsed_at":"2022-08-02T23:30:59.266Z","dependency_job_id":null,"html_url":"https://github.com/zbr17/GeDML","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zbr17%2FGeDML","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zbr17%2FGeDML/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zbr17%2FGeDML/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zbr17%2FGeDML/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zbr17","download_url":"https://codeload.github.com/zbr17/GeDML/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253096304,"owners_count":21853573,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computer-vision","contrastive-learning","deep-metric-learning","loss-functions","metric-learning","self-supervised-learning"],"created_at":"2024-08-03T03:02:08.462Z","updated_at":"2025-05-08T15:32:09.886Z","avatar_url":"https://github.com/zbr17.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003ca href=\"http://ivg.au.tsinghua.edu.cn/\"\u003e\n    \u003cimg alt=\"Logo\" src=\".docsrc/assets/readme/header.jpg\"\u003e\n  \u003c/a\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://badge.fury.io/py/gedml\"\u003e\n    \u003cimg alt=\"PyPi version\" src=\"https://badge.fury.io/py/gedml.svg\"\u003e\n  \u003c/a\u003e\n  \n  \u003ca href=\"https://github.com/zbr17/GeDML/blob/master/.github/workflows/sphinx_pages.yml\"\u003e\n    \u003cimg alt=\"Documentation build\" src=\"https://github.com/zbr17/GeDML/workflows/Documentation/badge.svg\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# News\n- **[2022-3-22]**: **`v0.2.2` has been released:\n  - Fix some bugs.\n- **[2021-11-3]**: **`v0.2.0` has been released:\n  - ***New features:***\n    - Change the format of `link` configuration.\n- **[2021-10-27]**: **`v0.1.4` has been released:\n  - ***New features:***\n    - Add contrastive representation learning methods (MoCo-V2).\n- **[2021-10-24]**: **`v0.1.2` has been released:\n  - ***New features:***\n    - Add distributed (DDP) support.\n- **[2021-10-7]**: **`v0.1.1` has been released:\n  - ***New features:***\n    - Change the Cars196 loading [method](http://ai.stanford.edu/~jkrause/cars/car_dataset.html).\n- **[2021-9-15]**: **`v0.1.0` has been released:\n  - ***New features:*** \n    - **output_wrapper** and **pipeline setting** are decomposed for convenience.\n    - Pipeline will be stored in the experiment folder using a directed graph.\n- **[2021-9-13]**: **`v0.0.1` has been released: \n  - ***New features:*** \n    - `config.yaml` will be created to store the configuration in the experiment folder.**\n- **[2021-9-6]**: `v0.0.0` has been released.\n\n# Introduction\n\n**GeDML** is an easy-to-use **generalized deep metric learning** library, which contains:\n- **State-of-the-art DML algorithms:** We contrain 18+ losses functions and 6+ sampling strategies, and divide these algorithms into three categories (i.e., collectors, selectors, and losses).\n- **Bridge bewteen DML and SSL**: We attempt to bridge the gap between deep metric learning and self-supervised learning through specially designed modules, such as `collectors`.\n- **Auxiliary modules to assist in building:** We also encapsulates the upper interface for users to start programs quickly and separates the codes and configs for managing hyper-parameters conveniently.\n\n# Installation\n\n## Pip\n\n```bash\npip install gedml\n```\n\n# Quickstart\n\n\n\n## Demo 1: **deep metric learning** \n\n```bash\nCUDA_VISIBLE_DEVICES=0 python demo.py \\\n--data_path \u003cpath_to_data\u003e \\\n--save_path \u003cpath_to_save\u003e \\\n--eval_exclude f1_score NMI AMI \\\n--device 0 --batch_size 128 --test_batch_size 128 \\\n--setting proxy_anchor --splits_to_eval test --embeddings_dim 128 \\\n--lr_trunk 0.0001 --lr_embedder 0.0001 --lr_collector 0.01 \\\n--dataset cub200 --delete_old \\\n```\n\n## Demo 2: **contrastive representation learning**\n\n```bash\nCUDA_VISIBLE_DEVICES=0 python demo.py \\\n--data_path \u003cpath_to_data\u003e \\\n--save_path \u003cpath_to_save\u003e \\\n--eval_exclude f1_score NMI AMI \\\n--device 0 --batch_size 128 --test_batch_size 128 \\\n--setting mocov2 --splits_to_eval test --embeddings_dim 128 \\\n--lr_trunk 0.015 --lr_embedder 0.015 \\\n--dataset imagenet --delete_old \\\n```\n\nIf you want to use our code to conduct **DML** or **CRL** experiments, please refer to the **up-to-date** and **most detailed** [configurations](examples) below: :point_down:\n\n- If you use the command line, you can run [`sample_run.sh`](examples/sample_run.sh) to try this project.\n- If you debug with VS Code, you can refer to [`launch.json`](examples/launch.json) to set `.vscode`.\n\n# API\n\n## Initialization\n\nUse `ParserWithConvert` to get parameters\n\n```python\n\u003e\u003e\u003e from gedml.launcher.misc import ParserWithConvert\n\u003e\u003e\u003e csv_path = ...\n\u003e\u003e\u003e parser = ParserWithConvert(csv_path=csv_path, name=\"...\")\n\u003e\u003e\u003e opt, convert_dict = parser.render()\n```\n\nUse `ConfigHandler` to create all objects.\n\n```python\n\u003e\u003e\u003e from gedml.launcher.creators import ConfigHandler\n\u003e\u003e\u003e link_path = ...\n\u003e\u003e\u003e assert_path = ...\n\u003e\u003e\u003e param_path = ...\n\u003e\u003e\u003e config_handler = ConfigHandler(\n    convert_dict=convert_dict,\n    link_path=link_path,\n    assert_path=assert_path,\n    params_path=param_path,\n    is_confirm_first=True\n)\n\u003e\u003e\u003e config_handler.get_params_dict()\n\u003e\u003e\u003e objects_dict = config_handler.create_all()\n```\n\n## Start\n\nUse `manager` to automatically call `trainer` and `tester`.\n\n```python\n\u003e\u003e\u003e from gedml.launcher.misc import utils\n\u003e\u003e\u003e manager = utils.get_default(objects_dict, \"managers\")\n\u003e\u003e\u003e manager.run()\n```\n\nOr directly use `trainer` and `tester`.\n\n```python\n\u003e\u003e\u003e from gedml.launcher.misc import utils\n\u003e\u003e\u003e trainer = utils.get_default(objects_dict, \"trainers\")\n\u003e\u003e\u003e tester = utils.get_default(objects_dict, \"testers\")\n\u003e\u003e\u003e recorder = utils.get_default(objects_dict, \"recorders\")\n# start to train\n\u003e\u003e\u003e utils.func_params_mediator(\n    [objects_dict],\n    trainer.__call__\n)\n# start to test\n\u003e\u003e\u003e metrics = utils.func_params_mediator(\n    [\n        {\"recorders\": recorder},\n        objects_dict,\n    ],\n    tester.__call__\n)\n```\n\n# Document \n\nFor more information, please refer to: :point_right: [**Docs** :book:](https://zbr17.github.io/GeDML/)\n\nSome specific guidances:\n\n- [How to write config](https://zbr17.github.io/GeDML/config.html#)\n- [How to define custom module](https://zbr17.github.io/GeDML/collectors.html)\n- ...\n\n## Configs\n\nWe will continually update the optimal parameters of different configs in [TsinghuaCloud](https://cloud.tsinghua.edu.cn/d/b753b4559de545b59ddc/)\n\n# Framework\n\nThis project is modular in design. The pipeline diagram is as follows:\n\n\u003ch1 align=\"center\"\u003e\n   \u003cimg alt=\"Pipeline\" src=\".docsrc/assets/readme/structure.png\"\u003e\n\u003c/h1\u003e\n\n## Code structure\n\n\u003c!-- - [.docsrc](.docsrc): Code for documentation generation.\n- [.github](.github): CI/CD. --\u003e\n- [tests](tests): Debug files.\n- [examples](examples): Demos.\n  - [config](examples/config): Folder which stores [`links`](examples/config/links), [`param`](examples/config/param), [`wrapper`](examples/config/wrapper), [`args.yaml`](examples/config/args.csv) and [`assert.yaml`](examples/config/assert.yaml).\n  - [demo.py](examples/demo.py): A demo python file.\n- [src/gedml](src/gedml): Main code.\n  - [core](src/gedml/core): Losses, selectors, collectors, etc.\n  - [client](src/gedml/client): Tmux manager.\n  - [config](src/gedml/config): Config files which define the hyper-string etc.\n  - [launcher](src/gedml/launcher): Manager, Trainer, Tester, etc.\n  - [recorder](src/gedml/recorder): Recorder.\n\n# Method\n\n## Collectors\n\n| method | description |\n| ---- | ---- |\n| BaseCollector | Base class |\n| DefaultCollector | Do nothing |\n| ProxyCollector | Maintain a set of proxies |\n| MoCoCollector | paper: [Momentum Contrast for Unsupervised Visual Representation Learning](https://openaccess.thecvf.com/content_CVPR_2020/html/He_Momentum_Contrast_for_Unsupervised_Visual_Representation_Learning_CVPR_2020_paper.html) |\n| SimSiamCollector | paper: [Exploring Simple Siamese Representation Learning](https://arxiv.org/abs/2011.10566) |\n| HDMLCollector | paper: [Hardness-Aware Deep Metric Learning](https://openaccess.thecvf.com/content_CVPR_2019/html/Zheng_Hardness-Aware_Deep_Metric_Learning_CVPR_2019_paper.html) |\n| DAMLCollector | paper: [Deep Adversarial Metric Learning](https://openaccess.thecvf.com/content_cvpr_2018/html/Duan_Deep_Adversarial_Metric_CVPR_2018_paper.html) |\n| DVMLCollector | paper: [Deep Variational Metric Learning](https://openaccess.thecvf.com/content_ECCV_2018/html/Xudong_Lin_Deep_Variational_Metric_ECCV_2018_paper.html) |\n\n## Losses\n\n### classifier-based\n\n| method | description |\n| ---- | ---- |\n| CrossEntropyLoss | Cross entropy loss for unsupervised methods |\n| LargeMarginSoftmaxLoss | paper: [Large-Margin Softmax Loss for Convolutional Neural Networks](https://www.jmlr.org/proceedings/papers/v48/liud16.pdf) |\n| ArcFaceLoss | paper: [ArcFace: Additive Angular Margin Loss for Deep Face Recognition](https://openaccess.thecvf.com/content_CVPR_2019/html/Deng_ArcFace_Additive_Angular_Margin_Loss_for_Deep_Face_Recognition_CVPR_2019_paper.html) |\n| CosFaceLoss | paper: [CosFace: Large Margin Cosine Loss for Deep Face Recognition](http://openaccess.thecvf.com/content_cvpr_2018/html/Wang_CosFace_Large_Margin_CVPR_2018_paper.html) |\n\n### pair-based\n\n| method | description |\n| ---- | ---- | \n| ContrastiveLoss | paper: [Learning a Similarity Metric Discriminatively, with Application to Face Verification](https://ieeexplore.ieee.org/abstract/document/1467314/) |\n| MarginLoss | paper: [Sampling Matters in Deep Embedding Learning](http://openaccess.thecvf.com/content_iccv_2017/html/Wu_Sampling_Matters_in_ICCV_2017_paper.html) |\n| TripletLoss | paper: [Learning local feature descriptors with triplets and shallow convolutional neural networks](https://www.researchgate.net/profile/Krystian_Mikolajczyk/publication/317192886_Learning_local_feature_descriptors_with_triplets_and_shallow_convolutional_neural_networks/links/5a038dad0f7e9beb1770c3c2/Learning-local-feature-descriptors-with-triplets-and-shallow-convolutional-neural-networks.pdf) |\n| AngularLoss | paper: [Deep Metric Learning with Angular Loss](https://openaccess.thecvf.com/content_iccv_2017/html/Wang_Deep_Metric_Learning_ICCV_2017_paper.html) |\n| CircleLoss | paper: [Circle Loss: A Unified Perspective of Pair Similarity Optimization](http://openaccess.thecvf.com/content_CVPR_2020/html/Sun_Circle_Loss_A_Unified_Perspective_of_Pair_Similarity_Optimization_CVPR_2020_paper.html) |\n| FastAPLoss | paper: [Deep Metric Learning to Rank](https://openaccess.thecvf.com/content_CVPR_2019/html/Cakir_Deep_Metric_Learning_to_Rank_CVPR_2019_paper.html) |\n| LiftedStructureLoss | paper: [Deep Metric Learning via Lifted Structured Feature Embedding](https://www.cv-foundation.org/openaccess/content_cvpr_2016/html/Song_Deep_Metric_Learning_CVPR_2016_paper.html) |\n| MultiSimilarityLoss | paper: [Multi-Similarity Loss With General Pair Weighting for Deep Metric Learning](https://openaccess.thecvf.com/content_CVPR_2019/html/Wang_Multi-Similarity_Loss_With_General_Pair_Weighting_for_Deep_Metric_Learning_CVPR_2019_paper.html) |\n| NPairLoss | paper: [Improved Deep Metric Learning with Multi-class N-pair Loss Objective](http://www.nec-labs.com/uploads/images/Department-Images/MediaAnalytics/papers/nips16_npairmetriclearning.pdf) |\n| SignalToNoiseRatioLoss | paper: [Signal-To-Noise Ratio: A Robust Distance Metric for Deep Metric Learning](https://openaccess.thecvf.com/content_CVPR_2019/html/Yuan_Signal-To-Noise_Ratio_A_Robust_Distance_Metric_for_Deep_Metric_Learning_CVPR_2019_paper.html) |\n| PosPairLoss | paper: [Exploring Simple Siamese Representation Learning](https://arxiv.org/abs/2011.10566) |\n\n### proxy-based\n\n| method | description |\n| ---- | ---- | \n| ProxyLoss | paper: [No Fuss Distance Metric Learning Using Proxies](https://openaccess.thecvf.com/content_iccv_2017/html/Movshovitz-Attias_No_Fuss_Distance_ICCV_2017_paper.html) |\n| ProxyAnchorLoss | paper: [Proxy Anchor Loss for Deep Metric Learning](http://openaccess.thecvf.com/content_CVPR_2020/html/Kim_Proxy_Anchor_Loss_for_Deep_Metric_Learning_CVPR_2020_paper.html) |\n| SoftTripleLoss | paper: [SoftTriple Loss: Deep Metric Learning Without Triplet Sampling](https://openaccess.thecvf.com/content_ICCV_2019/html/Qian_SoftTriple_Loss_Deep_Metric_Learning_Without_Triplet_Sampling_ICCV_2019_paper.html) |\n\n## Selectors\n\n| method | description |\n| ---- | ---- | \n| BaseSelector | Base class |\n| DefaultSelector | Do nothing |\n| DenseTripletSelector | Select all triples |\n| DensePairSelector | Select all pairs |\n\n# Code Reference\n\n- [KevinMusgrave / pytorch-metric-learning](https://github.com/KevinMusgrave/pytorch-metric-learning)\n- [KevinMusgrave / powerful-benchmarker](https://github.com/KevinMusgrave/powerful-benchmarker)\n- [Confusezius / Deep-Metric-Learning-Baselines](https://github.com/Confusezius/Deep-Metric-Learning-Baselines)\n- [facebookresearch / moco](https://github.com/facebookresearch/moco)\n- [PatrickHua / SimSiam](https://github.com/PatrickHua/SimSiam)\n- [ujjwaltiwari / Deep_Variational_Metric_Learning](https://github.com/ujjwaltiwari/Deep_Variational_Metric_Learning)\n- [idstcv / SoftTriple](https://github.com/idstcv/SoftTriple)\n- [wzzheng / HDML](https://github.com/wzzheng/HDML)\n- [google-research / simclr](https://github.com/google-research/simclr)\n- [kunhe / FastAP-metric-learning](https://github.com/kunhe/FastAP-metric-learning)\n- [wy1iu / LargeMargin_Softmax_Loss](https://github.com/wy1iu/LargeMargin_Softmax_Loss)\n- [tjddus9597 / Proxy-Anchor-CVPR2020](https://github.com/tjddus9597/Proxy-Anchor-CVPR2020)\n- [facebookresearch / deit](https://github.com/facebookresearch/deit)\n\n# TODO:\n- [ ] assert parameters.\n- [ ] write github action to automate unit-test, package publish and docs building.\n- [ ] add cross-validation splits protocol.\n- [ ] distributed tester for matrix-form input.\n- [ ] add metrics module.\n- [ ] how to improve the running efficiency.\n\n# IMPORTANT TODO:\n- [ ] re-define pipeline setting!!!\n- [ ] simplify distribution setting!!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzbr17%2FGeDML","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzbr17%2FGeDML","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzbr17%2FGeDML/lists"}