Functions to find particles (subtomograms) in a tomographic reconstruction. More...

#include "Bimage.h"
#include "mg_subtomo.h"
#include "mg_select.h"
#include "rwimg.h"
#include "mg_processing.h"
#include "linked_list.h"
#include "utilities.h"

Functions
Bparticle *	img_search_view (Bimage p, Bimage ptemp, Bimage *pmask, View view, double hires, double lores, double shiftlimit, double mindist, double threshold, int maxhits, int refinepeaks, fft_plan planf, fft_plan planb)

Bparticle *	img_refine_view (Bimage pcrop, Bimage ptemp, Bimage pmask, Bimage pmask2, View view, double hires, double lores, double shiftlimit, double shiftlimitz, double shiftlimitxy, double mindist, int refinepeaks, fft_plan planf, fft_plan planb)

long	reconstruction_search_subtomo (Breconstruction rec, Bimage p, Bimage ptemp, Bimage pmask, Bimage *pmask2, double alpha_step, double theta_step, double phi_step, double alpha_limit, double thetaphi_limit, double hires, double lores, double shiftlimit, double mindist, double threshold, int maxhits, Vector3< long > bin, Bsymmetry &sym, int refinepeaks, Bstring ccmax_file)

long	reconstruction_refine_subtomo (Breconstruction rec, Bimage p, Bimage ptemp, Bimage pmask, Bimage *pmask2, double alpha_step_orig, double theta_step_orig, double phi_step_orig, double alpha_limit_orig, double thetaphi_limit_orig, double hires, double lores, double shiftlimit_orig, double shiftlimitz_orig, double shiftlimitxy_orig, double mindist, Vector3< long > bin, Bsymmetry &sym, int iters, int refinepeaks, Bstring ccmax_file)
	Refines the view vectors for particles already in the project. More...

Bparticle *	img_find_refine_peaks (Bimage *pcc, View view, double shift_limit, double shift_along, double shift_orthogonal, double mindist, double threshold, int maxhits, int refinepeaks)
	Finds peaks in an image to the nearest voxel iteratively. More...

double	img_find_peak_subtomo (Bimage *p, View view, double shift, double shift_along, double shift_orthogonal)
	Finds the peak in an image to the nearest voxel. More...

Vector3< double >	closest_point_line (Vector3< double > p, Vector3< double > v, Vector3< double > w)
	Calculates the closest point on a line segment from a given point. More...

double	closest_point_line_distance2 (Vector3< double > p, Vector3< double > v, Vector3< double > w)
	Calculates the squared distance to the closest point on a line segment from a given point. More...

double	closest_point_disc_distance2 (Vector3< double > p, Vector3< double > q, View view, double radius)
	Calculates the squared distance to the closest point on a disc from a given point. More...

Sphere	locations_fit_sphere (Bparticle *part, int N, double Nstop)
	Least squares fit a sphere to 3D data (particle locations) More...

Variables
int	verbose

Detailed Description

Functions to find particles (subtomograms) in a tomographic reconstruction.

Author: Juha Huiskonen; Bernard Heymann

Date: Created: 20071010; Modified: 20120124 (BH); Modified: 20120308; Modified: 20120316; Modified: 20120528; Modified: 20121118 (fixed bug in img_divide_with_fom); Modified: 20150108 (BH) - incorporated into Bsoft; Modified: 20150806 (BH) Based on the code from img_find.c

Function Documentation

◆ closest_point_disc_distance2()

double closest_point_disc_distance2	(	Vector3< double >	p,
		Vector3< double >	q,
		View	view,
		double	radius
	)

Calculates the squared distance to the closest point on a disc from a given point.

Author: Juha Huiskonen

Parameters

p	point
q	centre point of the disc
view
radius

Returns

double squared distance to closest point

