10. astec_intraregistration

astec_intraregistration is used to compensate the apparent motion of the imaged object. It co-registers pairs of successive fusion images and compose the resulting transformations to get a still view of the imaged object.

Section astec_intraregistration parameters provides a view on all the parameters.

10.1. Intra-registration procedure overview

The sequence intra-registration procedure can be done either after the fusion step, or after the (post-)segmentation step. It aims at

  • compensating for the eventual motion of the imaged sample with respect to the microscope

  • resampling the fusion and/or the segmentation images into a common frame/geometry, so they can better be compared, and

  • building 2D+t images made of 2D sections from either the fusion and/or the segmentation images, so that the quality of the fusion and/of the tracking step can be visually assessed.

The intra-registration procedure is made of the following steps:

1. Co-registration of pairs of successive fused images (section Step 1: co-registration). This yields the transformations \(T_{t+1 \leftarrow t}\). Fused images are located in <EMBRYO>/FUSE/FUSE_<EXP_FUSE>: the parameter EXP_FUSE``is either set in the parameter file or is set at ``RELEASE. This step may be long.

2. Composition of transformations issued from the co-registration step. This step computes the transformations \(T_{ref \leftarrow t}\). towards a reference image ref given by the parameter intra_registration_reference_index.

3. Computation of the template image (section Step 3: template building). This template image dimension are computed so that the useful information of all resampled images fits into it. Useful information can be issued from either the fused sequence, the segmentation sequence or the post-segmentation sequence. It is indicated by the intra_registration_template_type which value can be either 'FUSION', 'SEGMENTATION', or 'POST-SEGMENTATION'. This step may be long.

4. Resampling of either the fused or the segmentation images (section Step 4: resampling fusion/segmentation images). Note that changing the parameters for this step will not require to re-compute the first steps.

5. Extraction of 2D+t images from the resampled sequences (section Step 5: 2D+t movies). Note that changing the parameters for this step (i.e. requiring extra movies) will not require to re-compute the first steps, with an eventual exception for the resampling step.

6. Computation of a maximum image from the resampled images (section Step 6: 3D maximum over the 3D+t sequence). Computing the maximum over the resampled fusion images may be useful to define a common cropping area for the sequence. Note that changing the parameters for this step will not require to re-compute the first steps.

10.2. astec_intraregistration additional options

The following options are available:

-t file

set the resampling transformation file for the reference image (see section Step 3: template building)

-a string

set the resampling transformation angles for the reference image (see section Step 3: template building)

10.3. Intra-registration / input data

10.3.1. Intra-registration / multichannel acquisition

The co-registration transformations are computed from one series of fused images, issued from the /path/to/experiment/FUSE/FUSE_<EXP_FUSE> directory.

In case of multi-channel acquisition, all fused image directories listed in the EXP_FUSE variable will be transformed by the transformations computed on the first fused image directory of the list.

As detailed in section Step 1: co-registration, specifying

EXP_FUSE = ['MEMBRANES', 'NUCLEI']

in the parameter file implies that co-registrations will be computed on the fused images from FUSE/FUSE_MEMBRANES/, but both fused image series will be transformed.

The same stands for segmentation and post-segmentation series: multiple directories can be specified in either EXP_SEG or EXP_POST.

10.4. Intra-registration / output data

The results are stored in sub-directories INTRAREG/INTRAREG_<EXP_INTRAREG> under the /path/to/experiment/ directory where <EXP_INTRAREG> is the value of the variable EXP_INTRAREG (its default value is 'RELEASE').

/path/to/experiment/
├── ...
├── INTRAREG/
│  └── INTRAREG_<EXP_INTRAREG>/
│     ├── CO-TRSFS/
│     ├── [FUSE/]
│     ├── LOGS/
│     ├── [MAXIMUM/]
│     ├── [MOVIES/]
│     ├── [POST/]
│     ├── [SEG/]
│     └── TRSFS_t<begin>-<end>/
...

Output data are of two kinds: image series (fused images, segmentation images, post-corrected segmentation images) can be resampled in the same common geometry (also known as the template), see section Step 4: resampling fusion/segmentation images, and 3D (ie 2D+t) images of the evolution (with respect to time) of one section (XY, XZ, or YZ) of the images of the series can be built, see section Step 5: 2D+t movies.

