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  public:
21  //! \brief ctor
22  /*
23  \param dimX: the x dimension of the grid, in Angstroms
24  \param dimY: the y dimension of the grid, in Angstroms
25  \param dimZ: the z dimension of the grid, in Angstroms
26  \param spacing: the grid spacing, in Angstroms
27  \param valType: the data type of the grid (determines the number of bits
28  per point)
29  \param offset: OPTIONAL: the offset of the grid from (0,0,0), in
30  Angstroms.
31 
32  \b Note: the values of arguments such as \c dimX and \c spacing
33  don't actually need to be in Angstroms, but they should be internally
34  consistent.
35 
36  */
37  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
89  it
90  \param center location of the sphere center
91  \param radius Radius of the base sphere
92  \param stepSize thickness of each layer on top of the base sphere
93  \param maxNumLayers maximum number of layers, if -1 this is
94  determined by
95  the number of bits used per grid points in the
96  storage
97  \param ignoreOutOfBound if true, ignore if center is outside the grid,
98  otherwise throw
99  an exception
100 
101  */
102  void setSphereOccupancy(const Point3D &center, double radius, double stepSize,
103  int maxNumLayers = -1, bool ignoreOutOfBound = true);
104 
105  //! \brief get the index of the grid point given the x, y, z indices
106  //!
107  //! \return the integer value, -1 if the indices are outside the grid
108  int getGridIndex(unsigned int xi, unsigned int yi, unsigned int zi) const;
109 
110  //! \brief get the x, y, and z indices of a grid-point index
111  //!
112  void getGridIndices(unsigned int idx, unsigned int &xi, unsigned int &yi,
113  unsigned int &zi) const;
114 
115  //! \brief get the number of grid points along x-axis
116  unsigned int getNumX() const { return d_numX; };
117 
118  //! \brief get the number of grid points along y-axis
119  unsigned int getNumY() const { return d_numY; };
120 
121  //! \brief get the number of grid points along z-axis
122  unsigned int getNumZ() const { return d_numZ; };
123 
124  //! \brief get the grid's offset
125  const Point3D &getOffset() const { return d_offSet; };
126 
127  //! \brief get the grid's spacing
128  double getSpacing() const { return d_spacing; };
129 
130  //! \brief return a \b const pointer to our occupancy vector
132  return dp_storage;
133  };
134 
135  //! \brief returns true if the grid \c other has parameters
136  //! compatible with ours.
137  virtual bool compareParams(const UniformGrid3D &other) const;
138  //! \brief calculates the union 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 intersection between 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 sum of 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  //! \brief calculates the difference between the data on this grid and
154  //! that on \c other.
155  //! This grid is modified.
156  //! NOTE that the grids must have the same parameters.
157  UniformGrid3D &operator-=(const UniformGrid3D &other);
158 
159  //! \brief create and return a pickle
160  std::string toString() const;
161 
162  UniformGrid3D operator&(const UniformGrid3D &other) const {
163  PRECONDITION(dp_storage, "bad storage");
164  PRECONDITION(compareParams(other), "mismatched params");
165  UniformGrid3D res(d_numX * d_spacing, d_numY * d_spacing,
166  d_numZ * d_spacing, d_spacing, dp_storage->getValueType(),
167  &d_offSet);
168  return res;
169  };
170 
171  private:
172  //! \brief internal initialization code
173  /*
174  \param dimX: the x dimension of the grid, in Angstroms
175  \param dimY: the y dimension of the grid, in Angstroms
176  \param dimZ: the z dimension of the grid, in Angstroms
177  \param spacing: the grid spacing, in Angstroms
178  \param valType: the data type of the grid (determines the number of bits
179  per point)
180  \param offset: the offset of the grid from (0,0,0), in Angstroms.
181  \param data: (optional) a pointer to a DiscreteValueVect to use, we
182  take
183  ownership of the pointer.
184  */
185  void initGrid(double dimX, double dimY, double dimZ, double spacing,
187  const RDGeom::Point3D &offSet,
188  RDKit::DiscreteValueVect *data = 0);
189  unsigned int d_numX, d_numY,
190  d_numZ; //! number of grid points along x, y, z axes
191  double d_spacing; //! grid spacing
192  Point3D d_offSet; //! the grid offset (from the origin)
194  dp_storage; //! storage for values at each grid point
195 
196  //! \brief construct from a pickle
197  void initFromText(const char *pkl, const unsigned int length);
198 };
199 
200 //! \brief writes the contents of the grid to a stream
201 /*
202  The grid is written in GRD format
203 */
204 void writeGridToStream(const UniformGrid3D &grid, std::ostream &outStrm);
205 
206 //! \brief writes the contents of the grid to a named file
207 /*
208  The grid is written in GRD format
209 */
210 void writeGridToFile(const UniformGrid3D &grid, const std::string &filename);
211 }
212 
213 #endif
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:36
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:37
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
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:107
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
void writeGridToFile(const UniformGrid3D &grid, const std::string &filename)
writes the contents of the grid to a named file
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.