| Bsoft 2.0.5 Bernard's software package

Functions
mg_align.h File Reference

Header file for functions to align micrographs or coordinates from micrographs and apply the resultant transformation. More...

`#include "mg_processing.h"`
`#include "Bimage.h"`
`#include "Vector3.h"`

Go to the source code of this file.

## Functions
int | mg_align_coordinates (Bproject *project, int refset)
| Aligns the particle coordinates of a series of micrographs. More...
int | mg_align_micrographs (Bproject *project, int refset, Vector3< long > tile_size, double res_lo, double res_hi, double max_shift, int filter_flag, int refine_flag)
| Aligns a focal series of micrographs. More...
int | mg_align_feature_extraction (Bproject *project, int max_features, double res_low, double res_high, double thresh, int extract_method)
| Aligns images by feature extraction. More...
int | mg_apply_transform (Bmicrograph *mg_ref, Bmicrograph *mg_apply)
| Applies a transformation to particle coordinates in a reference micrograph and writes them into an application micrograph structure. More...
int | mg_merge_focal_series (Bproject *project, int use_old_origins)
| Merges corresponding particle images in each focal series. More...
double | project_write_average_frames (Bproject *project, Bimage *pgr, Bstring &path, DataType datatype, Bstring &subset, Bstring &label)
| Calculates average micrograph frame images and write them to a file. More...
double | project_write_aligned_averages (Bproject *project, Bimage *pgr, Bstring &imgfile, DataType datatype, Bstring &subset, Bstring &label)
| Calculates aligned micrograph images and write them to a file. More...
double | project_write_aligned_images (Bproject *project, Bimage *pgr, Bstring &imgfile, DataType datatype, Bstring &label)
| Calculates aligned micrograph images and write them to a file. More...
double | project_align_frames (Bproject *project, int ref_img, Bimage *pgr, Bimage *pmask, Vector3< double > origin, double hi_res, double lo_res, double shift_limit, double edge_width, double gauss_width, Vector3< long > bin, JSvalue &dose_frac, Bstring &subset, int flag)
| Aligns a series of micrographs by cross-correlation. More...
double | project_align_series (Bproject *project, int ref_img, Bimage *pgr, Bimage *pmask, Vector3< double > origin, double hi_res, double lo_res, double shift_limit, double edge_width, double gauss_width, Vector3< long > bin, Bstring &subset, int flag)
| Aligns a series of micrographs by cross-correlation. More...
long | project_tomo_align (Bproject *project, long thickness, long iter, double dchange, long dimg, double resolution, double shift_limit, double edge_width, double gauss_width)
double | project_ssnr (Bproject *project)

## Detailed Description

Header file for functions to align micrographs or coordinates from micrographs and apply the resultant transformation.

Author
  Bernard Heymann and Samuel Payne

Date
  Created: 20000505
  Modified: 20191120 (BH)

Definition in file mg_align.h.

## Function Documentation

## ◆ mg_align_coordinates()

int mg_align_coordinates | ( | Bproject * | project,
|  | int | refset
| ) |  |

Aligns the particle coordinates of a series of micrographs.

Parameters

  *project | project parameter structure.
  refset | reference image or set of coordinates (-1 means undefined).

Returns
  int 0.

      The sets of micrograph coordinates of a focal series in an image
      processing parameter structure are fitted to each other, giving a
      rotation angle, and shifting and scaling in x and y for each pair
      of micrographs.
      There must be the same number of particles in each micrograph
      of a focal series.

Definition at line 38 of file mg_align.cpp.

## ◆ mg_align_feature_extraction()

int mg_align_feature_extraction | ( | Bproject * | project,
|  | int | max_features,
|  | double | res_low,
|  | double | res_high,
|  | double | thresh,
|  | int | extract_method
| ) |  |

Aligns images by feature extraction.

Author
  Samuel Payne

Parameters

  *project | the set of image parameters
  max_features | the maximum number of features to extract
  res_low | the low resolution limit
  res_high | the high resolution limit
  thresh | threshold used for feature extraction
  extract_method | method used for finding the center of particles

Returns
  int error code.