10.5. Step 1: co-registration

Default registration parameters for the co-registration are set by:

# intra_registration_compute_registration = True
# intra_registration_transformation_type = 'rigid'
# intra_registration_transformation_estimation_type = 'wlts'
# intra_registration_lts_fraction = 0.55
# intra_registration_pyramid_highest_level = 6
# intra_registration_pyramid_lowest_level = 3
# intra_registration_normalization = True

Computed transformations are stored in INTRAREG/INTRAREG_<EXP_INTRAREG>/CO-TRSFS.It may be advised to set the pyramid lowest level value to some higher value to speed up the co-registrations (recall that all pairs of successive images will be co-registered, i.e.

intra_registration_pyramid_lowest_level = 4

Co-registration are computed using the fused images of /path/to/experiment/FUSE/FUSE_<EXP_FUSE>. If EXP_FUSE is a list of strings (ie indicates a list a directories) rather than a single string, the fused image from the first directory are used for the co-registration computation.

Typically, if there are several fused series (eg, in case of multi-channel acquisition) as in

/path/to/experiment/
├── ...
├── FUSE/
│  ├── FUSE_MEMBRANES/
│  │   └── ...
│  └── FUSE_NUCLEI/
│      └── ...
...

Specifying

EXP_FUSE = ['MEMBRANES', 'NUCLEI']

in the parameter file implies that co-registrations will be done on the fused images from FUSE/FUSE_MEMBRANES/.

10.6. Step 3: template building

# intra_registration_reference_index = None
# intra_registration_reference_resampling_transformation_file = None
# intra_registration_reference_resampling_transformation_angles = None
#
# intra_registration_template_type = "FUSION"
# intra_registration_template_threshold = None
# intra_registration_margin = None
#
# intra_registration_resolution = 0.6
#
# intra_registration_rebuild_template = False

  • The intra_registration_reference_index allows to choose the reference image (the one which remains still, i.e. up to a translation), by default it is the first image image of the series (associated to begin). However, it may happen that this image has to be reoriented to fit the user’s expectation. The resampling transformationfootnote{The resampling transformation is the one that goes from the destination image towards the input image.}, that re-orient the reference image, can then be given and will be applied to the whole series.

    • intra_registration_reference_resampling_transformation_file can be given a resampling transformation file name.

    • intra_registration_reference_resampling_transformation_angles can be given a string describing the successive rotations (with respect to the frame axis) to be applied. E.g. the string "X 30 Y 50" defines a resampling transformation equal to \(R_X(30) \circ R_Y(50)\) where \(R_X(30)\) is a rotation of 30 degrees around the X axis and \(R_Y(50)\) is a rotation of 50 degrees around the Y axis.

  • Depending on intra_registration_template_type ('FUSION', 'SEGMENTATION' or 'POST-SEGMENTATION'), the two latter assume obviously that the segmentation has been done), the template image can be built either after the fusion or the segmentation images. If no threshold is given by intra_registration_template_threshold, the built template will be large enough to include all the transformed fields of view (in this case, the template is the same whatever intra_registration_template_type is).

    If intra_registration_template_type='FUSION' (respectively 'SEGMENTATION' and 'POST-SEGMENTATION'), the template is built from the images of the first directory indicated by EXP_FUSE (respectively EXP_SEG and EXP_POST) in case of EXP_FUSE contains a list of strings.

    If a threshold is given, the built template will be large enough to include all the transformed points above the threshold. E.g., the background is labeled with either ‘1’ or ‘0’ in segmentation images, then a threshold of ‘2’ ensures that all the embryo cells will not be cut by the resampling stage. In this case, adding an additional margin (with intra_registration_margin) to the template could be a good idea for visualization purpose.

  • Specifying using a different resolution for the drift-compensated series than the target_resolution (the resolution of the fused images) allows to decrease the resampled images volume. This can be achieved by setting intra_registration_resolution to the desired value (default is 0.6).

  • Last, co-registrations may have been computed during a first computation, fused images being used to compute the template. However, if a subsequent segmentation has been conducted, a smaller template is likely to be computed (with the segmentation images to build the template), without recomputing the co-registration. This is the purpose of the variable intra_registration_rebuild_template. If set to True, it forces to recompute the template as well as the transformations from the co-registrations (that are not re-computed). Obviously, resampling as well as 2D+t movies are also re-generated.

