This wiki page will walk-through an example to make an initial model. You may not need all the steps or you may need more steps based on your individual situation, but this will hopefully be a rough guide as to the steps involved. Please first go through this guide (Using an Initial Model) so you are familiar with how initial models are used. It is likely that the initial model you want already exists at MICe so ask around and check this directory (/hpf/largeprojects/MICe/tools/initial-models/). If the images you want to register are already in the standard space we use at MICe, then making a model is much easier (see option 1 in Using an Initial Model) and will not be covered here. If, however, the files you want to register are in a native space that is DIFFERENT to the standard space used at MICe, then this guide may be useful for you to make an initial model.

There are 5 files you need to make (see option 2 in Using an Initial Model):

  1. image.mnc - this is the initial model in standard space
  2. image_mask.mnc - this is the initial model's mask in standard space
  3. image_native_to_standard.xfm - this is the rigid transformation aligning the native space to the standard space.
  4. image_native.mnc - this is the initial model in native space
  5. image_native_mask.mnc - this is the initial model's mask in native space


This guide will show you how to make all of these files. In this example, I will create a directory and place all the files with the proper names in that directory.

mkdir ../spring-b0-DTI-80-micron-basket-jul-2021

Initial model in standard space

Here is an example of a native image: 

First register many (or all) the native images together using MBM.py and the bootstrap flag

