Functions to track fiducial markers in a tomographic series of images. More...

#include "Bimage.h"
#include "mg_tomography.h"
#include "mg_tomo_track.h"
#include "mg_select.h"
#include "mg_img_proc.h"
#include "linked_list.h"
#include "qsort_functions.h"
#include "random_numbers.h"
#include "utilities.h"
#include "timer.h"

Functions
int	mg_marker_z_search (Bmicrograph mg, Bmarker model, Vector3< double > oriref, Bimage pgold, double thickness, int cc_type, int iz, double z)

int	mg_z_matrix_update (Bmarker model, int nmg, int nmark, double z, double *w, int recenter)

double	fom_from_distance (double distance, double sigma)

int	marker_show (Bmarker m1, Bmarker m2)

Bimage *	img_marker_projection (Vector3< long > size, Vector3< double > offset, double radius, Bimage pmark, Bmarker mark)
	Generates a projection image of the global marker model. More...

double	mg_find_tilt_axis (Bmicrograph mgp, Bmicrograph mgn, Bmicrograph mg_ref, double axis_angle, Bimage pgold, double hi_res, double lo_res, double shift_limit, fft_plan planf, fft_plan planb)

double	project_find_tilt_axis (Bproject *project, double tilt, double axis_start, double axis_end, double axis_step, double hi_res, double lo_res, double shift_limit)
	Finds the tilt axis for a tomographic tilt series. More...

int	project_track_markers (Bproject *project, double hi_res, double lo_res, double shift_limit, double thickness, int max_cycle, double target, int cc_type, int recenter, Bstring paramfile)
	Aligns markers in a tomographic series. More...

int	project_track_markers_dual (Bproject *project, double hi_res, double lo_res, double shift_limit, double thickness, int max_cycle, double target, int cc_type, int recenter, Bstring paramfile)
	Aligns markers in a tomographic series. More...

double	marker_refine (Bmarker mark, Bmarker marklist, Bimage p, Bimage pgold, double radius, double hi_res, double lo_res)

int	project_refine_markers (Bproject *project, double hi_res, double lo_res)
	Refines marker positions in a tomographic series. More...

int	project_refine_one_marker (Bproject *project, int id, double hi_res, double lo_res)
	Refines marker positions in a tomographic series. More...

int	mg_refine_markers (Bmicrograph mg, Bimage pgold, double hi_res, double lo_res)
	Refines marker positions in a tomographic micrograph. More...

double	project_refine (Bproject *project, int iter, double tol, Bstring refop)
	Refines all the alignment parameters. More...

double	tomo_z_residual (Bproject project, Bmarker mark)

double	project_refine_z (Bproject *project)
	Refines the z coordinates of the marker model. More...

double	project_refine (Bproject *project, int do_view, int do_origin, int do_scale)
	Refines the views from the marker positions and marker model. More...

Vector3< double >	fit_line (vector< Vector3< double > > d)

double	project_tilt_axis_from_markers (Bproject *project)
	Calculates the tilt axis from the marker trajectories. More...

double	mg_marker_shift (Bmicrograph mg, Bimage pgold, double hi_res, double lo_res, double shift_limit, fft_plan planf, fft_plan planb)
	Finds the shift of a micrograph wrt the reference using markers. More...

double	marker_fom (Bimage *p, Vector3< double > loc, double radius)

double	mg_marker_z_search_one (Bmicrograph mg, Bimage p, Bmarker modmark, Vector3< double > oriref, Bimage pgold, double thickness, int cc_type, int i, double *z, fft_plan planf, fft_plan planb)

int	project_transfer_seed (Bproject *project, double rot_start, double rot_end, double rot_step, double hi_res, double lo_res, double shift_limit)
	Transfers the seed markers from the first to the second project. More...

int	project_transform_dual (Bproject *project)
	Calculates the transformation of the second tilt series to fit the first. More...

double	project_dual_zcompare (Bproject *project)
	Lists two sets of Z coordinates for comparison. More...

Variables
int	verbose

Detailed Description

Functions to track fiducial markers in a tomographic series of images.

Author: Bernard Heymann

Date: Created: 20020416; Modified: 20210112

Function Documentation

◆ fit_line()

Vector3< double > fit_line ( vector< Vector3< double > > d )

◆ fom_from_distance()

double fom_from_distance	(	double	distance,
		double	sigma
	)

