0
# Registration and Alignment
1

2
Image registration algorithms for aligning diffusion data, including affine and non-linear registration methods, motion correction, and streamline registration. DIPY provides high-level registration functions that handle common alignment tasks.
3

4
## Capabilities
5

6
### Non-linear Registration
7

8
Symmetric diffeomorphic registration for non-linear alignment between images.
9

10
```python { .api }
11
def syn_registration(moving, static, *, moving_affine=None, static_affine=None, step_length=0.25, metric="CC", dim=3, level_iters=None, prealign=None, **metric_kwargs):
12
    """
13
    Symmetric diffeomorphic registration between 2D/3D images.
14
    
15
    Parameters:
16
        moving (array/str): moving image data or file path
17
        static (array/str): static (target) image data or file path  
18
        moving_affine (array): 4x4 affine for moving image
19
        static_affine (array): 4x4 affine for static image
20
        step_length (float): optimization step length
21
        metric (str): similarity metric ('CC', 'EM', 'SSD')
22
        dim (int): image dimensions (2 or 3)
23
        level_iters (list): iterations at each pyramid level
24
        prealign (array): initial transformation matrix
25
        
26
    Returns:
27
        tuple: (warped_moving, mapping) - registered image and transformation
28
    """
29

30
def register_dwi_to_template(dwi, gtab, *, dwi_affine=None, template=None, template_affine=None, reg_method="syn", **reg_kwargs):
31
    """
32
    Register DWI data to template through B0 volumes.
33
    
34
    Parameters:
35
        dwi (array/str): DWI data or file path
36
        gtab (GradientTable): diffusion gradient table
37
        dwi_affine (array): 4x4 affine for DWI data
38
        template (array/str): template image or file path
39
        template_affine (array): 4x4 affine for template
40
        reg_method (str): registration method ('syn' or 'aff')
41
        
42
    Returns:
43
        tuple: (warped_b0, mapping) - registered B0 and transformation
44
    """
45
```
46

47
### Affine Registration  
48

49
Multi-step affine registration with gradual transformation fitting.
50

51
```python { .api }
52
def affine_registration(moving, static, *, moving_affine=None, static_affine=None, pipeline=None, starting_affine=None, metric="MI", level_iters=None, sigmas=None, factors=None, ret_metric=False, moving_mask=None, static_mask=None, **metric_kwargs):
53
    """
54
    Multi-step affine registration pipeline.
55
    
56
    Parameters:
57
        moving (array/str): moving image
58
        static (array/str): static image  
59
        moving_affine (array): 4x4 affine for moving image
60
        static_affine (array): 4x4 affine for static image
61
        pipeline (list): transformation sequence (['center_of_mass', 'translation', 'rigid', 'affine'])
62
        starting_affine (array): initial transformation
63
        metric (str): similarity metric ('MI')
64
        level_iters (list): iterations at each scale level  
65
        sigmas (list): smoothing parameters for scale space
66
        factors (list): scale factors for pyramid
67
        ret_metric (bool): return optimization metrics
68
        moving_mask (array): mask for moving image
69
        static_mask (array): mask for static image
70
        
71
    Returns:
72
        tuple: (resampled, final_affine) or (resampled, final_affine, xopt, fopt)
73
    """
74

75
def center_of_mass(moving, static, **kwargs):
76
    """Center of mass alignment transform."""
77

78
def translation(moving, static, **kwargs):  
79
    """Translation-only transform."""
80

81
def rigid(moving, static, **kwargs):
82
    """Rigid transform (translation + rotation)."""
83

84
def rigid_isoscaling(moving, static, **kwargs):
85
    """Rigid transform with isometric scaling."""
86

87
def rigid_scaling(moving, static, **kwargs):
88
    """Rigid transform with anisotropic scaling."""
89

90
def affine(moving, static, **kwargs):
91
    """Full affine transform (12 degrees of freedom)."""
92
```
93

94
### Series Registration
95

96
Registration of 4D image series and DWI datasets for motion correction.
97

98
```python { .api }
99
def register_series(series, ref, *, pipeline=None, series_affine=None, ref_affine=None, static_mask=None):
100
    """
101
    Register 4D image series to reference volume.
102
    
103
    Parameters:  
104
        series (array/str): 4D image series
105
        ref (int/array/str): reference volume index or image
106
        pipeline (list): transformation sequence
107
        series_affine (array): 4x4 affine for series
108
        ref_affine (array): 4x4 affine for reference
109
        static_mask (array): mask for reference image
110
        
111
    Returns:
112
        tuple: (xformed, affines) - registered series and transformation matrices
113
    """
114

115
def register_dwi_series(data, gtab, *, affine=None, b0_ref=0, pipeline=None, static_mask=None):
116
    """
117
    Register DWI series to mean B0 (motion correction).
118
    
119
    Parameters:
120
        data (array/str): 4D DWI data
121
        gtab (GradientTable): gradient table
122
        affine (array): 4x4 affine transformation
123
        b0_ref (int): reference B0 volume index
124
        pipeline (list): transformation sequence  
125
        static_mask (array): mask for reference
126
        
127
    Returns:
128
        tuple: (xform_img, affine_array) - registered data and transformations
129
    """
130

131
def motion_correction(data, gtab, **kwargs):
132
    """
133
    Motion correction for DWI datasets.
134
    
135
    Alias for register_dwi_series with standard pipeline.
136
    """
137
```
138

