Package: disptools
disptoolsGenerate displacement fields with known volume changesThis library provides utilities to generate and manipulate displacement fields with known volume changes. It implements three search-based algorithms for the generation of deformation fields, along with a small collection of utility functions, and provides optional GPU acceleration through a CUDA implementation.The three algorithms implemented are referred as:gradient: a gradient descent method (default).greedy: a greedy search method proposed in[1].matching: a volume matching method proposed in[2]and[3]. The implementation comes from thePREDICT atrophysim tool.The library is built on top of SimpleITK, in order to provide a simple yet powerful set of functionalities for image analysis. Images stored as numpy arrays can be easily converted from and toSimpleITKandITKimage objects.DocumentationThe complete documentation for this package is available onhttps://martinopilia.com/disptools.Quick exampleimportSimpleITKassitkimportdisptools.displacementsasdspimportdisptools.drawingasdrw# Create an example Jacobian map# A spherical ROI with a Jacobian of 1.1 (expansion)jacobian=drw.create_sphere(10,40,fg_val=1.1,bg_val=1.0)# Create a binary mask for the ROImask=drw.create_sphere(10,40)>0# Generate the displacementdisplacement=dsp.displacement(jacobian,mask=mask)# Check the correctness of the result within the ROIerror=jacobian-dsp.jacobian(displacement)error=sitk.Mask(error,mask)A 3D rendering of the resulting displacement field withParaView, and a visualisation of the the error on the Jacobian within the ROI:ArchitectureThe project is structured in three layers:a pure standardC99library (whose headers are insrc/headers), with no external dependencies, implementing the core algorithms for the generation of deformation fields. It is a standalone library that can be directly included in a C or C++ project. It is paired with an optionalCUDAlibrary, whose headers are incuda/headers, that depends onsrc/headersand provides a GPGPU implementation of the key routines.aPython C extensionpackage_disptools(whose source is in the filepython_c_extension/_disptools.c), providing a bare Python wrapper to the aforementioned library, using theNumPy C APIto pass arrays. This can be directly included in a Python project with no dependencies other than NumPy.a Python package (disptools), that wraps the_disptoolspackage providing file IO (through SimpleITK) and implementing high-level features (such as the multi-resolution framework) and auxiliary utilities and functions.disptools.displacements: module providing the main functions for the generation and manipulation of displacement fields.disptools.drawing: collection of utilities to create test images.disptools.io: collection of utilities to read and write to file.disptools.measure: collection of utilities to measure some image features.disptools.simulatrophy: routines to interface with theSimul@atrophytool.disptools.predict: routines to interface with thePREDICTtool.InstallThis package is available onPyPIboth as source distribution and as a Windows pre-compiled binary wheel. You can install it withpip:python3-mpipinstalldisptoolsBuild from sourceRequirementsThe library is a cross-platform Python 3.5+ package, with a compiled C extension. The Python dependencies are:numpy(pypi package)scipy(pypi package)SimpleITK(pypi package)Build dependencies are a standard C compiler (tested with gcc 8.2 on Linux, mingw-w64 7.2 and MSVC 19 on Windows 10),CMake, thenumpyand thesetuptoolspackages.scikit-buildmay be required to build the other Python dependencies.Some optional dependencies are required only for a limited set of features, and the package should build and run without them:itk(pypi package): fordisptools.drawing.sitk_to_itkvtk(pypi package): fordisptools.io.write_vtk_pointsply(pypi package): fordisptools.io.read_elastix_parametersscikit-image(pypi package): fordisptools.drawing.extract_slice, and to run the unit testsBuild optionsThe following build flags are recognised bysetup.py:--opt: enable non-portable optimisations.--debug: disable optimisations, compile with debug symbols.--cuda: enable CUDA support.Additional flags starting with-Dare also accepted and passed directly toCMake.Windows (Visual Studio) and LinuxInstall the dependencies with your favourite package manager. For example, withpip:python3-mpipinstallscikit-buildnumpyscipySimpleITKThe package provides asetuptoolsbased install script. To install the library, run from the project root folderpython3setup.pyinstallwhich should build the C extension and install the Python package.Windows (MinGW)First, be sure thatmingw, CMake and Python are installed and their executablesare in your PATH.Ensure thatgccis working correctly:> gcc --version
gcc (x86_64-posix-seh-rev1, Built by MinGW-W64 project) 7.2.0
Copyright (C) 2017 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.Ensure thatdistutilscorrectly recognises your version of Visual Studio (even when usingmingw). Open the fileC:\Users\yourname\AppData\Local\Programs\Python\Python3x\Lib\distutils\cygwinccompiler.py(the exact location may vary according to your setup) and check that your version of Visual Studio is present in the functionget_msvcr(); if not, adjust it according to the following:defget_msvcr():"""Include the appropriate MSVC runtime library if Python was builtwith MSVC 7.0 or later."""msc_pos=sys.version.find('MSC v.')ifmsc_pos!=-1:msc_ver=sys.version[msc_pos+6:msc_pos+10]ifmsc_ver=='1300':# MSVC 7.0return['msvcr70']elifmsc_ver=='1310':# MSVC 7.1return['msvcr71']elifmsc_ver=='1400':# VS2005 / MSVC 8.0return['msvcr80']elifmsc_ver=='1500':# VS2008 / MSVC 9.0return['msvcr90']elifmsc_ver=='1600':# VS2010 / MSVC 10.0return['msvcr100']elifmsc_ver=='1700':# Visual Studio 2012 / Visual C++ 11.0return['msvcr110']elifmsc_ver=='1800':# Visual Studio 2013 / Visual C++ 12.0return['msvcr120']elifmsc_ver=='1900':# Visual Studio 2015 / Visual C++ 14.0# "msvcr140.dll no longer exists" http://blogs.msdn.com/b/vcblog/archive/2014/06/03/visual-studio-14-ctp.aspxreturn['vcruntime140']else:raiseValueError("Unknown MS Compiler version%s"%msc_ver)Ensure that the libraryvcruntime140.dllis present in your library path. Otherwise, download it and place it inC:\Users\yourname\AppData\Local\Programs\Python\Python3x\libs(the exact path may vary according to your setup).Install the dependencies:> python -m pip install scikit-build numpy scipy SimpleITKClone the sources of this package withgit, or download and extract them as aziparchive. Move to the root folder of the sources (C:\Users\yourname\disptoolsin this example), specify the right compiler, and launch the setup script to build and install the package.> cd C:\Users\yourname\disptools
> python setup.py setopt --command=build --option=compiler --set-value=mingw32
> python setup.py installReferences[1] van Eede, M. C., Scholz, J., Chakravarty, M. M., Henkelman, R. M., and Lerch, J. P.Mapping registration sensitivity in MR mouse brain images.Neuroimage 82 (2013), 226–236.[2] Karaçali, B., and Davatzikos, C.Estimating topology preserving and smooth displacement fields.IEEE Transactions on Medical Imaging 23, 7 (2004), 868–880.[3] Karaçali, B., and Davatzikos, C.Simulation of tissue atrophy using a topology preserving transformation model.IEEE transactions on medical imaging 25, 5 (2006), 649–652.LicenseThe software is distributed under the MIT license.