IMP logo
IMP Reference Guide  develop.182d9373c4,2021/04/12
The Integrative Modeling Platform
ProjectionFinder.h
Go to the documentation of this file.
1 /**
2  * \file IMP/em2d/ProjectionFinder.h
3  * \brief Coarse registration of 2D projections from a 3D volume
4  *
5  * Copyright 2007-2021 IMP Inventors. All rights reserved.
6 */
7 
8 #ifndef IMPEM2D_PROJECTION_FINDER_H
9 #define IMPEM2D_PROJECTION_FINDER_H
10 
11 #include <IMP/em2d/em2d_config.h>
13 #include "IMP/em2d/align2D.h"
14 #include "IMP/em2d/project.h"
17 #include "IMP/em2d/Image.h"
18 #include "IMP/em2d/scores2D.h"
20 #include "IMP/algebra/Vector3D.h"
21 #include "IMP/algebra/Vector2D.h"
22 #include "IMP/algebra/Rotation3D.h"
23 #include "IMP/algebra/Rotation2D.h"
24 #include "IMP/Pointer.h"
25 #include "IMP/Particle.h"
26 #include <string>
27 
28 IMPEM2D_BEGIN_NAMESPACE
29 
30 //! Methods for registration used by the finder
31 const unsigned int ALIGN2D_NO_PREPROCESSING = 0;
32 const unsigned int ALIGN2D_PREPROCESSING = 1;
33 const unsigned int ALIGN2D_WITH_CENTERS = 2;
34 
35 //! Parameters used by Em2DRestraint and ProjectionFinder.
36 class IMPEM2DEXPORT Em2DRestraintParameters : public ProjectingParameters {
37 
38  void init_defaults() {
39  coarse_registration_method = ALIGN2D_PREPROCESSING;
40  save_match_images = false;
41  optimization_steps = 5;
42  simplex_initial_length = 0.1;
43  simplex_minimum_size = 0.01;
44  }
45 
46  public:
47  //! Number of model projections to generate when scoring
48  unsigned int n_projections;
49  unsigned int coarse_registration_method;
50  bool save_match_images;
51  unsigned int optimization_steps;
52  double simplex_initial_length;
53  double simplex_minimum_size;
54 
56  init_defaults();
57  };
58 
59  Em2DRestraintParameters(double ps, double res, unsigned int n_proj = 20)
60  : ProjectingParameters(ps, res), n_projections(n_proj) {
61  init_defaults();
62  }
63 
64  void show(std::ostream &out = std::cout) const {
65  out << "Em2DRestraintParameters: " << std::endl << "pixel_size "
66  << pixel_size << " resolution " << resolution
67  << " coarse_registration_method " << coarse_registration_method
68  << " optimization_steps " << optimization_steps
69  << " simplex_initial_length " << simplex_initial_length
70  << " simplex_minimum_size " << simplex_minimum_size << std::endl;
71  };
72 };
74 
75 //! Class to perform registration of model projections to images
76 class IMPEM2DEXPORT ProjectionFinder : public IMP::Object {
77  public:
79  : Object("ProjectionFinder%1%"),
80  parameters_setup_(false),
81  registration_done_(false) {};
82 
83  //! Initializes the parameters to generate and match projections
84  void setup(ScoreFunction *score_function,
85  const Em2DRestraintParameters &params) {
86 
87  score_function_ = score_function;
88  score_function_->set_was_used(true);
89  params_ = params;
90  masks_manager_ = MasksManagerPtr(new MasksManager);
91  masks_manager_->setup_kernel(params.resolution, params.pixel_size);
92  fast_optimization_mode_ = false;
93  parameters_setup_ = true;
94  preprocessing_time_ = 0.0;
95  coarse_registration_time_ = 0.0;
96  fine_registration_time_ = 0.0;
97  }
98 
99  //! Set EM images to use as restraints
100  void set_subjects(const em2d::Images &subjects);
101 
102  //! Set the projections of the model to use for initial coarse correlation
103  void set_projections(const em2d::Images &projections);
104 
105  //! Set the projections of the model to use for initial coarse correlation
106  void set_variance_images(const em2d::Images &variances);
107 
108  //! Set the particles where the em2D restraint is applied
109  void set_model_particles(const ParticlesTemp &ps);
110 
111  //! The projections of the model that best match the subject EM images
112  //! are saved.
113  /*!
114  Their name will be: coarse-match-i.spi for coarse registration and
115  fine_match-i.spi for full registration.
116  */
117  void set_save_match_images(bool x) { params_.save_match_images = x; }
118 
119  bool get_save_match_images() const { return params_.save_match_images; }
120  //! With this fast mode, only the first number n of best scoring
121  //! projections during the coarse search are refined.
122  //! Saves vast times of computation time with some loss of accuracy.
123  //! Try starting with 1 (risky) or 2, and increase it to get more chances
124  //! of finding the best projection
125  void set_fast_mode(unsigned int n);
126 
127  //! Recover the registration results. Only works if a registration has been
128  //! done previously
129  RegistrationResults get_registration_results() const;
130 
131  //! Coarse registration of all the images using the projections
132  //! Based in 2D alignments of the images
133  /**
134  \note Given that this registration is based on 2D alignment maximizing the
135  cross correlation, the a better score is the best correlation
136  **/
137  void get_coarse_registration();
138 
139  //! Performs complete registration of projections against the images.
140  //! This means the coarse registration followed by simplex optimization
141  void get_complete_registration();
142 
143  //! Get the em2d score for a model after the registration performed:
144  //! coarse or complete.
145  double get_global_score() const;
146 
147  void show(std::ostream &out) const;
148 
149  //! Time employed for preprocessing
150  double get_preprocessing_time() const;
151 
152  //! Time employed for the coarse registration part
153  double get_coarse_registration_time() const;
154 
155  //! Time employed for the fine registration part
156  double get_fine_registration_time() const;
157 
158  unsigned int get_number_of_subjects() const { return subjects_.size(); }
159 
160  void set_number_of_class_averages_members(Ints n_members) {
161  n_members_ = n_members;
162  }
163 
164  unsigned int get_number_of_projections() const { return projections_.size(); }
165 
167 
168  protected:
169  double preprocessing_time_, coarse_registration_time_,
170  fine_registration_time_;
171  //! Coarse registration for one subject
172  void get_coarse_registrations_for_subject(unsigned int i,
173  RegistrationResults &coarse_RRs);
174 
175  void do_preprocess_projection(unsigned int j);
176  void do_preprocess_subject(unsigned int i);
177 
178  //! Computes the weighted centroid and the FFT of the polar-resampled
179  //! autocorrelation.
180  void do_preprocess_for_fast_coarse_registration(const cv::Mat &m,
181  algebra::Vector2D &center,
182  cv::Mat &POLAR_AUTOC);
183  //! Main parameters
185  em2d::Images variances_;
186  em2d::Images projections_;
187  RegistrationResults registration_results_;
188  ParticlesTemp model_particles_;
189  Ints n_members_;
190  Pointer<ScoreFunction> score_function_;
191 
192  bool particles_set_, parameters_setup_, registration_done_,
193  fast_optimization_mode_;
194 
195  unsigned int number_of_optimized_projections_;
196  // FFT of subjects (storing the FFT of projections is not necessary
197  std::vector<cv::Mat> SUBJECTS_;
198  // FFT of the autocorrelation resampled images
199  std::vector<cv::Mat> SUBJECTS_POLAR_AUTOC_;
200  std::vector<cv::Mat> PROJECTIONS_POLAR_AUTOC_;
201  algebra::Vector2Ds subjects_cog_;
202  algebra::Vector2Ds projections_cog_;
203  PolarResamplingParameters polar_params_;
204 
205  Em2DRestraintParameters params_;
206  /**
207  MasksManager masks_manager_;
208  **/
209  MasksManagerPtr masks_manager_;
210 };
211 
213 
214 IMPEM2D_END_NAMESPACE
215 
216 #endif /* IMPEM2D_PROJECTION_FINDER_H */
Generation of projections from models or density maps Copyright 2007-2021 IMP Inventors. All rights reserved.
Represent a rotation in 2D space.
projection masks Copyright 2007-2021 IMP Inventors. All rights reserved.
VectorD< 2 > Vector2D
Definition: VectorD.h:417
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
Simple 2D vector class.
Alignment of images in 2D Copyright 2007-2021 IMP Inventors. All rights reserved. ...
Interface with OpenCV Copyright 2007-2021 IMP Inventors. All rights reserved.
A more IMP-like version of the std::vector.
Definition: Vector.h:40
const unsigned int ALIGN2D_NO_PREPROCESSING
Methods for registration used by the finder.
IMP images for Electron Microscopy using openCV matrices Copyright 2007-2021 IMP Inventors. All rights reserved.
A smart pointer to a reference counted object.
Definition: Pointer.h:87
Scoring functions for 2D Copyright 2007-2021 IMP Inventors. All rights reserved.
#define IMP_VALUES(Name, PluralName)
Define the type for storing sets of values.
Definition: value_macros.h:23
Common base class for heavy weight IMP objects.
Definition: Object.h:106
Base class for all scoring functions related to em2d.
Definition: scores2D.h:55
Functions related with rotations in em2d Copyright 2007-2021 IMP Inventors. All rights reserved...
em2d::Images subjects_
Main parameters.
void setup(ScoreFunction *score_function, const Em2DRestraintParameters &params)
Initializes the parameters to generate and match projections.
IMP::Vector< RegistrationResult > RegistrationResults
Simple 3D rotation class.
Parameters needed for the core projection routine.
Definition: project.h:30
Classes to handle individual model particles. (Note that implementation of inline functions is in int...
std::ostream & show(Hierarchy h, std::ostream &out=std::cout)
Print the hierarchy using a given decorator to display each node.
#define IMP_OBJECTS(Name, PluralName)
Define the types for storing lists of object pointers.
Definition: object_macros.h:44
A nullptr-initialized pointer to an IMP Object.
Parameters used by Em2DRestraint and ProjectionFinder.
unsigned int n_projections
Number of model projections to generate when scoring.
Object(std::string name)
Construct an object with the given name.
Simple 3D vector class.
void show(std::ostream &out=std::cout) const
Definition: project.h:48
IMP::Vector< Int > Ints
Standard way to pass a bunch of Int values.
Definition: types.h:49
double get_global_score(const RegistrationResults &RRs)
Registration results class Copyright 2007-2021 IMP Inventors. All rights reserved.
Class to perform registration of model projections to images.
Management of projection masks.
void set_was_used(bool tf) const