namespace itk {
namespace simple {
/**
\page FilterTemplatesPage Image Filter Templates ReadMe

This ReadMe outlines the system used to generate SimpleITK files using json
data files in conjunction with the template .h and .cxx files


\section Overview Overview
In order to create a uniform body of image filters, we use an automated code
generation system to wrap existing ITK filters into SimpleITK filters. The
development process consists of writing a JSON data file which specifies the
information needed to fill in the fields of the template file. During
compilation, all of the .json files are parsed using a lua template engine
which fills in the apropriate template file from the provided fields. This
ReadMe provides a detailed description of the fields that can be used in the
json data files and what effect each field has on the resulting image filter.
When writing your own json file, it should be saved in:

$SimpleITK_SOURCE_DIR/Code/$FILTER_DIR/json

Here $FILTER_DIR is the directory in which the code for the generated filter
should live.  For simple filters this is the "BasicFilters" directory.

\section FileStructure JSON File Structure
JSON (JavaScript Object Notation) is a simple text formatting system used to
specify data values. A full description of the specification can be found at
http://www.json.org/. For the purposes of SimpleITK, a json file consists of
a single data object (denoted by {}) which contains several string : value
pairs (here value may be a list denoted by []) and sub-objects. Here is an
example from LaplacianRecursiveGaussian:

\verbatim
{
  "name" : "LaplacianRecursiveGaussian",
  "template_code_filename" : "ImageFilter",
  "template_test_filename" : "ImageFilter",
  "doc" : "",
  "pixel_types" : "BasicPixelIDTypeList",
  "output_pixel_type" : "float",
  "members" : [ {
    "name" : "Sigma",
    "type" : "double",
    "default" : "1.0",
    "doc" : "",
    "briefdescriptionSet" : "",
    "detaileddescriptionSet" : "Set Sigma value. Sigma is measured in the units of image spacing.\n"
  }, {
    "name" : "NormalizeAcrossScale",
    "type" : "bool",
    "default" : "0",
    "doc" : "",
    "briefdescriptionSet" : "",
    "detaileddescriptionSet" : "Define which normalization factor will be used for the Gaussian\\see RecursiveGaussianImageFilter::SetNormalizeAcrossScale\n\n",
    "briefdescriptionGet" : "",
    "detaileddescriptionGet" : ""
  } ],
  "tests" : [ {
    "tag" : "default",
    "description" : "Simply run with default settings",
    "inputA" : "Input/RA-Float.nrrd",
    "settings" : [ ],
    "tolerance" : 1.0E-4
  } ],
  "briefdescription" : "Computes the Laplacian of an image by convolution with the second derivative of a Gaussian.\n",
  "detaileddescription" : "This filter is implemented using the recursive gaussian filters\n\n\\li {EdgesAndGradients/LaplacianRecursiveGaussianImageFilter,Compute the Laplacian of an image}\n\n"
}
\endverbatim

In this example, we see that all pairs must use a string as the key, but may
have any valid type as the value (string - "Abs", number - 1, list - [],
object - {}).

\section GlobalFields Fields For All Templates

This section describes the minimal set of fields required to wrap an ITK filter
into SimpleITK.

\subsection TopLevelFields Top Level Fields

- \b name: (\e string) This must be the name of the ITK filter with the
"ImageFilter" suffix removed

- \b templage_code_filename: (\e string) Which of the template files should be
used to generate the filter. Choices are: "ImageFilter",
"RegionGrowingImageFilter", "StructuringElementImageFilter",
"LevelSetImageFilter", "MathematicalMorphologyImageFilter"

- \b template_test_filename: (\e string) Which of the template files should be
used to generate the test for this filter. Choices are: "ImageFilter",
"RegionGrowingImageFilter"

- \b number_of_inputs: (\e integer) How many input images are used for this
filter. Currently, the template system only supports filters with 1 or 2 input
images

- \b briefdescription: (\e string) Brief description of the class
  (Doxygen format).  This string is automatically generated by the
  Utilities/BuildDocs and Utilities/GenerateDocumentation.groovy
  scripts.  If no corresponding ITK class exists, this field will not
  be modified.

- \b detaileddescription: (\e string) More detailed description of the class
  (Doxygen format).  This string is automatically generated by the
  Utilities/BuildDocs and Utilities/GenerateDocumentation.groovy
  scripts. If no corresponding ITK class exists, this field will not
  be modified.

- \b pixel_types: (\e string) Which of the pixel type lists should be supported
for this filter. The type lists are defined in sitkPixelIDTypeLists.h

- \b members: (\e list) This list specifies all member variables that should be
accessible to the user with a Get/Set mechanism and should be part of the
Execute signature for the filter. Each entry in the list must be an object

- \b tests: (\e list) This list specifies all automatic tests that should be
generated for the filter. Each entry in the list must be an object. If no tests
are specified, a test will be generated that fails with the message that a test
must be written for the filter

- [OPTIONAL] \b include_files: (\e list) This list of strings specifies
additional header files to include in the cxx file for this filter.

- [OPTIONAL] \b custom_set_intput: (\e string)  Code which is used to
  set input or multiple inputs to the filter. This overides the
  standard setting of the inputs.

- [OPTIONAL] \b output_pixel_type: (\e string) String representing the specific
pixel type to use for the output image of the filter.

- [OPTIONAL] \b filter_type: (\e string) Explicitly sets the
  FilterType used. This method overides
  additional_template_types. Useful typedefs are InputImageType, and
  OutputImageType.

- [OPTIONAL] \b public_declarations: (\e string) Any c++ code written in this
field will be placed into the public section of the filter's header file

- [OPTIONAL] \b additional_template_types: (\e list) The standard ITK image
filter template signature is:

\verbatim
<InputImageType, (if 2 inputs)InputImageType, OutputImageType)>
\endverbatim

Some filters require additional template types between the list of input image
types and the output image type such as the input type of a constant. This list
allows these additional parameters to be added so that the template signature
looks like:

\verbatim
<InputImageType, (if 2 inputs)InputImageType, (ADDITIONAL TYPES), OutputImageType)>
\endverbatim

Each type in the list is specified by an object with a only a \b type field
which is a string specifying the type to be used.

- [OPTIONAL] \b custom_methods: (\e list) This is a list of objects specifying
custom methods that should be added to the filter. The fields required for a
custom method are:
  - \b doc: (\e string) Documentation for this custom method
  - \b name: (\e string) The name of the method
  - \b return_type: (\e string) the return type of the method
  - [OPTIONAL] \b parameters: (\e list) A list of of parameters for the method.
  Each method is specified by an object with the following fields:
    - \b type: (\e string) The parameter's type
    - \b var_name: (\e string) The name of the variable to be used in the \b body
    field for the custom method

  - \b body: (\e string) This string is the body of the method and will be
  placed directly into the header file. The parameter names specified with
  \b var_name in each of the parameter obects can be used in this body

A sample custom method might look like:

\verbatim
{ "name" : "Foo",
  "doc" : "This method checks if a string is equal to Foo"
  "return_type" : "bool",
  "parameters" : [
    { "type" : "std::string",
      "var_name" : "inString"
    }
  ],
  "body" : "if (!strcmp(inString.c_str(), "Foo")) { return true; } else { return false; }"
}
\endverbatim

This will translate to a custom method that looks like:

\verbatim
  /**
   * This method checks if a string is equal to Foo
   */
  bool Foo( std::string inString )
    {
    if (!strcmp(inString.c_str(), "Foo")) { return true; } else { return false; }
    }
\endverbatim



\subsection MemberFileds Member Fields
A basic member object looks like:

\verbatim
{
  "name" : "Sigma",
  "type" : "double",
  "default" : 1.0,
  "briefdescriptionSet" : "",
  "detaileddescriptionSet" : "Define which normalization factor will be used for the Gaussian\\see RecursiveGaussianImageFilter::SetNormalizeAcrossScale\n\n",
  "briefdescriptionGet" : "",
  "detaileddescriptionGet" : ""
 }
\endverbatim

- \b name: (\e string) The name of the member variable. A variable named "Var"
will be accessible with the methods "GetVar" and "SetVar"

- \b type: (\e string) The c++ type for this member. If using a type contained
in a certain namespace (itk::simple for example), this must be included in the
type description. If the member variable is of type bool, the
additional ${name}On, and ${name}Off member functions are added.

- \b default: (\e string or \e number) The default value for this member. This
can be a number for numerical types or a string specifying the constructor for
non-basic types (std::vector< unsigned int >() for example)

- \b briefdescriptionSet/briefdescriptionGet: (\e string) Brief
  Doxygen documentation for this individual parameter.  The two forms
  (Set/Get) are used for the SetMember and GetMember functions.  This
  field is automatically generated from ITK's Doxgen for members that
  mirror ITK's members. If the member if a custom,
  this field will not be modified.

- \b detaileddescriptionSet/detaileddescriptionGet: (\e string)
  Detailed Doxygen documentation for this individual parameter.  The
  two forms (Set/Get) are used for the SetMember and GetMember
  functions. This field is automatically generated from ITK's Doxgen
  for members that mirror ITK's members.  If the member if a custom,
  this field will not be modified.

- [OPTIONAL] \b no_set_method: (0 or 1) If set to 1, the filter will not have a
Set method for this member

- [OPTIONAL] \b no_get_method: (0 or 1) If set to 1, the filter will not have a
Get method for this member

- [OPTIONAL] \b no_print: (0 or 1) If set to 1, this member will not be printed
in the ToString method

- [OPTIONAL] \b dim_vec: (0 or 1) If set to 1, this indicates that the member
is a std::vector with size equal to the dimension of the input image. As such,
it will be printed out correctly and cast to its corresponding ITK type
correctly

- [OPTIONAL] \b set_as_scalar: (0 or 1) If parameter is a dim_vec,
  then this method adds an additional set member method to set the
  variable as a scalar so that all components are the same


- [OPTIONAL] \b enum: [ "enum1", "enum2", ... ] Creates a member type
  of the class with the array of strings with a type defined by the
  name of this parameter. This field makes the "type" parameter
  optional. It is recommended to add a test to ensure the SimpleITK
  values correspond to the ITK values.

- [OPTIONAL] \b custom_itk_cast: (\e string) Some non-basic types will require
a custom cast before the corresponding ITK filter's member can be set. This
field allows the developer to specify exactly how the ITK filter sets the
member's value from the SimpleITK member's value for example:

\verbatim
"custom_itk_cast" :
  "filter->SetObjectValue(static_cast<typename FilterType::PixelType>(this->GetObjectValue()) );"
\endverbatim


\subsection TestFields Test Fields
A basic test object looks like:

\verbatim
{
  "tag" : "float",
  "description" : "Dilate a float image",
  "inputA" : "Input/RA-Slice-Float.nrrd",
  "tolerance" : 0.01,
  "settings" : []
}
\endverbatim

There are three ways of checking the resulting image: against a baseline image,
a sha1 hash, or an md5 hash. At least one of these options must be used for
each test.

- \b tag: (\e string) The tag to identify this specific test for the filter

- \b descriptoin: (\e string) Documentation to describe this specific test

- \b inputA: (\e string) The path from the SOURCE_DIR/Testing/Data directory
for the (first) input image

- \b inputA_cast: (\e string) an sitkPixelIDEnum, after inputA is read the CastImageFilter is run, to covert the image type.

- [OPTIONAL] \b inputB: (\e string) If \b number_of_inputs is 2, this specifies
the path from SOURCE_DIR/Testing/Data to the second input image

- [OPTIONAL] \b tolerance: (\e float) An error tolerance fo be used when
comparing the resulting image to the baseline. This is used to specify that the
result should be checked against a baseline image

- [OPTIONAL] \b md5hash: (\e string) An md5 hash value to compare the resulting
image against.

- [OPTIONAL] \b sha1hash: (\e string) A sha1 hash value to compare the resulting
image against.

- [OPTIONAL] \b settings: (\e list) A list of any specific parameters values
for this test. Each entry is an object of the form:

\verbatim
{ "parameter" : "Sigma",
  "value" : 1.0
}
\endverbatim

- \b Settings \b Options:
  - \b parameter: (\e string) The name of the parameter. This must match the
  name used when creating the filter
  - \b value: (\e string or \e number) The value to assign to the parameter.
  This can be a number for numerical types or a string representing the
  constructor for more complex types
  - [OPTIONAL] \b python_value: (\e string) For types that require a different
  syntax for setting the value in python, this will override the string in
  \b value
  - [OPTIONAL] \b lua_value: (\e string) For types that require a different
  syntax for setting the value in lua, this will override the string in
  \b value
  - [OPTIONAL] \b ruby_value: (\e string) For types that require a different
  syntax for setting the value in ruby, this will override the string in
  \b value
  - [OPTIONAL] \b java_value: (\e string) For types that require a different
  syntax for setting the value in java, this will override the string in
  \b value
  - [OPTIONAL] \b tcl_value: (\e string) For types that require a different
  syntax for setting the value in tcl, this will override the string in
  \b value
  - [OPTIONAL] \b R_value: (\e string) For types that require a different
  syntax for setting the value in R, this will override the string in
  \b value
  - [OPTIONAL] \b dim_vec: (0 or 1): Use this flag if this parameter is a
  std::vector. If set to 1, the \b type option must also be set
  - [OPTIONAL] \b no_get_method: (0 or 1). Set to 1 when the filter
  does not have a get method, so that this method will not be tested.
  - [OPTIONAL] \b type: (\e string): What type the vector should be. Due to
  constraints with java, this should only be a primitive type. For unsigned
  types, the java test will convert to the signed equivalent. An example for a
  dim_vec parameter is:

\verbatim
{ "parameter" : "Size",
  "dim_vec" : 1,
  "type" : "unsigned int"
  "value" : "{1,2}",
  "java_value" : "{1,2}",
  "tcl_value" : "[list 1 2]",
  "python_value" : "[1,2]",
  "lua_value" : "{1,2}",
  "ruby_value" : "[1,2]"
}
\endverbatim

\section Structure Directory Structure
The code generation system is designed to be agnostic of what subdirectory is
being parsed. An example of this is BasicFilters.  Here will just refer to
$FILTER_DIR

There are four important subdirectores in
$SimpleITK_SOURCE_DIR/Code/$FILTER_DIR:

