Bsoft 2.1.4
Bernard's software package
mg_tomography.cpp File Reference

Functions to manage tomographic series of images. More...

#include "mg_processing.h"
#include "mg_tomography.h"
#include "mg_select.h"
#include "mg_img_proc.h"
#include "rwimg.h"
#include "matrix_linear.h"
#include "simplex.h"
#include "linked_list.h"
#include "utilities.h"
#include "timer.h"

Functions

int mg_marker_init (Bmicrograph *mg, Bmarker *model)
 Initializes markers from the reference. More...
 
int mg_marker_update (Bmicrograph *mg, Bmarker *model, Vector3< double > oriref, int update_location)
 Calculates the predicted positions of markers from the reference. More...
 
Vector3< double > mg_3D_location_from_marker (Vector3< double > loc, Vector3< double > ori3D, Matrix3 mat, Vector3< double > ori)
 
int mg_update_model (Bmicrograph *mg, Bmarker *model, Vector3< double > oriref)
 Fills in missing markers in the 3D model from micrograph markers. More...
 
Vector3< double > mg_location_from_3D_model (Vector3< double > loc3D, Matrix3 mat, Vector3< double > ori)
 Calculates the 2D location of a marker from a 3D model. More...
 
Vector3< double > mg_location_from_3D_model (Vector3< double > loc3D, Matrix3 mat, Vector3< double > ori, Vector3< double > scale)
 
Vector3< double > mg_location_from_3D_model (Vector3< double > loc3D, Vector3< double > ori3D, Matrix3 mat, Vector3< double > ori)
 
Vector3< double > mg_location_from_3D_model (Vector3< double > loc3D, Vector3< double > ori3D, Matrix3 mat, Vector3< double > ori, Vector3< double > scale)
 
Bimageimg_gold_particle (Vector3< long > size, double radius)
 Generates an image representing a gold particle. More...
 
Bmarkerimg_find_gold_particles (Bimage *p, int img_select, double radius, long edge, double cutoff)
 Finds gold particles in micrograph images. More...
 
int project_mass_normalize (Bproject *project, double avg, double std, int norm_type, DataType datatype, int setinputZslices, int setoutputZslices, double cutmin, double cutmax, double replace_threshold)
 Normalizes a set of images in a project to a desired average and standard deviation. More...
 
double lambda_R (Bsimplex &simp)
 
vector< double > simplex_fit_tilt_intensities (vector< double > &a, vector< double > &I)
 
Bplotproject_intensity_plot (Bproject *project)
 Transfers the micrograph intensities for a field into a plot. More...
 
double project_fit_intensities (Bproject *project, Bplot *plot, int flag)
 Determines the thickness to mean free path ratio from a tilt series. More...
 
double project_thickness_to_lambda_ratio (Bproject *project)
 Determines the thickness to mean free path ratio from a tilt series. More...
 
double project_lambda (Bproject *project, double thickness)
 Determines the mean free path from a tilt series and thickness. More...
 
double project_thickness (Bproject *project, double lambda)
 Determines the thickness from a tilt series and mean free path. More...
 
int project_sort_markers_by_id (Bproject *project)
 Sorts markers for each micrograph by ID number. More...
 
double project_tomo_residuals (Bproject *project, int show)
 Calculates the residuals for an alignment solution. More...
 
double mg_tomo_residuals (Bmicrograph *mg, Bmarker *model, Vector3< double > oriref)
 Calculates the residuals for an alignment solution of one micrograph. More...
 
double project_tomo_errors (Bproject *project)
 Analyzes marker errors. More...
 
int project_calculate_model (Bproject *project)
 Calculates the z-coordinates of the marker model. More...
 
int project_generate_markers (Bproject *project)
 Generates missing micrograph and model markers. More...
 
long img_erase_markers (Bimage *p, Bmarker *mark, double marker_radius)
 Erases or paints markers in an image. More...
 
Bimagemg_erase_markers (Bmicrograph *mg, double marker_radius)
 Erases or paints markers in micrographs. More...
 
int project_erase_markers (Bproject *project, double marker_radius)
 Erases or paints markers in micrographs. More...
 
int mg_reset_model (Bmicrograph *mg, Bmarker *model)
 Resets the model x and y coordinates from the zero-tilt micrograph. More...
 