Calculates the transformation parameters for each set images, by picking features in the images and finding the best fit for the matching of the features.

The features are picked and returned using function img_extract_features(). The set of features is sent to find_transform_params() that finds the transformation parameters that relate the images to each other. The shift in xy directions, the scale in xy directions, and rotation angle is returned. The program works best if the images have at least 40 distinct features.

Definition at line 541 of file mg_align.cpp.

## ◆ mg_align_micrographs()

int mg_align_micrographs | ( | Bproject * | project,
|  | int | refset,
|  | Vector3< long > | tile_size,
|  | double | res_lo,
|  | double | res_hi,
|  | double | max_shift,
|  | int | filter_flag,
|  | int | refine_flag
| ) |  |

Aligns a focal series of micrographs.

Parameters

  *project | parameter structure.
  refset | reference image or set of coordinates (< 1 means undefined).
  tile_size | 3-valued vector for the size of sub-images.
  res_lo | low resolution limit for cross-correlation.
  res_hi | high resolution limit for cross-correlation.
  max_shift | maximum shift allowed (default 1/4 of tile).
  filter_flag | flag to filter micrograph extremes.
  refine_flag | flag to turn on refinement of shift.

Returns
  int 0, <0 on error.

      A series of micrograph images specified in an image processing
      parameter structure are aligned by segmented cross-correlation. The
      micrograph data blocks are assumed to be arranged with a series in
      consequent data blocks. The micrographs are segmented into tiles
      and the tile shifts with respect to each other determined by
      cross-correlation. The shifts are assumed to most accurately
      represent the displacement of the center of one tile with respect
      to the center of the corresponding tile in the other micrograph.
      The resultant sets of coordinates are fitted to each
      other, giving a 3-value shift vector, a 3-value scale vector,
      and a rotation angle for each pair of micrographs.
      A reference micrograph is chosen as:
          1.  the first micrograph with particle coordinates
          2.  otherwise, the first micrograph
      If coordinates are supplied for particles in the reference micrograph,
      the determined transformation parameters are applied and written into
      the other micrograph structures.

Definition at line 315 of file mg_align.cpp.

## ◆ mg_apply_transform()

int mg_apply_transform | ( | Bmicrograph * | mg_ref,
|  | Bmicrograph * | mg_apply
| ) |  |

Applies a transformation to particle coordinates in a reference micrograph and writes them into an application micrograph structure.

Parameters

  *mg_ref | micrograph used as reference.
  *mg_apply | micrograph to apply transformation to.

Returns
  int 0.

      The transformation parameters specified in the second micrograph
      are used.

Definition at line 630 of file mg_align.cpp.

## ◆ mg_merge_focal_series()

int mg_merge_focal_series | ( | Bproject * | project,
|  | int | use_old_origins
| ) |  |

Merges corresponding particle images in each focal series.

Parameters

  *project | project parameter structure.
  use_old_origins | flag to use old origins rather than cross-correlation.

Returns
  int error code.

Definition at line 762 of file mg_align.cpp.

## ◆ project_align_frames()

double project_align_frames | ( | Bproject * | project,
|  | int | ref_img,
|  | Bimage * | pgr,
|  | Bimage * | pmask,
|  | Vector3< double > | origin,
|  | double | hi_res,
|  | double | lo_res,
|  | double | shift_limit,
|  | double | edge_width,
|  | double | gauss_width,
|  | Vector3< long > | bin,
|  | JSvalue & | dose_frac,
|  | Bstring & | subset,
|  | int | flag
| ) |  |

Aligns a series of micrographs by cross-correlation.

Parameters

  *project | project parameter structure.
  ref_img | reference frame number (starts from 0).
  *pgr | gain reference.
  *pmask | reciprocal space mask, 0's and 1's.
  origin | tilt origin.
  hi_res | high resolution limit.
  lo_res | low resolution limit.
  shift_limit | maximum shift from nominal origin of image.
  edge_width | edge smoothing width (not done if 0).
  gauss_width | edge decay width.
  bin | 3-value vector of integer bin factors.
  dose_frac | dose fractionation parameters.
  subset | a subset to sum.
  flag | options flag.