  - \b include: Manually written header files
  - \b src: Manually written c++ files
  - \b json: The input json files used to generate new filters at build time
  - \b templates: The code templates that can be used to generate filters for
  this directory

When a filter is generated, it produces a .h and a .cxx file that are placed
in $SimpleITK_BUILD_DIR/Code/$FILTER_DIR/include and
$SimpleITK_BUILD_DIR/Code/$FILTER_DIR/src respectively.

It is also worth noting that the template files in the \b templates directory
are comprised of a combination of c++ code, lua template expansion directives,
and $(include xxx) statements.  These include statements each pull in a section
of template code from a file in $SimpleITK_SOURCE_DIR/ExpandTemplateGenerator/Components. These
component files represent pieces of templates that are shared by multiple
unique filter template types.


\section Templates Specialized Templates
The standard template is ImageFilter. This section describes the differences
for each of the other template types.

- <b>Region Growing Image Filters:</b> The region growing filters support an
additional set of methods for manipulating the seed list. Each region growing
filter has the SetSeed, AddSeed, and ClearSeeds methods. See
sitkConnectedThresholdImageFilter.h for details.

- <b>Kernel Image Filters:</b> The kernel image filters use
a KernelType and have an external enum which allows the user to select which
kernel to use. See sitkErodeObjectMorphologyImageFilter.h for details.

- <b> Dual Image Filter:</b> The dual image filter template's usage
should be avoided because it instantiates the combination of two pixel
type lists.
*/
}}
