Partial bugfix for TIRLFile object ID redundancy problem.

LICENSE.txt

+#   _______   _____   _____    _
+#  |__   __| |_   _| |  __ \  | |
+#     | |      | |   | |__) | | |
+#     | |      | |   |  _  /  | |
+#     | |     _| |_  | | \ \  | |____
+#     |_|    |_____| |_|  \_\ |______|
+#
+# Tensor Image Registration Library
+# Author: Istvan N. Huszar
+# Copyright (C) 2018-2020 University of Oxford
+# Part of the FMRIB Software Library (FSL)
+
+
+                               FSL Licence
+
+
+FMRIB Software Library, Release 6.0.4 (c) 2020, The University of Oxford
+(the "Software")
+
+The Software remains the property of the University of Oxford ("the
+University").
+
+The Software is distributed "AS IS" under this Licence solely for
+non-commercial use in the hope that it will be useful, but in order
+that the University as a charitable foundation protects its assets for
+the benefit of its educational and research purposes, the University
+makes clear that no condition is made or to be implied, nor is any
+warranty given or to be implied, as to the accuracy of the Software,
+or that it will be suitable for any particular purpose or for use
+under any specific conditions. Furthermore, the University disclaims
+all responsibility for the use which is made of the Software. It
+further disclaims any liability for the outcomes arising from using
+the Software.
+
+The Licensee agrees to indemnify the University and hold the
+University harmless from and against any and all claims, damages and
+liabilities asserted by third parties (including claims for
+negligence) which arise directly or indirectly from the use of the
+Software or the sale of any products based on the Software.
+
+No part of the Software may be reproduced, modified, transmitted or
+transferred in any form or by any means, electronic or mechanical,
+without the express permission of the University. The permission of
+the University is not required if the said reproduction, modification,
+transmission or transference is done without financial return, the
+conditions of this Licence are imposed upon the receiver of the
+product, and all original and amended source code is included in any
+transmitted product. You may be held legally responsible for any
+copyright infringement that is caused or encouraged by your failure to
+abide by these terms and conditions.
+
+You are not permitted under this Licence to use this Software
+commercially. Use for which any financial return is received shall be
+defined as commercial use, and includes (1) integration of all or part
+of the source code or the Software into a product for sale or license
+by or on behalf of Licensee to third parties or (2) use of the
+Software or any derivative of it for research with the final aim of
+developing software products for sale or license to a third party or
+(3) use of the Software or any derivative of it for research with the
+final aim of developing non-software products for sale or license to a
+third party, or (4) use of the Software to provide any service to an
+external organisation for which payment is received. If you are
+interested in using the Software commercially, please contact Oxford
+University Innovation ("OUI"), the technology transfer company of the
+University, to negotiate a licence. Contact details are:
+Innovation@innovation.ox.ac.uk quoting reference BS/9564.

MANIFEST.in

+recursive-include share *
+recursive-include tests *.py
\ No newline at end of file

README.md

+# tirl
+Tensor Image Registration Library
+
+
+If you are installing TIRL from source, you may create a separate
+enviroment for your installation using the provided tirlenv.yml environment
+descriptor file.
+
+## FSL Installation
+
+TIRL may be already installed on your system as part of FSL. To use this
+installation, activate the ```fslpython``` conda environment:
+
+```shell script
+source $FSLDIR/fslpython/bin/activate fslpython
+```
+
+The TIRL executable should now be accessible by typing ```tirl``` in your
+terminal:
+
+```shell script
+tirl
+```
+
+## Installation from source
+
+If you would like to use a more recent version of TIRL than what is installed
+with FSL, you can install the library from source. It is recommended that you
+create a separate conda environment for this purpose, as outlined below.
+
+1. Download the TIRL source code.
+
+```shell script
+mkdir -p ~/Applications/
+cd ~/Applications
+git clone https://git.fmrib.ox.ac.uk/ihuszar/tirl.git
+cd tirl
+```
+
+2. Create virtual environment for registration projects with TIRL.
+
+```shell script
+conda env create -n tirlenv -f tirlenv.yml
+```
+
+3. Activate the new tirlenv environment.
+
+```shell script
+conda activate tirlenv
+```
+
+4. Install TIRL from its source directory.
+
+```shell script
+python setup.py install
+```
+
+5. On some machines, the installer may not find the openBLAS headers in the conda environment automatically, and the installer will raise an error that "lapacke.h" was not found. If this happens to you, configure this environment variable, that will allow the gcc compiler to find the required header files. Type the following in your terminal while you are within tirlenv. You must deactivate and reactivate the environment after this step.
+
+```shell script
+conda env config vars set C_INCLUDE_PATH=${CONDA_PREFIX}/include:${C_INCLUDE_PATH}
+```
+
+If the variable is set, follow step 4 to install TIRL.
+
+## Configuration
+
+Note: to configure TIRL, you must be within the Python environment where you
+installed TIRL ('tirlenv' in the above example).
+
+To configure TIRL for your system, type ```tirl config``` in your terminal
+window. This will allow you to edit the configuration parameters using vim.
+
+To use another editor, e.g. nano, type ```tirl config nano```. Other options
+might include subl (Sublime Text), atom (Atom), or emacs (Emacs), depending on
+what is available on your system.
+
+Before you start using TIRL, you must make sure that the **temporary working
+directory (TWD)** is set correctly. You should have write access to this
+folder, and ideally it should be on a fast-access storage device such as an
+NVME SSD. TIRL will use this folder to deposit large files to avoid overloading
+the system memory. Files will normally disappear from this folder after a tirl
+script finishes, but if you notice that the files in this folder occupy a lot
+of disk space, you should delete them manually.
+
+## Basic test
+
+1. Open the python shell by typing ```python``` in the terminal window (make
+sure that you have previously activated the 'tirlenv' environment).
+
+2. Type the following in the interactive shell:
+
+```python
+import tirl
+img = tirl.testimg()
+img.preview()
+```
+
+### Full test ###
+
+1. Unless you used the tirlenv.yml file to create your environment, you should
+first make sure that the *coverage* library is installed in your environment:
+
+```shell script
+conda install coverage
+```
+
+2. Run the full test from the source root:
+
+```shell script
+python test.py
+```
+
+If all tests are successful, a line-by-line coverage report will be generated
+in HTML format that you can view in your browser.
+
+3. To test a single module of TIRL (e.g. chain.py), run:
+
+```shell script
+python test.py test_chain
+```

conda-recipies/build.sh

+#!/bin/bash
+
+# Copy share and test directories to the build directory
+mkdir -p ${PREFIX}/lib/python${PY_VER}/site-packages/tirl/tests
+cp -r $RECIPE_DIR/../tests ${PREFIX}/lib/python${PY_VER}/site-packages/tirl/
+mkdir -p ${PREFIX}/lib/python${PY_VER}/site-packages/tirl/share
+cp -r $RECIPE_DIR/../share ${PREFIX}/lib/python${PY_VER}/site-packages/tirl/
+
+# Install the python package to the build directory
+python setup.py install --single-version-externally-managed --record=record.txt
+
+# Replace placeholders with the appropriate licensing information
+python ${RECIPE_DIR}/replace.py ${PREFIX}
+

conda-recipies/meta.yaml

+{% set version = "2.2.1" %}
+package:
+    name: tirl
+    version: {{ version }}
+
+source:
+    path: ../
+
+requirements:
+    build:
+        - {{ compiler('cxx') }}
+
+    host:
+
+        - python
+        - cython
+        - numpy
+        - openblas
+
+    run:
+        - attrdict
+        - dask
+        - dill
+        - imagecodecs
+        - imageio
+        - joblib
+        - mayavi
+        - matplotlib
+        - nibabel
+        - nlopt
+        - numba
+        - numpy
+        - opencv
+        - openslide
+        - pillow
+        - psutil
+        - pygments
+        - python
+        - python-dateutil
+        - scikit-image
+        - scikit-learn
+        - scipy
+        - tifffile
+
+test:
+    imports:
+        - tirl
+        - tirl.fsl
+        - tirl.chain
+        - tirl.tfield
+        - tirl.timage
+        - tirl.domain
+        - tirl.point
+        - tirl.cmodules
+        - tirl.operations
+        - tirl.interpolators
+        - tirl.parameters
+        - tirl.transformations.basic
+        - tirl.transformations.linear
+        - tirl.transformations.nonlinear
+        - tirl.costs
+        - tirl.optimisation
+        - tirl.regularisers
+        - tirl.scripts
+        - tirl.tirlvision
+        - tirl.usermodules
+
+    commands:
+        - tirl home
+        - tirl version
+        - tirl info
+        - tirl module
+        - tirl histology_to_block
+        - tirl find_sites
+        - tirl block_to_slice
+        - tirl slice_to_volume
+        - tirl prepare_multi_stage3
+        - tirl combine
+        - tirl stripbg
+        - tirl extract_blocks
+        - tirl crop_centre
+        - tirl sliceview
+
+about:
+    home: https://git.fmrib.ox.ac.uk/ihuszar/tirl/
+    license: FSL
+    license_file: LICENSE.txt
+    summary: Tensor Image Registration Library
+    dev_url: https://git.fmrib.ox.ac.uk/ihuszar/tirl/

conda-recipies/post-link.sh

+if [ -e ${FSLDIR}/etc/fslconf/requestFSLpythonLink.sh ]; then
+  $FSLDIR/etc/fslconf/requestFSLpythonLink.sh tirl
+fi
+
+# Move the "share" directory if the package is installed in fslpython.
+if [ ! -z ${FSLDIR} ]; then
+  case "$PREFIX" in
+  "${FSLDIR}"*)
+    mkdir -p ${FSLDIR}/data/tirl
+    sharedir=${FSLDIR}/data/tirl/share
+    mv ${PREFIX}/lib/python*/site-packages/tirl/share ${sharedir}
+    ;;
+  *)
+    sharedir=$(echo "${PREFIX}/lib/python*/site-packages/tirl/share")
+    ;;
+  esac
+fi
+
+testsdir=$(echo "${PREFIX}/lib/python*/site-packages/tirl/tests")
+
+# Register the "share" and "tests" directory paths within TIRL
+python -c "import tirl; tirl.set_sharedir(\"${sharedir}\")"
+python -c "import tirl; tirl.set_testdir(\"${testsdir}\")"
+
+# Set the TIRLHOME environment variable
+conda env config vars set TIRLHOME="`tirl home`"

