0
# Molecular Visualization
1

2
2D molecular structure rendering and image generation with customizable display options for creating publication-quality molecular graphics. RDKit's drawing system provides comprehensive visualization capabilities for molecules, reactions, and chemical data with support for various output formats and styling options.
3

4
## Capabilities
5

6
### Basic Molecular Drawing
7

8
Generate 2D molecular structure images with standard or custom display options.
9

10
```python { .api }
11
def MolToImage(mol: Mol, size: tuple = (300, 300), kekulize: bool = True,
12
               wedgeBonds: bool = True, fitImage: bool = False, atomLabels: dict = None,
13
               bondLabels: dict = None, highlightAtoms: list = None, 
14
               highlightBonds: list = None, highlightAtomColors: dict = None,
15
               highlightBondColors: dict = None, highlightRadius: dict = None) -> PIL.Image:
16
    """
17
    Generate a PIL Image of a molecule.
18
    
19
    Parameters:
20
    - mol: Input molecule
21
    - size: Image dimensions as (width, height) tuple (default (300, 300))
22
    - kekulize: Convert aromatic bonds to alternating single/double (default True)
23
    - wedgeBonds: Draw wedge/dash bonds for stereochemistry (default True)
24
    - fitImage: Fit molecule to image bounds (default False)
25
    - atomLabels: Dictionary mapping atom indices to label strings
26
    - bondLabels: Dictionary mapping bond indices to label strings
27
    - highlightAtoms: List of atom indices to highlight
28
    - highlightBonds: List of bond indices to highlight
29
    - highlightAtomColors: Dictionary mapping atom indices to highlight colors
30
    - highlightBondColors: Dictionary mapping bond indices to highlight colors
31
    - highlightRadius: Dictionary mapping atom indices to highlight radii
32
    
33
    Returns:
34
    PIL Image object
35
    """
36

37
def MolToFile(mol: Mol, filename: str, size: tuple = (300, 300), 
38
              imageType: str = None, **kwargs) -> None:
39
    """
40
    Save molecule image directly to file.
41
    
42
    Parameters:
43
    - mol: Input molecule
44
    - filename: Output file path (extension determines format)
45
    - size: Image dimensions as (width, height) tuple (default (300, 300))
46
    - imageType: Force specific image type ('png', 'svg', etc.)
47
    - **kwargs: Additional arguments passed to drawing functions
48
    
49
    Returns:
50
    None
51
    """
52
```
53

54
### Reaction Drawing
55

56
Visualize chemical reactions with reactants, products, and reaction arrows.
57

58
```python { .api }
59
def ReactionToImage(rxn, subImgSize: tuple = (200, 200), **kwargs) -> PIL.Image:
60
    """
61
    Generate a PIL Image of a chemical reaction.
62
    
63
    Parameters:
64
    - rxn: ChemicalReaction object
65
    - subImgSize: Size for individual molecule images (default (200, 200))
66
    - **kwargs: Additional drawing options
67
    
68
    Returns:
69
    PIL Image object showing the complete reaction
70
    """
71

72
def DrawReaction(rxn, **kwargs):
73
    """
74
    Draw a chemical reaction using matplotlib backend.
75
    
76
    Parameters:
77
    - rxn: ChemicalReaction object
78
    - **kwargs: Drawing options
79
    
80
    Returns:
81
    Matplotlib figure object
82
    """
83
```
84

85
### Multi-Molecule Grid Display
86

87
Display multiple molecules in organized grid layouts for comparison and analysis.
88

89
```python { .api }
90
def MolsToGridImage(mols: list, molsPerRow: int = 4, subImgSize: tuple = (200, 200),
91
                    legends: list = None, highlightAtomLists: list = None,
92
                    highlightBondLists: list = None, useSVG: bool = False,
93
                    returnPNG: bool = True, **kwargs) -> PIL.Image:
94
    """
95
    Generate a grid image of multiple molecules.
96
    
97
    Parameters:
98
    - mols: List of molecule objects
99
    - molsPerRow: Number of molecules per row (default 4)
100
    - subImgSize: Size of each molecule image (default (200, 200))
101
    - legends: List of legend strings for each molecule
102
    - highlightAtomLists: List of atom index lists to highlight for each molecule
103
    - highlightBondLists: List of bond index lists to highlight for each molecule
104
    - useSVG: Use SVG rendering (default False)
105
    - returnPNG: Return PNG format (default True)
106
    - **kwargs: Additional drawing options
107
    
108
    Returns:
109
    PIL Image object containing the molecule grid
110
    """
111

112
def MolsToImage(mols: list, **kwargs) -> PIL.Image:
113
    """
114
    Generate a single image containing multiple molecules.
115
    
116
    Parameters:
117
    - mols: List of molecule objects
118
    - **kwargs: Drawing options (same as MolsToGridImage)
119
    
120
    Returns:
121
    PIL Image object
122
    """
123
```
124

