Merge pull request #21 from MIRTK/release/v1.2

Release v1.2

Atlases.cmake

@@ -0,0 +1,23 @@
+cmake_minimum_required(VERSION 2.7)
+
+include(${CMAKE_ROOT}/Modules/ExternalProject.cmake)
+
+set(ATLAS_URL "https://biomedic.doc.ic.ac.uk/brain-development/downloads/dHCP/atlases-dhcp-structural-pipeline-v1.zip")
+set(ATLAS_MD5 77e924bc17a4906f5814874009f5eca6)
+
+if(NOT EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/atlases)
+    ExternalProject_Add(atlases
+      URL ${ATLAS_URL}
+      URL_MD5 ${ATLAS_MD5}
+      PREFIX atlases
+      CONFIGURE_COMMAND ""
+      BUILD_COMMAND ""
+      INSTALL_COMMAND ""
+    )
+
+    add_custom_target(atlases_move ALL
+      ${CMAKE_COMMAND} -E rename ${CMAKE_CURRENT_BINARY_DIR}/atlases/src/atlases ${CMAKE_CURRENT_SOURCE_DIR}/atlases
+    )
+
+    ADD_DEPENDENCIES(atlases_move atlases)
+endif()

CMakeLists.txt

@@ -25,3 +25,6 @@ if (NOT COMMAND mirtk_configure_module)
 endif ()
 
 mirtk_configure_module()
+
+SUBDIRS(ThirdParty/ANTs)
+INCLUDE(Atlases.cmake)

README.md

