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"

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_aligned_averages (Bproject project, Bimage pgr, Bstring &imgfile, DataType datatype, Bstring &subset)
	Calculates aligned micrograph images and write them to a file. More...

double	project_write_aligned_images (Bproject project, Bimage pgr, Bstring &imgfile, DataType datatype)
	Calculates aligned micrograph images and write them to a file. More...

double	project_write_frame_sums (Bproject project, Bimage pgr, DataType datatype, Bstring &subset, double sampling_ratio, int flag)
	Sums aligned micrograph frames and write them to files. More...

double	project_align_frames (Bproject project, int ref_img, long window, long step, Bimage pgr, Bimage *pmask, Vector3< double > origin, double hi_res, double lo_res, double shift_limit, double edge_width, double gauss_width, long bin, 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, long bin, Bstring &subset, int flag)
	Aligns a series of micrographs by cross-correlation. More...

Bimage *	mg_tomo_reconstruct2D (Bproject *project, long dimg, Vector3< long > size, double scale, double hi_res)
	Reconstructs the zero-tilt image of a tilt-series. 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)
	Aligns a series of micrographs by cross-correlation sequentially. More...

double	project_ssnr (Bproject *project)

int	project_frames_snr (Bproject *project, double res_hi, long window, Bstring &subset, double sampling_ratio, int flag)
	Calculates the estimated SNR from aligned movie frames. More...

int	project_frame_shift_analysis (Bproject *project, long window, double resolution)
	Calculates the estimated SNR from aligned movie frames. More...

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: 20211004

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.

◆ 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.

◆ 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.

◆ 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.

◆ 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.

◆ mg_tomo_reconstruct2D()

Bimage * mg_tomo_reconstruct2D	(	Bproject *	project,
		long	dimg,
		Vector3< long >	size,
		double	scale,
		double	hi_res
	)

Reconstructs the zero-tilt image of a tilt-series.

Parameters

*project	project parameter structure.
dimg	number of adjacent images in reconstructions.
size	reconstruction size.
scale	reconstruction scale.
hi_res	high resolution limit (angstrom).

Returns: Bimage* new 2D image.

◆ project_align_frames()

double project_align_frames	(	Bproject *	project,
		int	ref_img,
		long	window,
		long	step,
		Bimage *	pgr,
		Bimage *	pmask,
		Vector3< double >	origin,
		double	hi_res,
		double	lo_res,
		double	shift_limit,
		double	edge_width,
		double	gauss_width,
		long	bin,
		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).
window	moving sum window (default 1, no moving sum).
step	moving sum interval (default 1).
*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	integer bin factor.
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".
16  initial alignment: local rather than progressive.

◆ 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,
		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".

◆ project_frame_shift_analysis()

int project_frame_shift_analysis	(	Bproject *	project,
		long	window,
		double	resolution
	)

Calculates the estimated SNR from aligned movie frames.

Parameters

*project	project parameter structure.
window	number of frames to sum for each curve.
resolution	resolution for calculating envelope.

Returns

int 0, <0 on failure.

The SNR is calculated as for reconstructions.

◆ project_frames_snr()

int project_frames_snr	(	Bproject *	project,
		double	res_hi,
		long	window,
		Bstring &	subset,
		double	sampling_ratio,
		int	flag
	)

Calculates the estimated SNR from aligned movie frames.

Parameters

*project	project parameter structure.
res_hi	high resolution limit.
window	number of frames to sum for each curve.
&subset	subset to average (all if empty).
sampling_ratio	radial sampling ratio (1 or larger).
flag	flag to convert to counts (1) and calculate a progressive sum (2), filter extremes (4).

Returns

int 0, <0 on failure.

The SNR is calculated as for reconstructions.

◆ project_ssnr()

double project_ssnr ( Bproject * project )

◆ 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
	)

Aligns a series of micrographs by cross-correlation sequentially.

Parameters

*project	project parameter structure.
thickness	reconstruction thickness.
iter	number of alignment iterations.
dchange	threshold change in origin.
dimg	number of adjacent images in reconstructions.
resolution	high resolution limit (angstrom).
shift_limit	limit on shift search (pixels).
edge_width	smoothing edge width.
gauss_width	smoothing edge decay.

Returns

long 0, <0 on failure.

Each pair of adjacent micrographs in the series is cross-correlated
and the relative shift determined. The relative shifts are adjusted
relative to the reference micrograph, defined as the one closest
to a zero degree tilt.
The images are stretched to compensate for tilt difference.
The relationship between an euler representation of the view and
the tilt axis and tilt angle is:
    tilt_axis = phi - 90 = - psi - 90
    tilt_angle = theta

◆ project_write_aligned_averages()

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

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)

Returns

double average SNR.

Only the origin is adjusted.

◆ project_write_aligned_images()

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

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.

Returns

double 0.

Only the origin is adjusted.

◆ project_write_frame_sums()

double project_write_frame_sums	(	Bproject *	project,
		Bimage *	pgr,
		DataType	datatype,
		Bstring &	subset,
		double	sampling_ratio,
		int	flag
	)

Sums aligned micrograph frames and write them to files.

Parameters

*project	micrograph project.
*pgr	gain reference.
datatype	output data type.
&subset	subset to average (all if empty).
sampling_ratio	radial sampling ratio (1 or larger).
flag	flag to calculate counts from histogram.

Returns

double average SNR.

Only the origin is adjusted.

Functions

Detailed Description

Function Documentation

◆ mg_align_coordinates()

◆ mg_align_feature_extraction()

◆ mg_align_micrographs()

◆ mg_apply_transform()

◆ mg_merge_focal_series()

◆ mg_tomo_reconstruct2D()

◆ project_align_frames()

◆ project_align_series()

◆ project_frame_shift_analysis()

◆ project_frames_snr()

◆ project_ssnr()

◆ project_tomo_align()

◆ project_write_aligned_averages()

◆ project_write_aligned_images()

◆ project_write_frame_sums()