..
  
  Web:   https://www.nitrc.org/projects/dramms/
         https://www.cbica.upenn.edu/sbia/
  Email: yangming.ou@mgh.harvard.edu
         sbia-software at uphs.upenn.edu
  
  Copyright (c) 2011-2013 University of Pennsylvania. All rights reserved.
                2014-2016 Massachusetts General Hospital. All rights reserved.
		2016-     Boston Childrens Hospital. All rights reserved.
  See http://www.cbica.upenn.edu/sbia/software/license.html or COPYING file.
  See https://www.nitrc.org/projects/dramms.


.. This file is formatted using reStructuredText (reST) and included by doc/changelog.rst !


Changes
=======


.. _v1.6.0:

Release 1.6.0 (TBA)
-------------------

- To enable probabilistic input for RAVENS calculation.
- To extend DRAMMS to multi-channel image registration.
- To provide tools for conversion of DRAMMS deformations to other common formats.

.. _v1.5.1:

Release 1.5.1 (Sept, 2018)
------------------
- Added Correlation Ratio as a new similarity metric on attributes.
- Modified Normalized Correlation Coefficient as a similarity metric on attributes for multi-modal registration.
- modified the calculatepenalty() function to be generally applicable to floating format, scientific format and hex format.

.. _v1.4.4:

Release 1.4.4 (Sept, 2016)
--------------------------------
- now can correctly analysis dynamicly linked files. Versions before 1.4.4 failed.
- added sinc interpolation beyond the linear and nearest neighbor interpolations.
- modified rules for running flirt-based linear registration. It was to be to run 2D_nosearch when the target image has thick slices, now to run 2D_nosearch also when the source image has thick slices.
- modified the selection rules to select the optimal linear registration among multiple flirt results. Used to be looking at similarity only within the overlap of two images' FOV, now also look at the similarity in the full image. The new criterion: prefer high similarity in the intersection of FOVs as long as the similarity in the whole image is not too low.


.. _v1.4.3:

Release 1.4.3 (Nov, 2015)
--------------------------------

- Added pointers to the newly availble 4D-dramms (for longitudinal analysis) and pop-dramms (for unbiased atlas construction).
- Updated the url of niftiCLib-2.0.0 from cbica location (which now has a problem installing in some linux systems) http://www.cbica.upenn.edu/sbia/software/distributions/nifticlib-2.0.0.tar.gz to http://pkgs.fedoraproject.org/repo/pkgs/nifticlib/nifticlib-2.0.0.tar.gz/425a711f8f92fb1e1f088cbc55bea53a/nifticlib-2.0.0.tar.gz.
- Use BASIS 3.2.0 instead of 2.1.4. BASIS 3.2.0 adapts well with cmake 3.0 or above. I downloaded BASIS 3.2.0 from Andreas Schuh's github site (https://github.com/schuhschuh/cmake-basis/archive/v3.2.0.tar.gz) and copied the file to http://www.nmr.mgh.harvard.edu/~you2/cmake-basis-3.2.0.tar.gz, updated the url and MD5 in build/CMakeList.txt (I got the MD5 from windows by the command in cmd.exe "CertUtil -hashfile cmake-basis-3.2.0.tar.gz MD5"). This was done on Nov 12 2015.
- Changed affine and rigid registration, to hirarchically search in different ranges and by different similarity measures, more adaptive to the input images, and adaptive to the affine/rigid needs.
- Added an option (the '-I' option) in CalculateImageSimilarity.cxx to calcualte image similarity only within the intersection of the two images'foreground areas, rather than in the whole image (the default setting).
- Now able to proceed even if some flirt-based affine registation jobs fail (very rare cases, but we did notice some flirt failures).
- Modified the FindAdaptiveThreshold() function in the utilities.cxx program, more conservative thresholding for background noise removal in the pre-processing steps. Improve registrations that involve OASIS skull-stripped images while not affecting many other registration tasks.
- Added a new function to allow rigid registration only (-a 4), and rigid followed by deformable registration (-a 3). Previously we only allowed affine only (-a 2) or affine followed by deformable (-a 1), or no affine/rigid and only deformable (-a 0).
- Modified the format of 2D deformation. It used to have dim[5]=2 to specify the two displacement components. Now we treat it as a special 3D deformation with dim[5]=3, dim[3]=1 and z displacement constantly 0. With this changes, we can apply all the deformation tools to 2D deformations.


.. _v1.4.2:

Release 1.4.2 (October, 6, 2014)
--------------------------------

