index.html 13 KB

Edit Raw Blame History

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">

  <title>Contribute - OpenBR</title>


  <link rel="shortcut icon" href="../docs/img/openbr.ico">


</head>

<body class="wy-body-for-nav" role="document">

  <div class="wy-grid-for-nav">


    <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
      <div class="wy-side-nav-search">
        <a href=".." class="icon icon-home"> OpenBR</a>
        <div role="search">
  <form id ="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
  </form>
</div>
      </div>

      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
      <ul class="current">


            <li class="toctree-l0 ">
            <a class="" href="..">Home</a>

            </li>


            <li class="toctree-l0 ">
            <a class="" href="../install/">Install</a>

            </li>


            <li class="toctree-l0 ">
            <a class="" href="../tutorials/">Tutorials</a>

            </li>


            <li class="toctree-l0 ">
            <a class="" href="../technical/">Technical Overviews</a>

            </li>


            <li class="toctree-l0 current">
            <a class="current" href="./">Contribute</a>

                <ul>


                            <li class="toctree-l1"><a href="#contributing-a-plugin">Contributing a Plugin</a></li>

                            <li class="toctree-l1"><a href="#contributing-to-the-api">Contributing to the API</a></li>


                </ul>

            </li>


            <li class="toctree-l0 ">
            <a class="" href="../papers/">Publications</a>

            </li>


            <span>API Docs</span>


            <li class="toctree-l1 ">
            <a class="" href="../api_docs/c_api/">C API</a>

            </li>


            <li class="toctree-l1 ">
            <a class="" href="../api_docs/cpp_api/">C++ Plugin API</a>

            </li>


            <li class="toctree-l1 ">
            <a class="" href="../api_docs/cl_api/">Command Line API</a>

            </li>


            <span>Plugin Docs</span>


            <li class="toctree-l1 ">
            <a class="" href="../api_docs/plugins/classification/">Classification</a>

            </li>


            <li class="toctree-l1 ">
            <a class="" href="../api_docs/plugins/cluster/">Cluster</a>

            </li>


            <li class="toctree-l1 ">
            <a class="" href="../api_docs/plugins/core/">Core</a>

            </li>


            <li class="toctree-l1 ">
            <a class="" href="../api_docs/plugins/distance/">Distance</a>

            </li>


            <li class="toctree-l1 ">
            <a class="" href="../api_docs/plugins/format/">Format</a>

            </li>


            <li class="toctree-l1 ">
            <a class="" href="../api_docs/plugins/gallery/">Gallery</a>

            </li>


            <li class="toctree-l1 ">
            <a class="" href="../api_docs/plugins/gui/">GUI</a>

            </li>


            <li class="toctree-l1 ">
            <a class="" href="../api_docs/plugins/imgproc/">Image Processing</a>

            </li>


            <li class="toctree-l1 ">
            <a class="" href="../api_docs/plugins/io/">I/O</a>

            </li>


            <li class="toctree-l1 ">
            <a class="" href="../api_docs/plugins/metadata/">Metadata</a>

            </li>


            <li class="toctree-l1 ">
            <a class="" href="../api_docs/plugins/output/">Output</a>

            </li>


            <li class="toctree-l1 ">
            <a class="" href="../api_docs/plugins/video/">Video</a>

            </li>


</ul>
      </div>
      &nbsp;
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">


      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
        <a href="..">OpenBR</a>
      </nav>


      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
    <li><a href="..">Docs</a> &raquo;</li>


    <li>Contribute</li>
    <li class="wy-breadcrumbs-aside">


          <a href="https://github.com/biometrics/openbr" class="icon icon-github"> Edit on GitHub</a>


    </li>
  </ul>
  <hr/>
</div>
          <div role="main">
            <div class="section">

                <p>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.</p>
<h2 id="contributing-a-plugin">Contributing a Plugin</h2>
<p>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-</p>
<ol>
<li>Check out the <a href="../api_docs/cpp_api/">C++ Plugin API</a> and decide which abstraction best suits the needs of your contribution</li>
<li>Select a module in the <tt>openbr/plugins/</tt> directory that describes your plugin, then create a new file in that module. Your file should have the same name as your plugin.</li>
<li>Implement your plugin! Make sure to have a look at the <a href="#style-guide">Style Guide</a> so your code matches what's already there. This increases overall readability and makes it easier for newcomers to learn!</li>
</ol>
<h3 id="common-mistakes">Common Mistakes</h3>
<p>Some common mistakes that will stop your plugin from working!</p>
<ul>
<li>The entire plugin should be inside <code>namespace br</code></li>
<li>Make sure your plugin declares <code>Q_OBJECT</code> right after it's definition</li>
<li>Remember to call <a href="../api_docs/cpp_api/factory/macros/#br_register">BR_REGISTER</a> at the end of your plugin!</li>
<li>Remeber to add <code>#include "module/filename.moc"</code> at the very bottom of your file</li>
</ul>
<p><a href="../api_docs/plugins/imgproc/#maddtransform">MAddTransform</a> is a simple and clear example of how a <a href="../api_docs/cpp_api/transform/transform/">Transform</a> should look.</p>
<h3 id="documenting">Documenting</h3>
<p>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 </p>
<pre><code>    /*!
     * ...
     */