long project_find_markers (Bproject *project, long edge, int add)
 Finds all markers in a project. More...
 
long mg_find_markers (Bmicrograph *mg, long edge, int add)
 Finds markers in a micrograph. More...
 
Bimagemg_composite_particle (Bmicrograph *mg, Vector3< long > size)
 Generates an average particle image from a micrograph. More...
 
long project_count_markers (Bproject *project)
 Counts the markers in a project hierarchy. More...
 
long project_show_markers (Bproject *project)
 Shows the markers in a project hierarchy. More...
 
long project_show_errors (Bproject *project, double error_cutoff)
 Shows the errors in marker coordinates in a project hierarchy. More...
 
long project_deselect_markers (Bproject *project, Bstring &deselect_list)
 Deletes selected markers in a project hierarchy. More...
 
long project_delete_markers (Bproject *project, Bstring &delete_list)
 Deletes selected markers in a project hierarchy. More...
 
long project_renumber_markers (Bproject *project)
 Renumbers the markers in a project hierarchy. More...
 
long project_mg_select (Bproject *project, Bstring &mg_select)
 Selects micrographs in a project hierarchy. More...
 
long project_mg_exclude (Bproject *project, Bstring &mg_exclude)
 Deselects micrographs in a project hierarchy. More...
 
int project_set_tilt_axis (Bproject *project, double tilt_axis)
 Sets the tilt axis angle in a project parameter structure. More...
 
int project_invert_tilt_axis (Bproject *project)
 Inverts the tilt axis in a project parameter structure. More...
 
int project_set_tilt_angles (Bproject *project, double tilt_start, double tilt_step)
 Sets the tilt and tilt axis angles in a project parameter structure. More...
 
int project_mg_tilt_to_matrix (Bproject *project)
 Sets the matrix from the tilt and axis angles for each micrograph. More...
 
int project_calculate_angles (Bproject *project)
 Calculates tilt and tilt axis angles from matrices in a project parameter structure. More...
 
int project_invert_matrices (Bproject *project)
 Inverts the micrograph matrices in a project parameter structure. More...
 
int project_mg_marker_select (Bproject *project, double fom)
 Selects markers. More...
 
int project_set_marker_radius (Bproject *project, double mark_radius)
 Sets the marker radius in a project parameter structure. More...
 
int project_check_markers (Bproject *project, int flags)
 Checks if the markers in a project parameter structure fall within micrographs. More...
 
int project_fix_markers (Bproject *project)
 Checks if the markers in a project parameter structure fall within micrographs. More...
 
int img_clear_extraneous_areas (Bimage *p, double tilt_axis, double tilt_angle, long thickness, double width)
 Clears extraneous areas from a micrograph. More...
 
int micrograph_clear_extraneous_areas (Bmicrograph *mg, Bimage *p, long thickness, double width)
 Clears extraneous areas from a micrograph. More...
 
int project_clear_extraneous_areas (Bproject *project, long thickness, double width)
 Clears areas from a tilt series not used in a reconstruction. More...
 
double project_marker_rotation_axis (Bproject *project)
 Determines the most likely rotation axis location for a tilt series. More...
 
int project_merge_rec_markers (Bproject *project)
 Merges the markers for two reconstructions. More...
 

Variables

int verbose
 

Detailed Description

Functions to manage tomographic series of images.

Author
Bernard Heymann
Date
Created: 20020416
Modified: 20200306

Function Documentation

◆ img_clear_extraneous_areas()

int img_clear_extraneous_areas ( Bimage p,
double  tilt_axis,
double  tilt_angle,
long  thickness,
double  width 
)

Clears extraneous areas from a micrograph.

Parameters
*pmicrograph image.
tilt_axistilt axis angle (radians).
tilt_angletilt angle (radians).
thicknessintended thickness of reconstruction.
widthedge smoothing width.
Returns
int 0.

◆ img_erase_markers()

long img_erase_markers ( Bimage p,
Bmarker mark,
double  marker_radius 
)

Erases or paints markers in an image.

Parameters
*pimage parameter structure.
*marklinked list of markers.
marker_radiusradius to mask out markers.
Returns
long number of markers erased.
Markers can be either erased to a background value or painted in with
a set value.

◆ img_find_gold_particles()

Bmarker * img_find_gold_particles ( Bimage p,
int  img_select,
double  radius,
long  edge,
double  cutoff 
)

