Chemical Data Processing Library C++ API - Version 1.1.1
FastGaussianShapeAlignment.hpp
Go to the documentation of this file.
1 /*
2  * FastGaussianShapeAlignment.hpp
3  *
4  * This file is part of the Chemical Data Processing Toolkit
5  *
6  * Copyright (C) 2003 Thomas Seidel <thomas.seidel@univie.ac.at>
7  *
8  * This library is free software; you can redistribute it and/or
9  * modify it under the terms of the GNU Lesser General Public
10  * License as published by the Free Software Foundation; either
11  * version 2 of the License, or (at your option) any later version.
12  *
13  * This library is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16  * Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public License
19  * along with this library; see the file COPYING. If not, write to
20  * the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21  * Boston, MA 02111-1307, USA.
22  */
23 
29 #ifndef CDPL_SHAPE_FASTGAUSSIANSHAPEALIGNMENT_HPP
30 #define CDPL_SHAPE_FASTGAUSSIANSHAPEALIGNMENT_HPP
31 
32 #include <vector>
33 #include <cstddef>
34 #include <utility>
35 #include <unordered_map>
36 #include <memory>
37 #include <functional>
38 
39 #include <boost/functional/hash.hpp>
40 #include <boost/random/mersenne_twister.hpp>
41 
42 #include "CDPL/Shape/APIPrefix.hpp"
47 #include "CDPL/Math/Matrix.hpp"
51 
52 
53 namespace CDPL
54 {
55 
56  namespace Shape
57  {
58 
60  {
61 
62  typedef std::vector<AlignmentResult> ResultList;
63 
64  public:
65  static constexpr double DEF_OPTIMIZATION_STOP_GRADIENT = 1.0;
66  static constexpr std::size_t DEF_MAX_OPTIMIZATION_ITERATIONS = 20;
67  static constexpr unsigned int DEF_RESULT_SELECTION_MODE = AlignmentResultSelectionMode::BEST_PER_REFERENCE_SET;
68  static constexpr double DEF_SYMMETRY_THRESHOLD = 0.15;
69  static constexpr std::size_t DEF_NUM_RANDOM_STARTS = 4;
70  static constexpr double DEF_MAX_RANDOM_TRANSLATION = 2.0;
71 
72  typedef std::shared_ptr<FastGaussianShapeAlignment> SharedPointer;
73 
74  typedef ResultList::const_iterator ConstResultIterator;
75  typedef ResultList::iterator ResultIterator;
76 
77  typedef std::function<double(const AlignmentResult&)> ScoringFunction;
78  typedef std::function<bool(const AlignmentResult&, const AlignmentResult&)> ResultCompareFunction;
79 
81 
83 
85 
87 
89 
91 
93 
95 
96  void setResultSelectionMode(unsigned int mode);
97 
98  unsigned int getResultSelectionMode() const;
99 
100  void performAlignment(bool perf_align);
101 
102  bool performAlignment() const;
103 
104  void optimizeOverlap(bool optimize);
105 
106  bool optimizeOverlap() const;
107 
108  void greedyOptimization(bool greedy);
109 
110  bool greedyOptimization() const;
111 
112  void setMaxNumOptimizationIterations(std::size_t max_iter);
113 
114  std::size_t getMaxNumOptimizationIterations() const;
115 
116  void setOptimizationStopGradient(double grad_norm);
117 
119 
121 
122  void addReferenceShape(const GaussianShape& shape, bool new_set = true);
123 
124  void addReferenceShapes(const GaussianShapeSet& shapes, bool new_set = true);
125 
126  std::size_t getNumReferenceShapes() const;
127 
128  void genShapeCenterStarts(bool generate);
129 
130  bool genShapeCenterStarts() const;
131 
132  void genColorCenterStarts(bool generate);
133 
134  bool genColorCenterStarts() const;
135 
136  void genNonColorCenterStarts(bool generate);
137 
139 
140  void genRandomStarts(bool generate);
141 
142  bool genRandomStarts() const;
143 
144  void genForAlignedShapeCenters(bool generate);
145 
147 
148  void genForReferenceShapeCenters(bool generate);
149 
151 
152  void genForLargerShapeCenters(bool generate);
153 
155 
156  void setSymmetryThreshold(double thresh);
157 
159 
160  void setMaxRandomTranslation(double max_trans);
161 
162  double getMaxRandomTranslation() const;
163 
164  void setNumRandomStarts(std::size_t num_starts);
165 
166  std::size_t getNumRandomStarts() const;
167 
168  void setRandomSeed(unsigned int seed);
169 
170  bool align(const GaussianShape& shape);
171 
172  bool align(const GaussianShapeSet& shapes);
173 
174  std::size_t getNumResults() const;
175 
176  const AlignmentResult& getResult(std::size_t idx) const;
177 
178  AlignmentResult& getResult(std::size_t idx);
179 
181 
183 
185 
187 
189 
191 
193 
195 
196  private:
197  struct ShapeData
198  {
199 
200  struct Element
201  {
202 
203  std::size_t color;
205  double radius;
206  double delta;
207  double weightFactor;
208  double volume;
209  };
210 
211  typedef std::vector<Element> ElementArray;
212 
213  ElementArray elements;
214  std::size_t colElemOffs;
215  std::size_t setIndex;
216  std::size_t index;
217  unsigned int symClass;
219  double selfOverlap;
220  double colSelfOverlap;
221  bool equalNonColDelta;
222  };
223 
224  typedef std::pair<std::size_t, std::size_t> ResultID;
225 
227 
228  FastGaussianShapeAlignment& operator=(const FastGaussianShapeAlignment& alignment);
229 
230  void alignAndProcessResults(std::size_t ref_idx, std::size_t al_idx);
231  void processResult(AlignmentResult& res, std::size_t ref_idx, std::size_t al_idx);
232 
233  void setupShapeData(const GaussianShape& shape, ShapeData& data, bool ref);
234  void setupShapeDataElement(const GaussianShape::Element& gs_elem, ShapeData::Element& sd_elem) const;
235 
236  void prepareForAlignment();
237 
238  bool generateStartTransforms(const ShapeData& ref_data);
239 
240  void generateTransformsForElementCenters(const ShapeData& data, unsigned int axes_swap_flags, bool ref_shape);
241  void generateTransforms(const Math::Vector3D& ctr_trans, unsigned int axes_swap_flags);
242 
243  template <typename QE>
244  void addStartTransform(Math::Vector3D::ConstPointer ctr_trans_data, const Math::QuaternionExpression<QE>& rot_quat);
245 
246  void transformAlignedShape();
247 
248  double calcAlignmentFunctionValue(const QuaternionTransformation& xform_quat);
249  double calcAlignmentFunctionGradient(const QuaternionTransformation& xform_quat, QuaternionTransformation& xform_grad);
250 
251  double calcOverlap(const ShapeData& ref_data, const ShapeData& ovl_data, bool color) const;
252  double calcOverlapGradient(const ShapeData& ref_data, Math::Vector3DArray& grad) const;
253 
254  bool getResultIndex(const ResultID& res_id, std::size_t& res_idx);
255 
256  typedef std::vector<ShapeData> ShapeDataArray;
257  typedef std::unordered_map<ResultID, std::size_t, boost::hash<ResultID> > ResultIndexMap;
258  typedef std::vector<QuaternionTransformation> StartTransformList;
259  typedef boost::random::mt11213b RandomEngine;
261 
262  bool perfAlignment;
263  bool optOverlap;
264  bool greedyOpt;
265  std::size_t maxNumOptIters;
266  double optStopGrad;
267  unsigned int resultSelMode;
268  ResultCompareFunction resultCmpFunc;
269  ScoringFunction scoringFunc;
270  ShapeDataArray refShapeData;
271  ShapeData algdShapeData;
272  ResultIndexMap resIndexMap;
273  ResultList results;
274  std::size_t currSetIndex;
275  std::size_t currShapeIndex;
276  bool shapeCtrStarts;
277  bool colCtrStarts;
278  bool nonColCtrStarts;
279  bool randomStarts;
280  bool genForAlgdShape;
281  bool genForRefShape;
282  bool genForLargerShape;
283  double symThreshold;
284  double maxRandomTrans;
285  std::size_t numRandomStarts;
286  std::size_t numSubTransforms;
287  RandomEngine randomEngine;
288  StartTransformList startTransforms;
289  Math::Vector3DArray startPoseCoords;
290  Math::Vector3DArray optPoseCoordsGrad;
291  BFGSMinimizer minimizer;
292  Math::Matrix4D xformMatrix;
293  QuaternionTransformation normXformQuat;
294  std::size_t currRefShapeIdx;
295  };
296  } // namespace Shape
297 } // namespace CDPL
298 
299 #endif // CDPL_SHAPE_FASTGAUSSIANSHAPEALIGNMENT_HPP
CDPL::Shape::FastGaussianShapeAlignment::getMaxNumOptimizationIterations
std::size_t getMaxNumOptimizationIterations() const
CDPL::Shape::FastGaussianShapeAlignment::genShapeCenterStarts
bool genShapeCenterStarts() const
CDPL::Shape::GaussianShape::Element
Definition: GaussianShape.hpp:55
CDPL::Shape::FastGaussianShapeAlignment::genShapeCenterStarts
void genShapeCenterStarts(bool generate)
CDPL::Shape::FastGaussianShapeAlignment::getNumReferenceShapes
std::size_t getNumReferenceShapes() const
CDPL::Shape::FastGaussianShapeAlignment::genForLargerShapeCenters
void genForLargerShapeCenters(bool generate)
CDPL::Shape::FastGaussianShapeAlignment::~FastGaussianShapeAlignment
~FastGaussianShapeAlignment()
CDPL::Shape::FastGaussianShapeAlignment::begin
ConstResultIterator begin() const
CDPL::Shape::GaussianShapeSet
Definition: GaussianShapeSet.hpp:46
CMatrix< double, 4, 4 >
VectorArray.hpp
Definition of the class CDPL::Math::VectorArray.
CDPL::Shape::FastGaussianShapeAlignment::FastGaussianShapeAlignment
FastGaussianShapeAlignment(const GaussianShapeSet &ref_shapes)
CDPL::Shape::FastGaussianShapeAlignment::greedyOptimization
void greedyOptimization(bool greedy)
CDPL::Shape::FastGaussianShapeAlignment
Definition: FastGaussianShapeAlignment.hpp:60
CDPL::Math::Vector3D
CVector< double, 3 > Vector3D
A bounded 3 element vector holding floating point values of type double.
Definition: Vector.hpp:1637
CDPL::Shape::FastGaussianShapeAlignment::performAlignment
void performAlignment(bool perf_align)
CDPL::Shape::FastGaussianShapeAlignment::optimizeOverlap
void optimizeOverlap(bool optimize)
AlignmentResult.hpp
Definition of the class CDPL::Shape::AlignmentResult.
CDPL::Shape::FastGaussianShapeAlignment::genRandomStarts
bool genRandomStarts() const
CDPL::Shape::FastGaussianShapeAlignment::getResult
AlignmentResult & getResult(std::size_t idx)
CDPL::Shape::transform
CDPL_SHAPE_API void transform(GaussianShape &shape, const Math::Matrix4D &xform)
CDPL::Shape::FastGaussianShapeAlignment::getResultsEnd
ConstResultIterator getResultsEnd() const
CDPL::Shape::AlignmentResultSelectionMode::BEST_PER_REFERENCE_SET
const unsigned int BEST_PER_REFERENCE_SET
Definition: AlignmentResultSelectionMode.hpp:45
QuaternionTransformation.hpp
Definition of the type CDPL::Shape::QuaternionTransformation.
CDPL::Shape::FastGaussianShapeAlignment::genForAlignedShapeCenters
void genForAlignedShapeCenters(bool generate)
CDPL::Shape::FastGaussianShapeAlignment::getSymmetryThreshold
double getSymmetryThreshold()
CDPL::Shape::FastGaussianShapeAlignment::getMaxRandomTranslation
double getMaxRandomTranslation() const
CDPL::Shape::FastGaussianShapeAlignment::ResultCompareFunction
std::function< bool(const AlignmentResult &, const AlignmentResult &)> ResultCompareFunction
Definition: FastGaussianShapeAlignment.hpp:78
CDPL::Shape::FastGaussianShapeAlignment::getResultsEnd
ResultIterator getResultsEnd()
QuaternionExpression.hpp
Definition of various quaternion expression types and operations.
GaussianShapeSet.hpp
Definition of the class CDPL::Shape::GaussianShapeSet.
BFGSMinimizer.hpp
Implementation of the BFGS optimization algorithm.
CDPL::Shape::FastGaussianShapeAlignment::getResultSelectionMode
unsigned int getResultSelectionMode() const
CDPL::Shape::FastGaussianShapeAlignment::getResult
const AlignmentResult & getResult(std::size_t idx) const
CDPL::Shape::FastGaussianShapeAlignment::setMaxRandomTranslation
void setMaxRandomTranslation(double max_trans)
CDPL::Math::QuaternionExpression
Definition: Expression.hpp:98
CDPL::Shape::FastGaussianShapeAlignment::performAlignment
bool performAlignment() const
CDPL::Shape::FastGaussianShapeAlignment::setRandomSeed
void setRandomSeed(unsigned int seed)
AlignmentResultSelectionMode.hpp
Definition of constants in namespace CDPL::Shape::AlignmentResultSelectionMode.
CDPL::Shape::FastGaussianShapeAlignment::getResultCompareFunction
const ResultCompareFunction & getResultCompareFunction() const
bool
CDPL::Shape::FastGaussianShapeAlignment::ShapeData::Element::radius
double radius
Definition: FastGaussianShapeAlignment.hpp:205
CDPL::Shape::FastGaussianShapeAlignment::ShapeData::Element
Definition: FastGaussianShapeAlignment.hpp:201
VectorArray< Vector3D >
CDPL::Shape::FastGaussianShapeAlignment::SharedPointer
std::shared_ptr< FastGaussianShapeAlignment > SharedPointer
Definition: FastGaussianShapeAlignment.hpp:72
CDPL::Shape::FastGaussianShapeAlignment::greedyOptimization
bool greedyOptimization() const
CDPL::Shape::FastGaussianShapeAlignment::ShapeData::Element::weightFactor
double weightFactor
Definition: FastGaussianShapeAlignment.hpp:207
CDPL::Shape::FastGaussianShapeAlignment::setSymmetryThreshold
void setSymmetryThreshold(double thresh)
double
CDPL::Shape::FastGaussianShapeAlignment::end
ConstResultIterator end() const
CDPL::Shape::FastGaussianShapeAlignment::getNumRandomStarts
std::size_t getNumRandomStarts() const
CDPL::Shape::FastGaussianShapeAlignment::addReferenceShape
void addReferenceShape(const GaussianShape &shape, bool new_set=true)
CDPL::Shape::FastGaussianShapeAlignment::optimizeOverlap
bool optimizeOverlap() const
CDPL::Shape::FastGaussianShapeAlignment::FastGaussianShapeAlignment
FastGaussianShapeAlignment(const GaussianShape &ref_shape)
CDPL::Math::CVector
Definition: Vector.hpp:1053
CDPL::Shape::GaussianShape
A data type for the descripton of arbitrary shapes composed of spheres approximated by gaussian funct...
Definition: GaussianShape.hpp:51
CDPL::Shape::FastGaussianShapeAlignment::setOptimizationStopGradient
void setOptimizationStopGradient(double grad_norm)
CDPL::Math::BFGSMinimizer< QuaternionTransformation >
CDPL::Shape::FastGaussianShapeAlignment::ShapeData::Element::delta
double delta
Definition: FastGaussianShapeAlignment.hpp:206
CDPL::Shape::FastGaussianShapeAlignment::ShapeData::Element::color
std::size_t color
Definition: FastGaussianShapeAlignment.hpp:203
CDPL::Shape::FastGaussianShapeAlignment::genForReferenceShapeCenters
bool genForReferenceShapeCenters() const
CDPL::Shape::FastGaussianShapeAlignment::setNumRandomStarts
void setNumRandomStarts(std::size_t num_starts)
CDPL::Shape::FastGaussianShapeAlignment::ScoringFunction
std::function< double(const AlignmentResult &)> ScoringFunction
Definition: FastGaussianShapeAlignment.hpp:77
CDPL::Shape::FastGaussianShapeAlignment::addReferenceShapes
void addReferenceShapes(const GaussianShapeSet &shapes, bool new_set=true)
CDPL::Shape::FastGaussianShapeAlignment::ShapeData::Element::center
Math::Vector3D center
Definition: FastGaussianShapeAlignment.hpp:204
CDPL::Shape::FastGaussianShapeAlignment::genNonColorCenterStarts
void genNonColorCenterStarts(bool generate)
CDPL_SHAPE_API
#define CDPL_SHAPE_API
Tells the compiler/linker which classes, functions and variables are part of the library API.
CDPL::Shape::FastGaussianShapeAlignment::setScoringFunction
void setScoringFunction(const ScoringFunction &func)
CDPL::Shape::FastGaussianShapeAlignment::align
bool align(const GaussianShape &shape)
CDPL
The namespace of the Chemical Data Processing Library.
CDPL::Shape::FastGaussianShapeAlignment::genForLargerShapeCenters
bool genForLargerShapeCenters() const
APIPrefix.hpp
Definition of the preprocessor macro CDPL_SHAPE_API.
CDPL::Shape::FastGaussianShapeAlignment::genNonColorCenterStarts
bool genNonColorCenterStarts() const
CDPL::Shape::FastGaussianShapeAlignment::ResultIterator
ResultList::iterator ResultIterator
Definition: FastGaussianShapeAlignment.hpp:75
CDPL::Shape::FastGaussianShapeAlignment::getOptimizationStopGradient
double getOptimizationStopGradient() const
CDPL::Shape::FastGaussianShapeAlignment::genRandomStarts
void genRandomStarts(bool generate)
CDPL::Shape::FastGaussianShapeAlignment::ShapeData::Element::volume
double volume
Definition: FastGaussianShapeAlignment.hpp:208
CDPL::Shape::AlignmentResult
Definition: AlignmentResult.hpp:45
CDPL::Shape::FastGaussianShapeAlignment::end
ResultIterator end()
CDPL::Shape::FastGaussianShapeAlignment::genForReferenceShapeCenters
void genForReferenceShapeCenters(bool generate)
Matrix.hpp
Definition of matrix data types.
CDPL::Shape::FastGaussianShapeAlignment::begin
ResultIterator begin()
CDPL::Shape::FastGaussianShapeAlignment::setMaxNumOptimizationIterations
void setMaxNumOptimizationIterations(std::size_t max_iter)
CDPL::Shape::FastGaussianShapeAlignment::setResultCompareFunction
void setResultCompareFunction(const ResultCompareFunction &func)
CDPL::Shape::FastGaussianShapeAlignment::genColorCenterStarts
void genColorCenterStarts(bool generate)
CDPL::Shape::FastGaussianShapeAlignment::genColorCenterStarts
bool genColorCenterStarts() const
CDPL::Shape::FastGaussianShapeAlignment::clearReferenceShapes
void clearReferenceShapes()
CDPL::Shape::FastGaussianShapeAlignment::setResultSelectionMode
void setResultSelectionMode(unsigned int mode)
CDPL::Shape::FastGaussianShapeAlignment::ConstResultIterator
ResultList::const_iterator ConstResultIterator
Definition: FastGaussianShapeAlignment.hpp:74
CDPL::Shape::FastGaussianShapeAlignment::align
bool align(const GaussianShapeSet &shapes)
CDPL::Shape::FastGaussianShapeAlignment::FastGaussianShapeAlignment
FastGaussianShapeAlignment()
CDPL::Shape::FastGaussianShapeAlignment::getResultsBegin
ConstResultIterator getResultsBegin() const
CDPL::Shape::FastGaussianShapeAlignment::getScoringFunction
const ScoringFunction & getScoringFunction() const
CDPL::Shape::FastGaussianShapeAlignment::getNumResults
std::size_t getNumResults() const
CDPL::Shape::FastGaussianShapeAlignment::getResultsBegin
ResultIterator getResultsBegin()
CDPL::Shape::FastGaussianShapeAlignment::genForAlignedShapeCenters
bool genForAlignedShapeCenters() const