</code></pre>
<p>Comments are organized using tags, which are of the form <tt>\tag</tt>. There are a few <strong>required</strong> tags that all OpenBR transforms must have.</p>
<table>
<thead>
<tr>
<th>Tag</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>\ingroup</td>
<td>The abstraction that your plugin belongs to</td>
</tr>
<tr>
<td>\brief</td>
<td>A description of your plugin</td>
</tr>
<tr>
<td>\author</td>
<td>Your name</td>
</tr>
<tr>
<td>\cite</td>
<td>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 <tt>openbr/docs/docs/contributors.md</tt></td>
</tr>
<tr>
<td>\br_property</td>
<td>Describes a <tt>BR_PROPERTY</tt> of your plugin. This should take the format <code>\br_property type name description</code>. 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 <strong>[]</strong> list. <code>[item1,item2,item3]</code> will appear like <ul><li>item1</li><li>item2</li><li>item3</li></ul> Each property of the plugin must have a corresponding \br_property tag.</td>
</tr>
</tbody>
</table>
<p>The mimimum comment would look like this</p>
<pre><code>    /*!
     * \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]
     */
</code></pre>
<p>There are also a few <strong>optional</strong> tags to provide more information.</p>
<table>
<thead>
<tr>
<th>Tag</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>\br_link</td>
<td>A link to a webpage</td>
</tr>
<tr>
<td>\br_paper</td>
<td>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.</td>
</tr>
<tr>
<td>\br_related_plugin</td>
<td>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.</td>
</tr>
<tr>
<td>\br_format</td>
<td>TODO define</td>
</tr>
</tbody>
</table>
<p>Optional tags could look like this</p>
<pre><code>    /*!
     * \br_link http://openbiometrics.org
     * \br_paper Author1, Author2, Author3
     *           Paper Title
     *           Conference. Year
     * \br_related_plugin ExampleTransform ExampleDistance ExampleGallery
     */
</code></pre>
<p>Finally, OpenBR supports automatic linking for abstractions found in comments. For example, Transform will automatically become <a href="../api_docs/cpp_api/transform/transform/">Transform</a>. Plural words like Transforms will also be linked but possesives like Tranform's will not. </p>
<hr />
<h2 id="contributing-to-the-api">Contributing to the API</h2>
<p>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 <em>very</em> <em>very</em> 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 <a href="https://github.com/biometrics/openbr/issues">open an issue</a> so that it can be discussed as a community.</p>
<!-- Links -->

<!-- Contributors -->

            </div>
          </div>
          <footer>

    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">

        <a href="../papers/" class="btn btn-neutral float-right" title="Publications"/>Next <span class="icon icon-circle-arrow-right"></span></a>


        <a href="../technical/" class="btn btn-neutral" title="Technical Overviews"><span class="icon icon-circle-arrow-left"></span> Previous</a>

    </div>


  <hr/>

  <div role="contentinfo">
    <p>
    <!-- Copyright etc -->
    </p>
  </div>

  Built with <a href="http://www.mkdocs.org">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>

        </div>
      </div>

    </section>

  </div>

<div class="rst-versions" role="note" style="cursor: pointer">
    <span class="rst-current-version" data-toggle="rst-current-version">

          <a class="icon icon-github" style="float: left; color: #fcfcfc"> GitHub</a>


        <span><a href="../technical/" style="color: #fcfcfc;">&laquo; Previous</a></span>


        <span style="margin-left: 15px"><a href="../papers/" style="color: #fcfcfc">Next &raquo;</a></span>

    </span>
</div>


<link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>

<link rel="stylesheet" href="../css/theme.css" type="text/css" />
<link rel="stylesheet" href="../css/theme_extra.css" type="text/css" />
<link rel="stylesheet" href="../css/highlight.css">

<script src="../js/jquery-2.1.1.min.js"></script>
<script src="../js/modernizr-2.8.3.min.js"></script>
<script type="text/javascript" src="../js/highlight.pack.js"></script>
<script src="../js/theme.js"></script>

<!--
MkDocs version      : 0.12.1
Docs Build Date UTC : 2015-04-24 17:55:27.427140
-->
</body>
</html>