@@ -1,58 +1,69 @@
-Draw-EM Segmentation Software
-==========================================
+# Draw-EM Segmentation Software
+
+![segmentation image](segmentation.png)
 
 Draw-EM (Developing brain Region Annotation With Expectation-Maximization) is a package of [MIRTK](https://github.com/BioMedIA/MIRTK) developed by Antonios Makropoulos and the [BioMedIA](https://biomedia.doc.ic.ac.uk/) research group. 
-It provides a collection of command-line tools as well as pipelines for the segmentation of developing brain MR images.
+It provides a collection of command-line tools and pipelines for the segmentation of developing brain MR images.
+
+Draw-EM is used as part of the [dHCP structural pipeline](https://github.com/BioMedIA/dhcp-structural-pipeline) for the structural analysis (segmentation and surface extraction) of the neonatal brain.
+
+
+## Dependencies
+### FSL
 
+The segmentation pipeline uses
+[FSL](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FSL). 
+See the [installation instructions](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FslInstallation) for FSL.
 
-Installation
-------------
+
+## Installation
 
 Draw-EM is part of MIRTK. 
-In order to compile it as part of MIRTK you need to do the following steps:
-- download (clone) Draw-EM inside the Packages folder of your MIRTK directory
-- enable compile of the package by setting the CMake flag "MODULE_DrawEM" of MIRTK to "ON" (using cmake or ccmake)
+In order to compile it as part of MIRTK you need to:
+- enable compilation of the package by setting the CMake flag "MODULE_DrawEM" of MIRTK to "ON" (using cmake or ccmake)
 - build MIRTK
 
 See the [installation instructions](https://mirtk.github.io/install.html) 
 for a step-by-step guide on how to install MIRTK.
 
-The segmentation pipeline further requires the following:
-- [FSL](http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/) installed
-- The atlases required by Draw-EM need to be downloaded from [here](https://www.doc.ic.ac.uk/~am411/atlases-DrawEM.html) and extracted inside the Draw-EM directory.
-- The N4 bias field correction from ITK is included in the ThirdParty/ITK folder. If the executable does not work, you will need to compile ITK and replace the ThirdParty/ITK/N4 binary with the N4BiasFieldCorrectionImageFilter binary
-
-
-Run
----
+## Running the pipeline
 
-The segmentation pipeline can be run with the following script:
+The segmentation pipeline can be run as follows:
 
-pipelines/neonatal-pipeline-v1.1.sh 
+mirtk neonatal-segmentation <subject_T2> <age_at_scan>
 
-The script requires the T2 image and the age at scan of the subject to be segmented (as first and second argument respectively).
-Run the script without arguments for a detailed list of options.
+```
+Arguments:
+  <subject_T2>                  Nifti Image: The T2 image of the subject to be segmented.
+  <age_at_scan>                 Integer: Subject age in weeks. This is used to select the appropriate template for the initial registration. 
+			        					If the age is <28w or >44w, it will be set to 28w or 44w respectively.
+Options:
+  -d / -data-dir  <directory>   The directory used to run the script and output the files. 
+  -c / -cleanup  <0/1>          Whether cleanup of temporary files is required (default: 1)
+  -p / -save-posteriors  <0/1>  Whether the structures' posteriors are required (default: 0)
+  -t / -threads  <number>       Number of threads (CPU cores) allowed for the registration to run in parallel (default: 1)
+  -v / -verbose  <0/1>          Whether the script progress is reported (default: 1)
+  -h / -help / --help           Print usage.
+```
 
 
-License
--------
+## License
 
 Draw-EM is distributed under the terms of the Apache License Version 2.
 See the accompanying [license file](LICENSE.txt) for details. The license enables usage of
 Draw-EM in both commercial and non-commercial applications, without restrictions on the
 licensing applied to the combined work.
 
-Draw-EM uses third-party software, namely the "ITK: The Insight Toolkit for Segmentation and Registration".
-ITK is distributed under the Apache License Version 2.
-Specifically, the N4 bias field correction by Tustison et al. is included (http://www.insight-journal.org/browse/publication/640).
-The covered file (N4) and license (LICENSE) can be found in ThirdParty/ITK.
+## Releases 
+- v1.2: dHCP segmentation pipeline, method improvements described in [2]: multi-channel registration, modelling of hyper and hypo-intensities.
+- v1.1: initial code release, method described in [1].
 
 
-Citation and acknowledgements
------------------------------
+## Citation and acknowledgements
 
 In case you found Draw-EM useful please give appropriate credit to the software.
 
-Publication:
+Publications:
 
-A. Makropoulos et al. Automatic whole brain MRI segmentation of the developing neonatal brain, IEEE TMI, 2014
+1. A. Makropoulos et al. *"Automatic whole brain MRI segmentation of the developing neonatal brain"*, IEEE TMI, 2014
+2. A. Makropoulos, E. C. Robinson et al. *"The Developing Human Connectome Project: a Minimal Processing Pipeline for Neonatal Cortical Surface Reconstruction"*, NeuroImage, 2018

ThirdParty/ANTs/CMakeLists.txt

@@ -0,0 +1,33 @@
+cmake_minimum_required(VERSION 2.7)
+if(COMMAND cmake_policy)
+  cmake_policy(SET CMP0046 NEW)
+  cmake_policy(SET CMP0048 NEW)
+endif(COMMAND cmake_policy)
+
+PROJECT( N4 )
+
+IF(NOT ITK_DIR)
+  INCLUDE(External_ITK.cmake)
+  SET(External_ITK 1)
+ENDIF()
+
+# Set up ITK
+FIND_PACKAGE(ITK)
+IF(ITK_FOUND)
+  INCLUDE(${ITK_USE_FILE})
+ELSE(ITK_FOUND)
+  MESSAGE(FATAL_ERROR
+    "Cannot build without ITK.  Please set ITK_DIR.")
+ENDIF(ITK_FOUND)
+
+INCLUDE_DIRECTORIES(${ITK_INCLUDE_DIRS})
+
+SET(SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/antsCommandLineParser" "${CMAKE_CURRENT_SOURCE_DIR}/antsCommandLineOption" )
+
+ADD_EXECUTABLE( N4 N4.cxx ${SOURCES} )
+TARGET_LINK_LIBRARIES(N4 ${ITK_LIBRARIES})
+set_target_properties(N4 PROPERTIES RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/${MIRTK_TOOLS_DIR}")
+
+IF(External_ITK)
+  ADD_DEPENDENCIES(N4 ITK)
+ENDIF()

ThirdParty/ANTs/External_ITK.cmake

@@ -0,0 +1,18 @@
+cmake_minimum_required(VERSION 2.7)
+
+include(${CMAKE_ROOT}/Modules/ExternalProject.cmake)
+
+ExternalProject_Add(
+  ITK
+  GIT_REPOSITORY "https://github.com/InsightSoftwareConsortium/ITK.git"
+  SOURCE_DIR "${CMAKE_SOURCE_DIR}/ThirdParty/ITK"
+  CMAKE_ARGS -DBUILD_EXAMPLES=OFF -DBUILD_SHARED_LIBS=ON -DBUILD_TESTING=OFF -DCMAKE_INSTALL_PREFIX=${ITK_DIR}
+  UPDATE_COMMAND ""
+  PATCH_COMMAND ""
+  INSTALL_COMMAND ""
+)
+
+ExternalProject_Get_Property(ITK SOURCE_DIR)
+ExternalProject_Get_Property(ITK BINARY_DIR)
+set(ITK_SOURCE_DIR ${SOURCE_DIR})
+set(ITK_DIR ${BINARY_DIR})

ThirdParty/ANTs/LICENSE.txt

@@ -0,0 +1,40 @@
+The file N4.cxx is based on the N4BiasFieldCorrection.cxx provided by ANTs.
+Minor modifications have been applied to allow to build N4BiasFieldCorrection as an external package without the need to build the whole ANTs package.
+Modifications are noted in the code with "modification{ ... }modification".
+
+
+------------------------------------------------------------------------------
+The following copyright applies to the files:
+antsCommandLineOption.cxx
+antsCommandLineOption.h
+antsCommandLineParser.cxx
+antsCommandLineParser.h
+N4BiasFieldCorrection.cxx
+
+
+ConsortiumOfANTS® - http://www.picsl.upenn.edu/ANTS/
+Copyright (c) 2009-2013 (updated to current year ad infinitum)
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+3. Neither the name of the consortium nor the names of its contributors
+  may be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE CONSORTIUM AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.