README.md 5.8 KB
Newer Older
Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
1
# SlideR :hamburger: : Slide Registration tools
Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
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

Collection of registration tools for microscopy.

Built upon the Tensor Image Registration Library: https://git.fmrib.ox.ac.uk/ihuszar/tirl

## Dependencies

You will need to download and install miniconda to manage the python environment:
https://docs.conda.io/en/latest/miniconda.html

## Installation
First clone TIRL:
```shell
git clone https://git.fmrib.ox.ac.uk/ihuszar/tirl.git
```

Create a virtual environment for SlideR:
```shell
conda env create -n slider -f tirl/tirlenv.yml
conda activate slider
```

Install TIRL:
```shell
cd tirl
python setup.py install
cd ..
```

Install SlideR:
```shell
git clone https://git.fmrib.ox.ac.uk/seanf/slider.git
pip install -e slider
```

## Usage

### Register 2D-slide to 2D-slide

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
41
42
43
You can register a 2D-slide to a 2D-slide using the `SLIDE` subcommand of the `slider_app.py` app.  

> Note that the `moving-resolution` and `fixed-resolution` is the resolution of the input images.  The resolution at which the registration is calculated is dictated by the config file (`slider/resources/slide.yaml`)
Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
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

```shell
>> slider_app.py SLIDE -h

usage: slider_app.py SLIDE [-h] [--out <dir>] [--config <config.json>]
                           <moving> <moving-resolution> <fixed> <fixed-resolution>

Register 2D slide to 2D slide

positional arguments:
  <moving>                Moving slide image
  <moving-resolution>     Moving image resolution (mm)
  <fixed>                 Fixed slide image
  <fixed-resolution>      Fixed image resolution (mm)

optional arguments:
  -h, --help              show this help message and exit
  --out <dir>             Output directory
  --config <config.json>  configuration file
```

For example:

```shell
slider_app.py SLIDE \
    mr247MBP_c24_s20a.jp2 0.0004 \
    mr247NeuN_c01_s19n.jp2 0.0004 \
    --out=mr247_mbp_to_neun.reg
```

### Apply transform to image

Once registered, you can apply the transform to the native image using the `APPLYXFM` subcommand of the `slider_app.py` app.

```shell
>> slider_app.py APPLYXFM -h
80
81

usage: slider_app.py APPLYXFM [-h] [--rlevel <rlevel>] [--inverse]
Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
                              <moving> <moving-resolution> <fixed> <fixed-resolution> <reg-moving>
                              <reg-fixed> <resampled-img>

Apply transform to image.

positional arguments:
  <moving>             Moving slide image
  <moving-resolution>  Moving image resolution (mm)
  <fixed>              Fixed slide image
  <fixed-resolution>   Fixed image resolution (mm)
  <reg-moving>         Moving timg from registration directory
  <reg-fixed>          Fixed timg from registration directory (e.g. fixed4_nonlinear.timg)
  <resampled-img>      Name for resampled output image

optional arguments:
  -h, --help           show this help message and exit
98
  --rlevel <rlevel>    Resolution level for output image (subsample by 2^rlevel)
Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
99
100
101
102
103
104
105
106
107
108
109
  --inverse            Invert the transformation chain
  ```

For example:

```shell
slider_app.py APPLYXFM \
    mr247MBP_c24_s20a.jp2 0.0004 \
    mr247NeuN_c01_s19n.jp2 0.0004 \
    mr247_mbp_to_neun.reg/moving.timg \
    mr247_mbp_to_neun.reg/fixed4_nonlinear.timg \
Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
110
111
    m4247_mbp_to_neun.jp2 \
    --rlevel=4
Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
112
113
114
115
116
117
118
119
120
121
122
```

Or the inverse:

```
slider_app.py APPLYXFM \
    mr247NeuN_c01_s19n.jp2 0.0004 \
    mr247MBP_c24_s20a.jp2 0.0004 \
    mr247_mbp_to_neun.reg/moving.timg \
    mr247_mbp_to_neun.reg/fixed4_nonlinear.timg \
    m4247_neun_to_mbp.jp2 \
Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
123
124
    --inverse \
    --rlevel=4
Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
125
126
127
128
129
130
```

### Register chart to slide

You can register a Neurolucida chart file to a 2D-slide using the `CHART` subcommand of the `slider_app.py` app.

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
131
132
> Note that the `slide-resolution` is the resolution of the input images.  The resolution at which the registration is calculated is dictated by the config file (`slider/resources/chart.yaml`)

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
133
134
```shell
>> slider_app.py CHART -h   
135
136
137
usage: slider_app.py CHART [-h] [--outdir <dir>] [--boundary_key <key>] [--justify <left-right>]
                           [--config <config.yaml>]
                           <chart> <slide> <slide-resolution>
Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
138
139
140
141

Register charting to 2D slide

positional arguments:
142
143
144
  <chart>                 Neurolucida chart file
  <slide>                 Fixed slide
  <slide-resolution>      Slide image resolution (mm)
Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
145
146

optional arguments:
147
148
149
150
151
152
  -h, --help              show this help message and exit
  --outdir <dir>          Output directory
  --boundary_key <key>    Name of boundary contour in chart
  --justify <left-right>  Justify chart bounding-box to the left/right of the image bounding box.
                          Useful when only one hemisphere is charted.
  --config <config.yaml>  configuration file
Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
153
154
155
156
157
158
159
160
161
  ```

For example:

```shell
slider_app.py CHART \
    mr250NeuN_c14_s03.ASC \
    mr250NeuN_c14_s03n.jp2 0.0004 \
    --out=mr250_chart_to_neun.reg
Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
162
163
```

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
### Batch processing

SlideR jobs can be batch processed by using the `BATCH` subcommand of the `slider_app.py` app.   

First, you must create a CSV with column names that match the SlideR arguments, and a row for each job to run.  `BATCH` will determine which SlideR subcommand to run (e.g. SLIDE, CHART, or APPLYXFM) from the column names.  For example, the CSV (`jobs.csv`) for 4 jobs  with the `SLIDE` subcommand would be:


| moving | moving_res | fixed | fixed_res | out |
| ---    | ---        | ---   | ---       | --- |
| mr250MBP_c13_s10n.jp2 | 0.0004 | mr250NeuN_c14_s10n.jp2 | 0.0004 | mr250MBP_c13_s10n.reg |
| mr250MBP_c13_s04n.jp2 | 0.0004 | mr250NeuN_c14_s03n.jp2 | 0.0004 | mr250MBP_c13_s04.reg |
| mr247MBP_c24_s20a.jp2 | 0.0004 | mr247NeuN_c01_s19n.jp2 | 0.0004 | mr247MBP_c24_s20a.reg |
| mr248MBP_c10_s11n.jp2 | 0.0004 | mr248NeuN_c11_s14n.jp2 | 0.0004 | mr248MBP_c10_s11n.reg |

This CSV is then passed to `BATCH` to run each of the jobs sequentially:
```shell
slider_app.py BATCH jobs.csv
```

Sean Fitzgibbon's avatar
Sean Fitzgibbon committed
183
184
185
186
187
## Coordinate System

SlideR defines:
- origin is the upper left corner of the image
- coordinate units are mm