VTK/Examples/GuideLines

From KitwarePublic

Jump to: navigation, search

Contents

Motivation

VTK is a large and powerful toolkit for visualization and modelling. New users can be overwhelmed by the size and what appears to be the complexity of the toolkit. There are several resources to help the new user:

In addition to these compilations of information, hundreds of tests are distributed with the toolkit source. However, these tests are meant to exercise the toolkit rather than illustrate how to use it. For the most part, the tests are not good educational resources.

The VTK source distribution also includes a sizeable number of examples. The goal of the VTK examples is to illustrate specific VTK concepts in a consistent and simple format.

The VTK examples are undergoing a major renovation sparked by the frustrations of new users.

Requirements

Although education of new users in the main motivation, the VTK examples should also:

  1. Encourage good programming style
  2. Promote the proper and modern way to use VTK and write VTK programs
  3. Facilitate the nightly compilation and testing of examples that reside in the VTK source code repository

These requirements must be met without compromising the main goal of user education.

Guidelines

All examples should follow the VTK programming style. The style include guidelines for indentation and naming conventions.

In addition to these fundamental guidelines, the following should be addressed:

  • All includes from the toolkit should use <> notation. This follows C++ programming conventions. For example: 
#include <vtkContourFilter.h>

is preferred over 

#include "vtkContourFilter.h"
  • The main program should have the following signature: 
int main (int argc, char *argv{})

or, if argc and argv are not referenced in the code, 

int main (int, char *[])
  • If arguments are required, a check similar to the following should be made at the start of the main program. 
if (argc != 3)
  {
  cerr << "Usage: " << argv[0] << "Alpha InputFile OutputFile" << endl;
  return EXIT_FAILURE;
  }
  • If the main program executes successfully, it should 
return EXIT_SUCCESS;

otherwise 

return EXIT_FAILURE;
  • The use of SmartPointers is preferred in VTK examples. 
 vtkSmartPointer<vtkCutter> cutter = vtkSmartPointer<vtkCutter>::New();

is preferred over 

 vtkCutter *cutter = vtkCutter::New();
  • When building pipelines, the new SetInputConnection(), GetOutputPort() methods should be used instead of SetInput(), GetOutput()
  • Currently, stl constructs should use the vtkstd:: namespace.

For example, 

#include <vtkstd::vector>
vtkstd::vector<float> scales;

is preferred over 

#include <vector>
std::vector<float> scales;
  • Currently, stream are in the global namespace, so 
cout << "Hello" << endl;

is preferred over 

std::cout << "Hello" << std::endl;
  • Input/Output filenames

When possible, filenames should be passed on the command line. This gives the examples utility beyond the data that is used in the specific example.

  • If there are just a few parameters for the example, these should be passed in as arguments. This increases the utility of the example and facilitates testing.

For example, this program 

Delaunay3DAlpha Alpha InputPolydataFileName(.vtp) OutputUnstructuredGridFilename(.vtu)

would use the arguments in this manner 

reader->SetFileName (argv[2]);
delaunay3D->SetAlpha(atof(argv[1]));
writer->SetFileName ( argv[3] );

The Life Cycle of an Example (under construction)

Examples exist in the Wiki and/or VTK source code repository.

There are many examples in the VTK source code repository. Some have been there since the inception of the toolkit. These examples have been subject to peer review and revision over the years. However, these examples only cover a small part of the capabilities of VTK.

Recently, spurred by a new user, David Doria, we have started to use the VTK wiki to provide examples. Users seeking solutions are using the wiki to find examples that answer questions like, "How do I extract normals from a filter's output?", How do I generate models from segmented data?", "How do I compute the area of a triangle?", "How do I generate a foo model from bar input?". Over time we hope that the examples will answer many of the users' questions. Some questions won't have a solution in the current example repertoire. For those questions, we encourage the user to create a simple example that illustrates either a dilemma or a new solution.

Currently, only a few of these examples exist in both the cvs repository and the wiki. Consequently, the wiki-only examples are not formally built and tested. We fear that over time, these examples will become obsolete unless they are integrated into the nightly build/test routine. Without this integration, the examples will eventually become a liability and not an asset.

A Question Motivates an Example

User Creates an Example

  1. Decide where the example will reside
  2. Create the Wiki page
    1. Descriptive title
    2. Brief description of the concepts illustrated by the example
    3. How to run the example
    4. Sample input data
    5. Source code listing with comments
    6. Sample CMakeLists.txt file
    7. Optional images of the example output

Peer Review of the Example

  1. Illustrates a useful concept?
  2. Does not duplicate an existing example?
  3. Conforms to VTK style?
  4. Produces expected results?

Example Moves to the Repository

  1. Decide where the example will reside
  2. Move example into VTK/Examples tree
  3. Create CMakeLists.txt
  4. Create any test driver code
  5. Submit Experimental dashboard build

Example is Integrated into the Nightly Build/Test Process

  1. Check in code and related CMakeLists.txt
  2. Check in image baselines if appropriate
  3. Check the continuous dashboard for troubles during the day
  4. The next day, check the dashboard for errors/warning
  5. Have a beer

Example testing - Under the Covers

The examples are tested using the existing vtk testing framework.

Retrieved from "http://www.itk.org/Wiki/VTK/Examples/GuideLines"
Personal tools