- Improved the error message for flirt being not detected in the system environment.
- Updated the publication list.
- Relaxed the requirement for identical voxel size between the source image (-S) and the label image (-L). Now these two images are considered to have identical voxel size as long as they differ less than 0.5%.
- Modified the CalculateJacobian.cxx code, so that it considers physical space other than image space. This correction is important for voxel based morphometry. As a consequency, the usage of dramms-jacobian has been slightly changed. It now requires the input of the source and target images, to convert the dramms deformation (which is in image space) to physical space before jacobian calculation.
- Corrected the exit signal for running affine registration only in dramms. When the "-a 2" option is used, dramms will only run and output the affine registration, and then exit with an 'exit 0' signal, not the 'exit 1' signal as before (Thanks to Lilla Zollei for reporting this issue).
- Increast the robustness wrt raw images --- utilize the imaginary parts of Gabor filter response as a way to detect whether there is a large amount of the background noise, and if there is, reply on real parts of the Gabor response, which is less affected by the background noise.
- Improved the condition and content of the error message for the memory shortage problem.
- Modified the 2D dramms registration weighting mechanism. Now the regularization weight ("-g" option) also applies to 2D dramms registration.
- Fixed the errors in the boundary conditions when inverting a deformation field. Now the "dramms-defop -i" deformation inverter is more robust (Thanks to Michael for reporting this problem).
- Fixed the problem in 2D-to-2D registration. The program essentially treats a 2D image as a 3D image with dim[3]=1 and pixdim[3]=1.0. Now the program enforces dim[3]=1 if it is <1, and enforces pixdim[3]=1.0 if it is 0. This way, it can better handle 2D images with varying dim[3] and pixdim[3] values.
- Fixed a bug in the generation of feature list for images. There shouldn't be vertical feature components if the downsampled 3D image is actually a 2D image (#zslices=1).
- Added a function to accept user-specified initial affine matrix.
- Added an option to accept user-specified mask also from the source image space.
- Corrected the error when saving mutual-saliency maps within the foreground mask in the target space.
- Added a clause to avoid POSIXLY_CORRECT from changing the default bash environment (thanks for Keith Bartley to report this issue).

.. _v1.4.1:

Release 1.4.1 (April, 4, 2014)
------------------------------

- Fixed a bug in imageio.cxx for when used with "-c 2" option (save mutual-saliency map). When images and masks are internally padded, we crop the images and masks to the original size when we save them. This cropping was done properly for images but not properly for mask, causing an error, which has now been fixed.
- Added an option (-a 2), through which users can choose to do flirt-based affine registration only in the dramms pipeline.
- Added warning message that if Deform3D (step 6 in the dramms pipeline) fails, it is usually because of the shortage of memeory, and users should prepare 12G memory (at rare cases 14G).
- Re-implemented the inverse of a deformation, based on Chen et al, 2007, Med Phys, "A Simple Fixed-Point Approach to Invert a Deformation Field".
- Added deformation operations (add, multiple with a scaler), which are used in the implementation of unbiased atlas construction.
- Modified how the image threshold is computed, allowing the maximum possible threshold relative to the intensity range to be adaptive to histogram distribution.
- Modified the default image threshold, which is adaptive to image histogram, which is set to be the maximum intensity number below 12, and by thresholding at which there will be no more than 40% of the image voxels being zeored out.
- Modified histogram matching part -- the program automatically decides to keep image before or after histogram matching based on image similarity. This is especially important for raw images.
- Uses basis 2.1.4 instead of 2.1.2.
- Improved the checking of image size and voxel size; dramms will report error for images with negative voxel size (thanks for Nikos Koutsouleris and Carlos Cabral for bringing this up).
- Modified CardiacLongitudinal.html webpage to include an additional example of how to use dramms registration to quantify cardiac motion.
- Modified how the mask is generated, to be more robust towards background noise in raw images. Therefore this v1.4.1 should work better for raw brain MR images.
- Modified the checking of voxel and image sizes between two images, to avoid unintended errors when registering 2D images. Therefore this v1.4.1 should work better/correctly if two input 2D images have arbitrary pixdim[3] (z dimension).
- Corrected a bug in determining the actual intensity range for byte input images, to avoid possible errors when registering binary images. Therefore this v1.4.1 will no longer fail to directly register binary mask images.
- Reduced computational burden by half for affine registration in most cases. The program will try 2.5D affine only for very large slice thickness compared to in-plane voxel size.
- Also, to inrease the robustness of flirt-base affine registration, added a qualiy assurance step --- we begin by search range [-180, 180], if the resultant affine results do not have cc*mi greater than 0.1 with the targe image, we search again with a narrower search range [-45, 45] to reduce the chance of being trapped at local minima.
- Modified interpolation in areas close to image bounding box, to avoid vanish of ending slices after registration especially when the number of slices is small.
- Added new functions for transformation operations: a) to add two transformations; b) to multiply or divide an input transformation.
- Updated website, added an example of using DRAMMS to track cardiac motion in the tutorial page.


