IMP  2.0.0
The Integrative Modeling Platform
ProjectionFinder.h
Go to the documentation of this file.
1 /**
2  * \file ProjectionFinder.h
3  * \brief Coarse registration of 2D projections from a 3D volume
4  *
5  * Copyright 2007-2013 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 
31 //! Methods for registration used by the finder
32 const unsigned int ALIGN2D_NO_PREPROCESSING = 0;
33 const unsigned int ALIGN2D_PREPROCESSING = 1;
34 const unsigned int ALIGN2D_WITH_CENTERS = 2;
35 
36 
37 class IMPEM2DEXPORT Em2DRestraintParameters: public ProjectingParameters {
38 
39  void init_defaults() {
40  coarse_registration_method = ALIGN2D_PREPROCESSING;
41  save_match_images = false;
42  optimization_steps = 5;
43  simplex_initial_length = 0.1;
44  simplex_minimum_size = 0.01;
45  }
46 
47 public:
48 
49  // Number of model projections to generate when scoring
50  unsigned int n_projections;
51  unsigned int coarse_registration_method;
52  bool save_match_images;
53  unsigned int optimization_steps;
54  double simplex_initial_length;
55  double simplex_minimum_size;
56 
57  Em2DRestraintParameters() {init_defaults();};
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
66  << "pixel_size " << 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 IMP_VALUES(Em2DRestraintParameters,Em2DRestraintParametersList);
73 
74 
75 
76 
77 //! class to perform registration of model projections to images images
78 class IMPEM2DEXPORT ProjectionFinder: public IMP::base::Object {
79 public:
80 
81  ProjectionFinder(): Object("ProjectionFinder%1%"),
82  parameters_setup_(false),registration_done_(false) {};
83 
84  //! Initializes the parameters to generate and match projections
85  /*!
86  \param[in] resolution to employ to generate projections for matching with
87  the EM images. Default is the maximum possible, 1.
88  \param[in] coarse_registration_method Method for 1st step of projection
89  finding, the 2D alignment:
90  0 => FFT alignment no preprocessing.
91  1 => FFT alignment with preprocessing (Default and recommended).
92  2 => FFT alginment and centers of gravity
93  (fast, but only works for low noise)
94  during testing.
95  \param[in] optimization steps to use by the simplex optimizer. The default
96  value is the one found during the benchmark to perform well
97  \param[in] simplex_initial_length Initial value to start the simplex search
98  The default value is based on the benchmark results
99  \param[in] Value of the simplex length stop the search. The smaller, the
100  more accurate the finder, but slower
101  */
102  void setup(ScoreFunction *score_function,
103  const Em2DRestraintParameters &params) {
104 
105  score_function_= score_function;
106  score_function_->set_was_used(true);
107  params_ = params;
108  masks_manager_ = MasksManagerPtr(new MasksManager);
109  masks_manager_->setup_kernel(params.resolution,params.pixel_size);
110  fast_optimization_mode_ = false;
111  parameters_setup_=true;
112  preprocessing_time_=0.0;
113  coarse_registration_time_=0.0;
114  fine_registration_time_ =0.0;
115  }
116 
117 
118  //! Set EM images to use as restraints
119  void set_subjects(const em2d::Images &subjects);
120 
121  //! Set the projections of the model to use for initial coarse correlation
122  void set_projections(const em2d::Images &projections);
123 
124  //! Set the projections of the model to use for initial coarse correlation
125  void set_variance_images(const em2d::Images &variances);
126 
127 
128  //! Set the particles where the em2D restraint is applied
129  void set_model_particles(const ParticlesTemp &ps);
130 
131  //! The projections of the model that best match the subject EM images
132  //! are saved.
133  /*!
134  Their name will be: coarse-match-i.spi for coarse registration and
135  fine_match-i.spi for full registration.
136  */
137  void set_save_match_images(bool x) {
138  params_.save_match_images = x;
139  }
140 
141  bool get_save_match_images() const {
142  return params_.save_match_images;
143  }
144  //! With this fast mode, only the first number n of best scoring
145  //! projections during the coarse search are refined.
146  //! Saves vast times of computation time with some loss of accuracy.
147  //! Try starting with 1 (risky) or 2, and increased it for get more chances
148  //! of finding the best projection
149  void set_fast_mode(unsigned int n);
150 
151  //! Recover the registration results. Only works if a registration has been
152  //! done previously
153  RegistrationResults get_registration_results() const;
154 
155  //! Coarse registration of all the images using the projections
156  //! Based in 2D alignments of the images
157  /**
158  \note Given that this registration is based on 2D alignment maximizing the
159  cross correlation, the a better score is the best correlation
160  **/
161  void get_coarse_registration();
162 
163  //! Performs complete registration of projections against the images.
164  //! This meaning the coarse registration followed by simplex optimization
165  void get_complete_registration();
166 
167  //! Get the em2d score for a model after the registration performed:
168  //! coarse or complete.
169  double get_global_score() const;
170 
171  void show(std::ostream &out) const;
172 
173  //! Time employed for preprocessing
174  double get_preprocessing_time() const;
175 
176  //! Time employed for the coarse registration part
177  double get_coarse_registration_time() const;
178 
179  //! Time employed for the fine registration part
180  double get_fine_registration_time() const;
181 
182  unsigned int get_number_of_subjects() const {
183  return subjects_.size();
184  }
185 
186  void set_number_of_class_averages_members(Ints n_members) {
187  n_members_ = n_members;
188  }
189 
190  unsigned int get_number_of_projections() const {
191  return projections_.size();
192  }
193 
194  IMP_OBJECT_METHODS(ProjectionFinder);
195 
196 protected:
197 
198  double preprocessing_time_,coarse_registration_time_,fine_registration_time_;
199  //! Coarse registration for one subject
200  void get_coarse_registrations_for_subject(unsigned int i,
201  RegistrationResults &coarse_RRs);
202 
203  void do_preprocess_projection(unsigned int j);
204  void do_preprocess_subject(unsigned int i);
205 
206  //! Computes the weighted centroid and the FFT of the polar-resampled
207  //! autocorrelation.
208  void do_preprocess_for_fast_coarse_registration(const cv::Mat &m,
209  algebra::Vector2D &center,
210  cv::Mat &POLAR_AUTOC);
211  //! Main parameters
213  em2d::Images variances_;
214  em2d::Images projections_;
215  RegistrationResults registration_results_;
216  ParticlesTemp model_particles_;
217  Ints n_members_;
218  Pointer<ScoreFunction> score_function_;
219 
220  bool particles_set_,
221  parameters_setup_,
222  registration_done_,
223  fast_optimization_mode_;
224 
225 
226  unsigned int number_of_optimized_projections_;
227  // FFT of subjects (storing the FFT of projections is not neccessary
228  std::vector< cv::Mat > SUBJECTS_;
229  // FFT of the autocorrelation resampled images
230  std::vector< cv::Mat > SUBJECTS_POLAR_AUTOC_;
231  std::vector< cv::Mat > PROJECTIONS_POLAR_AUTOC_;
232  algebra::Vector2Ds subjects_cog_;
233  algebra::Vector2Ds projections_cog_;
234  PolarResamplingParameters polar_params_;
235 
236  Em2DRestraintParameters params_;
237 /**
238  MasksManager masks_manager_;
239 **/
240  MasksManagerPtr masks_manager_;
241 };
242 
244 
245 IMPEM2D_END_NAMESPACE
246 
247 #endif /* IMPEM2D_PROJECTION_FINDER_H */