udlf / udlf

An Unsupervised Distance Learning Framework for Multimedia Retrieval

Unsupervised Distance Learning Framework

Access the official software webpage >>

Authors: Lucas Pascotti Valem and Daniel Carlos Guimarães Pedronette

Dept. of Statistic, Applied Math. and Computing, Universidade Estadual Paulista (UNESP), Rio Claro, Brazil

---

• Overview
• Get Started
• Binaries
• Compilation
• Execution
• Documentation
• Contributing
• Cite
• Contact
• Acknowledgments
• License

Overview

A framework of unsupervised distance learning methods for image and multimedia retrieval tasks. Currently, eleven different unsupervised learning methods are implemented (RFE, RDPAC, BFSTree, LHRR, ContextRR, Correlation Graph, CPRR, Rk Graph Dist., ReckNNGraph, RL-Recom, and RL-Sim*).

Get Started

An easy guide for your first use can be found in the software official webpage.

Binaries

Binaries are available for download in the release page.

Compilation

This project can be compiled by any C++ compiler that supports the C++2014 standard. There is a Makefile that can be used to compile the code. A executable called udlf will be generate inside the bin/ directory.

Execution

The executable is called in the terminal:

• Linux and MacOS: ./udlf [config.ini]

• Windows: call udlf.exe [config.ini]

NOTE: The binary must be executed inside the bin/ directory.

The configuration file specifies everything about the execution: the desired task, method being used, dataset information, input files, output files, evaluation settings, and other details. When the binary is executed, it searchs for a config.ini file in its current directory. The user can also specify a different configuration file that can be passed as a parameter: ./udlf my_conf.ini. The software considers only a single configuration file per execution.

NOTE: Complete examples of input files for distinct datasets are available here.

After the execution, a log.txt is generated:

 - GENERAL INFORMATION -
 --------------------------------------
 Task:             UDL
 Method:           CPRR
 Dataset Size:     1400
 Image List File:  desc/lists/mpeg7.txt
 Image Class File: desc/classes/mpeg7.txt
 Input File:       desc/matrices/mpeg7/cfd.txt
 Input Format:     MATRIX DIST
 Output File:      output/output
 Output Format:    RK ALL
 --------------------------------------
 - METHOD PARAMETERS -
 --------------------------------------
 PARAM_CPRR_K = 20
 PARAM_CPRR_L = 400
 PARAM_CPRR_T = 2
 --------------------------------------
 - EVALUATION RESULTS -
 --------------------------------------
 * Efficiency: Total Time of the Algorithm Execution: 0.0438 s
 * Effectiveness:
 Before:
	 P@20		0.7559
	 Recall@40	0.8444
	 MAP		0.8064
 After:
	 P@20		0.8979
	 Recall@40	0.9477
	 MAP		0.9215
 Relative Gains:
	 P@20		18.7866%
	 Recall@40	12.2404%
	 MAP		14.2707%
 --------------------------------------
 Log generated at 2017/1/26 16:37:24

The results can be exported in different formats. Below you can see some examples of ranked lists that were exported as a html page. The query images are presented in green borders and wrong results in red borders. The first line represents the original retrieval results and the second line, the results after the algorithm execution.

NOTE: The above examples consider the datasets Corel5k, MPEG-7, Oxford17Flowers, and Soccer; respectively.

Documentation

The documentation is available in the software wiki.

Contributing

We appreciate suggestions, ideas and contributions. If you want to contribute, feel free to contact us. Github pull requests should be avoided because they are not part of our review process. To report small bugs, you can use the issue tracker provided by GitHub.

Cite

If you use this software, please cite

@inproceedings{Valem:2017:UDL:3078971.3079017,
   author = {Valem, Lucas Pascotti and Pedronette, Daniel Carlos Guimar\~{a}es},
   title = {An Unsupervised Distance Learning Framework for Multimedia Retrieval},
   booktitle = {Proceedings of the 2017 ACM on International Conference on Multimedia Retrieval},
   series = {ICMR '17},
   year = {2017},
   isbn = {978-1-4503-4701-3},
   location = {Bucharest, Romania},
   pages = {107--111},
   numpages = {5},
   url = {http://doi.acm.org/10.1145/3078971.3079017},
   doi = {10.1145/3078971.3079017},
   acmid = {3079017},
   publisher = {ACM},
   address = {New York, NY, USA},
}

Contact

Lucas Pascotti Valem: [email protected] or [email protected]

Daniel Carlos Guimarães Pedronette: [email protected]

Acknowledgments

The authors are grateful to São Paulo Research Foundation - FAPESP (grants 2013/08645-0, and 2014/04220-8).

License

This project is licensed under GPLv2. See details.

udlf's Issues

How to run without class file

In the documentation, it is said that the workflow can be run without class file:
https://github.com/UDLF/UDLF/wiki/File-Formats#:~:text=NOTE%3A%20This%20file%20is%20only%20required%20when%20EFFECTIVENESS_EVALUATION%20is%20enabled.

However, it fails when the file is not provided. And it is not documented how to disable "EFFECTIVENESS_EVALUATION".

How to generate the similarity matrices？

I found that the similarity in the Soccer dataset is not a float between 0 and 1, but an integer. How to generate the similarity matrices？