So you want to contribute to OpenBR? That's awesome! These are some guidelines to follow so that your contribution fits nicely into our framework.

Contributing a Plugin

You should consider contributing a plugin (or plugins!) if you have an algorithm you are interested in moving to OpenBR or you have an extension to an existing algorithm. Below are the steps for creating and contributing a plugin-

1. Check out the C++ Plugin API and decide which abstraction best suits the needs of your contribution
2. Select a module in the openbr/plugins/ directory that describes your plugin, then create a new file in that module. Your file should have the same name as your plugin.
3. Implement your plugin! Make sure to have a look at the Style Guide so your code matches what's already there. This increases overall readability and makes it easier for newcomers to learn!

Common Mistakes

Some common mistakes that will stop your plugin from working!

• The entire plugin should be inside namespace br
• Make sure your plugin declares Q_OBJECT right after it's definition
• Remember to call BR_REGISTER at the end of your plugin!
• Remeber to add #include "module/filename.moc" at the very bottom of your file

MAddTransform is a simple and clear example of how a Transform should look.

Documenting

Documenting your plugin is very important. OpenBR supports custom, doxygen-style, in-code comments to make documentation simple, clear, and easy. Comments should appear like

    /*!
     * ...
     */

Comments are organized using tags, which are of the form \tag. There are a few required tags that all OpenBR transforms must have.

Tag	Description
\ingroup	The abstraction that your plugin belongs to
\brief	A description of your plugin
\author	Your name
\cite	The citation link for the author. There must be citation tag for every author who appears. If you haven't already please add your information to openbr/docs/docs/contributors.md
\br_property	Describes a BR_PROPERTY of your plugin. This should take the format \br_property type name description. In certain cases, for enumerations for example, it is beneficial to add a bulleted list to the description. This is done using a comma seperated [] list. [item1,item2,item3] will appear like item1 item2 item3 Each property of the plugin must have a corresponding \br_property tag.

The mimimum comment would look like this

    /*!
     * \ingroup abstraction group
     * \brief A description of the plugin
     * \author Your Name \cite Your Citation
     * \br_property percentage float The percentage of something
     * \br_property enum choice A choice with possible values: [choice1, choice2, choice3]
     */

There are also a few optional tags to provide more information.

Tag	Description
\br_link	A link to a webpage
\br_paper	An academic paper your plugin needs to cite. This is a multi-line tag- The first line should contain the paper authors, the second line should contain the paper title, and the third should contain other information about the paper (for example conference and year). See below for an example.
\br_related_plugin	Link to a related plugin within OpenBR. The full name of the plugin should be provided. Multiple plugins can be given and they should be seperated by a space.
\br_format	TODO define

Optional tags could look like this

    /*!
     * \br_link http://openbiometrics.org
     * \br_paper Author1, Author2, Author3
     *           Paper Title
     *           Conference. Year
     * \br_related_plugin ExampleTransform ExampleDistance ExampleGallery
     */

Finally, OpenBR supports automatic linking for abstractions found in comments. For example, Transform will automatically become Transform. Plural words like Transforms will also be linked but possesives like Tranform's will not.

---

Contributing to the API

You should contribute to the API if you want to add a new abstraction or extend an existing abstraction with new functionality. Please note, this occurs very very rarely. Our goal is to leave the core API as stable and consistent as possible and change only the surrounding plugins. If you believe your idea offers exciting new functionality or greatly increases efficiency please open an issue so that it can be discussed as a community.