conda-recipies/pre-unlink.sh

+if [ -e ${FSLDIR}/etc/fslconf/requestFSLpythonUnlink.sh ]; then 
+    $FSLDIR/etc/fslconf/requestFSLpythonUnlink.sh tirl
+fi

conda-recipies/replace.py

+#!/usr/bin/env python
+
+import os
+import re
+import sys
+
+cpattern = r"  CCOPYRIGHT  "
+pypattern = r"# SHBASECOPYRIGHT"
+cfiles = (".cpp", ".cxx", ".c", ".py")
+pyfiles = (".py", ".pyi", ".pyx", "tirl")
+
+# Load licence text
+with open("LICENSE.txt", "r") as fp:
+    for _ in range(16):
+        fp.readline()
+    licencetext = fp.read()
+
+# Make the licence text a comment (only for py)
+pylic = "# " + licencetext.replace("\n", "\n# ")
+clic = "\n " + licencetext.replace("\n", "\n ").rstrip(" ")
+
+for root, dirs, files in os.walk(sys.argv[1]):
+    for f in files:
+        src = os.path.realpath(os.path.join(root, f))
+        if src == __file__:
+            continue
+
+        if f.endswith(pyfiles):
+            try:
+                with open(src, "r") as fp:
+                    srctext = fp.read()
+                licenced = re.sub(pypattern, pylic, srctext)
+                with open(src, "w") as fp:
+                    fp.write(licenced)
+            except:
+                continue
+
+        elif f.endswith(cfiles):
+            try:
+                with open(src, "r") as fp:
+                    srctext = fp.read()
+                licenced = re.sub(cpattern, clic, srctext)
+                with open(src, "w") as fp:
+                    fp.write(licenced)
+            except:
+                continue
+
+        else:
+            continue