Finds gold particles in micrograph images.

Parameters
*pimage.
img_selectselected subimage, -1 if all.
radiusgold particle radius in voxel units.
edgeedge width to eliminate particles.
cutoffFOM cutoff, if 0 then half of maximum FOM.
Returns
Bmarker* list of markers.
An image of the size of an input sub-image is generated with a gold
particle (black or negative density) at its center.
Each sub-image is cross-correlated with the gold particle image
and the position within the image reported.
The FOM cutoff is used to select cross-correlation peaks, except it
is reset for the following:
    cutoff == 0 ==> cutoff = FOMavg + FOMstd
    cutoff <  0 ==> cutoff = FOMmax/2

◆ img_gold_particle()

Bimage * img_gold_particle ( Vector3< long >  size,
double  radius 
)

Generates an image representing a gold particle.

Parameters
sizesize of image to generate.
radiusgold particle radius in voxel units.
Returns
Bimage* gold particle image.
An image of the size of an input sub-image is generated with a gold
particle (black or negative density) at its center.

◆ lambda_R()

double lambda_R ( Bsimplex simp)

◆ mg_3D_location_from_marker()

Vector3< double > mg_3D_location_from_marker ( Vector3< double >  loc,
Vector3< double >  ori3D,
Matrix3  mat,
Vector3< double >  ori 
)

◆ mg_composite_particle()

Bimage * mg_composite_particle ( Bmicrograph mg,
Vector3< long >  size 
)

Generates an average particle image from a micrograph.

Parameters
*mgmicrograph to extract marker images from.
sizesize of image.
Returns
Bimage* composite marker projection image.

◆ mg_erase_markers()

Bimage * mg_erase_markers ( Bmicrograph mg,
double  marker_radius 
)

Erases or paints markers in micrographs.

Parameters
*mgmicrograph parameter structure.
marker_radiusradius to mask out markers.
Returns
Bimage* new micrograph image with erased markers.
Markers can be either erased to a background value or painted in with
a set value.

◆ mg_find_markers()

long mg_find_markers ( Bmicrograph mg,
long  edge,
int  add 
)

Finds markers in a micrograph.

Parameters
*mgproject parameter structure.
edgeedge to exclude.
addflag to add rather than replace the markers.
Returns
long number of markers.
The markers are located by cross-correlation with a synthetic reference
whose size is defined by the marker radius. Markers close to the edge
are eliminated using the given edge size. The main intent is to find 
the seed for a 3D marker model in a zero degree tilt micrograph. 

◆ mg_location_from_3D_model() [1/4]

Vector3< double > mg_location_from_3D_model ( Vector3< double >  loc3D,
Matrix3  mat,
Vector3< double >  ori 
)

Calculates the 2D location of a marker from a 3D model.

Parameters
loc3D3D marker location.
matmicrograph view matrix.
orimicrograph origin.
Returns
Vector3<double> transformed 2D marker location.

◆ mg_location_from_3D_model() [2/4]

Vector3< double > mg_location_from_3D_model ( Vector3< double >  loc3D,
Matrix3  mat,
Vector3< double >  ori,
Vector3< double >  scale 
)

◆ mg_location_from_3D_model() [3/4]

Vector3< double > mg_location_from_3D_model ( Vector3< double >  loc3D,
Vector3< double >  ori3D,
Matrix3  mat,
Vector3< double >  ori 
)

◆ mg_location_from_3D_model() [4/4]

Vector3< double > mg_location_from_3D_model ( Vector3< double >  loc3D,
Vector3< double >  ori3D,
Matrix3  mat,
Vector3< double >  ori,
Vector3< double >  scale 
)

◆ mg_marker_init()

int mg_marker_init ( Bmicrograph mg,
Bmarker model 
)

Initializes markers from the reference.

Parameters
*mgmicrograph to initialize.
*modelmarker model.
Returns
int 0.

◆ mg_marker_update()

int mg_marker_update ( Bmicrograph mg,
Bmarker model,
Vector3< double >  oriref,
int  update_location 
)

Calculates the predicted positions of markers from the reference.

Parameters
*mgmicrograph to update.
*modelmarker model.
orirefreference origin.
update_locationflag to update location based on marker model.
Returns
int 0.
If the marker does not exist in the micrograph, a new one is generated.