As an example, building a template image after the segmentation images can be done with

 # intra_registration_reference_index = None
intra_registration_template_type = "SEGMENTATION"
intra_registration_template_threshold = 2
# intra_registration_resolution = 0.6
intra_registration_margin = 10

Computed transformations from the template image as well as the template image itself are stored in INTRAREG/INTRAREG<EXP_INTRAREG>/TRSFS_t<F>-<L>/ where <F> and L are the first and the last index of the series (specified by begin and end from the parameter file).

10.7. Step 4: resampling fusion/segmentation images

The resampling of the fused and/or segmentation images are done depending on the value of the following variables (here commented). Resampling is done either if the following parameters are set to True or if movies are requested to be computed (section Step 5: 2D+t movies).

# intra_registration_resample_fusion_images = True
# intra_registration_resample_segmentation_images = False
# intra_registration_resample_post_segmentation_images = False

This default behavior implies that the fusion images will be resampled while the segmentation and the post-corrected segmentation images are not.

Resampled images will be stored in the INTRAREG/INTRAREG_<EXP_INTRAREG/> directory, with the same hierarchy than under /path/to/experiment. E.g.

/path/to/experiment/
├── ...
├── FUSE/
│  ├── FUSE_1/
│  │   └── ...
│  └── FUSE_2/
│      └── ...
...

Specifying

EXP_FUSE = ['1', '2']

in the parameter file causes the resampling of both fused image series (FUSE/FUSE_1/ and FUSE/FUSE_2/)

/path/to/experiment/
├── ...
├── FUSE/
│  ├── FUSE_1/
│  │   └── ...
│  └── FUSE_2/
│      └── ...
├── INTRAREG/
│  └── INTRAREG_<EXP_INTRAREG>/
│     ├── CO-TRSFS/
│     ├── FUSE/
│     │   ├── FUSE_1/
│     │   │   └── ...
│     │   └── FUSE_2/
│     │       └── ...
│     ...
...

The same behavior stands for EXP_SEG and EXP_POST.

10.8. Step 5: 2D+t movies

For either visual assessment or illustration purposes, 2D+t (i.e. 3D) images can be built from 2D sections extracted from the resampled temporal series. This is controlled by the following parameters:

# intra_registration_movie_fusion_images = True
# intra_registration_movie_segmentation_images = False
# intra_registration_movie_post_segmentation_images = False

# intra_registration_xy_movie_fusion_images = [];
# intra_registration_xz_movie_fusion_images = [];
# intra_registration_yz_movie_fusion_images = [];

# intra_registration_xy_movie_segmentation_images = [];
# intra_registration_xz_movie_segmentation_images = [];
# intra_registration_yz_movie_segmentation_images = [];

# intra_registration_xy_movie_post_segmentation_images = [];
# intra_registration_xz_movie_post_segmentation_images = [];
# intra_registration_yz_movie_post_segmentation_images = [];

If intra_registration_movie_fusion_images is set to True, a movie is made with the XY-section located at the middle of each resampled fusion image (recall that, after resampling, all images have the same geometry). Additional XY-movies can be done by specifying the wanted Z values in intra_registration_xy_movie_fusion_images. E.g.

intra_registration_xy_movie_fusion_images = [100, 200];

will build two movies with XY-sections located respectively at Z values of 100 and 200. The same stands for the other orientation and for the resampled segmentation images.

Movies will be stored in the INTRAREG/INTRAREG_<EXP_INTRAREG>/MOVIES/ directory, with the same hierarchy than under /path/to/experiment. E.g.,

EXP_FUSE = ['1', '2']

in the parameter file results in

/path/to/experiment/
├── ...
├── FUSE/
│  ├── FUSE_1/
│  │   └── ...
│  └── FUSE_2/
│      └── ...
├── INTRAREG/
│  └── INTRAREG_<EXP_INTRAREG>/
│     ├── CO-TRSFS/
│     ├── FUSE/
│     │   ├── FUSE_1/
│     │   │   └── ...
│     │   └── FUSE_2/
│     │       └── ...
│     ├── MOVIES/
│     │   └── FUSE/
│     │       ├── FUSE_1/
│     │       │   └── ...
│     │       └── FUSE_2/
│     │           └── ...
│     ...
...