requirements.txt

+attrdict
+cython
+dask
+dill
+ghalton
+imagecodecs
+imageio
+joblib
+mayavi
+matplotlib
+nibabel
+nlopt
+numba
+numpy
+opencv-python
+openslide-wrapper
+pillow
+psutil
+pygments
+python-dateutil
+scikit-image
+scikit-learn
+scipy
+tifffile
+threadpoolctl

setup.py

+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+#   _______   _____   _____    _
+#  |__   __| |_   _| |  __ \  | |
+#     | |      | |   | |__) | | |
+#     | |      | |   |  _  /  | |
+#     | |     _| |_  | | \ \  | |____
+#     |_|    |_____| |_|  \_\ |______|
+#
+# Copyright (C) 2018-2020 University of Oxford
+# Part of the FMRIB Software Library (FSL)
+# Author: Istvan N. Huszar
+
+
+# SHBASECOPYRIGHT
+
+import numpy as np
+from setuptools import setup, Extension, find_packages
+from Cython.Build import cythonize
+
+#-------------------------------- C/C++ Modules -------------------------------#
+
+# Field inversion (2D and 3D)
+fieldinversion = \
+    Extension("tirl.cmodules.finv",
+              sources=["src/tirl/cmodules/finv2d_src.c",
+                       "src/tirl/cmodules/finv3d_src.c",
+                       "src/tirl/cmodules/finv.pyx"],
+              include_dirs=[np.get_include()],
+              extra_link_args=["-lopenblas", "-lgfortran"],
+              extra_compile_args=["-std=c99"],
+              language="c")
+
+# FSLInterpolator
+# Implements the linear interpolation routine of FLIRT (FSL). This is meant to
+# be an example of a C++ extension to TIRL.
+fslinterpolator = \
+    Extension("tirl.cmodules.fslinterpolator",
+              sources=["src/tirl/cmodules/fslinterpolator_src.cpp",
+                       "src/tirl/cmodules/fslinterpolator.pyx"],
+              extra_compile_args=["-fpermissive"],
+              language="c++")
+
+cython_modules = cythonize([fieldinversion, fslinterpolator],
+    compiler_directives={'embedsignature': True, 'language_level': "3"}
+)
+
+
+#------------------------------ External Libraries ----------------------------#
+
+with open("requirements.txt", "r") as fp:
+    dependencies = [l.strip() for l in fp.readlines()]
+
+
+#-------------------------------- TIRL Installer ------------------------------#
+
+setup(name="tirl",
+      version="2.2.1",
+      description="Tensor Image Registration Library",
+      author="Istvan N. Huszar",
+      ext_modules=cython_modules,
+      install_requires=dependencies,
+      packages=find_packages("src"),
+      package_dir={"tirl": "src/tirl"},
+      scripts=["src/tirl/tirl"]
+)

