README.md 3.59 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
# 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
```