IMP logo
IMP Reference Guide  2.18.0
The Integrative Modeling Platform
Surface.h
Go to the documentation of this file.
1 /**
2  * \file IMP/core/Surface.h \brief Simple surface decorator.
3  *
4  * Copyright 2007-2022 IMP Inventors. All rights reserved.
5  *
6  */
7 
8 #ifndef IMPCORE_SURFACE_H
9 #define IMPCORE_SURFACE_H
10 
11 #include <IMP/core/core_config.h>
12 #include <IMP/core/XYZ.h>
13 #include <IMP/core/XYZR.h>
15 #include <IMP/algebra/Plane3D.h>
17 #include <IMP/algebra/Segment3D.h>
18 #include <IMP/algebra/Cylinder3D.h>
19 #include <IMP/Constraint.h>
20 #include <IMP/decorator_macros.h>
21 #include <IMP/Decorator.h>
22 #include <IMP/Particle.h>
23 #include <IMP/Object.h>
24 #include <IMP/Model.h>
25 #include <IMP/Pointer.h>
26 
27 
28 IMPCORE_BEGIN_NAMESPACE
29 
30 //! A decorator for a particle that represents a surface, its coordinates, and orientation.
31 /** \ingroup decorators
32  \see XYZ
33  \see Direction
34 */
35 class IMPCOREEXPORT Surface : public XYZ {
36  public:
37  static void do_setup_particle(Model *m, ParticleIndex pi,
38  const algebra::Vector3D &center = algebra::Vector3D(0, 0, 0),
39  const algebra::Vector3D &normal = algebra::Vector3D(0, 0, 1));
40 
41  static void do_setup_particle(Model *m, ParticleIndex pi,
42  const algebra::ReferenceFrame3D &rf);
43 
46  //! Set up the surface to align with the reference frame.
50  IMP_DECORATOR_GET_SET(normal_x, get_normal_key(0), Float, Float);
51  IMP_DECORATOR_GET_SET(normal_y, get_normal_key(1), Float, Float);
52  IMP_DECORATOR_GET_SET(normal_z, get_normal_key(2), Float, Float);
53 
54  //! Check if particle is setup as a surface.
55  static bool get_is_setup(Model *m, ParticleIndex pi);
56 
57  static FloatKey get_normal_key(unsigned int i);
58 
59  //! Get the vector of derivatives added to the surface normal.
61  return get_particle()->get_derivative(get_normal_key(i));
62  }
63 
64  //! Get the vector of derivatives added to the surface normal.
65  algebra::Vector3D get_normal_derivatives() const;
66 
67  //! Add v to the derivative of the ith coordinate of the normal.
69  get_particle()->add_to_derivative(get_normal_key(i), v, d);
70  }
71 
72  //! Add v to the derivatives of the x,y,z coordinates of the normal.
73  void add_to_normal_derivatives(const algebra::Vector3D &v,
75 
76  //! Get whether surface normal is optimized.
77  bool get_normal_is_optimized() const;
78 
79  //! Set whether surface normal is optimized.
80  void set_normal_is_optimized(bool tf) const;
81 
82  //! Get unit vector normal to surface.
83  algebra::Vector3D get_normal() const;
84 
85  //! Set surface normal.
86  void set_normal(const algebra::Vector3D &normal);
87 
88  //! Flip surface so normal is reversed.
89  void reflect() { set_normal(-get_normal()); }
90 
91  //! Get height of point above surface.
92  /** \note If point is below surface, value is negative. */
93  double get_height(const algebra::Vector3D &v) const;
94 
95  //! Get depth of point below surface.
96  /** \note If point is above surface, value is negative. */
97  double get_depth(const algebra::Vector3D &v) const;
98 
99  //! Get distance from point to surface.
100  double get_distance_to(const algebra::Vector3D &v) const;
101 
102  //! Get distance from point to center of surface.
103  double get_distance_to_center(const algebra::Vector3D &v) const;
104 
105  //! Set coordinates and normal from a reference frame.
109  set_coordinates(c);
110  set_normal(n);
111  }
112 
113  //! Get surface orientation as a reference frame.
114  algebra::ReferenceFrame3D get_reference_frame() const;
115 
116  //! Get a plane that lies along the surface.
118  return algebra::Plane3D(get_coordinates(), get_normal());
119  }
120 };
121 
122 IMP_DECORATORS(Surface, Surfaces, XYZs);
123 
124 //! Get height of sphere above surface.
125 /** \note If sphere crosses or is below surface, height is
126  negative the distance from the surface to the furthest point
127  of the sphere.
128 */
129 inline double get_height(const Surface &s, const XYZR &d) {
130  return s.get_height(d.get_coordinates()) - d.get_radius();
131 }
132 
133 //! Get height of point above surface.
134 inline double get_height(const Surface &s, const XYZ &d) {
135  return s.get_height(d.get_coordinates());
136 }
137 
138 //! Get depth of sphere below surface.
139 /** \note If sphere crosses or is above surface, depth is
140  negative the distance from the surface to the furthest point
141  of the sphere.
142 */
143 inline double get_depth(const Surface &s, const XYZR &d) {
144  return s.get_depth(d.get_coordinates()) - d.get_radius();
145 }
146 
147 //! Get depth of point below surface.
148 inline double get_depth(const Surface &s, const XYZ &d) {
149  return s.get_depth(d.get_coordinates());
150 }
151 
152 //! Get distance from sphere to surface.
153 inline double get_distance(const Surface &s, const XYZR &d) {
154  return s.get_distance_to(d.get_coordinates()) - d.get_radius();
155 }
156 
157 //! Get distance from point to surface.
158 inline double get_distance(const Surface &s, const XYZ &d) {
159  return s.get_distance_to(d.get_coordinates());
160 }
161 
162 /** \class SurfaceGeometry
163  \brief Display a Surface particle as a cylindrical disk.
164 
165  \class SurfacesGeometry
166  \brief Display an IMP::SingletonContainer of Surface particles
167  as cylindrical disks.
168 */
169 class IMPCOREEXPORT SurfaceGeometry : public display::Geometry {
170  Surface s_;
173 
174  //! Get disk aligned with surface plane for geometry.
175  algebra::Cylinder3D get_cylinder(double radius=10.0,
176  double thick=0.1) const;
177 
178  //! Get line segment along surface normal for geometry.
179  algebra::Segment3D get_segment(double length=5.0) const;
180 
181  public:
182  SurfaceGeometry(std::string n="SurfaceGeometry");
183  SurfaceGeometry(Surface s, const std::string n="SurfaceGeometry");
184  SurfaceGeometry(Surface s, const display::Color &c, std::string n="SurfaceGeometry");
185  virtual const Surface get_geometry() const { return s_; }
186  void set_geometry(Surface s);
187  virtual display::Geometries get_components() const override;
189 };
190 //! Create a geometry from a Surface
192  const Surface s, std::string name = std::string("SurfaceGeometry%1%")) {
193  IMP_NEW(SurfaceGeometry, g, (s, name));
194  return g.release();
195 }
197 
198 //! Constrain a SurfaceGeometry to a Surface.
199 /** \note Use IMP.core.get_constrained_surface_geometry to create.
200 */
201 class IMPCOREEXPORT SurfaceGeometryConstraint : public IMP::Constraint {
202  ParticleIndex pi_;
204 
205  public:
207  : IMP::Constraint(s.get_model(), "SurfaceGeometryConstraint%1%")
208  , pi_(s.get_particle_index()), g_(g) {}
209 
210  Surface get_surface() const { return Surface(get_model(), pi_); }
211 
212  SurfaceGeometry* get_geometry() const { return g_; }
213 
214  virtual void do_update_attributes() override {};
215  virtual void do_update_derivatives(DerivativeAccumulator *) override {};
216  virtual void do_before_evaluate() override { g_->set_geometry(get_surface());}
217  virtual void do_after_evaluate(DerivativeAccumulator *) override {
218  g_->set_geometry(get_surface());
219  };
220 
221 
222  virtual ModelObjectsTemp do_get_inputs() const override {
223  ParticlesTemp ps = ParticlesTemp(1, get_surface().get_particle());
224  return ps;
225  }
226 
227  virtual ModelObjectsTemp do_get_outputs() const override {
228  ParticlesTemp ps = ParticlesTemp(1, get_surface().get_particle());
229  return ps;
230  }
231 
233 };
234 
235 //! Get surface geometry constrained to the surface.
237  const Surface s, std::string name="SurfaceGeometry%1%") {
238  IMP_NEW(SurfaceGeometry, g, (s, name));
240  s.get_model()->add_score_state(c.release());
241  return g.release();
242 }
244 
245 //! Constrain the center of a Surface for visualization.
246 /** The Surface center can wander laterally. This constraint ensures
247  the center is placed in the Surface such that it is along the
248  normal from a point.
249 */
250 class IMPCOREEXPORT LateralSurfaceConstraint : public IMP::Constraint {
251  ParticleIndex spi_;
252  ParticleIndex dpi_;
253 
254  public:
256  : IMP::Constraint(s.get_model(), "LateralSurfaceConstraint%1%")
257  , spi_(s.get_particle_index()), dpi_(d.get_particle_index()) {}
258 
259  virtual void do_update_attributes() override {}
260  virtual void do_update_derivatives(DerivativeAccumulator *) override {}
261  virtual void do_before_evaluate() override {
262  algebra::Vector3D d = XYZ(get_model(), dpi_).get_coordinates();
263  Surface s = Surface(get_model(), spi_);
265  }
266  virtual void do_after_evaluate(DerivativeAccumulator *) override {}
267 
268  virtual ModelObjectsTemp do_get_inputs() const override {
269  ParticlesTemp ps;
270  ps.push_back(get_model()->get_particle(dpi_));
271  ps.push_back(get_model()->get_particle(spi_));
272  return ps;
273  }
274 
275  virtual ModelObjectsTemp do_get_outputs() const override {
276  ParticlesTemp ps = ParticlesTemp(1, get_model()->get_particle(spi_));
277  return ps;
278  }
279 
281 };
282 
283 IMPCORE_END_NAMESPACE
284 
285 #endif /* IMPCORE_SURFACE_H */
The base class for decorators.
#define IMP_DECORATOR_GET_SET(name, AttributeKey, Type, ReturnType)
Define methods for getting and setting a particular simple field.
double get_height(const Surface &s, const XYZR &d)
Get height of sphere above surface.
Definition: Surface.h:129
ParticleIndex get_particle_index() const
Returns the particle index decorated by this decorator.
Definition: Decorator.h:190
double get_height(const algebra::Vector3D &v) const
Get height of point above surface.
Represent an RGB color.
Definition: Color.h:25
double get_depth(const Surface &s, const XYZ &d)
Get depth of point below surface.
Definition: Surface.h:148
Float get_normal_derivative(int i) const
Get the vector of derivatives added to the surface normal.
Definition: Surface.h:60
Represent a cylinder in 3D.
The base class for geometry.
#define IMP_DECORATOR_SETUP_1(Name, FirstArgumentType, first_argument_name)
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
Constrain a SurfaceGeometry to a Surface.
Definition: Surface.h:201
Model * get_model() const
Returns the Model containing the particle.
Definition: Decorator.h:193
Storage of a model, its restraints, constraints and particles.
virtual ModelObjectsTemp do_get_inputs() const override
Definition: Surface.h:222
algebra::Plane3D get_plane() const
Get a plane that lies along the surface.
Definition: Surface.h:117
Display a Surface particle as a cylindrical disk.
Definition: Surface.h:169
Represent a cylinder in 3D.
Definition: Cylinder3D.h:27
Constrain the center of a Surface for visualization.
Definition: Surface.h:250
void add_to_normal_derivative(int i, Float v, DerivativeAccumulator &d)
Add v to the derivative of the ith coordinate of the normal.
Definition: Surface.h:68
virtual ModelObjectsTemp do_get_outputs() const override
Definition: Surface.h:275
double get_depth(const algebra::Vector3D &v) const
Get depth of point below surface.
Simple XYZ decorator.
A reference frame in 3D.
Simple implementation of segments in 3D.
#define IMP_NEW(Typename, varname, args)
Declare a ref counted pointer to a new object.
Definition: object_macros.h:74
Implement a constraint on the Model.
Definition: Constraint.h:49
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:73
virtual ModelObjectsTemp do_get_inputs() const override
Definition: Surface.h:268
virtual void do_before_evaluate() override
Update the state given the current state of the model.
Definition: Surface.h:216
Implement geometry for the basic shapes from IMP.algebra.
virtual ModelObjectsTemp do_get_outputs() const override
Definition: Surface.h:227
void set_coordinates(const algebra::Vector3D &v)
set all coordinates from a vector
Definition: XYZ.h:62
void set_reference_frame(const algebra::ReferenceFrame3D &rf)
Set coordinates and normal from a reference frame.
Definition: Surface.h:106
double get_height(const Surface &s, const XYZ &d)
Get height of point above surface.
Definition: Surface.h:134
SurfaceGeometry * create_geometry(const Surface s, std::string name=std::string("SurfaceGeometry%1%"))
Create a geometry from a Surface.
Definition: Surface.h:191
Helper macros for implementing Decorators.
A smart pointer to a ref-counted Object that is a class member.
Definition: Pointer.h:146
#define IMP_DECORATOR_SETUP_2(Name, FirstArgumentType, first_argument_name,SecondArgumentType, second_argument_name)
A decorator for a particle with x,y,z coordinates.
Definition: XYZ.h:30
#define IMP_DECORATOR_SETUP_0(Name)
const algebra::Vector3D & get_coordinates() const
Convert it to a vector.
Definition: XYZ.h:109
A base class for constraints.
A decorator for a particle that represents a surface, its coordinates, and orientation.
Definition: Surface.h:35
Particle * get_particle() const
Returns the particle decorated by this decorator.
Definition: Decorator.h:173
Classes to handle individual model particles. (Note that implementation of inline functions is in int...
double get_distance_to(const algebra::Vector3D &v) const
Get distance from point to surface.
Simple implementation of segments in 3D.
Definition: Segment3D.h:25
#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.
SurfaceGeometry * get_constrained_surface_geometry(const Surface s, std::string name="SurfaceGeometry%1%")
Get surface geometry constrained to the surface.
Definition: Surface.h:236
Simple 3D plane class.
virtual Geometries get_components() const
Return a set of geometry composing this one.
A shared base class to help in debugging and things.
virtual void do_after_evaluate(DerivativeAccumulator *) override
Do any necessary updates after the model score is calculated.
Definition: Surface.h:217
#define IMP_DECORATOR_METHODS(Name, Parent)
VectorD< 3 > Vector3D
Definition: VectorD.h:421
double Float
Basic floating-point value (could be float, double...)
Definition: types.h:19
void reflect()
Flip surface so normal is reversed.
Definition: Surface.h:89
double get_depth(const Surface &s, const XYZR &d)
Get depth of sphere below surface.
Definition: Surface.h:143
#define IMP_DECORATORS(Name, PluralName, Parent)
Define the types for storing sets of decorators.
Vector3D get_projected(const Vector3D &p) const
Project the point onto the plane.
Definition: Plane3D.h:38
virtual void do_after_evaluate(DerivativeAccumulator *) override
Do any necessary updates after the model score is calculated.
Definition: Surface.h:266
double get_distance(const Surface &s, const XYZ &d)
Get distance from point to surface.
Definition: Surface.h:158
A reference frame in 3D.
Vector3D get_global_coordinates(const Vector3D &v) const
Represent a plane in 3D.
Definition: Plane3D.h:21
Decorator for a sphere-like particle.
DensityMap * get_segment(DensityMap *map_to_segment, int nx_start, int nx_end, int ny_start, int ny_end, int nz_start, int nz_end)
Get a segment of the map according to xyz indexes.
virtual void do_before_evaluate() override
Update the state given the current state of the model.
Definition: Surface.h:261
Class for adding derivatives from restraints to the model.
A decorator for a particle with x,y,z coordinates and a radius.
Definition: XYZR.h:27