diff --git a/Documentation/Doxygen/3-DeveloperManual/Concepts/TestsGeneral.dox b/Documentation/Doxygen/3-DeveloperManual/Concepts/TestsGeneral.dox index 4e0992f1a5..79b1ca8636 100644 --- a/Documentation/Doxygen/3-DeveloperManual/Concepts/TestsGeneral.dox +++ b/Documentation/Doxygen/3-DeveloperManual/Concepts/TestsGeneral.dox @@ -1,93 +1,100 @@ /** \page GeneralTests General: Tests in MITK +MITK has switched to using the CppUnit framework. This page will be rewritten to reflect that. Until that is the done please take a look at either a CPPUnit tutorial (such as http://robotics.usc.edu/~ampereir/wordpress/?p=772) +or the following example test. + +\include Examples\FirstSteps\NewModule\test\mitkExampleDataStructureTest.cpp + +\warning The text below shows the old MITK test framework and will be replaced once a more comprehensive CppUnit text is available + Two types of standardizes automated tests are provided by MITK. These types are unit tests and rendering tests . This section will describe unit testing in MITK, while more information on rendering tests can be found in the section \ref RenderingTests. -# \ref GeneralTestsSection1 "Basic Information on Unit Testing" -# \ref GeneralTestsSection2 "Adding a Unit Test to MITK" -# \ref GeneralTestsSection2_1 "Structure your test method" -# \ref GeneralTestsSection3 "Run a Unit Test with MITK" -# \ref GeneralTestsSection4 "MITK Testing Macros" \section GeneralTestsSection1 Basic Information on Unit Testing The basic idea about unit testing is to write a test for every class (unit) of your software. The test should then run all methods of the tested class and check if the results are correct. Thus, the testing environment for MITK allows for simple implementation of corresponding test methods for MITK classes. The build system of MITK generates a test driver which includes all tests that have been added to the project. Alternativly you can run MITK tests by using the program ctest. This is the way all MITK tests run on the continous dart clients of MITK. The results of these runs can be found at http://cdash.mitk.org. The following sections will explain how to write your own tests with MITK and how to run them. The last section will describe the testing macros of MITK in detail. \section GeneralTestsSection2 Adding a Unit Test to MITK To add a test, you simply need to create a new file "mitkMyTest.cpp" in the folder "Testing" of the software module to which you want to add the test. The file must contain such a method: \code int mitkMyTest(int argc, char* argv[]) \endcode This method is automatically called by the test driver. A header file to this cpp file is not needed. An example for a simple test method is shown next. \code int mitkMyTest(int argc, char* argv[]) { MITK_TEST_BEGIN("MyTest"); MITK_TEST_CONDITION_REQUIRED(true,"Here we test our condition"); MITK_TEST_END(); } \endcode Additionaly you've to add the test file to the files.cmake of your testing directory. In the files.cmake you'll find a command "SET(MODULE_TESTS [...])", this is where you've to add the filename of your test. This will add your test to the test driver. A possible files.cmake where a test have already been added is shown next. \code SET(MODULE_TESTS mitkMyTest.cpp [...] ) \endcode Finally you only have to run cmake one your project and then compile the test driver. Don't forget to turn "BUILD_TESTING" on, when running cmake. \subsection GeneralTestsSection2_1 Structure your test method When implementing more complex test methods you might want to structure them, e.g. by using sub methods. This is also possible. You can create a test class and add static methods which can then be called in your main test method. This is a simple way to keep a clear structure in your test file. An example for such a structured test file is shown next. \code //first: your test class with static methods, if it comes before the main test method // like shown here, you still don't need a header and you can keep your code as // simple as possible class mitkMyTestClass { public: static void TestInstantiation() { //do your instantiation test here } static void TestMethod1() { //do a test of method 1 here } };//do not forget the semicolon at this place! //secondly: your main test method int mitkMyTest(int argc, char* argv[]) { MITK_TEST_BEGIN("MyTest"); mitkMyTestClass.TestInstantiation(); mitkMyTestClass.TestMethod1(); MITK_TEST_END(); } \endcode \section GeneralTestsSection3 Run a Unit Test with MITK After building and compiling MITK, there are two ways to run your test. Firstly, you can run your test using the executable test driver. Secondly, you can use the external program ctest. If you use the test driver, you only need to start the executable. If you start it without parameters, it will then give you an overview of all tests which are included in this test driver and you can choose one by typing a number. \note This way you can not set additional input, such as images. Alternatively you can give your test driver the name of your test as parameter. Then this test will be started directly. You are also allowed to give more parameters which are then given to the main test method as parameters (argv[]). If you want to use ctest instead of the test driver you need to start a command line, go to the binary directory of MITK and call ctest. To avoid errors, check if your path variable contains all relevant paths to start MITK. \section GeneralTestsSection4 MITK Testing Macros MITK offers testing macros to simplify testing, e.g. to test your testing conditions. These macros can be found in the header mitkTestingMacros.h . */ diff --git a/Documentation/Doxygen/3-DeveloperManual/Starting/FirstSteps/FirstSteps.dox b/Documentation/Doxygen/3-DeveloperManual/Starting/FirstSteps/FirstSteps.dox index 7b01d0b3e1..cb3f5cd61f 100644 --- a/Documentation/Doxygen/3-DeveloperManual/Starting/FirstSteps/FirstSteps.dox +++ b/Documentation/Doxygen/3-DeveloperManual/Starting/FirstSteps/FirstSteps.dox @@ -1,15 +1,16 @@ /** \page FirstSteps First steps in Development This section will show you how to extend MITK for your own project. */ diff --git a/Documentation/Doxygen/3-DeveloperManual/Starting/FirstSteps/NewDataType.dox b/Documentation/Doxygen/3-DeveloperManual/Starting/FirstSteps/NewDataType.dox new file mode 100644 index 0000000000..e30e8f3e7d --- /dev/null +++ b/Documentation/Doxygen/3-DeveloperManual/Starting/FirstSteps/NewDataType.dox @@ -0,0 +1,52 @@ +/** + +\page NewDataTypePage How to create a new custom data type + +\tableofcontents + + +\section NewDataTypePagePrerequisites Prerequisites and further reading + +We will use some concepts during this tutorial which we assume you are aware of, as well as taking advantage of infrastructure which needs to be set up. The following is a list of prerequisites which should be present to effectively use this tutorial. + + + +Some concepts will only be briefly touched upon in this tutorial, for a more concise presentation of these concepts please refer to the following further reading. + + + +\section NewDataTypePageCreatingANewDataType Creating a new data type + +A new data type needs to derive from mitk::BaseData in order to be handled by the mitk::DataStorage via mitk::DataNode. An example of a very simple data type is provided in the example module. This type encapsulates a string. + +\include mitkExampleDataStructure.h + +Overloading mitk::Equal to work with your data type will enable you to write simpler, standardized tests. + +\section NewDataTypePageAddingReadersAndWriters Adding readers and writers + +In order for your data type to be read from and written to disk, you need to implement readers and writers. In order for your readers/writers to be registered and available even if your module has not been loaded (usually after just starting the application), it is advisable to implement them separately in a autoload module. The default location for this is "YourModuleName/autoload/IO". + +More information regarding implementing IO and MimeTypes is available at \ref ReaderWriterPage. An example MimeType is implemented for the example data structure. + +\include mitkExampleIOMimeTypes.h + +\note{ You do not need to create your own class to manage your MimeTypes. Instead they can be defined within the Reader/Writer. } + +\section NewDataTypePageAddingReadersAndWriters Adding a mapper + +If your data type needs a special way to render its data for the user, you need to implement a new mapper. More information can be found at \ref QVTKRendering. + +

+If you meet any difficulties during this How-To, don't hesitate to ask on the MITK mailing list mitk-users@lists.sourceforge.net! +People there are kind and will try to help you. +If you notice that there is an error, or that the code has changed so the way shown here is no longer correct, please open a bug report a http://bugs.mitk.org .

+ +*/ diff --git a/Documentation/Doxygen/3-DeveloperManual/Starting/FirstSteps/NewModule.dox b/Documentation/Doxygen/3-DeveloperManual/Starting/FirstSteps/NewModule.dox index 20c324fd0a..b92cc2cdfc 100644 --- a/Documentation/Doxygen/3-DeveloperManual/Starting/FirstSteps/NewModule.dox +++ b/Documentation/Doxygen/3-DeveloperManual/Starting/FirstSteps/NewModule.dox @@ -1,82 +1,122 @@ /** \page NewModulePage How to create a new MITK Module \section NewModulePageCreateFolder 1) Create a Folder for your Module First, create a folder for your module within /Modules e.g. 'NewModule'. You need to add the new Folder to the CMakeLists.txt in the Module directory as well as well. -Open /Modules/CMakeLists.txt, it should be pretty clear how to add the Module, just insert it into the set(module_dirs) section. +Open /Modules/CMakeLists.txt, insert it into the set(module_dirs) section. \code set(module_dirs ... NewModule ) \endcode -Inside the folder create a new folder called "Testing", which will later contain the module tests. -Also create subfolders for you sourceFiles, for example "NewModuleFilters" and "NewModuleSourceFiles". +A simple example module is provided in the MITK/Examples/FirstSteps/NewModule directory, it includes a new data type +(more information at \ref NewDataTypePage) and adds a MiniApp for that data type (more information at \ref MiniAppCommandLineToolHowToPage). + +Within the module we recommend using a Unix like directory structure. This helps others finding their way around your code. +Depending on your use case you might not need every directory. + +\code +NewModule/ + autoload/ + doc/ + include/ + MiniApps/ + resource/ + src/ + test/ +\endcode + +Subsequently a quick description of what each directory contains. + +\subsection NewModulePageCreateFolderAutoload autoload + +This directory should not directly contain files. Instead it contains further directories each of which is its own module. + +These modules provide functionality which should be available at application start, but will not be included by other modules. +Examples would be a module registering readers/writers or providing an interface for specific hardware. + +For an example of an autoload module take a look at NewModule/autoload/IO. + +\subsection NewModulePageCreateFolderDoc doc + +This directory contains the documentation for your module. + +\subsection NewModulePageCreateFolderInclude include + +This directory contains all header files which might be included by other modules. + +\subsection NewModulePageCreateFolderMiniApps MiniApps + +This directory contains all MiniApps (command line tools) related to your module. For more information see \ref MiniAppCommandLineToolHowToPage. + +\subsection NewModulePageCreateFolderResource resource + +This directory contains resources needed by your module, such as xmls, images or similar. + +\subsection NewModulePageCreateFolderSrc src + +This directory contains source and header files which should not be included by other modules. Further subdivision can help keeping it organized. +(e.g. src/DataManagement src/Algorithms) + +\subsection NewModulePageCreateFolderTest test + +This directory contains all tests for your module. + \section NewModulePageCreateCMakeLists 2) Create CMakeLists.txt -Within your module create the following file named CMakeLists.txt with the following content: +Within your module create a CMakeLists.txt using the MITK_CREATE_MODULE macro: -\code -MITK_CREATE_MODULE(NewModule #<-- module name - SUBPROJECTS - INCLUDE_DIRS NewModuleFilters NewModuleServices #<-- sub-folders of module - INTERNAL_INCLUDE_DIRS ${INCLUDE_DIRS_INTERNAL} - DEPENDS Mitk #<-- modules on which your module depends on -) +An example: -ADD_SUBDIRECTORY(Testing) #<-- Directory for tests -\endcode +\include Examples\FirstSteps\NewModule\CMakeLists.txt + +If you do not choose a module name, one will be generated based on the folder name (In this case the resulting name will be MitkNewModule). +This name has to be unique across the entire project in order to avoid collisions. It should only contain Letters (both upper- and lowercase), +no numbers, no underscores etc. + +An example of an autoload module that sets its own name is: -Choose a fitting module name. This name should only contain Letters (both upper- and lowercase), no numbers, no underscores etc. -This name will be used to qualify your Module within the MITK Framework, so make sure it is unique. -Typically, the name will be the same as name of the Folder the Module resides in. +\include Examples\FirstSteps\NewModule\autoload\IO\CMakeLists.txt -It is good practice to create subfolders in your module to structure your classes. -Make sure to include these folders in the List of subfolders, or CMake will not find the internal Files. +the resulting name is MitkNewModuleIO. -In the DEPENDS section, you can enter the modules that your module requires to function. -You will not be able to use classes from modules that are not listed here. +\note For more information about the parameters of the new module macro see mitkFunctionCreateModule.cmake \section NewModulePageCreatefilesdotcmake 3) Create files.cmake -Next, create a new file and name it files.cmake, containing the following: +Next, create a new file and name it files.cmake, containing the files of your module. -\code -SET(CPP_FILES - NewModuleFilters/File1.cpp - NewModuleFilters/File2.cpp +An example: - NewModuleServices/Filter1.cpp -) -\endcode +\include Examples\FirstSteps\NewModule\autoload\IO\files.cmake -Add each .cpp file you create to this file. -Also, only add you .cpp files here, not the header files! +If you do not add a source file here it will not be compiled, unless it is included elsewhere. -\section NewModulePageCreateTEstingEnvironment 4) Set up the Test environment +\section NewModulePageCreateTestingEnvironment 4) Set up the Test environment -We also need to set up a testing environment where you can add your tests. -Inside your "Testing" Folder, create a new files.cmake containing the following: +Providing tests for your code is a very good way to save yourself a lot of debugging time and ensure +consistency. An example of a small test environment is provided in the NewModule example. -\code -SET(MODULE_TESTS - mitkNewModuleTest.cpp -) -\endcode +Again you need a CMakeLists.txt, e.g.: -Also, create a new CMakeLists.text: +\include Examples\FirstSteps\NewModule\test\CMakeLists.txt -\code -MITK_CREATE_MODULE_TESTS() -\endcode +a files.cmake, e.g.: + +\include Examples\FirstSteps\NewModule\test\files.cmake + +and an actual test, e.g.: + +\include Examples\FirstSteps\NewModule\test\mitkExampleDataStructureTest.cpp -That's it! Enjoy your new module! After following these steps, it should look something like this: +For more information regarding tests please refer to \ref AboutTestingPage. -\imageMacro{NewModule.png,"Your shiny new module!",6} +That's it! Enjoy your new module! */ \ No newline at end of file diff --git a/Documentation/Doxygen/3-DeveloperManual/Starting/GettingToKnow/Tutorial/Tutorial.dox b/Documentation/Doxygen/3-DeveloperManual/Starting/GettingToKnow/Tutorial/Tutorial.dox index c556bd47af..ee7517c3d1 100644 --- a/Documentation/Doxygen/3-DeveloperManual/Starting/GettingToKnow/Tutorial/Tutorial.dox +++ b/Documentation/Doxygen/3-DeveloperManual/Starting/GettingToKnow/Tutorial/Tutorial.dox @@ -1,46 +1,48 @@ /** \page TutorialPage The MITK Tutorial If you have set up and compiled MITK already and want to know more about developing with MITK you might want to read the \ref TutorialSection. If you want help setting up MITK and creating your own project using MITK you should take a look at \ref HowToNewProject. \section TutorialFirstSteps First steps in MITK If you are absolutely new to MITK you might want to read up on setting up MITK to use in your development. The following pages will help you in this task. \section TutorialSection Tutorial chapters This tutorial will give you an introduction to developing with MITK. We will start with configuring MITK to compile the tutorial, continue to show how to display and do basic interaction with images, and finally show how to build a plug-in and add new interactions. The source code of the examples can be found in Examples/Tutorial/ \n Two data files are used to execute the example code. \li Pic3D.nrrd \n This file contains an image and can be downloaded from http://mitk.org/download/tutorial-data/Pic3D.nrrd . \li lungs.vtk \n This file contains a surface and can be downloaded from http://mitk.org/download/tutorial-data/lungs.vtk . \li \subpage Step00Page "Step 0: Getting started" \li \subpage Step01Page "Step 1: Displaying an image" \li \subpage Step02Page "Step 2: Load one or more data sets" \li \subpage Step03Page "Step 3: Create 3D view" \li \subpage Step04Page "Step 4: Use several views to explore data" \li \subpage Step05Page "Step 5: Interactively add points" \li \subpage Step06Page "Step 6: Use an interactive region-grower" \li \subpage Step07Page "Step 7: Convert result of region growing into a surface" \li \subpage Step08Page "Step 8: Use QmitkStdMultiWidget as widget" \li \subpage Step09Page "Step 9: A plug-in" \li \subpage Step10Page "Step 10: How to use Interactor and how to implement new ones" +More advanced How-Tos can be found at \ref FirstSteps . + Enjoy MITK! */ diff --git a/Documentation/Doxygen/3-DeveloperManual/images/NewModule.png b/Documentation/Doxygen/3-DeveloperManual/images/NewModule.png deleted file mode 100644 index c379c6649a..0000000000 Binary files a/Documentation/Doxygen/3-DeveloperManual/images/NewModule.png and /dev/null differ