◆ mg_reset_model()

int mg_reset_model ( Bmicrograph mg,
Bmarker model 
)

Resets the model x and y coordinates from the zero-tilt micrograph.

Parameters
*mgreference micrograph parameter structure.
*modelmodel marker list.
Returns
int markers selected in model.
Missing model markers are added in and excessive model markers deleted.

◆ mg_tomo_residuals()

double mg_tomo_residuals ( Bmicrograph mg,
Bmarker model,
Vector3< double >  oriref 
)

Calculates the residuals for an alignment solution of one micrograph.

Parameters
*mgmicrograph.
*modelmodel marker list.
orirefreference origin.
Returns
double average residual.
Requires the matrices in the micrograph structures to be defined.

◆ mg_update_model()

int mg_update_model ( Bmicrograph mg,
Bmarker model,
Vector3< double >  oriref 
)

Fills in missing markers in the 3D model from micrograph markers.

Parameters
*mgmicrograph to update.
*modelmarker model.
orirefreference origin.
Returns
int 0.
If the marker does not exist in the model, a new one is generated.

◆ micrograph_clear_extraneous_areas()

int micrograph_clear_extraneous_areas ( Bmicrograph mg,
Bimage p,
long  thickness,
double  width 
)

Clears extraneous areas from a micrograph.

Parameters
*mgmicrograph parameter structure.
*pmicrograph image.
thicknessintended thickness of reconstruction.
widthedge smoothing width.
Returns
int 0.

◆ project_calculate_angles()

int project_calculate_angles ( Bproject project)

Calculates tilt and tilt axis angles from matrices in a project parameter structure.

Parameters
*projectproject parameter structure.
Returns
int 0.
From each matrix, a quaternion is calculated, giving the tilt axis
and rotation angle.
The level angle is calculated as the arcsin of the z-coordinate of the axis.

◆ project_calculate_model()

int project_calculate_model ( Bproject project)

Calculates the z-coordinates of the marker model.

Parameters
*projectproject parameter structure.
Returns
int 0.
If the project does not have markers, it returns without any change.
If the reconstruction model is not defined, it is created.

◆ project_check_markers()

int project_check_markers ( Bproject project,
int  flags 
)

Checks if the markers in a project parameter structure fall within micrographs.

Parameters
*projectproject parameter structure.
flagsflags to modify actions.
Returns
int 0.
Markers outside the boundaries are dealt with based on the flags variable:
1   show markers outside the image boundaries.
2   set marker selections to zero.
4   set marker fom's to zero.
8   set marker errors to zero.

◆ project_clear_extraneous_areas()

int project_clear_extraneous_areas ( Bproject project,
long  thickness,
double  width 
)

Clears areas from a tilt series not used in a reconstruction.

Parameters
*projectproject parameter structure.
thicknessintended thickness of reconstruction.
widthedge smoothing width.
Returns
int 0.

◆ project_count_markers()

long project_count_markers ( Bproject project)

Counts the markers in a project hierarchy.

Parameters
*projectproject parameter structure.
Returns
long number of markers.

◆ project_delete_markers()

long project_delete_markers ( Bproject project,
Bstring delete_list 
)

Deletes selected markers in a project hierarchy.

Parameters
*projectproject parameter structure.
&delete_listlist of markers to deselect.
Returns
long number of markers.
All the occurrences of selected markers in the tilt series are deleted.

◆ project_deselect_markers()

long project_deselect_markers ( Bproject project,
Bstring deselect_list 
)

Deletes selected markers in a project hierarchy.

Parameters
*projectproject parameter structure.
&deselect_listlist of markers to deselect.
Returns
long number of markers.
All the occurrences of selected markers in the tilt series are deleted.

◆ project_erase_markers()

int project_erase_markers ( Bproject project,
double  marker_radius 
)

Erases or paints markers in micrographs.

Parameters
*projectproject parameter structure.
marker_radiusradius to mask out markers.
Returns
int 0, <0 on error.
Markers can be either erased to a background value or painted in with
a set value.

◆ project_find_markers()

long project_find_markers ( Bproject project,
long  edge,
int  add 
)

Finds all markers in a project.

Parameters
*projectproject parameter structure.
edgeedge to exclude.
addflag to add rather than replace the markers.
Returns
long number of markers.
Markers are located in each micrograph by cross-correlation.

