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 <boost/tuple/tuple.hpp>
17
18// ****************************************************************************
19
20namespace RDKit {
21class MolDraw2D;
22
23namespace MolDraw2DUtils {
24
25//! Does some cleanup operations on the molecule to prepare it to draw nicely
26/*
27The operations include: kekulization, addition of chiral Hs (so that we can draw
28wedges to them), wedging of bonds at chiral centers, and generation of a 2D
29conformation 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
39NOTE: the kekulization step can fail, throwing a MolSanitizeExecption. If this
40happens the molecule will be in an inconsistent, partially kekulized, state.
41This isn't normally a problem for molecules that have been sanitized, but can be
42problematic 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);
74
76 const char *json);
78 const std::string &json);
80 const char *json);
82 MolDrawOptions &opts, const std::string &json);
83
85 bool setScale = true; // assumes the grid is drawn first
86 bool dashNegative = true; // use dashed lines for negative contours
87 bool fillGrid = false; // shade the grid
88 double gridResolution = 0.15; // spacing between elements of the grid
89 double contourWidth = 1.0; // linewidth for drawing contours
90 double extraGridPadding = 0.0; // extra padding (in molecule coordinates)
91 DrawColour contourColour = {0.5, 0.5, 0.5,
92 0.5}; // color for drawing contours
93 std::vector<DrawColour> colourMap = {
94 {0.557, 0.004, 0.322, 0.5},
95 {1, 1, 1, 0.5},
96 {0.153, 0.392, 0.098, 0.5}}; // similarity map color scheme
97};
98
99//! Generates and draws contours for data on a grid
100/*
101 \param drawer: the MolDraw2D object to use
102 \param grid: the data to be contoured
103 \param xcoords: x positions of the grid points
104 \param ycoords: y positions of the grid points
105 \param nContours: the number of contours to draw
106 \param levels: the contours to use
107 \param ps: additional parameters controlling the contouring.
108 \param mol: molecule to be used to adjust the scale of the drawing.
109 If the \c levels argument is empty, the contour levels will be determined
110 automatically from the max and min values on the grid and \c levels will
111 be updated to include the contour levels.
112
113 If \c ps.fillGrid is set, the data on the grid will also be drawn using
114 the color scheme in \c ps.colourMap
115
116 if the \c mol argument is given, it will be used to adjust the scale of
117 drawing. This is because a common use is to draw the molecule onto
118 the contour, and it makes sense if it fits.
119
120*/
122 MolDraw2D &drawer, const double *grid, const std::vector<double> &xcoords,
123 const std::vector<double> &ycoords, size_t nContours,
124 std::vector<double> &levels, const ContourParams &ps = ContourParams(),
125 const ROMol *mol = nullptr);
126//! \overload
128 MolDraw2D &drawer, const double *grid, const std::vector<double> &xcoords,
129 const std::vector<double> &ycoords, size_t nContours = 10,
130 const ContourParams &ps = ContourParams(), const ROMol *mol = nullptr) {
131 std::vector<double> levels;
132 contourAndDrawGrid(drawer, grid, xcoords, ycoords, nContours, levels, ps,
133 mol);
134};
135
136//! Generates and draws contours for a set of gaussians
137/*
138 \param drawer: the MolDraw2D object to use
139 \param locs: locations of the gaussians
140 \param heights: the heights (or weights) of the gaussians
141 \param widths: the standard deviations of the gaussians
142 \param nContours: the number of contours to draw
143 \param levels: the contours to use
144 \param ps: additional parameters controlling the contouring.
145 \param mol: molecule to be used to adjust the scale of the drawing.
146
147 The values are calculated on a grid with spacing \c ps.gridResolution.
148 If \c ps.setScale is set, the grid size will be calculated based on the
149 locations of the gaussians and \c ps.extraGridPadding. Otherwise the current
150 size of the viewport will be used.
151
152 If the \c levels argument is empty, the contour levels will be determined
153 automatically from the max and min values on the grid and \c levels will
154 be updated to include the contour levels.
155
156 If \c ps.fillGrid is set, the data on the grid will also be drawn using
157 the color scheme in \c ps.colourMap
158
159 if the \c mol argument is given, it will be used to adjust the scale of
160 drawing. This is because a common use is to draw the molecule onto
161 the contour, and it makes sense if it fits.
162
163*/
165 MolDraw2D &drawer, const std::vector<Point2D> &locs,
166 const std::vector<double> &heights, const std::vector<double> &widths,
167 size_t nContours, std::vector<double> &levels,
168 const ContourParams &ps = ContourParams(), const ROMol *mol = nullptr);
169//! \overload
171 MolDraw2D &drawer, const std::vector<Point2D> &locs,
172 const std::vector<double> &heights, const std::vector<double> &widths,
173 size_t nContours = 10, const ContourParams &ps = ContourParams(),
174 const ROMol *mol = nullptr) {
175 std::vector<double> levels;
176 contourAndDrawGaussians(drawer, locs, heights, widths, nContours, levels, ps,
177 mol);
178};
179
180//! Draw a molecule to a MolDraw2D object according to ACS 1996 guidelines
181/*
182 The ACS1996 guidelines, as described at
183 https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Chemistry/Structure_drawing
184 A number of values in drawer.drawOptions() are changed.
185 This is designed to be used with a flexiCanvas, i.e. a MolDraw2D object
186 created with width and height -1, because it works to a fixed scale.
187 It will issue a warning if the dimensions are otherwise and the picture may
188 look sub-optimal.
189 */
191 MolDraw2D &drawer, const ROMol &mol, const std::string &legend,
192 const std::vector<int> *highlight_atoms,
193 const std::vector<int> *highlight_bonds,
194 const std::map<int, DrawColour> *highlight_atom_map = nullptr,
195 const std::map<int, DrawColour> *highlight_bond_map = nullptr,
196 const std::map<int, double> *highlight_radii = nullptr, int confId = -1);
197
198//! Set the draw options to produce something as close as possible to
199//! the ACS 1996 guidelines as described at
200//! https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Chemistry/Structure_drawing
201/*
202 \param MolDrawOptions opt - the options what will be changed
203 \param float meanBondLength - mean bond length of the molecule
204
205 Works best if the MolDraw2D object is created with width and height -1 (a
206 flexiCanvas).
207 The mean bond length may be calculated with MolDraw2DUtils::meanBondLength.
208 It is used to calculate the offset for the lines in multiple bonds.
209
210 Options changed are:
211 bondLineWidth = 0.6
212 scaleBondWidth = false
213 scalingFactor = 14.4 / meanBondLen
214 multipleBondOffset = 0.18
215 highlightBondWidthMultiplier = 32
216 setMonochromeMode - black and white
217 fixedFontSize = 10
218 additionalAtomLabelPadding = 0.066
219 fontFile - if it isn't set already, then if RDBASE is set and the file
220 exists, uses $RDBASE/Fonts/Data/FreeSans.ttf. Otherwise uses
221 BuiltinRobotoRegular.
222 */
224 double meanBondLen = 1.0);
225RDKIT_MOLDRAW2D_EXPORT double meanBondLength(const ROMol &mol, int confId = -1);
226} // namespace MolDraw2DUtils
227
228} // namespace RDKit
229#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 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.
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)
prepare a molecule for drawing and draw it
Std stuff.
Definition: Abbreviations.h:19
std::vector< DrawColour > colourMap