Returns
  double root-mean-square of offsets.

      Each micrograph frame is cross-correlated with the reference
      frame and the shift determined.
      Options encoded in the flag:
      1   rescale image based on histogram.
      2   weigh by accumulated dose.
      4   write aligned frames with insert "_aln".
      8   write aligned frame sum with insert "_sum".

Definition at line 1307 of file mg_align.cpp.

## ◆ project_align_series()

double project_align_series | ( | Bproject * | project,
|  | int | ref_img,
|  | Bimage * | pgr,
|  | Bimage * | pmask,
|  | Vector3< double > | origin,
|  | double | hi_res,
|  | double | lo_res,
|  | double | shift_limit,
|  | double | edge_width,
|  | double | gauss_width,
|  | Vector3< long > | bin,
|  | Bstring & | subset,
|  | int | flag
| ) |  |

Aligns a series of micrographs by cross-correlation.

Parameters

  *project | project parameter structure.
  ref_img | reference micrograph number (starts from 0).
  *pgr | gain reference.
  *pmask | reciprocal space mask, 0's and 1's.
  origin | tilt origin.
  hi_res | high resolution limit.
  lo_res | low resolution limit.
  shift_limit | maximum shift from nominal origin of image.
  edge_width | edge smoothing width (not done if 0).
  gauss_width | edge decay width.
  bin | 3-value vector of integer bin factors.
  &subset | subset to average (all if empty)
  flag | options flag.

Returns
  double root-mean-square of offsets.

      Each micrograph in the series is cross-correlated with the reference
      micrograph and the shift determined.
      Options encoded in the flag:
      1   rescale image based on histogram.
      2   weigh by accumulated dose.
      4   write aligned frames with insert "_aln".
      8   write aligned frame sum with insert "_avg".

Definition at line 1532 of file mg_align.cpp.

## ◆ project_ssnr()

double project_ssnr | ( | Bproject * | project | ) |

Definition at line 1939 of file mg_align.cpp.

## ◆ project_tomo_align()

long project_tomo_align | ( | Bproject * | project,
|  | long | thickness,
|  | long | iter,
|  | double | dchange,
|  | long | dimg,
|  | double | resolution,
|  | double | shift_limit,
|  | double | edge_width,
|  | double | gauss_width
| ) |  |

Definition at line 1783 of file mg_align.cpp.

## ◆ project_write_aligned_averages()

double project_write_aligned_averages | ( | Bproject * | project,
|  | Bimage * | pgr,
|  | Bstring & | imgfile,
|  | DataType | datatype,
|  | Bstring & | subset,
|  | Bstring & | label
| ) |  |

Calculates aligned micrograph images and write them to a file.

Parameters

  *project | micrograph project.
  *pgr | gain reference.
  &imgfile | output image file name.
  datatype | output data type.
  &subset | subset to average (all if empty)
  &label | string to write into image headers.

Returns
  double average SNR.

      Only the origin is adjusted.

Definition at line 1122 of file mg_align.cpp.

## ◆ project_write_aligned_images()

double project_write_aligned_images | ( | Bproject * | project,
|  | Bimage * | pgr,
|  | Bstring & | imgfile,
|  | DataType | datatype,
|  | Bstring & | label
| ) |  |

Calculates aligned micrograph images and write them to a file.

Parameters

  *project | micrograph project.
  *pgr | gain reference.
  &imgfile | output image file name.
  datatype | output data type.
  &label | string to write into image headers.

Returns
  double 0.

      Only the origin is adjusted.

Definition at line 950 of file mg_align.cpp.

## ◆ project_write_average_frames()

double project_write_average_frames | ( | Bproject * | project,
|  | Bimage * | pgr,
|  | Bstring & | avgfile,
|  | DataType | datatype,
|  | Bstring & | subset,
|  | Bstring & | label
| ) |  |

Calculates average micrograph frame images and write them to a file.

Parameters

  *project | micrograph project.
  *pgr | gain reference.
  &avgfile | output path.
  datatype | output data type.
  &subset | subset to average (all if empty)
  &label | string to write into image headers.

Returns
  double average SNR.

Definition at line 1067 of file mg_align.cpp.