125
### SVG Generation
126

127
Generate scalable vector graphics for high-quality molecular illustrations.
128

129
```python { .api }
130
def MolToSVG(mol: Mol, size: tuple = (300, 300), kekulize: bool = True,
131
             drawer: object = None, **kwargs) -> str:
132
    """
133
    Generate SVG representation of a molecule.
134
    
135
    Parameters:
136
    - mol: Input molecule
137
    - size: Image dimensions as (width, height) tuple (default (300, 300))
138
    - kekulize: Convert aromatic bonds to alternating single/double (default True)
139
    - drawer: Custom drawer object (default None for auto-selection)
140
    - **kwargs: Additional drawing options
141
    
142
    Returns:
143
    SVG string representation
144
    """
145

146
def ReactionToSVG(rxn, **kwargs) -> str:
147
    """
148
    Generate SVG representation of a chemical reaction.
149
    
150
    Parameters:
151
    - rxn: ChemicalReaction object
152
    - **kwargs: Drawing options
153
    
154
    Returns:
155
    SVG string representation
156
    """
157
```
158

159
### Drawing Options and Styling
160

161
Customize molecular drawing appearance with detailed styling controls.
162

163
```python { .api }
164
class DrawingOptions:
165
    """
166
    Configuration object for molecular drawing options.
167
    """
168
    atomLabelFontSize: int = 12  # Font size for atom labels
169
    bondLineWidth: float = 2.0   # Width of bond lines
170
    multipleBondOffset: float = 0.15  # Offset for multiple bonds
171
    dummiesAreAttachments: bool = False  # Treat dummy atoms as attachment points
172
    circleAtoms: bool = True     # Draw circles around atoms
173
    highlightColour: tuple = (1, 1, 0)  # Default highlight color (RGB)
174
    atomColourPalette: dict = {}  # Custom atom color palette
175
    includeAtomTags: bool = False  # Include atom tags in drawing
176
    clearBackground: bool = True  # Use transparent background
177
    bgColor: tuple = (1, 1, 1)   # Background color (RGB)
178
    legendFontSize: int = 12     # Font size for legends
179

180
def SetDrawingOptions(opts: DrawingOptions) -> None:
181
    """
182
    Set global drawing options.
183
    
184
    Parameters:
185
    - opts: DrawingOptions object with configuration
186
    
187
    Returns:
188
    None
189
    """
190
```
191

192
### Interactive Drawing
193

194
Enable interactive molecular editing and manipulation.
195

196
```python { .api }
197
def MolFromPNG(pngData: bytes) -> Mol:
198
    """
199
    Extract molecule from PNG image data (if embedded).
200
    
201
    Parameters:
202
    - pngData: PNG image data as bytes
203
    
204
    Returns:
205
    Mol object or None if extraction fails
206
    """
207

208
def MolFromSVG(svgData: str) -> Mol:
209
    """
210
    Extract molecule from SVG string data (if embedded).
211
    
212
    Parameters:
213
    - svgData: SVG string data
214
    
215
    Returns:
216
    Mol object or None if extraction fails
217
    """
218
```
219

220
## Types
221

222
```python { .api }
223
# External types used in visualization functions
224
class PIL.Image:
225
    """Pillow Image object for raster graphics"""
226
    def save(self, filename: str) -> None: ...
227
    def show(self) -> None: ...
228
```
229

230
## Usage Examples
231

232
### Basic Molecular Drawing
233