Checks whether projection of the point (p') falls on the disc. If yes, this is the closest point
Otherwise point on the circumference of the disc is the closest point.

◆ closest_point_line()

Vector3< double > closest_point_line	(	Vector3< double >	p,
		Vector3< double >	v,
		Vector3< double >	w
	)

Calculates the closest point on a line segment from a given point.

Author: Juha Huiskonen

Parameters

p	point
v	endpoint 1
w	endpoint 2

Returns

Vector3<double> closest point

Checks whether one of the end points is the closest point

◆ closest_point_line_distance2()

double closest_point_line_distance2	(	Vector3< double >	p,
		Vector3< double >	v,
		Vector3< double >	w
	)

Calculates the squared distance to the closest point on a line segment from a given point.

Author: Juha Huiskonen

Parameters

p	point
v	endpoint 1
w	endpoint 2

Returns

double squared distance to the closest point

Checks wether the closet point falls within the line segment. If not, one of the endpoints
is the closest point.

◆ img_find_peak_subtomo()

double img_find_peak_subtomo	(	Bimage *	p,
		View	view,
		double	shift,
		double	shift_along,
		double	shift_orthogonal
	)

Finds the peak in an image to the nearest voxel.

Author: Juha Huiskonen

Parameters

*p	image (not altered).
view	view of the particle to be refined
shift	radius of spherical or cylindrical search space (if < 0, default 1e30).
shift_along	additional shift allowed in the direction of the view vector.
shift_orthogonal	additional shift allowed orthogonal to the view vector.

Returns

double peak maximum.

An image is searched for the global maximum (typically used to find the shift vector in a cross-correlation map).
The peak vector is returned in the image origin in actual pixel coordinates (no wrapping).
The maximum is returned in the image FOM.

◆ img_find_refine_peaks()

Bparticle * img_find_refine_peaks	(	Bimage *	pcc,
		View	view,
		double	shift_limit,
		double	shift_along,
		double	shift_orthogonal,
		double	mindist,
		double	threshold,
		int	maxhits,
		int	refinepeaks
	)

Finds peaks in an image to the nearest voxel iteratively.

Author: Juha Huiskonen

Parameters

*pcc	cross correlation map (not altered).
view	view of the particle to be refined
shift_limit	radius of spherical or cylindrical search space (if < 0, default 1e30).
shift_along	additional shift allowed in the direction of the view vector.
shift_orthogonal	additional shift allowed orthogonal to the view vector.
mindist	2 * template radius: used for a spherical mask
threshold	threshold. if value is <0, only the global maximum is returned
maxhits
refinepeaks

Returns

Bparticle* list of peaks as particles.

After a maximum value is found, it is masked with a spherical mask and the next largest value
is found, until all the values are below the threshold .

◆ img_refine_view()

Bparticle * img_refine_view	(	Bimage *	pcrop,
		Bimage *	ptemp,
		Bimage *	pmask,
		Bimage *	pmask2,
		View	view,
		double	hires,
		double	lores,
		double	shiftlimit,
		double	shiftlimitz,
		double	shiftlimitxy,
		double	mindist,
		int	refinepeaks,
		fft_plan	planf,
		fft_plan	planb
	)

◆ img_search_view()

Bparticle * img_search_view	(	Bimage *	p,
		Bimage *	ptemp,
		Bimage *	pmask,
		View	view,
		double	hires,
		double	lores,
		double	shiftlimit,
		double	mindist,
		double	threshold,
		int	maxhits,
		int	refinepeaks,
		fft_plan	planf,
		fft_plan	planb
	)

◆ locations_fit_sphere()

Sphere locations_fit_sphere	(	Bparticle *	part,
		int	N,
		double	Nstop
	)

Least squares fit a sphere to 3D data (particle locations)

Author: Juha Huiskonen

Parameters

*part	particle
N	iterations
Nstop	stopping condition: tolerance in change of sphere center

Returns

Sphere fitted sphere struct

Algorithm by ImaginaryZ
From http://imaginaryz.blogspot.co.uk/2011/04/least-squares-fit-sphere-to-3d-data.html

All you have to do is define:

Error = Sum( |Position[n] - Center|^2 - Radius^2 )

Then define the squared error:

Squared Error = Sum( ( |Position[n] - Center|^2 - Radius^2 )^2 )

And solve the summation using a iterative method (like newtons, below) after pulling out the summation terms.
For example, if you do: Sum( (P.x[n] - Cx)^2 ) You get (after Expand):
Sum( P.x[n]^2 - 2*P.x[n]*Cx + Cx^2 )
And you can then split up the sum:
Sum( P.x[n]^2 ) + Sum( P.x[n] ) * -2*Cx + Cx * Nelements
Note you HAVE to ultimately divide the sums by Nelements

Note that "Center" is A,B,C (3D) and I use Rsq as Radius^2.

This method is not fast, but it converges, and the way the code is written it is independent of dataset size,
but you do have to compute a number of sums and products before running the algorithm.

Note this method is used to generate the equations used to compute linear and quadratic fits instantly, given you compute some sums first.

◆ reconstruction_refine_subtomo()

long reconstruction_refine_subtomo	(	Breconstruction *	rec,
		Bimage *	p,
		Bimage *	ptemp,
		Bimage *	pmask,
		Bimage *	pmask2,
		double	alpha_step_orig,
		double	theta_step_orig,
		double	phi_step_orig,
		double	alpha_limit_orig,
		double	thetaphi_limit_orig,
		double	hires,
		double	lores,
		double	shiftlimit_orig,
		double	shiftlimitz_orig,
		double	shiftlimitxy_orig,
		double	mindist,
		Vector3< long >	bin,
		Bsymmetry &	sym,
		int	iters,
		int	refinepeaks,
		Bstring	ccmax_file
	)

Refines the view vectors for particles already in the project.

Author: Juha Huiskonen

Parameters

*rec	reconstruction parameters.
*p	the image.
*ptemp	the template to be searched for.
*pmask	reciprocal space mask for cross-correlation (ignored if NULL).
*pmask2	real space mask for cross-correlation (ignored if NULL).
alpha_step_orig	angular step size around view vector (radians).
theta_step_orig	angular step size around view vector (radians).
phi_step_orig	angular step size around view vector (radians).
alpha_limit_orig	angular limit for refinement in alpha (radians).
thetaphi_limit_orig	angular limit for refinement in theta & phi (radians).
hires	high resolution limit.
lores	low resolution limit.
shiftlimit_orig	maximum shift from the original position (binned units).
shiftlimitz_orig	maximum z-shift from the original position (binned units).
shiftlimitxy_orig	maximum xy-shift from the original position (binned units).
mindist	minimun distance for cc peaks (binned units).
bin	binning for map, template and mask
*sym	symmetry to generate a list of views for search mode
iters	number of iterations in refine
refinepeaks	flag to run several iterations in refine
ccmax_file	file for cross-correlation map (max ccc for each position and rotation of the template)

Returns

double the best correlation coefficient.

The template is rotated and cross-correlated to find fits above the
    threshold.

◆ reconstruction_search_subtomo()

long reconstruction_search_subtomo	(	Breconstruction *	rec,
		Bimage *	p,
		Bimage *	ptemp,
		Bimage *	pmask,
		Bimage *	pmask2,
		double	alpha_step,
		double	theta_step,
		double	phi_step,
		double	alpha_limit,
		double	thetaphi_limit,
		double	hires,
		double	lores,
		double	shiftlimit,
		double	mindist,
		double	threshold,
		int	maxhits,
		Vector3< long >	bin,
		Bsymmetry &	sym,
		int	refinepeaks,
		Bstring	ccmax_file
	)

Variable Documentation

◆ verbose

int verbose

extern

Functions

Variables

Detailed Description

Function Documentation

◆ closest_point_disc_distance2()

◆ closest_point_line()

◆ closest_point_line_distance2()

◆ img_find_peak_subtomo()

◆ img_find_refine_peaks()

◆ img_refine_view()

◆ img_search_view()

◆ locations_fit_sphere()

◆ reconstruction_refine_subtomo()

◆ reconstruction_search_subtomo()

Variable Documentation

◆ verbose