MBM.py \
     --bootstrap \
     --pipeline-name=bootstrap_b0 \
     --subject-matter mousebrain \
     --num-executors 30 \
     --time 48:00:00 \
     --no-common-space-registration \
     --no-run-maget --maget-no-mask \
     --lsq12-protocol /hpf/largeprojects/MICe/tools/protocols/linear/Pydpiper_testing_default_lsq12.csv \
     --files ../b0_images/*.mnc


Check the information of the consensus average. This file we will be the starting point of our initial model.

mincinfo bootstrap_b0_nlin/bootstrap_b0-nlin-3.mnc
# file: bootstrap_b0_nlin/bootstrap_b0-nlin-3.mnc
# image: unsigned short 0 to 65535
# image dimensions: zspace xspace yspace
#     dimension name         length         step        start
#     --------------         ------         ----        -----
#     zspace                    180    0.0777778     -25.9611
#     xspace                    180   -0.0777778      29.9611
#     yspace                    324   -0.0771605      12.4614

Copy the consensus average file so you can modify it without worry.

cp bootstrap_b0_nlin/bootstrap_b0-nlin-3.mnc reg_avg.mnc

Sometimes, you may need to modify direction cosines to align the directions. If you don't need to, running this command will do nothing (so there is no real risk to run it)

minc_modify_header -dinsert xspace:direction_cosines=1,0,0 reg_avg.mnc
minc_modify_header -dinsert yspace:direction_cosines=0,1,0 reg_avg.mnc
minc_modify_header -dinsert zspace:direction_cosines=0,0,1 reg_avg.mnc

Use register to align our consensus average to one of the existing initial models at MICe. Make sure to use 5 or more tag points and be careful about your left/right axis.

register /hpf/largeprojects/MICe/tools/initial-models/Pydpiper-40-micron-basket-dec-2014/basket_mouse_brain_40micron.mnc reg_avg.mnc

Also, note the start and length information from the reference init model.

mincinfo /hpf/largeprojects/MICe/tools/initial-models/Pydpiper-40-micron-basket-dec-2014/basket_mouse_brain_40micron.mnc
# file: /hpf/largeprojects/MICe/tools/initial-models/Pydpiper-40-micron-basket-dec-2014/basket_mouse_brain_40micron.mnc
# image: unsigned short 0 to 65535
# image dimensions: zspace yspace xspace
#     dimension name         length         step        start
#     --------------         ------         ----        -----
#     zspace                    241         0.04         -4.2
#     yspace                    478         0.04        -8.19
#     xspace                    315         0.04        -6.27

Transform our consensus average to this new orientation.

mincresample -like /hpf/largeprojects/MICe/tools/initial-models/Pydpiper-40-micron-basket-dec-2014/basket_mouse_brain_40micron.mnc \
   -transform rough_align.xfm \
   reg_avg.mnc reg_avg_rough_orient.mnc

Our consensus average is now sampled the same way as the reference initial model

mincinfo  reg_avg_rough_orient.mnc
# file: reg_avg_rough_orient.mnc
# image: unsigned short 0 to 65535
# image dimensions: zspace yspace xspace
#     dimension name         length         step        start
#     --------------         ------         ----        -----
#     zspace                    241         0.04         -4.2
#     yspace                    478         0.04        -8.19
#     xspace                    315         0.04        -6.27

You may have to do some finer adjustments to our consensus average. In this example, the consensus average still needs to be rotated about the y-axis by roughly 1 degree

To perform the rotation sensibly, use the center of the volume as the center of rotation. To find center of mass, use the information from the mincinfo command run earlier. Here is an example for to calculate center of mass in the y-coordinate.

0.5 * ( 478 * 0.04 ) - 8.19
# 1.37

In the same way, center of mass in the x and z coordinates can be determined.

To rotate by 1 degree along the y axis, create a transformation file (using param2xfm) and resample the file with this transformation (using mincresample).

param2xfm \
   -center 0.03 1.37 0.62   \
   -rotations 0 1 0 fine_align1.xfm

mincresample -use_input_sampling \
   -transform fine_align1.xfm \
   reg_avg_rough_orient.mnc reg_avg_fine_align.mnc

This fine-adjustment is sufficient.


Furthermore, I noticed that the sagittal mid-place is x=162 (green line). But the middle of the volume in the x-dimension is 157.5 (red line).

This means to center the brain in the volume, we need to move the sampling window 4.5 voxels to the right (i.e. 0.18mm to the right).

mincresample -use_input_sampling \
     -xstart -6.09 \
     reg_avg_fine_align.mnc reg_avg_centered.mnc

Lastly, we want to set the resolution closer to our native images (80um in this case). We change length correspondingly to ensure that the volume remains the same. For example, the new length for the x-axis is:

315 * 0.04 / 0.08
# 157.5

Similarily, you can determine the new dimension lengths for the other dimensions and pass them to mincresample using the nelements argument.

mincresample \
     -step 0.08 0.08 0.08 \
     -nelements 158 239 121 \
     reg_avg_centered.mnc reg_avg_centered_proper_resolution.mnc

Notice the resolution is now correct.

mincinfo reg_avg_centered_proper_resolution.mnc
# file: reg_avg_centered_proper_resolution.mnc
# image: unsigned short 0 to 65535
# image dimensions: zspace yspace xspace
#     dimension name         length         step        start
#     --------------         ------         ----        -----
#     zspace                    121         0.08         -4.2
#     yspace                    239         0.08        -8.19
#     xspace                    158         0.08        -6.09

This file will go on to be the initial model in standard space. Copy the file into final directory:

cp reg_avg_centered_proper_resolution.mnc ../spring-b0-DTI-80-micron-basket-jul-2021/b0_DTI_80um.mnc

Initial model mask in standard space

There are many ways to make a mask. In this example, I will create a mask by register an atlas to our initial model. The atlas I will be using is the DSURQEE atlas and the resultant transformation is called atl_to_modl.xfm

# Do an affine registration
antsRegistration -d 3 \
   -o affine_atl_to_modl \
   -a 1 -z 1 \
   -t Affine[0.25] -m MI[reg_avg_centered_proper_resolution.mnc,/hpf/largeprojects/MICe/tools/atlases/Dorr_2008_Steadman_2013_Ullmann_2013_Richards_2011_Qiu_2016_Egan_2015_Elder_2019_40micron/DSURQEE_40micron_average.mnc,1,32,Regular,0.25] \
   --convergence [1000x500x250x100,1e-6,10] \
   --shrink-factors 8x4x2x1 \
   --smoothing-sigmas 0.2x0.1x0.05x0mm \
   --minc -v 1 --use-histogram-matching 1

# resample the atlas and its mask
mincresample \
     -like reg_avg_centered_proper_resolution.mnc \
     -transform affine_atl_to_modl.xfm /hpf/largeprojects/MICe/tools/atlases/Dorr_2008_Steadman_2013_Ullmann_2013_Richards_2011_Qiu_2016_Egan_2015_Elder_2019_40micron/DSURQEE_40micron_average.mnc \
     atl_avg_affine.mnc
mincresample -nearest -label \
     -like reg_avg_centered_proper_resolution.mnc \
     -transform affine_atl_to_modl.xfm /hpf/largeprojects/MICe/tools/atlases/Dorr_2008_Steadman_2013_Ullmann_2013_Richards_2011_Qiu_2016_Egan_2015_Elder_2019_40micron/DSURQEE_40micron_mask.mnc \
     atl_mask_affine_nondilated.mnc

# generously dilate the mask before using it in the non-affine registration
mincmorph \
     -successive DDDDDDDDDDDDDDDDDDDDD \
     atl_mask_affine_nondilated.mnc atl_mask_affine.mnc

# Do a non-affine registration
antsRegistration -d 3 \
   -o non_affine_atl_to_modl \
   -x atl_mask_affine.mnc \
   -a 1 -z 1 \
   -t SyN[0.1,2,0] \
   -m MI[atl_avg_affine.mnc,reg_avg_centered_proper_resolution.mnc,1,32,Regular,0.25] \
   --convergence [1000x1000x1000x1000,1e-6,10] \
   --shrink-factors 8x4x2x1 \
   --smoothing-sigmas 0.2x0.1x0.05x0mm \
   --minc -v 1 --use-histogram-matching 1

# concatenate the affine and non-affine transformations
xfmconcat affine_atl_to_modl.xfm non_affine_atl_to_modl.xfm atl_to_modl.xfm

We can transform the atlas mask so it aligns with our initial model.

mincresample -nearest -label \
   -like reg_avg_centered_proper_resolution.mnc \
   -transform atl_to_modl.xfm \
   /hpf/largeprojects/MICe/tools/atlases/Dorr_2008_Steadman_2013_Ullmann_2013_Richards_2011_Qiu_2016_Egan_2015_Elder_2019_40micron/DSURQEE_40micron_mask.mnc \
   mask_nondilated.mnc

Before using the mask as for our initial model is it best to dilate and erode the mask. You want it to cover the entirety of the brain and still have a 0.3-0.7 mm buffer. Exactly how much you want to dilate and erode is something you should decide manually. In this example, this is the command I used:

mincmorph -successive EEDEEDEEDEEDEEDEEDEEDEEDDDDDDDDDDDDDDDD mask_nondilated.mnc mask.mnc

We are now done making the standard mask. Copy it to the final directory with the proper name.

cp mask.mnc ../spring-b0-DTI-80-micron-basket-jul-2021/b0_DTI_80um_mask.mnc

Native-to-standard space transformation

Look at the native and standard brains from earlier:

Notice that rotating by 180 degrees about the z-axis roughly accounts for the native-to-standard transformation. However, we want to define the center of mass to be the center of rotation. We can use mincinfo to find center of mass.

mincinfo reg_avg_centered_proper_resolution.mnc
# file: reg_avg_centered_proper_resolution.mnc
# image: unsigned short 0 to 65535
# image dimensions: zspace yspace xspace
#     dimension name         length         step        start
#     --------------         ------         ----        -----
#     zspace                    121         0.08         -4.2
#     yspace                    239         0.08        -8.19
#     xspace                    158         0.08        -6.09

From this information, we can determine that the xyz-coordinates of the center of mass (in mm) is (0.23,1.37,0.64)

To create the native-to-standard transformation, use param2xfm.

param2xfm -center 0.23 1.37 0.64 -rotation 0 0 180 native_to_standard.xfm

We have completed making the native-to-standard transformation. Copy it to the final directory with the proper name.

cp native_to_standard.xfm ../spring-b0-DTI-80-micron-basket-jul-2021/b0_DTI_80um_native_to_standard.xfm

Initial model in native space

By inverting the native-to-standard transformation, we can take our standard initial model and move it to native space.

mincresample -use_input_sampling \
     -invert -transform native_to_standard.xfm \
     reg_avg_centered_proper_resolution.mnc \
     native_cropped_nodimorder.mnc

There are two things we still have to do before we use these native model. First, we have to change the dimension order. Note that the consensus average has dimension order Z-X-Y.

mincinfo bootstrap_b0_nlin/bootstrap_b0-nlin-3.mnc 
# file: bootstrap_b0_nlin/bootstrap_b0-nlin-3.mnc
# image: unsigned short 0 to 65535
# image dimensions: zspace xspace yspace
#     dimension name         length         step        start
#     --------------         ------         ----        -----
#     zspace                    180    0.0777778     -25.9611
#     xspace                    180   -0.0777778      29.9611
#     yspace                    324   -0.0771605      12.4614

But our native model has dimension order Z-Y-X.

# mincinfo native_cropped_nodimorder.mnc
# file: native_cropped_nodimorder.mnc
# image: unsigned short 0 to 65535
# image dimensions: zspace yspace xspace
#     dimension name         length         step        start
#     --------------         ------         ----        -----
#     zspace                    121         0.08         -4.2
#     yspace                    239         0.08        -8.19
#     xspace                    158         0.08        -6.09

Use mincreshape to change the dimension order.

mincreshape \
     -dimorder zspace,xspace,yspace \
     native_cropped_nodimorder.mnc \
     native_cropped.mnc

The second (and last) thing we have to do to the native model is to pad it so the volume is the same as the volume of our native images. You can manually compute how length and start coordinate need to change in order to pad native_cropped.mnc symmetrically to be the same volume as the consensus average. For example, here is the computation for the x coordinate.

# length of x-axis of the nlin volume
Lx1 = 180 * abs(-0.0777778)
# length of x-axis of the cropped volume
Lx2 = 158 * abs(0.08)
# difference in length
dLx =  Lx1 - Lx2
# To pad left, reduce start value by half the length
new_start_x = -6.09 - dLx/2   #(value is -6.770002)
# To pad right, increase length value
new_length_x = 158 + dLx/0.08  #(value is 175)

You can repeat this procedure for the other dimensions. Then use the mincresample command.

mincresample \
   -start -6.770002 -11.130001  -6.360002 \
   -nelements 175 313 175 \
   native_cropped.mnc native.mnc

We have completed making the native model. Copy it to the final directory with the proper name.

cp native.mnc ../spring-b0-DTI-80-micron-basket-jul-2021/b0_DTI_80um_native.mnc

Initial model mask in native space

Repeat the same transformations you did for create the initial model in native space, except this time use the standard mask as the input and add the -nearest and -labels flags to mincresample.

# transform to native
mincresample -nearest -labels -use_input_sampling \
     -invert -transform native_to_standard.xfm \
     mask.mnc native_cropped_nodimorder_mask.mnc

# reorder dimensions
mincreshape \
     -dimorder zspace,xspace,yspace \
     native_cropped_nodimorder_mask.mnc \
     native_cropped_mask.mnc

# pad volume
mincresample -nearest -label \
   -start -6.770002 -11.130001  -6.360002 \
   -nelements 175 313 175 \
   native_cropped_mask.mnc native_mask.mnc

We have completed making the native model mask. Copy it to the final directory with the proper name.

cp native_mask.mnc ../spring-b0-DTI-80-micron-basket-jul-2021/b0_DTI_80um_native_mask.mnc

The final directory should now contain the following files:

  1. b0_DTI_80um.mnc - this is the initial model in standard space
  2. b0_DTI_80um_mask.mnc - this is the initial model's mask in standard space
  3. b0_DTI_80um_native_to_standard.xfm - this is the rigid transformation aligning the native space to the standard space.
  4. b0_DTI_80um_native.mnc - this is the initial model in native space
  5. b0_DTI_80um_native_mask.mnc - this is the initial model's mask in native space

You can now use this initial model in your registration.

MBM.py \
     --init-model=../spring-b0-DTI-80-micron-basket-jul-2021/b0_DTI_80um.mnc \
     --pipeline-name=b0 \
     --subject-matter mousebrain \
     --num-executors 30 \
     --time 48:00:00 \
     --no-common-space-registration \
     --no-run-maget --maget-no-mask \
     --lsq12-protocol /hpf/largeprojects/MICe/tools/protocols/linear/Pydpiper_testing_default_lsq12.csv \
     --files ../b0_images/*.mnc