234
```python
235
from rdkit import Chem
236
from rdkit.Chem import Draw
237

238
# Create and draw a molecule
239
mol = Chem.MolFromSmiles('CCO')  # Ethanol
240
img = Draw.MolToImage(mol, size=(400, 400))
241
img.save('ethanol.png')
242

243
# Draw with custom options
244
img = Draw.MolToImage(mol, 
245
                      size=(500, 500),
246
                      highlightAtoms=[0, 1],  # Highlight first two carbons
247
                      highlightAtomColors={0: (1, 0, 0), 1: (0, 1, 0)})  # Red and green
248
img.save('ethanol_highlighted.png')
249
```
250

251
### Grid Display of Multiple Molecules
252

253
```python
254
from rdkit import Chem
255
from rdkit.Chem import Draw
256

257
# Create a list of molecules
258
smiles_list = ['CCO', 'CCCO', 'CCCCO', 'CCCCCO']
259
mols = [Chem.MolFromSmiles(smi) for smi in smiles_list]
260
legends = ['Ethanol', 'Propanol', 'Butanol', 'Pentanol']
261

262
# Create grid image
263
img = Draw.MolsToGridImage(mols,
264
                           molsPerRow=2,
265
                           subImgSize=(250, 250),
266
                           legends=legends)
267
img.save('alcohol_series.png')
268
```
269

270
### SVG Generation
271

272
```python
273
from rdkit import Chem
274
from rdkit.Chem import Draw
275

276
# Generate SVG for scalable graphics
277
mol = Chem.MolFromSmiles('c1ccccc1')  # Benzene
278
svg_string = Draw.MolToSVG(mol, size=(400, 400))
279

280
# Save SVG to file
281
with open('benzene.svg', 'w') as f:
282
    f.write(svg_string)
283
```
284

285
### Reaction Visualization
286

287
```python
288
from rdkit import Chem
289
from rdkit.Chem import AllChem, Draw
290

291
# Create a chemical reaction
292
rxn = AllChem.ReactionFromSmarts('[C:1](=[O:2])-[OD1].[N!H0:3]>>[C:1](=[O:2])[N:3]')
293

294
# Draw the reaction
295
img = Draw.ReactionToImage(rxn, subImgSize=(300, 300))
296
img.save('amidation_reaction.png')
297
```
298

299
### Custom Drawing Options
300

301
```python
302
from rdkit import Chem
303
from rdkit.Chem import Draw
304

305
# Create custom drawing options
306
opts = Draw.DrawingOptions()
307
opts.atomLabelFontSize = 18
308
opts.bondLineWidth = 3.0
309
opts.highlightColour = (0, 1, 0)  # Green highlights
310
opts.bgColor = (0.9, 0.9, 0.9)   # Light gray background
311

312
# Apply custom options
313
Draw.SetDrawingOptions(opts)
314

315
# Draw with custom styling
316
mol = Chem.MolFromSmiles('CCO')
317
img = Draw.MolToImage(mol, size=(400, 400))
318
img.save('ethanol_custom_style.png')
319
```
320

321
### Highlighting Substructures
322

323
```python
324
from rdkit import Chem
325
from rdkit.Chem import Draw
326

327
# Create molecule and define substructure
328
mol = Chem.MolFromSmiles('CCO')
329
pattern = Chem.MolFromSmarts('CO')  # Alcohol pattern
330

331
# Find matches
332
matches = mol.GetSubstructMatches(pattern)
333

334
if matches:
335
    # Highlight the first match
336
    highlight_atoms = list(matches[0])
337
    img = Draw.MolToImage(mol,
338
                          highlightAtoms=highlight_atoms,
339
                          highlightAtomColors={atom: (1, 0, 0) for atom in highlight_atoms})
340
    img.save('ethanol_alcohol_highlighted.png')
341
```
342

343
### Molecule with Atom Labels
344

345
```python
346
from rdkit import Chem
347
from rdkit.Chem import Draw
348

349
# Create molecule with custom atom labels
350
mol = Chem.MolFromSmiles('CCO')
351
atom_labels = {0: 'C1', 1: 'C2', 2: 'O'}
352

353
img = Draw.MolToImage(mol,
354
                      size=(400, 400),
355
                      atomLabels=atom_labels)
356
img.save('ethanol_labeled.png')
357
```