◆ img_marker_projection()

Bimage * img_marker_projection	(	Vector3< long >	size,
		Vector3< double >	offset,
		double	radius,
		Bimage *	pmark,
		Bmarker *	mark
	)

Generates a projection image of the global marker model.

Parameters

size	size of image.
offset	offset to add to marker locations.
radius	gold fiducial marker radius.
*pmark	average marker image (can be NULL).
*mark	list of markers.

Returns

Bimage* marker projection image.

If the input marker image is NULL, synthetic particle images are 
generated using the input radius.

◆ marker_fom()

double marker_fom	(	Bimage *	p,
		Vector3< double >	loc,
		double	radius
	)

◆ marker_refine()

double marker_refine	(	Bmarker *	mark,
		Bmarker *	marklist,
		Bimage *	p,
		Bimage *	pgold,
		double	radius,
		double	hi_res,
		double	lo_res
	)

◆ marker_show()

int marker_show	(	Bmarker *	m1,
		Bmarker *	m2
	)

◆ mg_find_tilt_axis()

double mg_find_tilt_axis	(	Bmicrograph *	mgp,
		Bmicrograph *	mgn,
		Bmicrograph *	mg_ref,
		double	axis_angle,
		Bimage *	pgold,
		double	hi_res,
		double	lo_res,
		double	shift_limit,
		fft_plan	planf,
		fft_plan	planb
	)

◆ mg_marker_shift()

double mg_marker_shift	(	Bmicrograph *	mg,
		Bimage *	pgold,
		double	hi_res,
		double	lo_res,
		double	shift_limit,
		fft_plan	planf,
		fft_plan	planb
	)

Finds the shift of a micrograph wrt the reference using markers.

Parameters

*mg	micrograph.
*pgold	marker reference image (can be NULL).
hi_res	high resolution limit for cross-correlation.
lo_res	low resolution limit for cross-correlation.
shift_limit	maximum micrograph shift to search for.
planf	FFT forward plan.
planb	FFT backward plan.

Returns

double correlation coefficient.

The marker locations and marker radius must already be set.
The correlation coefficient for the correlation between the micrograph
and the 2D image generated from the markers is retuned.

◆ mg_marker_z_search()

int mg_marker_z_search	(	Bmicrograph *	mg,
		Bmarker *	model,
		Vector3< double >	oriref,
		Bimage *	pgold,
		double	thickness,
		int	cc_type,
		int	iz,
		double *	z
	)

◆ mg_marker_z_search_one()

double mg_marker_z_search_one	(	Bmicrograph *	mg,
		Bimage *	p,
		Bmarker *	modmark,
		Vector3< double >	oriref,
		Bimage *	pgold,
		double	thickness,
		int	cc_type,
		int	i,
		double *	z,
		fft_plan	planf,
		fft_plan	planb
	)

◆ mg_refine_markers()

int mg_refine_markers	(	Bmicrograph *	mg,
		Bimage *	pgold,
		double	hi_res,
		double	lo_res
	)

Refines marker positions in a tomographic micrograph.

Parameters

*mg	micrograph.
*pgold	marker reference image (can be NULL).
hi_res	high resolution limit for cross-correlation.
lo_res	low resolution limit for cross-correlation.

Returns

int 0.

The area around a marker is extracted and cross-correlated with the
corresponding projection from the 3D marker model.

◆ mg_z_matrix_update()

int mg_z_matrix_update	(	Bmarker *	model,
		int	nmg,
		int	nmark,
		double *	z,
		double *	w,
		int	recenter
	)

◆ project_dual_zcompare()

double project_dual_zcompare ( Bproject * project )

Lists two sets of Z coordinates for comparison.

Author: Jessica Mavadia, Bernard Heymann

Parameters

*project project with two tilt series.

Returns

double root-mean-square-difference.

The root-mean-square-difference between the z coordinates is calculated.

◆ project_find_tilt_axis()

double project_find_tilt_axis	(	Bproject *	project,
		double	tilt,
		double	axis_start,
		double	axis_end,
		double	axis_step,
		double	hi_res,
		double	lo_res,
		double	shift_limit
	)

Finds the tilt axis for a tomographic tilt series.

Parameters

