EMAN2

Fourier space 3D reconstruction The Fourier reconstructor is designed to work in an iterative fashion, where similarity ("quality") metrics are used to determine if a slice should be inserted into the 3D in each subsequent iteration. More...
#include <reconstructor.h>
Public Member Functions  
FourierPlaneReconstructor ()  
Default constructor calls load_default_settings()  
virtual  ~FourierPlaneReconstructor ()  
Deconstructor calls free_memory()  
virtual void  setup ()  
Setup the Fourier reconstructor
 
virtual void  setup_seed (EMData *seed, float seed_weight)  
Initialize the reconstructor with a seed volume.  
virtual EMData *  preprocess_slice (const EMData *const slice, const Transform &t=Transform())  
Preprocess the slice prior to insertion into the 3D volume this Fourier tranforms the slice and make sure all the pixels are in the right position it always returns a copy of the provided slice, so it should be deleted by someone eventually.  
virtual int  insert_slice (const EMData *const slice, const Transform &euler, const float weight)  
Insert a slice into a 3D volume, in a given orientation.  
virtual int  determine_slice_agreement (EMData *slice, const Transform &euler, const float weight=1.0, bool sub=true)  
Compares a slice to the current reconstruction volume and computes a normalization factor and quality.  
virtual EMData *  finish (bool doift=true)  
Get the reconstructed volume Normally will return the volume in realspace with the requested size.  
virtual void  clear ()  
clear the volume and tmp_data for use in Monte Carlo reconstructions  
virtual string  get_name () const  
Get the unique name of the reconstructor.  
virtual string  get_desc () const  
Get the one line description of the reconstructor.  
virtual TypeDict  get_param_types () const  
Get the parameter types of this object.  
Static Public Member Functions  
static Reconstructor *  NEW ()  
Factory incorporation uses the pointer of this function.  
Static Public Attributes  
static const string  NAME = "fourier_plane"  
Protected Member Functions  
virtual void  load_default_settings ()  
Load default settings.  
virtual void  free_memory ()  
Frees the memory owned by this object (but not parent objects) Deletes the FourierPixelInserter3D pointer.  
virtual void  load_inserter ()  
Load the pixel inserter based on the information in params.  
virtual void  do_insert_slice_work (const EMData *const input_slice, const Transform &euler, const float weight)  
A function to perform the nuts and bolts of inserting an image slice.  
virtual void  do_compare_slice_work (EMData *input_slice, const Transform &euler, float weight)  
A function to perform the nuts and bolts of comparing an image slice.  
virtual bool  pixel_at (const float &xx, const float &yy, const float &zz, float *dt)  
This is a mode2 pixel extractor.  
Protected Attributes  
FourierPixelInserter3D *  inserter  
A pixel inserter pointer which inserts pixels into the 3D volume using one of a variety of insertion methods.  
Private Member Functions  
FourierPlaneReconstructor (const FourierPlaneReconstructor &that)  
Disallow copy construction.  
FourierPlaneReconstructor &  operator= (const FourierPlaneReconstructor &)  
Disallow assignment. 
Fourier space 3D reconstruction The Fourier reconstructor is designed to work in an iterative fashion, where similarity ("quality") metrics are used to determine if a slice should be inserted into the 3D in each subsequent iteration.
The client creates a Fourier reconstructor to insert real images into a 3D volume. The return image is a real space image
This reconstructor is based on EMAN1's Fourier reconstructor with a handful of modifications including 1.  Fourier ring correlation (FRC) as opposed to the mean phase residual is used to estimate slice quality. The FRC of the slice in the 3D volume is determined  but the slice is removed from the 3D volume before doing this so the score reflects the extent to which the slice agrees with the contribution of the other slices in the 3D volume. The FRC is converted to SNR using the relationship described by Penczek ( Threedimensional spectral signal to noise ratio for a class of reconstruction algorithms, JSB 2002 138 (2446) ) FRC = S/(sqrt(S+N1)sqrt(S+N2)) Where N1 is the noise in the slice of the 3D volume and N2 is the noise in the image slice being inserted. We make the assumption that the noise in the 3D volume is 0 (N1=0) to get FRC^2 = SNR/(1+SNR) which gives a spectral SNR plot  we then divide each SNR value by the number of particles in the class average (seeing as SNR should scale linearly with the number of particles) to get the estimated SNR per contributing particle in this class average. If the particles that have been averaged are not homogenous this score should be low etc. The scaled SNR curve is then converted back to a FRC curve and integrated. This integral is the similarity metric, and depends on how far information extends to in Fourier space  typical values range from 0.05 to 0.2, but can vary substantially depending on the data.
2  Uses half of the memory used by EMAN1's equivalent reconstruction algorithm
Reconstructor* r = Factory<Reconstructor>::get("fourier", params); r>setup(); for k in 0:num_iterations1 // First do a round of slice quality (metric) determination  only possible if a 3D volume has // already been generated (k>0) if ( k > 0 ) // Determine the agreement of the slices with the previous reconstructed volume (in memory) for i in 0:num_slices1 r>determine_slice_agreement(image[i], image[i].euler_orientation); // Insert the slices into the 3D volume // Will decide not to insert the slice if the its "quality" is not good enough for i in 0:num_slices1 int failure = r>insert_slice(image[i], image[i].euler_orientation); if ( failure ) cout << "Slice was not inserted due to poor quality" << endl; // Get the resulting volume EMData* result = r>finish(); result>write_image("threed.mrc");
Definition at line 703 of file reconstructor.h.
EMAN::FourierPlaneReconstructor::FourierPlaneReconstructor  (  )  [inline] 
Default constructor calls load_default_settings()
Definition at line 709 of file reconstructor.h.
References load_default_settings().
Referenced by NEW().
{ load_default_settings(); }
virtual EMAN::FourierPlaneReconstructor::~FourierPlaneReconstructor  (  )  [inline, virtual] 
Deconstructor calls free_memory()
Definition at line 714 of file reconstructor.h.
References free_memory().
{ free_memory(); }
EMAN::FourierPlaneReconstructor::FourierPlaneReconstructor  (  const FourierPlaneReconstructor &  that  )  [private] 
Disallow copy construction.
void FourierPlaneReconstructor::clear  (  )  [virtual] 
clear the volume and tmp_data for use in Monte Carlo reconstructions
Reimplemented from EMAN::Reconstructor.
Definition at line 335 of file reconstructor.cpp.
{}
int FourierPlaneReconstructor::determine_slice_agreement  (  EMData *  slice, 
const Transform &  euler,  
const float  weight = 1.0 , 

bool  sub = true 

)  [virtual] 
Compares a slice to the current reconstruction volume and computes a normalization factor and quality.
Normalization and quality are returned via attributes set in the passed slice. You may freely mix calls to determine_slice_agreement with calls to insert_slice, but note that determine_slice_agreement can only use information from slices that have already been inserted. Attributes set in the slice are: reconstruct_norm the relative normalization factor which should be applied before inserting the slice reconstruct_qual a scaled quality factor (larger better) for this slice as compared to the existing reconstruction reconstruct_absqual the absolute (not scaled based on weight) quality factor comparing this slice to the existing reconstruction reconstruct_weight the summed weights from all voxels intersecting with the inserted slice, larger > more overlap with other slices
input_slice  The EMData slice to be compared 
euler  The orientation of the slice as a Transform object 
weight  A weighting factor for this slice, generally the number of particles in a classaverage. May be ignored by some reconstructors 
sub  Flag indicating whether to subtract the slice from the volume before comparing. May be ignored by some reconstructors 
NullPointerException  if the input EMData pointer is null 
ImageFormatException  if the image is complex as opposed to real 
Reimplemented from EMAN::Reconstructor.
Definition at line 339 of file reconstructor.cpp.
{ return 0; }
void FourierPlaneReconstructor::do_compare_slice_work  (  EMData *  input_slice, 
const Transform &  euler,  
float  weight  
)  [protected, virtual] 
A function to perform the nuts and bolts of comparing an image slice.
input_slice  the slice to insert into the 3D volume 
euler  a transform storing the slice euler angle 
Definition at line 340 of file reconstructor.cpp.
{}
void FourierPlaneReconstructor::do_insert_slice_work  (  const EMData *const  input_slice, 
const Transform &  euler,  
const float  weight  
)  [protected, virtual] 
A function to perform the nuts and bolts of inserting an image slice.
input_slice  the slice to insert into the 3D volume 
euler  a transform storing the slice euler angle 
weight  weighting factor for this slice (usually number of particles in a classaverage) 
Definition at line 338 of file reconstructor.cpp.
{}
EMData * FourierPlaneReconstructor::finish  (  bool  doift = true  )  [virtual] 
Get the reconstructed volume Normally will return the volume in realspace with the requested size.
The calling application is responsible for removing any padding.
doift  A flag indicating whether the returned object should be guaranteed to be in realspace (true) or should be left in whatever space the reconstructor generated 
Reimplemented from EMAN::Reconstructor.
Definition at line 342 of file reconstructor.cpp.
{ return NULL; }
void FourierPlaneReconstructor::free_memory  (  )  [protected, virtual] 
Frees the memory owned by this object (but not parent objects) Deletes the FourierPixelInserter3D pointer.
Reimplemented from EMAN::ReconstructorVolumeData.
Definition at line 331 of file reconstructor.cpp.
Referenced by ~FourierPlaneReconstructor().
{}
virtual string EMAN::FourierPlaneReconstructor::get_desc  (  )  const [inline, virtual] 
Get the one line description of the reconstructor.
Implements EMAN::FactoryBase.
Definition at line 792 of file reconstructor.h.
{ return "Reconstruction via direct Fourier methods using one of a variety of different kernels, most of which are Gaussian based"; }
virtual string EMAN::FourierPlaneReconstructor::get_name  (  )  const [inline, virtual] 
Get the unique name of the reconstructor.
Implements EMAN::FactoryBase.
Definition at line 785 of file reconstructor.h.
References NAME.
{ return NAME; }
virtual TypeDict EMAN::FourierPlaneReconstructor::get_param_types  (  )  const [inline, virtual] 
Get the parameter types of this object.
Implements EMAN::FactoryBase.
Definition at line 808 of file reconstructor.h.
References EMAN::EMObject::BOOL, EMAN::EMObject::INTARRAY, EMAN::TypeDict::put(), and EMAN::EMObject::STRING.
{ TypeDict d; d.put("size", EMObject::INTARRAY, "Required. The dimensions of the realspace output volume, including any padding (must be handled by the calling application). Assumed that apix x/y/z identical."); d.put("sym", EMObject::STRING, "Optional. The symmetry of the reconstructed volume, c?, d?, oct, tet, icos, h?. Default is c1, ie  an asymmetric object"); d.put("mode", EMObject::STRING, "Optional. Fourier pixel insertion mode name (nearest_neighbor, gauss_2, gauss_3, gauss_5, gauss_5_slow, gypergeom_5, experimental) gauss_2 is the default."); d.put("sqrtnorm", EMObject::BOOL, "Optional. When normalizing, additionally divides by the sqrt of the normalization factor to damp exaggerated features. Is this justifyable ? No idea (yet). Default is false."); d.put("verbose", EMObject::BOOL, "Optional. Toggles writing useful information to standard out. Default is false."); d.put("quiet", EMObject::BOOL, "Optional. If false, print verbose information."); return d; }
int FourierPlaneReconstructor::insert_slice  (  const EMData *const  slice, 
const Transform &  euler,  
const float  weight  
)  [virtual] 
Insert a slice into a 3D volume, in a given orientation.
slice  the image slice to be inserted into the 3D volume 
euler  Euler angle of this image slice. 
weight  A weighting factor for this slice, generally the number of particles in a classaverage. May be ignored by some reconstructors 
NullPointerException  if the input EMData pointer is null 
ImageFormatException  if the image is complex as opposed to real 
Reimplemented from EMAN::Reconstructor.
Definition at line 337 of file reconstructor.cpp.
{ return 0; }
void FourierPlaneReconstructor::load_default_settings  (  )  [protected, virtual] 
Load default settings.
Definition at line 330 of file reconstructor.cpp.
Referenced by FourierPlaneReconstructor().
{}
void FourierPlaneReconstructor::load_inserter  (  )  [protected, virtual] 
Load the pixel inserter based on the information in params.
Definition at line 332 of file reconstructor.cpp.
{}
static Reconstructor* EMAN::FourierPlaneReconstructor::NEW  (  )  [inline, static] 
Factory incorporation uses the pointer of this function.
Definition at line 800 of file reconstructor.h.
References FourierPlaneReconstructor().
{ return new FourierPlaneReconstructor(); }
FourierPlaneReconstructor& EMAN::FourierPlaneReconstructor::operator=  (  const FourierPlaneReconstructor &  )  [private] 
Disallow assignment.
bool FourierPlaneReconstructor::pixel_at  (  const float &  xx, 
const float &  yy,  
const float &  zz,  
float *  dt  
)  [protected, virtual] 
This is a mode2 pixel extractor.
xx,yy,zz  voxel coordinates (need not be integers) 
dt  float pointer with 3 floats allocated for returned complex value and weight sum 
Definition at line 341 of file reconstructor.cpp.
{ return false; }
EMData * FourierPlaneReconstructor::preprocess_slice  (  const EMData *const  slice, 
const Transform &  t = Transform() 

)  [virtual] 
Preprocess the slice prior to insertion into the 3D volume this Fourier tranforms the slice and make sure all the pixels are in the right position it always returns a copy of the provided slice, so it should be deleted by someone eventually.
slice  the slice to be prepocessed 
t  transform to be used for insertion 
InvalidValueException  when the specified padding value is less than the size of the images 
Reimplemented from EMAN::Reconstructor.
Definition at line 336 of file reconstructor.cpp.
{ return NULL; }
void FourierPlaneReconstructor::setup  (  )  [virtual] 
Setup the Fourier reconstructor
InvalidValueException  When one of the input parameters is invalid. 
Implements EMAN::Reconstructor.
Definition at line 333 of file reconstructor.cpp.
{}
void FourierPlaneReconstructor::setup_seed  (  EMData *  seed, 
float  seed_weight  
)  [virtual] 
Initialize the reconstructor with a seed volume.
This can be used to provide some 'default' value when there is missing data in Fourier space. The passed 'seed' must be of the appropriate padded size, must be in Fourier space, and the same EMData* object will be returned by finish(), meaning the Reconstructor is implicitly taking ownership of the object. However, in Python, this means the seed may be passed in without copying, as the same EMData will be coming back out at the end. The seed_weight determines how 'strong' the seed volume should be as compared to other inserted slices in Fourier space.
InvalidValueException  When one of the input parameters is invalid 
Reimplemented from EMAN::Reconstructor.
Definition at line 334 of file reconstructor.cpp.
{}
A pixel inserter pointer which inserts pixels into the 3D volume using one of a variety of insertion methods.
Definition at line 856 of file reconstructor.h.
const string FourierPlaneReconstructor::NAME = "fourier_plane" [static] 
Definition at line 820 of file reconstructor.h.
Referenced by get_name().