RDKit
Open-source cheminformatics and machine learning.
UniformGrid3D.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2005-2013 Greg Landrum and Rational Discovery LLC
3 //
4 // @@ All Rights Reserved @@
5 // This file is part of the RDKit.
6 // The contents are covered by the terms of the BSD license
7 // which is included in the file license.txt, found at the root
8 // of the RDKit source tree.
9 //
10 #ifndef _UNIFORMGRID3D_H_20050124_1703
11 #define _UNIFORMGRID3D_H_20050124_1703
12 
13 #include "point.h"
15 #include "Grid3D.h"
16 #include <iostream>
17 
18 namespace RDGeom {
19  class UniformGrid3D : public Grid3D {
20 
21  public:
22 
23  //! \brief ctor
24  /*
25  \param dimX: the x dimension of the grid, in Angstroms
26  \param dimY: the y dimension of the grid, in Angstroms
27  \param dimZ: the z dimension of the grid, in Angstroms
28  \param spacing: the grid spacing, in Angstroms
29  \param valType: the data type of the grid (determines the number of bits
30  per point)
31  \param offset: OPTIONAL: the offset of the grid from (0,0,0), in Angstroms.
32 
33  \b Note: the values of arguments such as \c dimX and \c spacing
34  don't actually need to be in Angstroms, but they should be internally
35  consistent.
36 
37  */
38  UniformGrid3D(double dimX, double dimY, double dimZ, double spacing=0.5,
40  const RDGeom::Point3D *offset=0){
41  if (offset == 0) {
42  initGrid(dimX, dimY, dimZ, spacing, valType,
43  Point3D(-0.5*dimX, -0.5*dimY, -0.5*dimZ));
44  } else {
45  initGrid(dimX, dimY, dimZ, spacing, valType, *offset);
46  }
47  }
48  //! copy ctor
49  UniformGrid3D(const UniformGrid3D &other);
50  //! construct from a string pickle
51  UniformGrid3D(const std::string pkl);
52  //! construct from a text pickle
53  UniformGrid3D(const char *pkl,unsigned int);
54 
56 
57  //! \brief Get the index of the grid point closest to point
58  //!
59  //! \return the integer index, -1 if the specified point is outside the grid
60  int getGridPointIndex(const Point3D &point) const;
61 
62  //! \brief Get the value at the grid point closest to the specified point
63  //!
64  //! \return the integer value, -1 if the specified index is outside the grid
65  int getVal(const Point3D &point) const;
66 
67  //! \brief Get the value at a specified grid point
68  //!
69  //! \return the unsigned integer value
70  unsigned int getVal(unsigned int pointId) const;
71 
72  //! \brief Set the value at the grid point closest to the specified point
73  //!
74  //! doesn't do anything if the point is outside the grid
75  void setVal(const Point3D &point, unsigned int val);
76 
77  //! \brief get the location of the specified grid point
78  Point3D getGridPointLoc(unsigned int pointId) const;
79 
80  //! \brief Set the value at the specified grid point
81  void setVal(unsigned int pointId, unsigned int val);
82 
83  //! \brief get the size of the grid (number of grid points)
84  unsigned int getSize() const { return d_numX*d_numY*d_numZ; };
85 
86  //! \brief set the occupancy for a multi-layered sphere
87  /*!
88  This function encodes the occupancy for a sphere and multiple layers around it
89  \param center location of the sphere center
90  \param radius Radius of the base sphere
91  \param stepSize thickness of each layer on top of the base sphere
92  \param maxNumLayers maximum number of layers, if -1 this is determined by
93  the number of bits used per grid points in the storage
94  \param ignoreOutOfBound if true, ignore if center is outside the grid, otherwise throw
95  an exception
96 
97  */
98  void setSphereOccupancy(const Point3D & center, double radius,
99  double stepSize, int maxNumLayers=-1,
100  bool ignoreOutOfBound=true);
101 
102  //! \brief get the index of the grid point given the x, y, z indices
103  //!
104  //! \return the integer value, -1 if the indices are outside the grid
105  int getGridIndex(unsigned int xi, unsigned int yi, unsigned int zi) const;
106 
107  //! \brief get the x, y, and z indices of a grid-point index
108  //!
109  void getGridIndices(unsigned int idx,unsigned int &xi, unsigned int &yi, unsigned int &zi) const;
110 
111 
112  //! \brief get the number of grid points along x-axis
113  unsigned int getNumX() const { return d_numX; };
114 
115  //! \brief get the number of grid points along y-axis
116  unsigned int getNumY() const { return d_numY; };
117 
118  //! \brief get the number of grid points along z-axis
119  unsigned int getNumZ() const { return d_numZ; };
120 
121  //! \brief get the grid's offset
122  const Point3D &getOffset() const { return d_offSet; };
123 
124  //! \brief get the grid's spacing
125  double getSpacing() const { return d_spacing; };
126 
127  //! \brief return a \b const pointer to our occupancy vector
128  const RDKit::DiscreteValueVect *getOccupancyVect() const { return dp_storage;} ;
129 
130  //! \brief returns true if the grid \c other has parameters
131  //! compatible with ours.
132  virtual bool compareParams(const UniformGrid3D &other) const;
133  //! \brief calculates the union between the data on this grid and
134  //! that on \c other.
135  //! This grid is modified.
136  //! NOTE that the grids must have the same parameters.
137  UniformGrid3D &operator|=(const UniformGrid3D &other);
138  //! \brief calculates the intersection between the data on this grid and
139  //! that on \c other.
140  //! This grid is modified.
141  //! NOTE that the grids must have the same parameters.
142  UniformGrid3D &operator&=(const UniformGrid3D &other);
143  //! \brief calculates the sum of the data on this grid and
144  //! that on \c other.
145  //! This grid is modified.
146  //! NOTE that the grids must have the same parameters.
147  UniformGrid3D &operator+=(const UniformGrid3D &other);
148  //! \brief calculates the difference between the data on this grid and
149  //! that on \c other.
150  //! This grid is modified.
151  //! NOTE that the grids must have the same parameters.
152  UniformGrid3D &operator-=(const UniformGrid3D &other);
153 
154  //! \brief create and return a pickle
155  std::string toString() const;
156 
158  PRECONDITION(dp_storage,"bad storage");
159  PRECONDITION(compareParams(other),"mismatched params");
160  UniformGrid3D res(d_numX*d_spacing,d_numY*d_spacing,d_numZ*d_spacing,
161  d_spacing,dp_storage->getValueType(),&d_offSet);
162  return res;
163  };
164 
165  private:
166  //! \brief internal initialization code
167  /*
168  \param dimX: the x dimension of the grid, in Angstroms
169  \param dimY: the y dimension of the grid, in Angstroms
170  \param dimZ: the z dimension of the grid, in Angstroms
171  \param spacing: the grid spacing, in Angstroms
172  \param valType: the data type of the grid (determines the number of bits
173  per point)
174  \param offset: the offset of the grid from (0,0,0), in Angstroms.
175  \param data: (optional) a pointer to a DiscreteValueVect to use, we take
176  ownership of the pointer.
177  */
178  void initGrid(double dimX, double dimY, double dimZ, double spacing,
180  const RDGeom::Point3D &offSet,RDKit::DiscreteValueVect *data=0);
181  unsigned int d_numX, d_numY, d_numZ; //! number of grid points along x, y, z axes
182  double d_spacing; //! grid spacing
183  Point3D d_offSet; //! the grid offset (from the origin)
184  RDKit::DiscreteValueVect *dp_storage; //! storage for values at each grid point
185 
186  //! \brief construct from a pickle
187  void initFromText(const char *pkl,const unsigned int length);
188 
189  };
190 
191  //! \brief writes the contents of the grid to a stream
192  /*
193  The grid is written in GRD format
194  */
195  void writeGridToStream(const UniformGrid3D &grid, std::ostream &outStrm);
196 
197  //! \brief writes the contents of the grid to a named file
198  /*
199  The grid is written in GRD format
200  */
201  void writeGridToFile(const UniformGrid3D &grid, std::string filename);
202 
203 }
204 
205 #endif
206 
int getGridIndex(unsigned int xi, unsigned int yi, unsigned int zi) const
get the index of the grid point given the x, y, z indices
Point3D getGridPointLoc(unsigned int pointId) const
get the location of the specified grid point
void writeGridToStream(const UniformGrid3D &grid, std::ostream &outStrm)
writes the contents of the grid to a stream
DiscreteValueType
used to define the possible range of the values
UniformGrid3D & operator-=(const UniformGrid3D &other)
calculates the difference between the data on this grid and that on other. This grid is modified...
int getVal(const Point3D &point) const
Get the value at the grid point closest to the specified point.
unsigned int getNumZ() const
get the number of grid points along z-axis
void setVal(const Point3D &point, unsigned int val)
Set the value at the grid point closest to the specified point.
UniformGrid3D & operator&=(const UniformGrid3D &other)
calculates the intersection between the data on this grid and that on other. This grid is modified...
std::string toString() const
create and return a pickle
Virtual base class for a grid object.
Definition: Grid3D.h:35
a class for efficiently storing vectors of discrete values
const Point3D & getOffset() const
get the grid&#39;s offset
const RDKit::DiscreteValueVect * getOccupancyVect() const
return a const pointer to our occupancy vector
UniformGrid3D(double dimX, double dimY, double dimZ, double spacing=0.5, RDKit::DiscreteValueVect::DiscreteValueType valType=RDKit::DiscreteValueVect::TWOBITVALUE, const RDGeom::Point3D *offset=0)
ctor
Definition: UniformGrid3D.h:38
virtual bool compareParams(const UniformGrid3D &other) const
returns true if the grid other has parameters compatible with ours.
double getSpacing() const
get the grid&#39;s spacing
unsigned int getNumX() const
get the number of grid points along x-axis
unsigned int getNumY() const
get the number of grid points along y-axis
void setSphereOccupancy(const Point3D &center, double radius, double stepSize, int maxNumLayers=-1, bool ignoreOutOfBound=true)
set the occupancy for a multi-layered sphere
void writeGridToFile(const UniformGrid3D &grid, std::string filename)
writes the contents of the grid to a named file
unsigned int getSize() const
get the size of the grid (number of grid points)
Definition: UniformGrid3D.h:84
#define PRECONDITION(expr, mess)
Definition: Invariant.h:119
UniformGrid3D operator&(const UniformGrid3D &other) const
void getGridIndices(unsigned int idx, unsigned int &xi, unsigned int &yi, unsigned int &zi) const
get the x, y, and z indices of a grid-point index
UniformGrid3D & operator|=(const UniformGrid3D &other)
calculates the union between the data on this grid and that on other. This grid is modified...
UniformGrid3D & operator+=(const UniformGrid3D &other)
calculates the sum of the data on this grid and that on other. This grid is modified. NOTE that the grids must have the same parameters.
DiscreteValueType getValueType() const
return the type of value being stored
int getGridPointIndex(const Point3D &point) const
Get the index of the grid point closest to point.