*project	project parameter structure.
tilt	user-chosen tilt angle to use (radians).
axis_start	starting tilt axis angle.
axis_end	ending tilt axis angle.
axis_step	tilt axis angle step size (radians).
hi_res	high resolution limit for cross-correlation.
lo_res	low resolution limit for cross-correlation.
shift_limit	maximum micrograph shift to search for.

Returns

double best correlation coefficient.

The zero-tilt reference marker set must be defined.
The micrographs closest to the positive and negative values of the
given tilt angle is selected to find the tilt axis.
The tilt axis for each of these micrographs is incremented from
-PI to PI, markers generated from the reference seed, and 
cross-correlated with the micrograph image.
The tilt axis angle giving the best cross-correlation is chosen
and assigned to all the micrographs.
The markers for the chosen tilted micrographs are deleted.

◆ project_refine() [1/2]

double project_refine	(	Bproject *	project,
		int	do_view,
		int	do_origin,
		int	do_scale
	)

Refines the views from the marker positions and marker model.

Parameters

*project	micrograph project.
do_view	refine micrograph views.
do_origin	refine micrograph origins.
do_scale	refine micrograph scales.

Returns

double best residual.

Requires the matrices in the micrograph structures to be defined.

◆ project_refine() [2/2]

double project_refine	(	Bproject *	project,
		int	iter,
		double	tol,
		Bstring	refop
	)

Refines all the alignment parameters.

Parameters

*project	micrograph project.
iter	maximum number of iterations.
tol	tolerance for exit condition.
refop	string holding sequence of refinement operations.

Returns: double marker RMSD.

◆ project_refine_markers()

int project_refine_markers	(	Bproject *	project,
		double	hi_res,
		double	lo_res
	)

Refines marker positions in a tomographic series.

Parameters

*project	project parameter structure.
hi_res	high resolution limit for cross-correlation.
lo_res	low resolution limit for cross-correlation.

Returns

int 0, <0 on error.

The area around a marker is extracted and cross-correlated with the
corresponding projection from the 3D marker model.

◆ project_refine_one_marker()

int project_refine_one_marker	(	Bproject *	project,
		int	id,
		double	hi_res,
		double	lo_res
	)

Refines marker positions in a tomographic series.

Parameters

*project	project parameter structure.
id	marker identifier.
hi_res	high resolution limit for cross-correlation.
lo_res	low resolution limit for cross-correlation.

Returns

int 0, <0 on error.

The area around a marker is extracted and cross-correlated with the
corresponding projection from the 3D marker model.

◆ project_refine_z()

double project_refine_z ( Bproject * project )

Refines the z coordinates of the marker model.

Parameters

*project micrograph project.

Returns: double overall RMS change.

◆ project_tilt_axis_from_markers()

double project_tilt_axis_from_markers ( Bproject * project )

Calculates the tilt axis from the marker trajectories.

Parameters

*project micrograph project.

Returns

double best residual.

If the rotation is around a single axis, the trajectory of a marker should lie in a plane.

◆ project_track_markers()

int project_track_markers	(	Bproject *	project,
		double	hi_res,
		double	lo_res,
		double	shift_limit,
		double	thickness,
		int	max_cycle,
		double	target,
		int	cc_type,
		int	recenter,
		Bstring	paramfile
	)

Aligns markers in a tomographic series.

Parameters

*project	project parameter structure.
hi_res	high resolution limit for cross-correlation.
lo_res	low resolution limit for cross-correlation.
shift_limit	maximum micrograph shift to search for.
thickness	estimated tomogram thickness (angstrom).
max_cycle	maximum number of iterations.
target	target residual to terminate tracking.
cc_type	indicates type of marker correlation: 0=real space, 1=cross correlation
recenter	flag to recenter z coordinates.
paramfile	output parameter file name.

Returns

int 0, <0 on error.

From the fiducial marker seed in the zero-degree tilt image, the 
z coordinates of the markers as well as the image shift for 
each micrograph is determined. The algorithm first attempts to 
find the z-coordinate for each marker in an image by doing 
real space correlations along a line determined by the tilt direction. 
It then generates a projection image from the whole marker set at 
the nominal tilt angle and cross-correlates it with the image to 
find the shift. The process proceeds from the low-angle tilts to 
higher tilts in both directions, using the lower dependence of the 
low-tilt images on correct marker z-coordinates. This process is 
iterated (typically 2-5 times) until the change in z-coordinates drops
below one pixel on average or up to the maximum number of iterations. 
The resolution limits are used in the cross-correlations.
The shift limit prevents setting micrograph origin to far from the nominal origin.
The thickness determines the extent of searching for the z coordinate of a marker.