.. _v1.4.0:

Release 1.4.0 (Sept, 10, 2013)
------------------------------

- Now dramms correctly supports cost-function-masking approach. That is, users can input a binary mask to "inform" dramms only to register within the foreground of the input mask.
- Added support for warping a 4D image (time-series) by a 3D deformation field, which is often used in fMRI time-series image analysis.
- Slightly changed the two functions added in Release 1.3.1. for handling the raw images. change 1: the default threshold in the adpative thresholding has been increased; change 2: the selection criteria for features has been loosened to remove more imaginary feature images that possibly contain background noise.
- Website updated (FAQ page, manual page, publication page).


.. _v1.3.1:

Release 1.3.1 (June 18, 2013)
-----------------------------

- Added ``#include <unistd.h>`` in every program to comply with more strict requirement in latest gcc version 4.7.
- Improved ``ConvertImage`` to scale intensities at once instead of in two steps to minimize quantization error.
- Fixed downsampling of images in ``Deform3D`` to obtain identical downsampled images as those used for Gabor feature computation.
- No longer reproducing the exact results of :ref:`v0.7.0` because of the second and third changes in this version.
- Updated the website.
- Added one option (-M) in the dramms cript to allow users to force histogram matching.
- Added the support of one more similarity metric (correlation coefficient), mainly for multi-modal registration.
- Better handling of raw images with background noise, by two additional functions: 1) an adaptive thresholding scheme in ConvertImage; 2) an automatic selection of imaginary and real feature components (imaginary feature usually keep noise, whenever it happens, we only keep real features which do not carry noise information).


.. _v1.2.1:

Release 1.2.1 (Nov 2, 2012)
---------------------------

- Removed FastPD sources from DRAMMS. Download FastPD from `here <http://www.csd.uoc.gr/~komod/FastPD/>`__ instead and patch it during the bundle build.
- Updated bundle build to use `BASIS 2.1.2`_.
- Further modified license section on download page.


.. _v1.2.0:

Release 1.2.0 (Oct 30, 2012)
----------------------------

- Clarified copyright, license, and patent information of FastPD.
- Fixed support for signed integer datatype of input NIfTI-1 images.
- Fixed errors in calculating RAVENS maps to make sure maps are always in template space.
- Restructured manual page of documentation.


.. _v1.1.0:

Release 1.1.0 (Sep 21, 2012)
----------------------------

- Fixed ``dramms-warp`` when used with ``-t`` option to specify target space.
- Fixed parsing of ``-v`` option in ``dramms`` script.
- Added ``-I`` option to ``dramms``, allowing user to specify directory intermediate results.
- Modified ``dramms-combine`` to make composition of affine and deformable transformation more general.
- Re-structured home page and updated to `BASIS 2.1`_ (new web page layout and bug fixes).


.. _v1.0.0:

Release 1.0.0 (Aug 24, 2012)
----------------------------

- First public release of DRAMMS software and website, including home page and supporting documentation.
- Completely revised implementation starting with :ref:`v0.4.0`. Andreas offered tremendous help since Oct 2011.
- This revised implementation reproduces the results of :ref:`v0.7.0`.
- Added full support for NIfTI-1 and ANALYZE 7.5 using NiftiCLib_.
- Based DRAMMS on BASIS_, a meta project developed at SBIA to standardize software development.


.. raw:: html

    <br />


.. _v0.7.0:

Pre-Release 0.7.0 (Aug 17, 2012)
--------------------------------

- Better memory management: 1) reduced image padding margins to balance memory use and accuracy; 2) added option ``-u`` for users to control memory usages (4 levels); 3) automatically reduce memory use when users choose a smoother deformation (g>=0.5).
- Better FLIRT affine registrations within ``dramms``: 1) on by default (was off before); 2) affine is much more robust (can work in difficult cardiac, prostate cases), because the program will automatically try four different set of flirt parameters for each pair of images and automatically choose a best set with highest similarity (CC*MI); 3) force affine/flirt output to be in NIFTI_PAIR format so that this part of ``dramms`` works in different systems and different FSL default settings.
- Better file/folder management: 1) random files are now all in temp directories; 2) if multiple dramms jobs are running on a same node, intermediate files will no longer overwrite each other as they are now saved into unique directories; 3) the program catches interruption and exit signals and automatically removes all intermediate files. 
- Fixed bugs in ``CalculateJacobian``, which now works for 2D deformations.
- Re-set default regularization to 0.2 (was 0.15).
- Fixed bugs in ``dramms``, which now recognizes different orientations in headers.


.. _v0.6.0:

Pre-Release 0.6.0 (May 26, 2012)
--------------------------------

