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