The same behavior stands for EXP_SEG and EXP_POST.

10.9. Step 6: 3D maximum over the 3D+t sequence

To set a cropping area valid for the whole resampled sequence, a maximum image can be built from the resampled temporal series. This is controlled by the following parameters:

# intra_registration_maximum_fusion_images = False
# intra_registration_maximum_segmentation_images = False
# intra_registration_maximum_post_segmentation_images = False

If intra_registration_maximum_fusion_images is set to True, a maximum image is computed over the sequence of resampled fusion images (recall that, after resampling, all images have the same geometry). The value of a voxel in this maximum image is the maximum value (over time) of this voxel in the sequence.

The maximum image will be stored in the INTRAREG/INTRAREG_<EXP_INTRAREG>/MAXIMUM/ directory, with the same hierarchy than under /path/to/experiment. E.g.,

EXP_FUSE = ['1', '2']

in the parameter file results in

/path/to/experiment/
├── ...
├── FUSE/
│  ├── FUSE_1/
│  │   └── ...
│  └── FUSE_2/
│      └── ...
├── INTRAREG/
│  └── INTRAREG_<EXP_INTRAREG>/
│     ├── CO-TRSFS/
│     ├── FUSE/
│     │   ├── FUSE_1/
│     │   │   └── ...
│     │   └── FUSE_2/
│     │       └── ...
│     ├── MAXIMUM/
│     │   └── FUSE/
│     │       ├── FUSE_1/
│     │       │   └── ...
│     │       └── FUSE_2/
│     │           └── ...
│     ...
...

The same behavior stands for EXP_SEG and EXP_POST.

10.10. Intra-registration / parameter file examples

10.10.1. Intra-registration of fusion images

PATH_EMBRYO = "/path/to/experiment/"
EN = "embryo-name"

EXP_FUSE = ['1', '2']
first_time_point = 0
last_time_point = 199

movie_fusion_images = True

resolution = 0.45
template_type = 'FUSION'
template_threshold = 140

will co-register pairs of successive images in FUSE/FUSE_1, compose these transformations to compensate the drift for the whole sequence and resample both the images from FUSE/FUSE_1 and FUSE/FUSE_2. The resulting image geometry ensures that all voxels with a value larger than 140 from FUSE/FUSE_1 images (value given by template_threshold) will be included into the resampled images. A movie is generated from the XY-sections located at the middle of each resampled fusion image to qualitatively assess the fusion quality for the whole sequence.

Note

If no threshold is given by template_threshold, all points of the FUSE/FUSE_1 images will be included into the resampled images, meaning that the resulting image geometry can be quite large. It is then advised to use either segmentation or post-correction images as template.

10.10.2. Intra-registration of segmentation images

PATH_EMBRYO = "/path/to/experiment/"
EN = "embryo-name"

EXP_FUSE = '1'
EXP_SEG = 'RELEASE'
first_time_point = 0
last_time_point = 199

movie_fusion_images = True
movie_segmentation_images = True

resolution = 0.45
template_type = 'SEGMENTATION'
template_threshold = 2
registration_margin = 20

will co-register pairs of successive images in FUSE/FUSE_1, compose these transformations to compensate the drift for the whole sequence and resample both the images from FUSE/FUSE_1 and SEG/SEG_RELEASE. The resulting image geometry ensures that all voxels with a value larger than 2 from FUSE/FUSE_1 images (value given by template_threshold) will be included into the resampled images (recall that the background is encoded by 1), with an extra margin of 20. A movie is generated from the XY-sections located at the middle of each resampled fusion/segmentation image.

10.10.3. Intra-registration of post-segmentation images

PATH_EMBRYO = "/path/to/experiment/"
EN = "embryo-name"

EXP_FUSE = '1'
EXP_POST = 'RELEASE'
first_time_point = 0
last_time_point = 199

movie_fusion_images = True
movie_post_segmentation_images = True

resolution = 0.45
template_type = 'POST-SEGMENTATION'
template_threshold = 2
registration_margin = 20