mg_align.cpp File Reference

Functions to align micrographs or coordinates from micrographs and apply the resultant transformation. More...

#include "Bimage.h"
#include "mg_align.h"
#include "rwimg.h"
#include "mg_processing.h"
#include "mg_img_proc.h"
#include "mg_ctf_fit.h"
#include "mg_select.h"
#include "mg_tomography.h"
#include "marker.h"
#include "matrix_linear.h"
#include "simplex.h"
#include "ps_marker.h"
#include "linked_list.h"
#include "utilities.h"
#include <sys/stat.h>
#include <fstream>

Functions
int	mg_align_coordinates (Bproject *project, int refset)
	Aligns the particle coordinates of a series of micrographs. More...
Transform	img_align (Bimage *p1, Bimage *p2, Vector3< long > tile_size, double res_lo, double res_hi, double max_shift, int filter_flag, int refine_flag)
Bimage *	img_sum_subset (Bimage *p, Bstring &subset, double dose_per_frame, double time_per_frame)
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...
Bmarker *	img_extract_features (Bimage *p, int extract_method, int target_num, double threshold)
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	field_write_aligned_average (Bfield *field, Bimage *pgr, Bstring &imgfile, DataType datatype, Bstring &subset)
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_aligned_averages (Bproject *project, Bimage *pgr, Bstring &imgfile, DataType datatype, Bstring &subset)
	Calculates aligned micrograph images and write them to a file. More...
double	mg_write_frame_sum (Bmicrograph *mg, Bimage *pgr, DataType datatype, Bstring &subset, double sampling_ratio, int flag)
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	mg_align_frames (Bmicrograph *mg, long ref_num, long window, long step, Bimage *pgr, Bimage *pmask, double hi_res, double lo_res, double shift_limit, double edge_width, double gauss_width, long bin, Bstring &subset, int flag)
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	mg_align_series (Bmicrograph *mg, Bmicrograph *mg_ref, Bimage *pref, Bimage *pgr, Bimage *pmask, double hi_res, double lo_res, double shift_limit, double edge_width, double gauss_width, long bin, fft_plan planf, fft_plan planb)
double	field_align_series (Bfield *field, 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)
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_reconstruct (Bmicrograph **mgarr, long mg_id, long mg_min, long mg_max, double hi_res, double scale, Vector3< long > size, long ft_size, fft_plan planf, fft_plan planb)
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...
double	mg_reconstruct_align (Bmicrograph **mgarr, long nmg, long mg_id, long dimg, double resolution, double shift_limit, Vector3< long > size, double edge_width, double gauss_width, long ft_size, fft_plan planf, fft_plan planb)
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	field_ssnr (Bfield *field, fft_plan plan)
double	project_ssnr (Bproject *project)
double	progressive_snr_R (Bsimplex &simp)
double	fit_progressive_snr (vector< double > &x, vector< double > &y, double &snr, double &cd)
double	fit_individual_progressive_snr (Bplot *plot, vector< double > &minima, long nimg, double dose_per_subset)
double	progressive_snr_R2 (Bsimplex &simp)
double	fit_progressive_snr2 (vector< double > &x, vector< double > &y, double &snr, double &c)
double	fit_full_progressive_snr (Bplot *plot, vector< double > &minima, long nimg, double dose_per_subset)
int	img_filter_spikes (Bimage *p, double ratio)
int	mg_frames_snr (Bmicrograph *mg, double res_hi, long window, Bstring &subset, double sampling_ratio, int flag)
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	mg_frame_shift_analysis (Bmicrograph *mg, long window, double resolution)
int	project_frame_shift_analysis (Bproject *project, long window, double resolution)
	Calculates the estimated SNR from aligned movie frames. More...

Variables
int	verbose
Bstring	progsnr_file
Bstring	pssnr_curves

Detailed Description

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

field_align_series()

double field_align_series	(	Bfield *	field,
		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
	)

field_ssnr()

double field_ssnr	(	Bfield *	field,
		fft_plan	plan
	)