◆ project_fit_intensities()

double project_fit_intensities ( Bproject project,
Bplot plot,
int  flag 
)

Determines the thickness to mean free path ratio from a tilt series.

Parameters
*projectproject structure.
*plotplot structure with intensity-tilt data.
flagflag to apply tilt angle adjustment.
Returns
double ratio.
The micrographs should be unmodified gain-corrected images obtained from the detector.

◆ project_fix_markers()

int project_fix_markers ( Bproject project)

Checks if the markers in a project parameter structure fall within micrographs.

Parameters
*projectproject parameter structure.
Returns
int 0.

◆ project_generate_markers()

int project_generate_markers ( Bproject project)

Generates missing micrograph and model markers.

Parameters
*projectproject parameter structure.
Returns
int 0, <0 on error.
First the 3D model is updated to represent all markers from all micrographs.
Then the missing markers in the micrographs are generated from the
updated model.

◆ project_intensity_plot()

Bplot * project_intensity_plot ( Bproject project)

Transfers the micrograph intensities for a field into a plot.

Parameters
*projectproject structure.
Returns
Bplot* plot structure.
The micrographs should be unmodified gain-corrected images obtained from the detector.

◆ project_invert_matrices()

int project_invert_matrices ( Bproject project)

Inverts the micrograph matrices in a project parameter structure.

Parameters
*projectproject parameter structure.
Returns
int 0.
The tilt axis angle for all the micrographs are set to the same value.

◆ project_invert_tilt_axis()

int project_invert_tilt_axis ( Bproject project)

Inverts the tilt axis in a project parameter structure.

Parameters
*projectproject parameter structure.
Returns
int 0.
The tilt axis angle for all the micrographs are set to the same value.

◆ project_lambda()

double project_lambda ( Bproject project,
double  thickness 
)

Determines the mean free path from a tilt series and thickness.

Parameters
*projectproject structure.
thicknesstomogram thickness (in angstrom).
Returns
double ratio.
The micrographs should be unmodified gain-corrected images obtained from the detector.

◆ project_marker_rotation_axis()

double project_marker_rotation_axis ( Bproject project)

Determines the most likely rotation axis location for a tilt series.

Parameters
*projectproject parameter structure.
Returns
double average z offset from marker z average.
All micrographs must have associated markers.

◆ project_mass_normalize()

int project_mass_normalize ( Bproject project,
double  avg,
double  std,
int  norm_type,
DataType  datatype,
int  setinputZslices,
int  setoutputZslices,
double  cutmin,
double  cutmax,
double  replace_threshold 
)

Normalizes a set of images in a project to a desired average and standard deviation.

Parameters
*projectproject structure.
avgdesired average.
stddesired standard deviation (if 0, use defaults).
norm_typetype of determining the effective average and standard deviation: 0=simple, 1=Gaussian, 2=Poisson.
datatypedata type for normalized images.
setinputZslicesconvert z-slices in the input to 2D images.
setoutputZslicesconvert output image back to z-slices.
cutmintruncate to minimum.
cutmaxtruncate to maximum.
replace_thresholdreplace maxima above this threshold.
Returns
int 0, <0 on error.
The effective average and standard deviation for each image is obtained
in one of three ways:
    0.      The simple avergae and standard devaition for the image.
    1.      Gaussian fit of the histogram.
    2.      Poisson fit of the histogram.
A histogram of an image is calculated with a given number of bins.
The histogram is fit to a Gaussian or Poisson function with exclusion of a
small number of bins in the histogram (defined as outliers).
The effective average and standard deviation are used to 
rescale the data for each image.

◆ project_merge_rec_markers()

int project_merge_rec_markers ( Bproject project)

Merges the markers for two reconstructions.

Parameters
*projectproject parameter structure.
Returns
int number of markers merged.
The reconstructions must have corresponding markers.
The marker locations are set to the average of the two.
The second reconstruction is removed.

◆ project_mg_exclude()

long project_mg_exclude ( Bproject project,
Bstring mg_exclude 
)

Deselects micrographs in a project hierarchy.

Parameters
*projectproject parameter structure.
&mg_excludelist of micrograph numbers.
Returns
long number of micrographs excluded.

◆ project_mg_marker_select()

