Skip to content

Latest commit

 

History

History
196 lines (137 loc) · 6.32 KB

CONTRIBUTING.md

File metadata and controls

196 lines (137 loc) · 6.32 KB

How to contribute to DGtalTools-contrib

In this document, we describe how to contribute to the DGtalTools-contrib projects. Please keep in mind the DGtalTools-contrib project is an open-source initiative under LGPL license.

A first way to contribute to the project is to give us feedbacks and comments using Github issue tracker. Do not hesitate to create an issue (feature request, bug report, issues with the tool descriptions...).

Choice between DGtalTools/DGtalTools-contrib

The DGtalTools project is mainly defined to host tools with a direct link to the DGtal library and should exploit some specific DGtal features. For instance, the 3dCurvatureViewer tool is based on the integral invariant estimator.

Contrary to the DGtalTools project, the DGtalTools-contrib project can contain some tools which are not directly related to DGtal but which use some feature of DGtal. Note that the DGtalTools-contrib project can also contain some development tools or prototype used to share recent research.

Contribution reviewing process

We process contributions to the project using GitHub Pull-request mechanism. If you want to contribute, you would have to:

  • create an account on GitHub;

  • clone and install the last version of the DGtal main repository;

  • clone DGtalTools-contrib ;

  • create a branch for your contribution and push it to your DGtalTools-contrib clone;

  • create a GitHub pull-request to ask for an inclusion.

Each pull-request must contain:

  • an informative pull-request comment describing the new contribution;
  • a new entry in the project Changelog.md file.

Once the pull-request has been sent, a DGtalTools-contribs package manager will review the code and may ask for edits before being merged to the DGtalTools master branch. Note that we use Travis as Continuous Integration platform. When creating a pull-request, several builds are tested on several systems (linux, macos), compilers (gcc, clang) and configurations (DGtal dependencies). On Microsoft Windows platforms, we use Appeveyor service to test DGtalTools build. Before being merged, a pull-request must pass all these tests.

More information are described in the DGtal documentation.

Project organisation

The DGtalTools-contrib project is organized with the following structure:

  • Geometry2d: various utilities related to 2d geometry (2d estimators, 2d contour tools, ...);
  • Geometry2d: same as kind of tools in 3d.
  • Visualisation: tools related to visualisation.

Tools structure

The simplest way to start creating a new tool is to use the script newtools.sh given in the DGtalScripts scripts. This script generates a new empty tool containing only these minimal features:

  • inclusion of a DGtal base headers;

  • example of input options use (based on the boost::program_options). For instance, you can complete this example of options:

       po::options_description general_opt("Allowed options are");
   general_opt.add_options()
        ("help,h", "display this message")
        ("param,p", po::value< double >(), "a special parameter")

  • description the tool including a simple use example. You can refer to existing samples of the DGtal directory:

       trace.info() << "Usage: " << argv[0] << " [options] input\n"
             << "Display a 3D curve given as the <input> filename (with possibly projections and/or tangent information) by using QGLviewer.\n"
             << general_opt << "\n\n";
   trace.info() << "Example:\n"
             << "3dCurveViewer -C -b 1 -3 -2 -c ${DGtal}/examples/samples/sinus.dat\n";
  return 0;





Then, when your tool is defined, you have to include it in the
CMakeLists.txt file associated to its group. For instance, if you
create a new tool **xxx** in the group **Visualisation**, you have to
update the *CMakeLists.txt* file of the directory ```DGtalTools/visualisation```:
```cmake

SET(DGTAL_TOOLS_SRC
	displayTgtCoverAlphaTS
        xxx
)

Indent style

The indent style should be the same as the one of the DGtal library: the indent style follow Allman Style for C/C++ code. Here you have an example:

template< typename TemplatedType>
class NewClass
{
  public:
    typedef TemplatedType Type;

    void aMethod(const int aParameter)
    {
      if ( myMember == aParameter )
      {
        something1();
        something2();
      }
      else
      {
        somethingelse1();
        somethingelse2();
      }
      finalthing();
    }

    unsigned int myMember;
};

Naming rules

  • Types/methods/variable/classes in CamelCase: (e.g. BreadthFirstVisitor, myImage...)
  • methods, functions or variables start with lowercase letter
  • Types start with capital letters ( e.g. DigitalSurface,Value...)
  • Concepts classes start with a "C" (e.g. CInteger, CSpace ...)
  • Class members are prefixed by "my" (e.g. myImage, myParameter)
  • Method or function parameter are prefixed by "a". For instance:

c++ void superFunction(const Value & aParameter);

Contributor license agreement

At this point, we do not have Contributor License Agreement. However, contributors must agree with DGtal LGPL license and include the appropriate license header in their own code.

Documentation are published under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

If you want your package to be distributed under different licenses. Please contact us (see below).

Contacts

If you have any questions, do not hesitate to contact the developers on the mailing-lists: [email protected] or [email protected].