Registration: debug images and repeated stages

[maxpietsch]

• registration resolution levels are renamed to stages
• stages can be repeated (without the need to resize the images) using different optimisation algorithms (default: start with BB GD, finish with GD)
• Option to write diagnostic images after each registration stage (related to docs: registration troubleshooting #908).
  By limiting the number of gradient descent iterations per stage, one can output diagnostic images at fixed intervals (or at convergence) during registration.

So far all changes affect linear registration only.

stage options:

  -linstage.iterations num or comma separated list
     number of iterations for each registration stage, not to be confused with
     -rigid_niter or -affine_niter. This can be used to generate intermediate
     diagnostics images (-linstage.diagnostics.prefix) or to change the cost
     function optimiser during registration (without the need to repeatedly
     resize the images). (Default: 1 == no repetition)

  -linstage.optimiser.first algorithm
     Cost function optimisation algorithm to use at first iteration of all
     stages. Valid choices: bbgd (Barzilai-Borwein gradient descent) or gd
     (simple gradient descent). (Default: bbgd)

  -linstage.optimiser.last algorithm
     Cost function optimisation algorithm to use at last iteration of all
     stages (if there are more than one). Valid choices: bbgd (Barzilai-Borwein
     gradient descent) or gd (simple gradient descent). (Default: bbgd)

  -linstage.optimiser.default algorithm
     Cost function optimisation algorithm to use at any stage iteration other
     than first or last iteration. Valid choices: bbgd (Barzilai-Borwein
     gradient descent) or gd (simple gradient descent). (Default: bbgd)

  -linstage.diagnostics.prefix file prefix
     generate diagnostics images after every registration stage

Example of a diagnostic image:
Red = image1, Green =image2. NaN = outside mask or outside FOV

Info output using default parameters and -linstage.iter 2:

mrregister: [INFO] Linear registration stage parameters:
mrregister: [INFO] scale factor 0.25, lmax 0, GD max_iter 500, iterations: 2, optimiser: BBGD GD 
mrregister: [INFO] scale factor 0.5, lmax 2, GD max_iter 500, iterations: 2, optimiser: BBGD GD 
mrregister: [INFO] scale factor 1, lmax 4, GD max_iter 500, iterations: 2, optimiser: BBGD GD 
mrregister: linear stage 1/3, scale factor 0.25, lmax 0, GD max_iter 500, iterations: 2, optimiser: BBGD GD 
mrregister: [INFO] smoothing image 1
mrregister: [INFO] smoothing image 2
mrregister: [INFO] registration stage running...
mrregister: [INFO]     iteration: 1/2 GD iterations: 55 cost: 0.37877956179137451 overlap: 7458
mrregister: [INFO]     iteration: 2/2 GD iterations: 7 cost: 0.37877956179137445 overlap: 7458
mrregister: linear stage 2/3, scale factor 0.5, lmax 2, GD max_iter 500, iterations: 2, optimiser: BBGD GD 
mrregister: [INFO] smoothing image 1
mrregister: [INFO] smoothing image 2
mrregister: [INFO] registration stage running...
mrregister: [INFO]     iteration: 1/2 GD iterations: 14 cost: 4.5879727906352041 overlap: 55219
mrregister: [INFO]     iteration: 2/2 GD iterations: 17 cost: 4.5798951121985123 overlap: 55097
mrregister: linear stage 3/3, scale factor 1, lmax 4, GD max_iter 500, iterations: 2, optimiser: BBGD GD 
mrregister: [INFO] smoothing image 1
mrregister: [INFO] smoothing image 2
mrregister: [INFO] registration stage running...
mrregister: [INFO]     iteration: 1/2 GD iterations: 13 cost: 96.939197829846123 overlap: 439894
mrregister: [INFO]     iteration: 2/2 GD iterations: 13 cost: 96.162797259063908 overlap: 438396
mrregister: [INFO] linear registration done

also write initialisation: -linstage.iter 1,2,2 -linstage.diag /tmp/diag -affine_niter 0,500,500

mrregister: SH series detected, performing FOD registration
mrregister: running affine registration
mrregister: initialising translation and centre of rotation using centre of mass
mrregister: linear stage 1/3, scale factor 0.25, lmax 0, GD max_iter 0, optimiser: BBGD 
mrregister:     creating diagnostics image: /tmp/diag_stage-1_iter-1.mif
mrregister: linear stage 2/3, scale factor 0.5, lmax 2, GD max_iter 500, iterations: 2, optimiser: BBGD GD 
mrregister:     creating diagnostics image: /tmp/diag_stage-2_iter-1.mif
mrregister:     creating diagnostics image: /tmp/diag_stage-2_iter-2.mif
mrregister: linear stage 3/3, scale factor 1, lmax 4, GD max_iter 500, iterations: 2, optimiser: BBGD GD 
mrregister:     creating diagnostics image: /tmp/diag_stage-3_iter-1.mif
mrregister:     creating diagnostics image: /tmp/diag_stage-3_iter-2.mif
mrregister: running non-linear registration
mrregister: nonlinear stage 1, scale factor 0.25, lmax 0
mrregister: nonlinear stage 2, scale factor 0.5, lmax 2
mrregister: nonlinear stage 3, scale factor 1, lmax 4