RDKit
Open-source cheminformatics and machine learning.
MolDraw2DUtils.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2016-2021 Greg Landrum and other RDKit contributors
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 
11 #include <RDGeneral/export.h>
12 #ifndef MOLDRAW2DUTILS_H
13 #define MOLDRAW2DUTILS_H
14 #include <GraphMol/RWMol.h>
15 
16 #include <tuple>
17 
18 // ****************************************************************************
19 
20 namespace RDKit {
21 class MolDraw2D;
22 
23 namespace MolDraw2DUtils {
24 
25 //! Does some cleanup operations on the molecule to prepare it to draw nicely
26 /*
27 The operations include: kekulization, addition of chiral Hs (so that we can draw
28 wedges to them), wedging of bonds at chiral centers, and generation of a 2D
29 conformation if the molecule does not already have a conformation
30 
31 \param mol: the molecule to be modified
32 \param kekulize: toggles kekulization (this can fail, see below)
33 \param addChiralHs: adds Hs to the graph on chiral atoms
34 \param wedgeBonds: calls WedgeMolBonds()
35 \param forceCoords: generates a 2D conformation even if one is present already
36 \param wavyBonds: calls addWavyBondsForStereoAny() and clears other markers that
37  double bond stereo is unknown
38 
39 NOTE: the kekulization step can fail, throwing a MolSanitizeExecption. If this
40 happens the molecule will be in an inconsistent, partially kekulized, state.
41 This isn't normally a problem for molecules that have been sanitized, but can be
42 problematic if the molecules have been modified post santitization.
43 */
45  RWMol &mol, bool kekulize = true, bool addChiralHs = true,
46  bool wedgeBonds = true, bool forceCoords = false, bool wavyBonds = false);
47 
48 //! prepare a molecule for drawing and draw it
49 /*
50  \param mol: the molecule to draw
51  \param legend: (optional) the legend (to be drawn under the molecule)
52  \param highlight_atoms: (optional) vector of atom ids to highlight
53  \param highlight_atoms: (optional) vector of bond ids to highlight
54  \param highlight_atom_map: (optional) map from atomId -> DrawColour
55  providing the highlight colors. If not provided the default
56  highlight colour from \c drawOptions() will be used.
57  \param highlight_bond_map: (optional) map from bondId -> DrawColour
58  providing the highlight colors. If not provided the default
59  highlight colour from \c drawOptions() will be used.
60  \param highlight_radii: (optional) map from atomId -> radius (in molecule
61  coordinates) for the radii of atomic highlights. If not provided
62  the default value from \c drawOptions() will be used.
63  \param confId: (optional) conformer ID to be used for atomic coordinates
64 
65 */
67  MolDraw2D &drawer, const ROMol &mol, const std::string &legend = "",
68  const std::vector<int> *highlight_atoms = nullptr,
69  const std::vector<int> *highlight_bonds = nullptr,
70  const std::map<int, DrawColour> *highlight_atom_map = nullptr,
71  const std::map<int, DrawColour> *highlight_bond_map = nullptr,
72  const std::map<int, double> *highlight_radii = nullptr, int confId = -1,
73  bool kekulize = true, bool addChiralHs = true, bool wedgeBonds = true,
74  bool forceCoords = false, bool wavyBonds = false);
75 
77  const char *json);
79  const std::string &json);
81  const char *json);
83  MolDrawOptions &opts, const std::string &json);
84 
85 struct ContourParams {
86  bool setScale = true; // assumes the grid is drawn first
87  bool dashNegative = true; // use dashed lines for negative contours
88  bool fillGrid = false; // shade the grid
89  double gridResolution = 0.15; // spacing between elements of the grid
90  double contourWidth = 1.0; // linewidth for drawing contours
91  double extraGridPadding = 0.0; // extra padding (in molecule coordinates)
92  DrawColour contourColour = {0.5, 0.5, 0.5,
93  0.5}; // color for drawing contours
94  std::vector<DrawColour> colourMap = {
95  {0.557, 0.004, 0.322, 0.5},
96  {1, 1, 1, 0.5},
97  {0.153, 0.392, 0.098, 0.5}}; // similarity map color scheme
98 };
99 
100 //! Generates and draws contours for data on a grid
101 /*
102  \param drawer: the MolDraw2D object to use
103  \param grid: the data to be contoured
104  \param xcoords: x positions of the grid points
105  \param ycoords: y positions of the grid points
106  \param nContours: the number of contours to draw
107  \param levels: the contours to use
108  \param ps: additional parameters controlling the contouring.
109  \param mol: molecule to be used to adjust the scale of the drawing.
110  If the \c levels argument is empty, the contour levels will be determined
111  automatically from the max and min values on the grid and \c levels will
112  be updated to include the contour levels.
113 
114  If \c ps.fillGrid is set, the data on the grid will also be drawn using
115  the color scheme in \c ps.colourMap
116 
117  if the \c mol argument is given, it will be used to adjust the scale of
118  drawing. This is because a common use is to draw the molecule onto
119  the contour, and it makes sense if it fits.
120 
121 */
123  MolDraw2D &drawer, const double *grid, const std::vector<double> &xcoords,
124  const std::vector<double> &ycoords, size_t nContours,
125  std::vector<double> &levels, const ContourParams &ps = ContourParams(),
126  const ROMol *mol = nullptr);
127 //! \overload
129  MolDraw2D &drawer, const double *grid, const std::vector<double> &xcoords,
130  const std::vector<double> &ycoords, size_t nContours = 10,
131  const ContourParams &ps = ContourParams(), const ROMol *mol = nullptr) {
132  std::vector<double> levels;
133  contourAndDrawGrid(drawer, grid, xcoords, ycoords, nContours, levels, ps,
134  mol);
135 };
136 
137 //! Generates and draws contours for a set of gaussians
138 /*
139  \param drawer: the MolDraw2D object to use
140  \param locs: locations of the gaussians
141  \param heights: the heights (or weights) of the gaussians
142  \param widths: the standard deviations of the gaussians
143  \param nContours: the number of contours to draw
144  \param levels: the contours to use
145  \param ps: additional parameters controlling the contouring.
146  \param mol: molecule to be used to adjust the scale of the drawing.
147 
148  The values are calculated on a grid with spacing \c ps.gridResolution.
149  If \c ps.setScale is set, the grid size will be calculated based on the
150  locations of the gaussians and \c ps.extraGridPadding. Otherwise the current
151  size of the viewport will be used.
152 
153  If the \c levels argument is empty, the contour levels will be determined
154  automatically from the max and min values on the grid and \c levels will
155  be updated to include the contour levels.
156 
157  If \c ps.fillGrid is set, the data on the grid will also be drawn using
158  the color scheme in \c ps.colourMap
159 
160  if the \c mol argument is given, it will be used to adjust the scale of
161  drawing. This is because a common use is to draw the molecule onto
162  the contour, and it makes sense if it fits.
163 
164 */
166  MolDraw2D &drawer, const std::vector<Point2D> &locs,
167  const std::vector<double> &heights, const std::vector<double> &widths,
168  size_t nContours, std::vector<double> &levels,
169  const ContourParams &ps = ContourParams(), const ROMol *mol = nullptr);
170 //! \overload
172  MolDraw2D &drawer, const std::vector<Point2D> &locs,
173  const std::vector<double> &heights, const std::vector<double> &widths,
174  size_t nContours = 10, const ContourParams &ps = ContourParams(),
175  const ROMol *mol = nullptr) {
176  std::vector<double> levels;
177  contourAndDrawGaussians(drawer, locs, heights, widths, nContours, levels, ps,
178  mol);
179 };
180 
181 //! Draw a molecule to a MolDraw2D object according to ACS 1996 guidelines
182 /*
183  The ACS1996 guidelines, as described at
184  https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Chemistry/Structure_drawing
185  A number of values in drawer.drawOptions() are changed.
186  This is designed to be used with a flexiCanvas, i.e. a MolDraw2D object
187  created with width and height -1, because it works to a fixed scale.
188  It will issue a warning if the dimensions are otherwise and the picture may
189  look sub-optimal.
190  */
192  MolDraw2D &drawer, const ROMol &mol, const std::string &legend,
193  const std::vector<int> *highlight_atoms,
194  const std::vector<int> *highlight_bonds,
195  const std::map<int, DrawColour> *highlight_atom_map = nullptr,
196  const std::map<int, DrawColour> *highlight_bond_map = nullptr,
197  const std::map<int, double> *highlight_radii = nullptr, int confId = -1);
198 
199 //! Set the draw options to produce something as close as possible to
200 //! the ACS 1996 guidelines as described at
201 //! https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Chemistry/Structure_drawing
202 /*
203  \param MolDrawOptions opt - the options what will be changed
204  \param float meanBondLength - mean bond length of the molecule
205 
206  Works best if the MolDraw2D object is created with width and height -1 (a
207  flexiCanvas).
208  The mean bond length may be calculated with MolDraw2DUtils::meanBondLength.
209  It is used to calculate the offset for the lines in multiple bonds.
210 
211  Options changed are:
212  bondLineWidth = 0.6
213  scaleBondWidth = false
214  scalingFactor = 14.4 / meanBondLen
215  multipleBondOffset = 0.18
216  highlightBondWidthMultiplier = 32
217  setMonochromeMode - black and white
218  fixedFontSize = 10
219  additionalAtomLabelPadding = 0.066
220  fontFile - if it isn't set already, then if RDBASE is set and the file
221  exists, uses $RDBASE/Fonts/Data/FreeSans.ttf. Otherwise uses
222  BuiltinRobotoRegular.
223  */
225  double meanBondLen = 1.0);
226 RDKIT_MOLDRAW2D_EXPORT double meanBondLength(const ROMol &mol, int confId = -1);
227 } // namespace MolDraw2DUtils
228 
229 } // namespace RDKit
230 #endif // MOLDRAW2DUTILS_H
Defines the editable molecule class RWMol.
MolDraw2D is the base class for doing 2D renderings of molecules.
Definition: MolDraw2D.h:47
RWMol is a molecule class that is intended to be edited.
Definition: RWMol.h:32
#define RDKIT_MOLDRAW2D_EXPORT
Definition: export.h:281
RDKIT_MOLDRAW2D_EXPORT void updateMolDrawOptionsFromJSON(MolDrawOptions &opts, const char *json)
RDKIT_MOLDRAW2D_EXPORT void contourAndDrawGrid(MolDraw2D &drawer, const double *grid, const std::vector< double > &xcoords, const std::vector< double > &ycoords, size_t nContours, std::vector< double > &levels, const ContourParams &ps=ContourParams(), const ROMol *mol=nullptr)
Generates and draws contours for data on a grid.
RDKIT_MOLDRAW2D_EXPORT void prepareAndDrawMolecule(MolDraw2D &drawer, const ROMol &mol, const std::string &legend="", const std::vector< int > *highlight_atoms=nullptr, const std::vector< int > *highlight_bonds=nullptr, const std::map< int, DrawColour > *highlight_atom_map=nullptr, const std::map< int, DrawColour > *highlight_bond_map=nullptr, const std::map< int, double > *highlight_radii=nullptr, int confId=-1, bool kekulize=true, bool addChiralHs=true, bool wedgeBonds=true, bool forceCoords=false, bool wavyBonds=false)
prepare a molecule for drawing and draw it
RDKIT_MOLDRAW2D_EXPORT void prepareMolForDrawing(RWMol &mol, bool kekulize=true, bool addChiralHs=true, bool wedgeBonds=true, bool forceCoords=false, bool wavyBonds=false)
Does some cleanup operations on the molecule to prepare it to draw nicely.
RDKIT_MOLDRAW2D_EXPORT void setACS1996Options(MolDrawOptions &opts, double meanBondLen=1.0)
RDKIT_MOLDRAW2D_EXPORT void updateDrawerParamsFromJSON(MolDraw2D &drawer, const char *json)
RDKIT_MOLDRAW2D_EXPORT double meanBondLength(const ROMol &mol, int confId=-1)
RDKIT_MOLDRAW2D_EXPORT void drawMolACS1996(MolDraw2D &drawer, const ROMol &mol, const std::string &legend, const std::vector< int > *highlight_atoms, const std::vector< int > *highlight_bonds, const std::map< int, DrawColour > *highlight_atom_map=nullptr, const std::map< int, DrawColour > *highlight_bond_map=nullptr, const std::map< int, double > *highlight_radii=nullptr, int confId=-1)
Draw a molecule to a MolDraw2D object according to ACS 1996 guidelines.
RDKIT_MOLDRAW2D_EXPORT void contourAndDrawGaussians(MolDraw2D &drawer, const std::vector< Point2D > &locs, const std::vector< double > &heights, const std::vector< double > &widths, size_t nContours, std::vector< double > &levels, const ContourParams &ps=ContourParams(), const ROMol *mol=nullptr)
Generates and draws contours for a set of gaussians.
Std stuff.
Definition: Abbreviations.h:19
std::vector< DrawColour > colourMap