Click me! ⬆️🖱️

MODI: Multicommodity Optimal Transport Dynamics on Images

⚠ Important note:
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 (Multicommodity Optimal transport Dynamics on Images) is a Python implementation of the algorithms used in:

• [1] Alessandro Lonardi*, Diego Baptista*, and Caterina De Bacco. Immiscible Color Flows in Optimal Transport Networks for Image Classification. Front. Phys. 11:1089114 [arXiv] [poster] [CO₂ compensation].

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].
The symbol “*” denotes equal contribution.

Requirements

All the dependencies needed to run the algorithm can be installed using the following command:

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:

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.

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.
• 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).

Contacts

For any issues or questions, feel free to contact us sending an email to:

• alessandro.lonardi@tuebingen.mpg.de
  or
• diego.theuerkauf@tuebingen.mpg.de

License

Copyright (c) 2022 Alessandro Lonardi, Diego Baptista and Caterina De Bacco

_{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:}

_{The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.}

_{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.}