Adding New Tool

New tools added to the OpenDR GitHub repo should provide the following files:

• source code to apply the tool for training and inference
• unit tests
• documentation of the tools including:
  • a short description of the method itself. It is not necessary to give all the details, but it is good to link to the related paper or reference if any.
  • details description of the API needed by the user to apply the tool to her scenario
  • step-by-step description about how to run the example
• example (preferably using Webots) of how to apply the tool to a scenario

The following instructions will provide paths using the following wildcards:

• <type>: tool type, e.g., control, perception, planning, navigation
• <task_name>: task addressed by the tool, for example "pose_estimation"
• <algorithm_name>: name of the algorithms used to solve the task, for example "lightweight_open_pose"

Code

New Tool Public API

New tools should follow the OpenDR code guidelines and ensure a common interface:

• the public API should extend the the engine.BaseLearner anstract class and implement these functions:
  • save():
  • load()
  • optimize()
  • reset()
• all the perception algorithms should inherit and extent the engine.Learner class and implement these methods:
  • fit()
  • eval()
  • infer()
• they should be compatible with the style guidelines (TODO)

Sources Path

The source code of the tool has to be stored in the /src/<type>/<task_name>/<algorithm_name> folder. The expected files are:

1. README.md: containing a short description of the task and algorithms (1-2 lines), the list of the sources of third-party code (if any) and the modifications to the original code
2. <algorithm_name>_learner.py: main class providing the entry point to the functionality
3. algorithm/: folder containing the algorithm implementation

CI tests

The files in /src are tested by the CI (Continuous Integration) system to check the compatibility with the OpenDR guidelines. Tests on original files taken from third-party that are copied and pasted without modifications can be skipped. In particular the OpenDR license test should be skipped because it is now allowed to change license and copyrights of third-party code. It is possible to skip tests for a folder by adding the path to the skippedDirectoryPaths variable in the test itself: https://github.com/tasostefas/opendr_internal/blob/12982dfac04ea47366c08d05e642e49b58ad3dc0/tests/sources/test_license.py#L81-L83

Third-party Code and License

If not modified and available on a public GitHub repo, third-party code should be linked (as a "submodule") instead of copied in the OpenDR repository. If not available on a GitHub repo or some modifications are applied:

• commit the algorithms sources in the OpenDR repo
• specify the link to the original code in the tool README.md file, the author and list all the modifications

OpenDR license doesn't have to be applied on third-party code!

OpenDR Apache License version 2.0 is a permissive license: work can be redistributed even for commercial use. So, third-party code integrated in OpenDR toolkit should also be permissive. Non-commercial licensed code cannot be integrated. Common compatible licenses are:

• MIT
• BSD

Documentation

All the documentation needed by the user should be added in the /docs/reference folder, i.e. in the Reference Manual of the OpenDR toolkit. A single file named after the method should be added and should contain these information:

1. Description of the method
2. Specifications of the API
3. Instructions to run the example

Adding documentation directly in the code is recommended to make the code more readable and understandable. But this is not considered part of the OpenDR API documentation needed to use the toolkit.

Description of the method

This include a description of the method: what is the purpose of the method, which are the techniques used, overview of the performance etc. This is not intended to be a detailed description of how the method is implemented or all the research behind it, but it should give enough information to the user to understand if this method could be applied to his scenario. It it good to link to the related paper or similar, so that interested users can look into the details.

Specifications of the API

All the public method of the tool have to be listed and described. This includes the description of the function arguments, returned values, and functionality.

Instructions to run the examples

The last section of the documentation page should include the step-by-step instructions to run the provided example. A short description of the example and the expected result should able be included.

Example

The example files have to be added in a dedicated folder in the /projects folder. For example: /projects/<type>/<task_name>/algorithm_name The example should be as simple as possible but still providing a meaningful application where the tool potentialities are demonstrated. It should preferably be a Webots project.

Keeping in mind that OpenDR is a set of many different tools it is important to carefully choose the dependencies and try when possible and meaningful to reuse dependencies already included instead of adding new ones. New dependencies needed to run this specific example and that are not generically needed to run the tool, should be listed in the /projects/<type>/<task_name>/<algorithm_name>/dependencies.ini file. More information about listing dependencies is specified in section (TODO).