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