CONTRIBUTING.md

How to contribute to DGtalTools

In this document, we describe how to contribute to the DGtalTools projects. Please keep in mind the DGtalTools 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 ;

• create a branch for your contribution and push it to your DGtalTools 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 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 project is organized with the following structure:

• Converters: utilities to convert various simple file formats;
• Estimators: geometric estimators based on DGtal algorithms (2D/3D curvature, length or tangent estimators);
• ShapeGenerator: tools to generate shapes;
• Visualization: tools to display results of DGtal algorithms (contours/surface display, volumetric images...);
• Volumetric: 3d volumetric processing tools (marching cubes, image transforms,...).

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;

• description the tool including a simple use example. You can refer to existing samples of the DGtal directory: ```c++ std::stringstream ss; ss << "Usage: " << argv[0] << " [options] input\n" << "Display a 3D curve given as the filename (with possibly projections and/or tangent information) by using QGLviewer.\n" << general_opt << "\n\n"; ss << "Example:\n" << "3dCurveViewer -C -b 1 -3 -2 -c ${DGtal}/examples/samples/sinus.dat\n";

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

  CLI::App app;
  app.description("Description of your tool with basic usage." + ss.str());
  app.add_option("--input,-i,1", inputFilename, "description of the input...");
  app.add_option("--output,-o,2", outputFilename, "description of the output...");
  app.get_formatter()->column_width(40);
      CLI11_PARSE(app, argc, argv);

• doxygen tool documentation: you have to add the documentation in the doxygen format including the following elements:

  • brief description of the tool,
  • main usage,
  • list of the parameters,
  • typical examples of with illustrations (if available)

You can use as model the documentation of one tool of the main DGtalTools documentation and start from the template generated by the script newtools.sh of the DGtalScripts project.

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:

SET(DGTAL_TOOLS_SRC
	displayContours
        patternTriangulation
        3dCurvatureViewer
        3dCurvatureViewerNoise
        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: dgtal-devel@lists.gforge.liris.cnrs.fr or contacts@dgtal.org.