- Corrected smoothing in the boundary.
- Corrected convolution errors around the image bounding box and grouped them into libraries.
- Corrected the output and usage for mutual-saliency, now user can either not to use it, use it but not to save, and use and save it.
- Corrected header orientation issue, especially when x-y plane is axial (like in MICCAI 2012 multi-atlas challenge).
- Corrected padding/cropping problem in mutual-saliency map.


.. _v0.5.0:

Pre-Release 0.5.0 (May 16, 2012)
--------------------------------

- Separated x-y search range and ``distBetweenControlPoints``, good to handle elongated images with larger deformation in only one dimension.
- Changed ``ScaleIntensity`` to better handle effective intensity range and the long-tail phenomenon in histogram (better for mouse images).
- Changed highest Gabor frequency in the finest image resolution (will affect images larger than 256*256*z).
- Added internal padding if necessary (good for images where foreground is too close to the boundary as in ADNI_).
- Added function to accept initial deformation (used for mouse geodesic registration)
- Added function to accept initial mask.


.. _v0.4.0:

Pre-Release 0.4.0 (May 16, 2012)
--------------------------------

- Fixed bugs in registering two 2D images.
- Fixed bugs in Gabor extraction, removing possible segmentation fault in rare cases when extracting Gabor features along x axis.
- Fixed a bug in ``CalculateJacobian``, no segmentation fault now for 2D images (out of image box mapping has been excluded).
- Searches the effective intensity range more effectively when scaling intensities for better image contrast, removing ad hoc parameters that might cause problems when dealing with raw brain images with background noise.
- Determines whether to match histogram with more caution, which is especially more helpful when dealing with raw brain images with background noise.
- Expands flirt's search range of rotation angles from default [-90 90] to [-180 180] to cope with large orientation difference in images, or possibly caused just by converting nifti to analyze in intermediate process.
- Fixed interpolation errors in rare cases such as in Guray's flair-to-flair lesion image registration, when a voxel is mapped outside the bounding box of image.


.. _v0.3.0:

Pre-Release 0.3.0 (Jan 20, 2012)
--------------------------------

- Slight change in deformation mechanism, when to have two grid levels, how aggressive the default is, which parameter to use for extracting Gabor features.


.. _v0.2.0:

Pre-Release 0.2.0 (Dec 21, 2011)
--------------------------------

- Changed default parameter settings (number of grid levels, maximum displacement in each grid level) to i) capture large deformations as usually observed in raw brain images with skull; and ii) preserve accuracies in capturing small deformations like in skull-stripped images.


.. _v0.1.0:

Pre-Release 0.1.0 (Dec 2, 2011)
-------------------------------

- Fixed a bug in ``CalculateRAVENS`` program, to make sure RAVENS values are always non-negative.
- Fixed bugs in generating image headers of output images. Registered images should always reside in template/target image space.
- Slightly changed deformation parameters (maximum displacement, default regularization, number of control point grid levels) to increase registration accuracy in default settings.
- Added functions in main ``DAMMS3D`` script for calculating Jacobian map, RAVENS map, and warping images. 


.. _v0.0.0:

Pre-Release 0.0.0 (Jan, 2009 -- Nov 4, 2011)
---------------------------------------------

- In Jan. 2009, Yangming started to work on integrating all parts of DRAMMS code into a complete, one-line command tool, which takes two input images and output the deformed image.
- In summer 2009, DRAMMS migrated to `FastPD`_ optimizer under Aris' help. This significantly speeds up the software.
- In Sep 2009, a first documentation -- `DRAMMS wiki page (SBIA internal only) <https://sbia-wiki.uphs.upenn.edu/wiki/index.php/DRAMMS>`_ -- was set up internally and open to all SBIA testers.
- From Sept 2009 to summer 2011, we distributed SVN-ed DRAMMS to SBIA internal :ref:`testers <SoftwareTesters>` and get precious feedback/suggestions. 
- At the same time (Sep 2009 -- summer 2011), Yangming was optimizing DRAMMS parameters in large-scale brain, cardiac and breast registration tasks involving public dataset and in comparisons with 10+ public and state-of-the-art registration software packages.
- During Sept 2009 and Nov 2011, incorporated many suggestions and feedback from internal testers.
- In Nov 2011, we have a first version of DRAMMS relatively stable for further internal tests.





.. _ADNI: http://adni.loni.ucla.edu/
.. _BASIS: http://www.cbica.upenn.edu/sbia/software/basis/
.. _BASIS 2.1: http://www.cbica.upenn.edu/sbia/software/basis/changelog.html#v2.1.0
.. _BASIS 2.1.2: http://www.cbica.upenn.edu/sbia/software/basis/changelog.html#v2.1.2
.. _NiftiCLib: http://niftilib.sourceforge.net/
.. _FastPD: http://www.csd.uoc.gr/~komod/FastPD/