field_write_aligned_average()

double field_write_aligned_average	(	Bfield *	field,
		Bimage *	pgr,
		Bstring &	imgfile,
		DataType	datatype,
		Bstring &	subset
	)

fit_full_progressive_snr()

double fit_full_progressive_snr	(	Bplot *	plot,
		vector< double > &	minima,
		long	nimg,
		double	dose_per_subset
	)

fit_individual_progressive_snr()

double fit_individual_progressive_snr	(	Bplot *	plot,
		vector< double > &	minima,
		long	nimg,
		double	dose_per_subset
	)

fit_progressive_snr()

double fit_progressive_snr	(	vector< double > &	x,
		vector< double > &	y,
		double &	snr,
		double &	cd
	)

fit_progressive_snr2()

double fit_progressive_snr2	(	vector< double > &	x,
		vector< double > &	y,
		double &	snr,
		double &	c
	)

img_align()

Transform img_align	(	Bimage *	p1,
		Bimage *	p2,
		Vector3< long >	tile_size,
		double	res_lo,
		double	res_hi,
		double	max_shift,
		int	filter_flag,
		int	refine_flag
	)

img_extract_features()

Bmarker * img_extract_features	(	Bimage *	p,
		int	extract_method,
		int	target_num,
		double	threshold
	)

img_filter_spikes()

int img_filter_spikes	(	Bimage *	p,
		double	ratio
	)

img_sum_subset()

Bimage * img_sum_subset	(	Bimage *	p,
		Bstring &	subset,
		double	dose_per_frame,
		double	time_per_frame
	)

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_frames()

double mg_align_frames	(	Bmicrograph *	mg,
		long	ref_num,
		long	window,
		long	step,
		Bimage *	pgr,
		Bimage *	pmask,
		double	hi_res,
		double	lo_res,
		double	shift_limit,
		double	edge_width,
		double	gauss_width,
		long	bin,
		Bstring &	subset,
		int	flag
	)

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_align_series()

double mg_align_series	(	Bmicrograph *	mg,
		Bmicrograph *	mg_ref,
		Bimage *	pref,
		Bimage *	pgr,
		Bimage *	pmask,
		double	hi_res,
		double	lo_res,
		double	shift_limit,
		double	edge_width,
		double	gauss_width,
		long	bin,
		fft_plan	planf,
		fft_plan	planb
	)

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_frame_shift_analysis()

int mg_frame_shift_analysis	(	Bmicrograph *	mg,
		long	window,
		double	resolution
	)

mg_frames_snr()

int mg_frames_snr	(	Bmicrograph *	mg,
		double	res_hi,
		long	window,
		Bstring &	subset,
		double	sampling_ratio,
		int	flag
	)

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_reconstruct_align()

double mg_reconstruct_align	(	Bmicrograph **	mgarr,
		long	nmg,
		long	mg_id,
		long	dimg,
		double	resolution,
		double	shift_limit,
		Vector3< long >	size,
		double	edge_width,
		double	gauss_width,
		long	ft_size,
		fft_plan	planf,
		fft_plan	planb
	)

mg_tomo_reconstruct()

Bimage * mg_tomo_reconstruct	(	Bmicrograph **	mgarr,
		long	mg_id,
		long	mg_min,
		long	mg_max,
		double	hi_res,
		double	scale,
		Vector3< long >	size,
		long	ft_size,
		fft_plan	planf,
		fft_plan	planb
	)

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.

mg_write_frame_sum()

double mg_write_frame_sum	(	Bmicrograph *	mg,
		Bimage *	pgr,
		DataType	datatype,
		Bstring &	subset,
		double	sampling_ratio,
		int	flag
	)

progressive_snr_R()

double progressive_snr_R

(

Bsimplex &

simp

)

progressive_snr_R2()

double progressive_snr_R2

(

Bsimplex &

simp

)

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.

Variable Documentation

progsnr_file

Bstring progsnr_file

pssnr_curves

Bstring pssnr_curves

verbose

int verbose

extern