<p align="center">
<a href=https://en.wikipedia.org/wiki/Amedeo_Modigliani><img src="https://user-images.githubusercontent.com/34717973/163191831-69d0a9d0-eadd-4bf4-bc65-836f2cda5fcb.png" width="650"></a>
</p>
<p align="center">
Click me! ⬆️🖱️
</p>
___
<h1 align="center">
MODI: Multicommodity Optimal Transport Dynamics on Images
</h1>
<p align="center">
<a href="https://arxiv.org/abs/2205.02938" target="_blank">
<img alt="ARXIV: 2205.02938" src="https://img.shields.io/badge/arXiv-2212.08593-red.svg">
</a>
<a href="https://www.treedom.net/en/page/register?id=49Z-KEWX" target="_blank">
<img alt="Treedom" src="https://img.shields.io/badge/CO2%20compensation%20-Treedom%20%F0%9F%8C%B4-brightgreen">
</a>
<a href="https://pypi.org/project/modi-flows/" target="_blank">
<img alt="PyPI Version" src="https://img.shields.io/pypi/v/modi-flows">
</a>
<a href="https://github.com/aleable/MODI/actions/workflows/pytest.yml" target="_blank">
<img alt="Run Pytest" src="https://github.com/aleable/MODI/actions/workflows/pytest.yml/badge.svg">
</a>
<a href="https://colab.research.google.com/github/aleable/MODI/blob/main/notebooks/dashboard.ipynb">
<img alt="Open in Colab" src="https://colab.research.google.com/assets/colab-badge.svg">
</a>
</p>
> <strong>⚠ Important note:<br/></strong> MODI is currently under reconstruction, thus you may find some inconsistencies in its documentation. In case you have problems using the code, please do not hesitate to contact us.
**MODI** (**M**ulticommodity **O**ptimal transport **D**ynamics on **I**mages) is a Python implementation of the algorithms used in:
- [1] Alessandro Lonardi\*, Diego Baptista\*, and Caterina De Bacco. <i>Immiscible Color Flows in Optimal Transport Networks for Image Classification</i>. <a href="https://doi.org/10.3389/fphy.2023.1089114">Front. Phys. 11:1089114</a> [<a href="https://arxiv.org/abs/2205.02938">arXiv</a>] [<a href="https://github.com/aleable/MODI/tree/main/misc/POSTER_MODI.pdf">poster</a>] [<a href="https://www.treedom.net/en/page/register?id=49Z-KEWX">CO₂ compensation</a>].
This is a scheme capable of performing supervised classification by finding multicommodity optimal transport paths between a pair of images.
**If you use this code, please cite [1].**<br/>
The symbol “*” denotes equal contribution.
## Requirements
All the dependencies needed to run the algorithm can be installed using the following command:
```bash
pip install modi-flows
```
Please note that as of the latest release, the `scikit-umfpack` package is no longer a mandatory requirement for `modi-flows`. However, we highly recommend installing it to take advantage of enhanced performance. If you choose to install `scikit-umfpack`, it can be easily obtained from the conda repository:
```bash
conda install -c conda-forge scikit-umfpack
```
Now, you are ready to use the code! To do so, you can simply use the notebook ```dashboard.ipynb```, from which you can access our solver. <br/>
Here's the directory structure:
## What's included
- `src/modi_flows`: Contains all the scripts necessary to run MODI.
- `notebooks`: Holds user-friendly Jupyter notebooks, such as `dashboard.ipynb`, which allow you to interact with the code and visualize results.
- `data`: Contains input data used in the examples.
- `input`: Holds a small sample of images taken from [2]. These images can be preprocessed using `code/dashboard.ipynb`. The complete dataset can be downloaded as a .zip file from the [Harvard Dataverse](https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/QDHYST).
- `misc`: Includes supplementary files such as the MODI poster.
- `tests`: Contains test scripts to validate the functionality of the code.
- `docs`: Contains documentation files, including Sphinx configuration and source files.
[2] Marco Seeland, Michael Rzanny, Nedal Alaqraa, Jana Wäldchen, and Patrick Mäder, [Jena Flowers 30 Dataset, Harvard Dataverse (2017)](https://doi.org/10.7910/DVN/QDHYST).
## Contacts
For any issues or questions, feel free to contact us sending an email to:
- <a href="alessandro.lonardi@tuebingen.mpg.de">alessandro.lonardi@tuebingen.mpg.de</a><br/>
or
- <a href="diego.theuerkauf@tuebingen.mpg.de">diego.theuerkauf@tuebingen.mpg.de</a>
## License
Copyright (c) 2022 <a href="https://aleable.github.io/">Alessandro Lonardi</a>, <a href="https://github.com/diegoabt">Diego Baptista</a> and <a href="https://www.cdebacco.com/">Caterina De Bacco</a>
<sub>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</sub>
<sub>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</sub>
<sub>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</sub>
Raw data
{
"_id": null,
"home_page": "",
"name": "modi-flows",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "multicommodity,optimal transport,image classification",
"author": "Alessandro Lonardi, Diego Baptista",
"author_email": "diego.theuerkauf@tuebingen.mpg.de",
"download_url": "https://files.pythonhosted.org/packages/56/34/36c4bfd16735582919cbbb3a35318eb515cf9d143b6c87bc6ebf5be522f2/modi-flows-0.1.7.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n<a href=https://en.wikipedia.org/wiki/Amedeo_Modigliani><img src=\"https://user-images.githubusercontent.com/34717973/163191831-69d0a9d0-eadd-4bf4-bc65-836f2cda5fcb.png\" width=\"650\"></a>\n</p>\n\n<p align=\"center\">\nClick me! \u2b06\ufe0f\ud83d\uddb1\ufe0f\n</p>\n\n___\n\n<h1 align=\"center\">\nMODI: Multicommodity Optimal Transport Dynamics on Images\n</h1>\n<p align=\"center\">\n<a href=\"https://arxiv.org/abs/2205.02938\" target=\"_blank\">\n<img alt=\"ARXIV: 2205.02938\" src=\"https://img.shields.io/badge/arXiv-2212.08593-red.svg\">\n</a>\n\n<a href=\"https://www.treedom.net/en/page/register?id=49Z-KEWX\" target=\"_blank\">\n<img alt=\"Treedom\" src=\"https://img.shields.io/badge/CO2%20compensation%20-Treedom%20%F0%9F%8C%B4-brightgreen\">\n</a>\n\n<a href=\"https://pypi.org/project/modi-flows/\" target=\"_blank\">\n <img alt=\"PyPI Version\" src=\"https://img.shields.io/pypi/v/modi-flows\">\n</a>\n\n<a href=\"https://github.com/aleable/MODI/actions/workflows/pytest.yml\" target=\"_blank\">\n <img alt=\"Run Pytest\" src=\"https://github.com/aleable/MODI/actions/workflows/pytest.yml/badge.svg\">\n</a>\n\n<a href=\"https://colab.research.google.com/github/aleable/MODI/blob/main/notebooks/dashboard.ipynb\">\n <img alt=\"Open in Colab\" src=\"https://colab.research.google.com/assets/colab-badge.svg\">\n</a>\n\n</p>\n\n> <strong>⚠ Important note:<br/></strong> MODI is currently under reconstruction, thus you may find some inconsistencies in its documentation. In case you have problems using the code, please do not hesitate to contact us.\n\n**MODI** (**M**ulticommodity **O**ptimal transport **D**ynamics on **I**mages) is a Python implementation of the algorithms used in:\n\n- [1] Alessandro Lonardi\\*, Diego Baptista\\*, and Caterina De Bacco. <i>Immiscible Color Flows in Optimal Transport Networks for Image Classification</i>. <a href=\"https://doi.org/10.3389/fphy.2023.1089114\">Front. Phys. 11:1089114</a> [<a href=\"https://arxiv.org/abs/2205.02938\">arXiv</a>] [<a href=\"https://github.com/aleable/MODI/tree/main/misc/POSTER_MODI.pdf\">poster</a>] [<a href=\"https://www.treedom.net/en/page/register?id=49Z-KEWX\">CO\u2082 compensation</a>].\n\nThis is a scheme capable of performing supervised classification by finding multicommodity optimal transport paths between a pair of images.\n\n**If you use this code, please cite [1].**<br/>\nThe symbol \u201c*\u201d denotes equal contribution.\n\n\n## Requirements\n\nAll the dependencies needed to run the algorithm can be installed using the following command:\n\n```bash\npip install modi-flows\n```\n\nPlease note that as of the latest release, the `scikit-umfpack` package is no longer a mandatory requirement for `modi-flows`. However, we highly recommend installing it to take advantage of enhanced performance. If you choose to install `scikit-umfpack`, it can be easily obtained from the conda repository:\n\n```bash\nconda install -c conda-forge scikit-umfpack\n```\nNow, you are ready to use the code! To do so, you can simply use the notebook ```dashboard.ipynb```, from which you can access our solver. <br/>\n\n\nHere's the directory structure:\n\n## What's included\n\n- `src/modi_flows`: Contains all the scripts necessary to run MODI.\n- `notebooks`: Holds user-friendly Jupyter notebooks, such as `dashboard.ipynb`, which allow you to interact with the code and visualize results.\n- `data`: Contains input data used in the examples.\n - `input`: Holds a small sample of images taken from [2]. These images can be preprocessed using `code/dashboard.ipynb`. The complete dataset can be downloaded as a .zip file from the [Harvard Dataverse](https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/QDHYST).\n- `misc`: Includes supplementary files such as the MODI poster.\n- `tests`: Contains test scripts to validate the functionality of the code.\n- `docs`: Contains documentation files, including Sphinx configuration and source files.\n\n[2] Marco Seeland, Michael Rzanny, Nedal Alaqraa, Jana W\u00e4ldchen, and Patrick M\u00e4der, [Jena Flowers 30 Dataset, Harvard Dataverse (2017)](https://doi.org/10.7910/DVN/QDHYST).\n\n\n## Contacts\n\nFor any issues or questions, feel free to contact us sending an email to:\n- <a href=\"alessandro.lonardi@tuebingen.mpg.de\">alessandro.lonardi@tuebingen.mpg.de</a><br/>\nor\n- <a href=\"diego.theuerkauf@tuebingen.mpg.de\">diego.theuerkauf@tuebingen.mpg.de</a>\n\n## License\n\nCopyright (c) 2022 <a href=\"https://aleable.github.io/\">Alessandro Lonardi</a>, <a href=\"https://github.com/diegoabt\">Diego Baptista</a> and <a href=\"https://www.cdebacco.com/\">Caterina De Bacco</a>\n\n<sub>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</sub>\n\n<sub>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</sub>\n\n<sub>THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</sub>\n",
"bugtrack_url": null,
"license": "",
"summary": "MODI: Multicommodity Optimal Transport-based Dynamics for Image Classification",
"version": "0.1.7",
"project_urls": {
"bug-tracker": "https://github.com/aleable/MODI/issues",
"homepage": "https://github.com/aleable/MODI",
"repository": "https://github.com/aleable/MODI"
},
"split_keywords": [
"multicommodity",
"optimal transport",
"image classification"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8cde422d9067990260bc39bf658457923a3e1a33c8b7cd10898c265478b10944",
"md5": "dbea2e25aedc449cc45657479f6e2a77",
"sha256": "bea70a07063fbb03eef381b7fcfb25ff34f5b1471a7e7428b7bec7f78b7f9877"
},
"downloads": -1,
"filename": "modi_flows-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dbea2e25aedc449cc45657479f6e2a77",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 15409,
"upload_time": "2023-08-30T13:42:11",
"upload_time_iso_8601": "2023-08-30T13:42:11.208423Z",
"url": "https://files.pythonhosted.org/packages/8c/de/422d9067990260bc39bf658457923a3e1a33c8b7cd10898c265478b10944/modi_flows-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "563436c4bfd16735582919cbbb3a35318eb515cf9d143b6c87bc6ebf5be522f2",
"md5": "5bf2147dfebbb03038abde801eb5022d",
"sha256": "6939ffd6ffbad92264c0389a76bfe64cc934ac2282fce38795e81a475b17d637"
},
"downloads": -1,
"filename": "modi-flows-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "5bf2147dfebbb03038abde801eb5022d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 6237456,
"upload_time": "2023-08-30T13:42:35",
"upload_time_iso_8601": "2023-08-30T13:42:35.882246Z",
"url": "https://files.pythonhosted.org/packages/56/34/36c4bfd16735582919cbbb3a35318eb515cf9d143b6c87bc6ebf5be522f2/modi-flows-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-30 13:42:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aleable",
"github_project": "MODI",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "modi-flows"
}
JSON