int project_mg_marker_select ( Bproject project,
double  fom 
)

Selects markers.

Parameters
*projectproject parameter structure.
fomfom cutoff.
Returns
int 0.
Selects all micrograph markers above the given fom cutoff.

◆ project_mg_select()

long project_mg_select ( Bproject project,
Bstring mg_select 
)

Selects micrographs in a project hierarchy.

Parameters
*projectproject parameter structure.
&mg_selectlist of micrograph numbers.
Returns
long number of micrographs selected.
A micrograph is only selected when it has its selection already set
and it is in the list of numbers.

◆ project_mg_tilt_to_matrix()

int project_mg_tilt_to_matrix ( Bproject project)

Sets the matrix from the tilt and axis angles for each micrograph.

Parameters
*projectproject parameter structure.
Returns
int 0.
This is in preparation for reconstruction.

◆ project_renumber_markers()

long project_renumber_markers ( Bproject project)

Renumbers the markers in a project hierarchy.

Parameters
*projectproject parameter structure.
Returns
long number of markers.
The markers are assumed to correspond across micrographs and reconstructions.
The existing marker ids are mapped to an array, and new marker ids generated.

◆ project_set_marker_radius()

int project_set_marker_radius ( Bproject project,
double  mark_radius 
)

Sets the marker radius in a project parameter structure.

Parameters
*projectproject parameter structure.
mark_radiusgold fiducial marker radius (voxels).
Returns
int 0.

◆ project_set_tilt_angles()

int project_set_tilt_angles ( Bproject project,
double  tilt_start,
double  tilt_step 
)

Sets the tilt and tilt axis angles in a project parameter structure.

Parameters
*projectproject parameter structure.
tilt_startstarting tilt angle (usually negative).
tilt_steptilt increment angle.
Returns
int 0.
The single tilt series is defined by a starting tilt angle and a
tilt increment angle, as well as the tilt axis angle.

◆ project_set_tilt_axis()

int project_set_tilt_axis ( Bproject project,
double  tilt_axis 
)

Sets the tilt axis angle in a project parameter structure.

Parameters
*projectproject parameter structure.
tilt_axistilt axis angle (wrt x-axis).
Returns
int 0.
The tilt axis angle for all the micrographs are set to the same value.

◆ project_show_errors()

long project_show_errors ( Bproject project,
double  error_cutoff 
)

Shows the errors in marker coordinates in a project hierarchy.

Parameters
*projectproject parameter structure.
error_cutoffthreshold to show errors (distance in pixels).
Returns
long number of errors above threshold.

◆ project_show_markers()

long project_show_markers ( Bproject project)

Shows the markers in a project hierarchy.

Parameters
*projectproject parameter structure.
Returns
long number of markers.

◆ project_sort_markers_by_id()

int project_sort_markers_by_id ( Bproject project)

Sorts markers for each micrograph by ID number.

Parameters
*projectmicrograph project.
Returns
int 0.
Requires the matrices in the micrograph structures to be defined.

◆ project_thickness()

double project_thickness ( Bproject project,
double  lambda 
)

Determines the thickness from a tilt series and mean free path.

Parameters
*projectproject structure.
lambdaproportionality parameter (in angstrom).
Returns
double ratio.
The micrographs should be unmodified gain-corrected images obtained from the detector.

◆ project_thickness_to_lambda_ratio()

double project_thickness_to_lambda_ratio ( Bproject project)

Determines the thickness to mean free path ratio from a tilt series.

Parameters
*projectproject structure.
Returns
double ratio.
The micrographs should be unmodified gain-corrected images obtained from the detector.

◆ project_tomo_errors()

double project_tomo_errors ( Bproject project)

Analyzes marker errors.

Parameters
*projectmicrograph project.
Returns
double 0.
Requires the marker errors to be calculated.

◆ project_tomo_residuals()

double project_tomo_residuals ( Bproject project,
int  show 
)

Calculates the residuals for an alignment solution.

Parameters
*projectmicrograph project.
showflag to indicate showing lists.
Returns
double average residual.
Requires the matrices in the micrograph structures to be defined.

◆ simplex_fit_tilt_intensities()

vector< double > simplex_fit_tilt_intensities ( vector< double > &  a,
vector< double > &  I 
)

Variable Documentation

◆ verbose

int verbose
extern