share/example/config/1_histology_to_block.json

+{
+    "header": {
+        "title": "TIRL MND (Stage 1) Histology-to-block image registration routine",
+        "description": "Developed for the Oxford MND Post-Mortem Imaging Biomarkers study.",
+        "author": "Istvan N Huszar"
+    },
+    "general": {
+        "name": "histology_to_block",
+        "direction": "h2b",
+        "system": "linux",
+        "loglevel": "debug",
+        "logfile": null,
+        "paramlogfile": null,
+        "verbose": false,
+        "outputdir": "/Users/inhuszar/temp/stage1",
+        "stages": ["rotation", "rigid", "affine", "nonlinear"],
+        "warnings": false,
+	"isotropic": true
+    },
+    "histology": {
+        "file": "/Users/inhuszar/temp/1_histology/histology.tif",
+        "storage": "mem",
+        "dtype": "f4",
+        "resolution": 0.008,
+        "mask": {
+            "file": null,
+            "normalise": true,
+            "function": null,
+            "automask": {
+                "thr": 0,
+                "uthr": 1
+            }
+        },
+        "preview": false,
+        "export": true,
+        "snapshot": true
+    },
+    "block": {
+        "file": "/Users/inhuszar/temp/2_tissue_block/tissue_block.tif",
+        "storage": "mem",
+        "dtype": "f4",
+        "resolution": 0.05,
+        "mask": {
+            "file": null,
+            "normalise": true,
+            "function": "dilated_object_mask",
+            "automask": {
+                "thr": 0,
+                "uthr": 1
+            }
+        },
+        "preview": false,
+        "export": false,
+        "snapshot": false
+    },
+    "preprocessing": {
+        "histology": ["match_block_resolution", "histology_preprocessing", "pad"],
+        "block": ["block_preprocessing"]
+    },
+    "regparams": {
+        "init": {
+            "scale": {
+                "x0": 1.0,
+                "lb": 0.9,
+                "ub": 1.1
+            },
+            "rotation": {
+                "x0": 0.0,
+                "mode": "deg",
+                "lb": -180,
+                "ub": 180
+            },
+            "translation": {
+                "x0": [0.0, 0.0],
+                "lb": [-5.0, -5.0],
+                "ub": [5.0, 5.0]
+            },
+            "affine": {
+                "x0": [1.0, 0.0, 0.0, 0.0, 1.0, 0.0],
+                "lb": [0.95, -0.2, -1.0, -0.2, 0.95, -1.0],
+                "ub": [1.05, 0.2, 1.0, 0.2, 1.05, 1.0]
+            },
+            "nonlinear": {
+                "x0": 0.0,
+                "lb": null,
+                "ub": null
+            }
+        },
+        "rotsearch": {
+            "coarse": 30,
+            "scale": 0.125,
+            "visualise": false,
+            "xtol_rel": 0.01,
+            "xtol_abs": [0.001, 0.001, 0.001, 0.001],
+            "opt_step": 0.5
+        },
+        "rigid": {
+            "scaling": [16, 8, 4],
+            "smoothing": [0, 0, 0],
+            "xtol_rel": 0.01,
+            "xtol_abs": [0.001, 0.001, 0.001, 0.001],
+            "opt_step": 0.1,
+            "visualise": false
+        },
+        "affine": {
+          "scaling": [8, 4],
+            "smoothing": [0, 0],
+            "xtol_rel": 0.01,
+            "xtol_abs": [0.001, 0.001, 0.001, 0.001, 0.001, 0.001],
+            "opt_step": 0.1,
+            "visualise": false
+        },
+        "nonlinear": {
+            "scaling": [16, 8, 4],
+            "smoothing": [0, 0, 0],
+            "sigma": 1,
+            "truncate": 1.5,
+            "regweight": 0.6,
+            "maxiter": [20, 20, 20, 20, 5],
+            "xtol_abs": 0.1,
+            "xtol_rel": 0.01,
+            "visualise": false
+        }
+    }
+}