IMP  2.2.1
The Integrative Modeling Platform
vector_generators.h
Go to the documentation of this file.
1 /**
2  * \file IMP/algebra/vector_generators.h
3  * \brief Functions to generate vectors.
4  *
5  * Copyright 2007-2014 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPALGEBRA_VECTOR_GENERATORS_H
10 #define IMPALGEBRA_VECTOR_GENERATORS_H
11 
12 #include "VectorD.h"
13 #include "Cylinder3D.h"
14 #include "Cone3D.h"
15 #include "Sphere3D.h"
16 #include "SpherePatch3D.h"
17 #include "BoundingBoxD.h"
18 #include "utility.h"
19 #include "internal/grid_range_d.h"
20 #include "internal/internal_vector_generators.h"
21 
22 IMPALGEBRA_BEGIN_NAMESPACE
23 
24 /** @name Vector Generators
25 
26  These functions generate vector objects. Some
27  of the methods, those with random in their name, generate
28  a single vector chosen uniformly from the specified domain.
29  Others, the cover methods, generate a set of points distributed
30  (somewhat) evenly over the domain.
31  @{
32  */
33 
34 //! Generate a random vector in a box with uniform density
35 /** See BoundingBoxD
36  See VectorD
37  */
38 template <int D>
41 }
42 
43 //! Generate a random vector on a box with uniform density
44 /** See BoundingBoxD
45  See VectorD
46  */
47 template <int D>
49  return internal::RandomVectorOnBB<D>::get(bb);
50 }
51 
52 //! Generate a random vector in a sphere with uniform density
53 /** See VectorD
54  See SphereD
55  */
56 template <int D>
58  IMP_USAGE_CHECK(s.get_radius() > 0, "The sphere must have positive radius");
60  double norm;
61  VectorD<D> ret;
62  double r2 = get_squared(s.get_radius());
63  // \todo This algorithm could be more efficient.
64  do {
65  ret = get_random_vector_in(bb);
66  norm = (s.get_center() - ret).get_squared_magnitude();
67  } while (norm > r2);
68  return ret;
69 }
70 
71 #ifndef SWIG
72 /** Generates a random vector in a circle
73  with uniform density with respect to the area of the circle
74 
75  @param s a 2D sphere (circle)
76 
77  See VectorD
78  See SphereD
79 */
80 IMPALGEBRAEXPORT VectorD<2> get_random_vector_in(const SphereD<2> &s);
81 #endif
82 
83 //! Generate a random vector in a cylinder with uniform density
84 /** See VectorD
85  See Cylinder3D
86  */
87 IMPALGEBRAEXPORT Vector3D get_random_vector_in(const Cylinder3D &c);
88 
89 //! returns a random vector on a sphere of radius 1 with uniform density
90 //! and implementation optimized for the 3D + unit vector case
93 }
94 
95 //! Generate a random vector on a sphere with uniform density
96 /** See VectorD
97  See SphereD
98  */
99 template <int D>
102 }
103 
104 //! Generate a set of vectors which covers a sphere uniformly
105 /** The function is currently pretty slow, especially in non-optimized
106  builds. Complain if this bugs you. We might be able to do better,
107  at least in 3D.
108 
109  Creates at least the requested number of points.
110  \cgalpredicate
111 
112  See VectorD
113  See SphereD
114  */
115 template <int D>
117  unsigned int n) {
118  return internal::uniform_cover_sphere(n, s.get_center(), s.get_radius(),
119  true);
120 }
121 
122 //! Generate a set of 3d points that uniformly cover a cylinder
123 /** See VectorD
124  See Cylinder3D
125 */
126 IMPALGEBRAEXPORT Vector3Ds
127  get_uniform_surface_cover(const Cylinder3D &cyl, int number_of_points);
128 
129 //! Generate a set of 3D points that uniformly cover a hemisphere
130 /** The points all lie on the upper hemisphere, eg, all their
131  z coordinates are greater than those of the center of the sphere.
132  */
133 template <int D>
135  const SphereD<D> &s, unsigned int n) {
136  return internal::uniform_cover_sphere(n, s.get_center(), s.get_radius(),
137  false);
138 }
139 
140 //! Generate a grid of 3d points on a cylinder surface
141 /** See Vector3D
142  See Cylinder3D
143 */
144 IMPALGEBRAEXPORT Vector3Ds
145  get_grid_surface_cover(const Cylinder3D &cyl, int number_of_cycles,
146  int number_of_points_on_cycle);
147 
148 //! Generate a set of 3d points that uniformly cover a patch of a sphere
149 /**
150  \note the implementation can be improved
151  See SpherePatch3D
152  See VectorD
153  */
154 IMPALGEBRAEXPORT Vector3Ds
155  get_uniform_surface_cover(const SpherePatch3D &sph,
156  unsigned int number_of_points);
157 
158 /** See VectorD
159  See Cone3D
160 */
161 IMPALGEBRAEXPORT Vector3Ds
162  get_uniform_surface_cover(const Cone3D &cone,
163  unsigned int number_of_points);
164 
165 /** Cover the interior of the bounding box by equal sized
166  parallelograms of approximately full-width s, returning the
167  list of centers of the cubes.
168  */
169 template <int D>
171  const BoundingBoxD<D> &bb, double s) {
172  const unsigned int dim = bb.get_dimension();
173  Ints ns(dim);
174  algebra::VectorD<D> start(bb.get_corner(0));
175  algebra::VectorD<D> spacing(bb.get_corner(0));
176  for (unsigned int i = 0; i < dim; ++i) {
177  double w = bb.get_corner(1)[i] - bb.get_corner(0)[i];
178  if (w < s) {
179  start[i] = bb.get_corner(0)[i] + w * .5;
180  spacing[i] = 1;
181  ns[i] = 1;
182  } else {
183  ns[i] = static_cast<int>(std::floor(w / s));
184  spacing[i] = w / ns[i];
185  start[i] = bb.get_corner(0)[i] + spacing[i] * .5;
186  }
187  }
188  Ints cur(D, 0);
190  do {
191  ret.push_back(start + get_elementwise_product(cur, spacing));
192  unsigned int i;
193  for (i = 0; i < dim; ++i) {
194  ++cur[i];
195  if (cur[i] == ns[i]) {
196  cur[i] = 0;
197  } else {
198  break;
199  }
200  }
201  if (i == dim) break;
202  } while (true);
203  return ret;
204 }
205 
206 //! Generate a random chain with no collisions
207 /** This function generates a random chain, starting at (0,0,0)
208  with n particles each with radius r. Consecutive particles are
209  approximately distance 2r apart and no pair of particles is closer
210  than 2r.
211 
212  If an obstacles parameter is provided then chain spheres also don't
213  intersect the obstacle spheres.
214 
215  \note The current implementation is not very clever and can be made
216  more clever if needed.
217  */
218 IMPALGEBRAEXPORT Vector3Ds
219  get_random_chain(unsigned int n, double r,
220  const Vector3D &start = Vector3D(0, 0, 0),
221  const Sphere3Ds &obstacles = Sphere3Ds());
222 
223 /** @} */
224 
225 /** Return a cover of the surface of the volume defined by a union of balls
226  bounded by the spheres.
227 
228  This is effectively a sampling of the solvent exposed surface of a set of
229  spheres. The density of points has approximately the passed value.
230 
231  This method is much faster than get_connolly_surface().
232 */
233 IMPALGEBRAEXPORT Vector3Ds
235  double points_per_square_angstrom);
236 IMPALGEBRA_END_NAMESPACE
237 
238 #endif /* IMPALGEBRA_VECTOR_GENERATORS_H */
IMP::base::Vector< Sphere3D > Sphere3Ds
Definition: SphereD.h:89
base::Vector< VectorD< D > > get_uniform_upper_hemisphere_cover(const SphereD< D > &s, unsigned int n)
Generate a set of 3D points that uniformly cover a hemisphere.
Simple 3D sphere patch class.
VectorD< D > get_elementwise_product(const algebra::VectorD< D > &a, const algebra::VectorD< D > &b)
Definition: VectorD.h:432
const VectorD< D > & get_corner(unsigned int i) const
For 0 return lower corner and 1 upper corner.
Definition: BoundingBoxD.h:123
VectorD< 3 > get_random_vector_on_unit_sphere()
stores a cylinder
Vector3Ds get_random_chain(unsigned int n, double r, const Vector3D &start=Vector3D(0, 0, 0), const Sphere3Ds &obstacles=Sphere3Ds())
Generate a random chain with no collisions.
Vector3D get_random_vector_in(const Cylinder3D &c)
Generate a random vector in a cylinder with uniform density.
#define IMP_USAGE_CHECK(expr, message)
A runtime test for incorrect usage of a class or method.
base::Vector< VectorD< 3 > > Vector3Ds
Definition: VectorD.h:397
Functions to deal with very common math operations.
A Cartesian vector in D-dimensions.
Definition: VectorD.h:52
A bounding box in D dimensions.
Simple D vector class.
An axis-aligned bounding box.
Definition: BoundingBoxD.h:27
base::Vector< VectorD< D > > get_grid_interior_cover_by_spacing(const BoundingBoxD< D > &bb, double s)
Vector3Ds get_uniform_surface_cover(const Sphere3Ds &in, double points_per_square_angstrom)
stores a cone
VectorD< 3 > Vector3D
Definition: VectorD.h:395
VectorD< D > get_random_vector_on(const SphereD< D > &s)
Generate a random vector on a sphere with uniform density.
Simple 3D sphere class.
Vector3Ds get_grid_surface_cover(const Cylinder3D &cyl, int number_of_cycles, int number_of_points_on_cycle)
Generate a grid of 3d points on a cylinder surface.
BoundingBoxD< D > get_bounding_box(const BoundingBoxD< D > &g)
Definition: BoundingBoxD.h:160