[Brains-users] New b2 commands::b2 apropos affine

[Greg Harris]

This announcement documents a new ability to numerically
generate 3D affine transforms in brains2.

You can generate the identity tranform for lining up the centers of two 
images with
    set i [b2 load image . . .]
    set j [b2 load image . . .]
    b2 create affine-transform [b2 get dims image $i] [b2 get res image 
$i] [b2 get dims image $j] [b2 get res image $j]
The result will be a transform you can set on image j to make it 
identically addressable with image i.

You can take any existing affine transform, such as one generated by 
image fitting,
and apply nudging parameters to it, even in degrees not radians, with
    set inRadians [expr 3.14159 / 180]
    b2 nudge affine-transform $tx rx= [expr 5 * $inRadians] . . . etc.
In general, a rotation about the x axis is given in radians with the 
'rx=' keyword;
a translation along the x axis is given in millimeters with the 'dx=' 
keyword;
and likewise for 'ry=', 'dy=', 'rz=', and 'dz='.  The result is a new, 
nudged transform.

The nudging parameters are available with 'b2 create affine-transform' 
as well.

You can obtain the matrix inverse of any existing affine transform with
'b2 invert affine-transform'.

= = = APPENDIX = = =
Usage   b2 create affine-transform [standard-dims-list] 
[standard-res-list] [reslice-dims-list] [reslice-res-list] <rx= F32> 
<ry= F32> <rz= F32> <dx= F32> <dy= F32> <dz= F32>

Description     This command will create a resampling transform
                that maps from the reslice image space to the standard 
image space.
                You are supposed to set the resulting transform on the 
reslice image.

[standard-dims-list]    A string list beginning with the xdim, ydim and zdim
                        integers for defining the standard image space.
[standard-res-list]     A string list beginning with the xres, yres and zres
                        decimal numbers for defining the standard image 
space.
[reslice-dims-list]     A string list beginning with the xdim, ydim and zdim
                        integers for defining the reslice image space.
[reslice-res-list]      A string list beginning with the xres, yres and zres
                        decimal numbers for defining the reslice image 
space.
<rx= F32>       A rotation about the x axis, pitch, given in radians.
<ry= F32>       A rotation about the y axis, yaw, given in radians.
<rz= F32>       A rotation about the z axis, roll, given in radians.
<dx= F32>       A translation along the x axis, lateral, given in mm.
<dy= F32>       A translation along the y axis, inferior-superior, given 
in mm.
<dz= F32>       A translation along the z axis, rostro-caudal, given in mm.

Hint:           You can generate the identity tranform for an image with
                b2 create affine-transform [b2 get dims image $i] [b2 
get res image $i] [b2 get dims image $i] [b2 get res image $i]

Return          Upon successful completion a newly created
                object identifier is returned,  otherwise
                an error status of -1 is returned.

= = = APPENDIX = = =
Usage   b2 nudge affine-transform [transform] <rx= F32> <ry= F32> <rz= 
F32> <dx= F32> <dy= F32> <dz= F32>

Description     This command will nudge a resampling transform
                and return a nudged copy without changing the original.
                You are supposed to set the resulting nudged transform 
on the
                reslice image to view the effect of each successive nudge.

[transform]     The affine transform to modify, probably created by
                'b2 create affine-transform'.
<rx= F32>       A rotation about the x axis, pitch, given in radians.
<ry= F32>       A rotation about the y axis, yaw, given in radians.
<rz= F32>       A rotation about the z axis, roll, given in radians.
<dx= F32>       A translation along the x axis, lateral, given in mm.
<dy= F32>       A translation along the y axis, inferior-superior, given 
in mm.
<dz= F32>       A translation along the z axis, rostro-caudal, given in mm.

Hint:           You can provide rotation nudges in degrees not radians with
                set inRadians [expr 3.14159 / 180]
                b2 nudge affine-transform $tx rx= [expr 5 * $inRadians] 
. . . etc.

Return          Upon successful completion a newly created
                object identifier is returned,  otherwise
                an error status of -1 is returned.

= = = APPENDIX = = =
Usage   b2 invert affine-transform [transform]
Description     This command will invert an affine resampling transform
                and return the inverse transform without changing the 
original.
                You are supposed to set the resulting inverse transform 
on the
                reslice image.

[transform]     The affine transform to invert, probably created by
                'b2 create affine-transform'.
Return          Upon successful completion a newly created
                object identifier is returned,  otherwise
                an error status of -1 is returned.