◆ project_track_markers_dual()

int project_track_markers_dual	(	Bproject *	project,
		double	hi_res,
		double	lo_res,
		double	shift_limit,
		double	thickness,
		int	max_cycle,
		double	target,
		int	cc_type,
		int	recenter,
		Bstring	paramfile
	)

Aligns markers in a tomographic series.

Parameters

*project	project parameter structure.
hi_res	high resolution limit for cross-correlation.
lo_res	low resolution limit for cross-correlation.
shift_limit	maximum micrograph shift to search for.
thickness	estimated tomogram thickness (angstrom).
max_cycle	maximum number of iterations.
target	target residual to terminate tracking.
cc_type	indicates type of marker correlation: 0=real space, 1=cross correlation
recenter	flag to recenter z coordinates.
paramfile	output parameter file name.

Returns

int 0, <0 on error.

From the fiducial marker seed in the zero-degree tilt image, the 
z coordinates of the markers as well as the image shift for 
each micrograph is determined. The algorithm first attempts to 
find the z-coordinate for each marker in an image by doing 
real space correlations along a line determined by the tilt direction. 
It then generates a projection image from the whole marker set at 
the nominal tilt angle and cross-correlates it with the image to 
find the shift. The process proceeds from the low-angle tilts to 
higher tilts in both directions, using the lower dependence of the 
low-tilt images on correct marker z-coordinates. This process is 
iterated (typically 2-5 times) until the change in z-coordinates drops
below one pixel on average or up to the maximum number of iterations. 
The resolution limits are used in the cross-correlations.
The shift limit prevents setting micrograph origin to far from the nominal origin.
The thickness determines the extent of searching for the z coordinate of a marker.

◆ project_transfer_seed()

int project_transfer_seed	(	Bproject *	project,
		double	rot_start,
		double	rot_end,
		double	rot_step,
		double	hi_res,
		double	lo_res,
		double	shift_limit
	)

Transfers the seed markers from the first to the second project.

Parameters

*project	project with seed markers in first field.
rot_start	starting rotation angle.
rot_end	final rotation angle.
rot_step	angular search step size.
hi_res	high resolution limit for cross-correlation.
lo_res	low resolution limit for cross-correlation.
shift_limit	maximum micrograph shift to search for.

Returns

int number of markers.

The markers from the first series are rotated around the micrograph
origin by the search angle. The markers are then used to generate
an image with synthetic markers, and this image is cross-correlated 
with the zero-tilt micrograph of the second series. The search angle
giving the best correlation coefficient is selected and the seed marker
locations for the second series are calculated.

◆ project_transform_dual()

int project_transform_dual ( Bproject * project )

Calculates the transformation of the second tilt series to fit the first.

Parameters

*project project with seed markers.

Returns

int number of markers compared.

The 3D marker coordinates from the second series are fitted to those
of the first series to determine the rotation matrix and shifts.
The 3D marker locations and the micrograph orientations and origins
of the second series are then adkjusted to correspond to the first.
Restrictions: The first two fields should contain the two tilt series
and the first two reconstructions the corresponding 3D marker sets.

◆ tomo_z_residual()

double tomo_z_residual	(	Bproject *	project,
		Bmarker *	mark
	)

Variable Documentation

◆ verbose

int verbose

extern

Functions

Variables

Detailed Description

Function Documentation

◆ fit_line()

◆ fom_from_distance()

◆ img_marker_projection()

◆ marker_fom()

◆ marker_refine()

◆ marker_show()

◆ mg_find_tilt_axis()

◆ mg_marker_shift()

◆ mg_marker_z_search()

◆ mg_marker_z_search_one()

◆ mg_refine_markers()

◆ mg_z_matrix_update()

◆ project_dual_zcompare()

◆ project_find_tilt_axis()

◆ project_refine() [1/2]

◆ project_refine() [2/2]

◆ project_refine_markers()

◆ project_refine_one_marker()

◆ project_refine_z()

◆ project_tilt_axis_from_markers()

◆ project_track_markers()

◆ project_track_markers_dual()

◆ project_transfer_seed()

◆ project_transform_dual()

◆ tomo_z_residual()

Variable Documentation

◆ verbose