Developer Documentation *********************** Introduction ============ ANTS is a collection of application routines built using the ITK Toolkit, and extensions to the ITK toolkit. This document is meant for developers of ANTS itself, not for users who are using ANTS for analysis or for developing other tools, although the installation instructions and other notes may be of use to the latter group. .. NOTE:: This document is a work in progress... .. _git-main-label: Git === Git is used for version control of the ANTS project. It is a powerful tool but there are only a few actions that are performed regularly. See the "Pro Git" Primer (http://progit.org/book/) if you're new to Git. Chapters 1-3 will get you started enough to begin contributing code to the ANTS project. Another Git tutorial: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html. Git sourceforge tutorial: https://sourceforge.net/apps/trac/sourceforge/wiki/Git For accessing the ANTS project via Git, see :ref:`ants-git-label`. For using Git with ITK, see :ref:`git-for-itk-label` A nice and brief summary of why/how to use rebase: http://www.gitready.com/intermediate/2009/01/31/intro-to-rebase.html It is also helpful to know how to create a patch file: http://ariejan.net/2009/10/26/how-to-create-and-apply-a-patch-with-git/ .. todo:: Git - best practices? Should we decide on these for ants? See the itk git topic on workflow for ideas: http://www.itk.org/Wiki/Git/Workflow/Topic. Try This: I like the method proposed by Charles for rebasing with origin/master in the link you sent, see Common Rebasing Use Practices section - I've incorporated it below: http://www.eecs.harvard.edu/~cduan/technical/git/git-5.shtml So the basic practice might look like below (comments to be fleshed out). This seems to use a minimum of steps and a minimum of extra commit messages. Of course it only works cleanly if used only from private repos, excepting the last step. #Create a new local branch to make some changes/additions based on your local master git checkout master git checkout -b my_branch #Make your changes and commit locally #Rebase your changes back into local master branch. (Doing it this way instead of rebasing into my_branch means one less step since you don't have to also then merge into local master) git checkout master git rebase my_branch #Fetch (not pull) from remote master to get any changes that may have happened there. To see changes before trying to rebase, use 'git diff FETCH_HEAD'. git fetch [origin/master] #Rebase onto origin/master. This merges in changes from origin/master (via FETCH_HEAD) into your local master tree. Your local changes will appear 'upstream' of any changes in origin/master. That is, they'll appear as more recent commits in the final history. git rebase origin/master #Push to origin. This will be a fast forward merge since the rebase just put your changes as a descendant of what was fetched from origin. git push Directory Contents ================== .. todo:: dir contents - verify descriptions with Brian. decide on name for the exe's in UserTools dir. Applications? Routines? The root ANTS *source* directory looks like this: - ``Code`` -- source code for base ANTS functionality - ``Developer`` -- project files for developer documentation - ``DocumentationStatic`` -- source files and scripts for building the test documentation. See :ref:`test-docs-label`. - ``ExampleData`` -- test data used by routines in the Testing directory - ``Testing`` -- test scripts for each routine. See :ref:`test-docs-label`. - ``UserTools`` -- source code for higher-level user tools for ANTS functionality. These are referred to in this document as the applications or routines. Files: - ``CMakeLists.txt`` -- the main configuration file for CMake. - ``CTestConfig.cmake`` -- configuration file for using CTest with Dashboard. - ``SuperBuild.cmake`` -- configuration file for CMake for setting up a super-build that incorporates other projects. This is not in use at time of this writing. The root ANTS ``build`` directory has these main directories and files after a successful build: Directories: - ``CMakeFiles`` -- used by CMake tool - ``Documentation`` -- created only after running the ctests. See :ref:`test-docs-label`. - ``Testing`` -- used as a temporary directory during the ctest process. Other uses? - ``Temporary`` -- after running ctest, contains the testing log files. - ``UserTools`` -- binary and executable output for ANTS command line applications and utilities. Files (partial list): - ``CMakeCache.txt``, ``CPack*``, ``DartConfiguration.txt`` -- files used by CMake. You will generally not need to examine these files, they are automatically generated by CMake. - ``CTestTestfile.cmake`` -- generated by CMake, lists the tests to be run by ctest. Useful to review the paths used to call the tests. - ``Makefile`` -- generated by CMake, used to build the project. - ``UserTools/libANTSCommandLine.a`` -- library generated from ``/Code/Utilities/antsCommandLine*`` source files. Provides command line parsing functionality for user routines. - ``UserTools/libITKLabelOverlapMeasuresImageFilter.a`` -- ??? Examples ========= For basic usage examples of ANTS user routines, see the documentation in ``/Documentation/build/html/index.html``. Multi-Threaded Example ---------------------- .. todo:: ask Gang for a good one, or just use addImage filter (sp?) which is a simple one .. _test-docs-label: Testing & User Documentation ============================ The ANTS testing and documentation process has two goals: 1. Run application-level tests of the ANTS routines. These test that the code has been built correctly by running test scripts that each call an ANTS routine with known inputs, and compare the output to known results. 2. Create user documentation that consists of documentation and example usage for each routine. The documentation and testing process has three main components: 1. Good long and short usage output within the routines themselves. That is, each routine responds to command line arguments ``-h`` and ``--help`` with detailed usage. 2. A bash test script, one for each routine, implementing use cases on an input image and testing against "known" output. These scripts also create documentation source files. 3. A Sphinx page devoted to richer explanation, documentation, and creation of a web representation with figures - currently built into ``/Documentation/sources`` with the same naming prefix as the test script. Sphinx is a documentation generation tool that accepts reStructuredTest (reST)-formatted source files (with .rst extension) and creates a variety of output formats, including html and pdf. The user documentation is built by a separate process from the rest of the distribution. 1. Create usage documentation Provided by developer in routine itself. This is the output in response to ``-h`` and ``--help`` command line options. 2. Create test script This must test the routine's operation and create a documentation source file (in .rst format) specific to the routine. See ``/Testing/antsExampleTest`` for how this is done. Be sure to output into the proper directories as given in the example. The test script name must have the form "antsTest" so that the documentation build steps can include its output automatically. 3. Define the test Test are defined in ``/CMakeLists.txt``. A ctest definition takes the test name, the script to run and any script arguments. See the usage of ADD_TEST() in ``CMakeLists.txt``. You must re-configure the CMake build in ```` after changing ``CMakeLists.txt``, by running ``ccmake`` as described here: :ref:`ants-building-label`. 4. Run the tests To run all tests, call ``/ctest``. (Of course this must be done after buiding the distribution.) The CTest tool is a part of CMake. By convention, scripts are run from the ANTS source dir, and create output in the build directory. The developer must pass the proper paths when defining the test in ``CMakeLists.txt``. You can review the paths that will be used when tests are called by checking ``/CTestTestfile.cmake``. Running ``ctest`` performs the following actions, as defined in ``CMakeLists.txt``: 1. Run ANTS_SETUP_DOCS - creates the output directory ``/Documentation`` and copies documentation source files from ``/DocumentationStatic``. 2. Run all routine-specific tests. 3. Run ANTS_TESTS - this collects all the script-generated .rst files and adds them to the index in the main documentation source file via ``/Documentation/source/antsTesting.rst``. 4. Run ANTS_BUILD_DOCS - this calls Sphinx to build the documentation via ``/Documentation/Makefile``. Note that this makefile is not created by the CMake system. It's a static file that was created once during the initialization of the Sphinx project. The default output is html format, in ``/Documentation/build/html/index.html``. .. note:: Running a single test Running ``ctest`` runs all the tests defined in ``CMakeLists.txt``. If this takes too long, you can instead run the steps manually for your particular test. From ````, type:: ctest -R ANTS_SETUP_DOCS ctest -R ctest -R ANTS_TESTS ctest -R ANTS_BUILD_DOCS Note that once you've run these steps once after building the whole source distribution, the output documentation folder will be setup and antsTesting.rst will be updated, so you can just run ``ctest -R `` and ``ctest -R ANTS_BUILD_DOCS``. .. note:: Failed tests If your test fails when run from the CTest tool, all you'll see in the console is a message that your test failed. The log files with stdout and stderr from your script are located in ``/Testing/Temporary``. Dashboard --------- .. todo:: Dashboard (http://www.picsl.upenn.edu/cdash/) - seems unused - will it be used in the future? .. _cmake-ctest-notes-label: CMake & CTest Notes =================== This section is for notes and tips on using CMake and CTest. For a basic introduction, see :ref:`cmake-intro-label`. Changing configuration settings: If you change configuration settings, e.g. by adding a test to CMakeLists.txt, you must run ccmake again and choose the 'configure' option to update the cmake files in the build directory. You do not need to delete the build directory and run ccmake from scratch. Setting include directories For an example, see the call to ``SET( ANTS_INCLUDE_DIRS...`` in ``/UserTools/CMakeLists.txt``. Note that this CMakeLists.txt file is not in the top-level directory, but rather in a subdirectory, and relates to the source files in the subdirectory. New Image Registration Framework ================================= A new registration framework is under development as part of the ANTS 2 project. The base components will be included as a part of ITK 4. The wiki discussion is here: http://www.itk.org/Wiki/ITK_Release_4/Enhancing_Image_Registration_Framework ANTS UI ======= The ANTS user tool routines have a command line user inteface, provided by the libANTSCommandLine.a library. For example usage see antsSegmentation.cxx, the functions ``main`` and ``InitializeCommandLineOptions``. ITK Usage ========= For installing and building ITK, see :ref:`itk-install-label`. Learning ITK ------------ **ITK Software Guide** http://www.itk.org/ItkSoftwareGuide.pdf This is the official developer guide for ITK. See Chapter 8 for Registration. **Methods In Medical Image Analysis** http://www.cs.cmu.edu/~galeotti/methods_course/ An introductory course for using ITK. .. _git-for-itk-label: Git for ITK ----------- ITK Git project for current development: http://www.itk.org/Wiki/ITK/Git .. note:: We're currently using the stable 3.20 release available by direct download or via an SVN repository (see :ref:`itk-install-label`). .. todo:: This will be changing as we move closer to ITK 4. ITK uses Gerrit to manage the code review process: http://www.itk.org/Wiki/ITK/Gerrit/Primer Development Style Guidelines ---------------------------- .. todo:: dev style - what's happening here? When do we start enforcing? Presumably after new guidelines have been set by ITK team. The ITK development protocol specifies guidelines for code style. As of this writing, however, they are set to be updated, along the lines of this proposal: http://www.itk.org/Wiki/ITKv4_StyleChangeProposal. So for now, we're not using any tools to enforce style, simply copy the coding styling as best you can while working with the source code. The tools used to enforce code style are: - KWstyle: http://public.kitware.com/KWStyle/ - uncrustify: http://uncrustify.sourceforge.net/ Miscellaneous ============= The main segementation algorithm in ANTS is called *Atropos*. Why, you ask? From Wikipedia: In Greek mythology, Atropos (pronounced /ˈætrəpɒs/) (from Greek Άτροπος, "without turn") was one of the three Moirae, goddesses of fate and destiny. Her Roman equivalent was Morta. Atropos was the oldest of the Three Fates, and was known as the "inflexible" or "inevitable". It was Atropos who chose the mechanism of death and ended the life of each mortal by cutting their thread with her "abhorred shears".