139
### Streamline Registration
140

141
Registration of streamline bundles to align tractography results.
142

143
```python { .api }
144
def streamline_registration(moving, static, *, n_points=100, native_resampled=False):
145
    """
146
    Register streamline bundles to each other.
147
    
148
    Parameters:
149
        moving (list/str): moving streamlines or file path
150
        static (list/str): static streamlines or file path  
151
        n_points (int): number of points for resampling
152
        native_resampled (bool): return in original space but resampled
153
        
154
    Returns:
155
        tuple: (aligned, matrix) - aligned streamlines and 4x4 transformation
156
    """
157
```
158

159
### Resampling and Mapping
160

161
Utilities for resampling images between different spaces and managing transformations.
162

163
```python { .api }
164
def resample(moving, static, *, moving_affine=None, static_affine=None, between_affine=None):
165
    """
166
    Resample image from one space to another.
167
    
168
    Parameters:
169
        moving (array/str): moving image
170
        static (array/str): target image defining output space
171
        moving_affine (array): 4x4 affine for moving image
172
        static_affine (array): 4x4 affine for static image  
173
        between_affine (array): additional transformation between spaces
174
        
175
    Returns:
176
        Nifti1Image: resampled image in target space
177
    """
178

179
def write_mapping(mapping, fname):
180
    """
181
    Save registration mapping to nifti file.
182
    
183
    Parameters:
184
        mapping (DiffeomorphicMap): registration mapping
185
        fname (str): output file path
186
    """
187

188
def read_mapping(disp, domain_img, codomain_img, *, prealign=None):
189
    """
190
    Load registration mapping from nifti file.
191
    
192
    Parameters:
193
        disp (str/array): displacement field file or data
194
        domain_img (str/array): domain image
195
        codomain_img (str/array): codomain image
196
        prealign (array): pre-alignment transformation
197
        
198
    Returns:
199
        DiffeomorphicMap: loaded registration mapping
200
    """
201
```
202

203
### Usage Examples
204

205
```python
206
# Basic non-linear registration
207
from dipy.align import syn_registration
208
from dipy.data import read_stanford_hardi
209
import numpy as np
210

211
# Load example data  
212
img, _ = read_stanford_hardi()
213
data = img.get_fdata()
214

215
# Use first and last volumes as moving and static
216
moving = data[..., 0] 
217
static = data[..., -1]
218

219
# Perform symmetric diffeomorphic registration
220
warped, mapping = syn_registration(moving, static, metric='CC')
221

222
print(f"Original shape: {moving.shape}")
223
print(f"Warped shape: {warped.shape}")
224

225
# Motion correction for DWI series
226
from dipy.align import motion_correction
227

228
# Load full DWI data
229
img, gtab = read_stanford_hardi()
230
data = img.get_fdata()
231

232
# Apply motion correction
233
corrected_img, transforms = motion_correction(data, gtab)
234

235
print(f"Applied {transforms.shape[-1]} transformations")
236

237
# Affine registration with custom pipeline
238
from dipy.align import affine_registration
239

240
# Register with rigid transformation only
241
result, affine_matrix = affine_registration(
242
    moving, static,
243
    pipeline=['center_of_mass', 'translation', 'rigid']
244
)
245

246
print(f"Final affine transformation:\n{affine_matrix}")
247

248
# Streamline bundle registration  
249
from dipy.align import streamline_registration
250
from dipy.data import read_bundles_2_subjects
251

252
# Load example streamline bundles
253
streamlines1, streamlines2 = read_bundles_2_subjects()
254

255
# Register bundles
256
aligned_streamlines, transform_matrix = streamline_registration(
257
    streamlines1, streamlines2, n_points=20
258
)
259

260
print(f"Registered {len(aligned_streamlines)} streamlines")
261
print(f"Transform matrix shape: {transform_matrix.shape}")
262

263
# Resampling between spaces
264
from dipy.align import resample
265

266
# Resample moving image to static image space
267
resampled_img = resample(moving, static)
268

269
print(f"Resampled image type: {type(resampled_img)}")
270
```