# OEDepict TK

> 2D molecular depiction and visualization toolkit for generating publication-quality molecular images

## Links
- [Full Documentation](https://docs.eyesopen.com/toolkits/python/depicttk/index.html)
- [Theory](https://docs.eyesopen.com/toolkits/python/depicttk/theory.html)
- [Code Examples](https://docs.eyesopen.com/toolkits/python/depicttk/examples_summary.html)
- [API Reference](https://docs.eyesopen.com/toolkits/python/depicttk/api.html)

## Core API - Function Quick Reference

### Image Creation & Rendering
```
OEPrepareDepiction(mol: OEMolBase, clearcoords: bool = True, suppressH: bool = True) -> bool
  Use for: Prepare molecule for 2D depiction by generating coordinates
  Example: OEPrepareDepiction(mol)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OEPrepareDepiction.html

OERenderMolecule(image: OEImageBase, disp: OE2DMolDisplay) -> bool
  Use for: Render a prepared molecule display to an image
  Example: OERenderMolecule(image, disp)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OERenderMolecule.html

OEWriteImage(filename: str, image: OEImageBase) -> bool
  Use for: Write image to file (supports PNG, PDF, SVG formats)
  Example: OEWriteImage("output.png", image)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OEWriteImage.html
```

### Display Objects
```
OE2DMolDisplay(mol: OEMolBase, opts: OE2DMolDisplayOptions = None) -> OE2DMolDisplay
  Use for: Create a 2D molecule display object with rendering settings
  Example: disp = OE2DMolDisplay(mol, opts)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictClasses/OE2DMolDisplay.html

OE2DMolDisplayOptions(width: float = 200.0, height: float = 200.0) -> OE2DMolDisplayOptions
  Use for: Configure display settings (size, colors, atom/bond styles)
  Example: opts = OE2DMolDisplayOptions(400, 300)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictClasses/OE2DMolDisplayOptions.html

OEImage(width: float, height: float) -> OEImageBase
  Use for: Create blank image canvas for rendering
  Example: image = OEImage(400, 300)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictClasses/OEImage.html
```

### Highlighting
```
OEAddHighlighting(disp: OE2DMolDisplay, color: OEColor, style: OEHighlightStyle, atoms: OEAtomBondSet) -> bool
  Use for: Add colored highlighting to specific atoms/bonds
  Example: OEAddHighlighting(disp, OEBlueTint, OEHighlightStyle_Stick, atomset)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OEAddHighlighting.html

OEAddHighlightOverlay(disp: OE2DMolDisplay, overlay: OEHighlightOverlay) -> bool
  Use for: Add complex multi-color highlighting patterns
  Example: OEAddHighlightOverlay(disp, overlay)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OEAddHighlightOverlay.html
```

### Alignment & Superposition
```
OEPrepareAlignedDepiction(mol: OEMolBase, refmol: OEMolBase = None) -> bool
  Use for: Align molecule coordinates to reference for consistent orientation
  Example: OEPrepareAlignedDepiction(mol, refmol)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OEPrepareAlignedDepiction.html

OESetMolAlignmentCoords(mol: OEMolBase, refmol: OEMolBase, match: OEMatchBase) -> bool
  Use for: Set coordinates based on substructure match to reference
  Example: OESetMolAlignmentCoords(mol, refmol, match)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OESetMolAlignmentCoords.html
```

### Multi-Molecule Layouts
```
OEImageGrid(image: OEImageBase, rows: int, cols: int) -> OEImageGrid
  Use for: Create grid layout for multiple molecules
  Example: grid = OEImageGrid(image, 3, 4)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictClasses/OEImageGrid.html

OEImageFrame(image: OEImageBase, width: float, height: float, rows: int, cols: int) -> OEImageFrame
  Use for: Create multi-page layout with frames
  Example: frame = OEImageFrame(image, 400, 300, 2, 2)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictClasses/OEImageFrame.html
```

### Atom/Bond Styling
```
OESetBondWidthScaling(opts: OE2DMolDisplayOptions, scaling: float) -> None
  Use for: Adjust bond line thickness
  Example: OESetBondWidthScaling(opts, 1.5)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OESetBondWidthScaling.html

OESetAtomColorStyle(opts: OE2DMolDisplayOptions, style: int) -> None
  Use for: Set atom coloring scheme (CPK, monochrome, etc.)
  Example: OESetAtomColorStyle(opts, OEAtomColorStyle_WhiteMonochrome)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OESetAtomColorStyle.html

OESetAtomStereoStyle(opts: OE2DMolDisplayOptions, style: int) -> None
  Use for: Control stereochemistry wedge/hash display
  Example: OESetAtomStereoStyle(opts, OEAtomStereoStyle_Display_All)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OESetAtomStereoStyle.html
```

### SVG Interactive Features
```
OEAddInteractiveIcon(disp: OE2DMolDisplay, icon: OEIconBase) -> bool
  Use for: Add interactive elements to SVG output
  Example: OEAddInteractiveIcon(disp, icon)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OEAddInteractiveIcon.html

OEAddSVGHover(disp: OE2DMolDisplay, atom: OEAtomBase, text: str) -> bool
  Use for: Add hover tooltips to atoms in SVG
  Example: OEAddSVGHover(disp, atom, "Atom info")
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OEAddSVGHover.html
```

### MDL Query Depiction
```
OEPrepareDepictionFrom3D(mol: OEMolBase) -> bool
  Use for: Generate 2D coordinates from 3D structure
  Example: OEPrepareDepictionFrom3D(mol)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OEPrepareDepictionFrom3D.html

OERenderMDLQueryFeatures(image: OEImageBase, disp: OE2DMolDisplay) -> bool
  Use for: Render MDL query features (atom lists, bond topology)
  Example: OERenderMDLQueryFeatures(image, disp)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OERenderMDLQueryFeatures.html
```

### Reaction Depiction
```
OEPrepareDepictionReaction(rxn: OEUniMolecularRxn) -> bool
  Use for: Prepare reaction for depiction
  Example: OEPrepareDepictionReaction(rxn)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OEPrepareDepictionReaction.html

OERenderReaction(image: OEImageBase, rxndisp: OE2DReactionDisplay) -> bool
  Use for: Render reaction scheme to image
  Example: OERenderReaction(image, rxndisp)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OERenderReaction.html
```

### Utility Functions
```
OEGetMoleculeScale(mol: OEMolBase, opts: OE2DMolDisplayOptions) -> float
  Use for: Calculate optimal scaling factor for molecule display
  Example: scale = OEGetMoleculeScale(mol, opts)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OEGetMoleculeScale.html

OEGetCenter(disp: OE2DMolDisplay) -> OE2DPoint
  Use for: Get center coordinates of molecule display
  Example: center = OEGetCenter(disp)
  See: https://docs.eyesopen.com/toolkits/python/depicttk/OEDepictFunctions/OEGetCenter.html
```

## Common Patterns - Complete Working Examples

### Pattern: Basic Molecule Depiction
```python
from openeye import oechem, oedepict

# Read molecule and prepare for depiction
mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "c1ccccc1C(=O)O")
oedepict.OEPrepareDepiction(mol)

# Create image and display options
opts = oedepict.OE2DMolDisplayOptions(400, 300, oedepict.OEScale_AutoScale)
disp = oedepict.OE2DMolDisplay(mol, opts)

# Render to image file
image = oedepict.OEImage(400, 300)
oedepict.OERenderMolecule(image, disp)
oedepict.OEWriteImage("molecule.png", image)
```
Use when: Creating simple 2D molecular structure images for documentation or reports

### Pattern: Highlighting Substructure Matches
```python
from openeye import oechem, oedepict

# Setup molecule and substructure search
mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "c1cc(O)c(O)cc1CCN")
oedepict.OEPrepareDepiction(mol)

ss = oechem.OESubSearch("c1ccc(O)cc1")
oechem.OEPrepareSearch(mol, ss)

# Highlight matches
opts = oedepict.OE2DMolDisplayOptions(400, 300, oedepict.OEScale_AutoScale)
disp = oedepict.OE2DMolDisplay(mol, opts)

for match in ss.Match(mol):
    oedepict.OEAddHighlighting(disp, oechem.OEColor(oechem.OELightGreen),
                               oedepict.OEHighlightStyle_Stick, match)

image = oedepict.OEImage(400, 300)
oedepict.OERenderMolecule(image, disp)
oedepict.OEWriteImage("highlighted.png", image)
```
Use when: Visualizing substructure search results or showing matched patterns

### Pattern: Aligned Molecule Depiction
```python
from openeye import oechem, oedepict

# Read reference and target molecules
refmol = oechem.OEGraphMol()
oechem.OESmilesToMol(refmol, "c1ccccc1C(=O)O")
oedepict.OEPrepareDepiction(refmol)

mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "c1ccccc1C(=O)N")
oedepict.OEPrepareAlignedDepiction(mol, refmol)

# Render aligned molecule
opts = oedepict.OE2DMolDisplayOptions(400, 300, oedepict.OEScale_AutoScale)
disp = oedepict.OE2DMolDisplay(mol, opts)

image = oedepict.OEImage(400, 300)
oedepict.OERenderMolecule(image, disp)
oedepict.OEWriteImage("aligned.png", image)
```
Use when: Comparing similar molecules with consistent orientation (SAR tables, series comparison)

### Pattern: Multi-Molecule Grid Layout
```python
from openeye import oechem, oedepict

# Read multiple molecules
mols = []
for smi in ["c1ccccc1", "c1cccnc1", "c1ccoc1", "c1ccsc1"]:
    mol = oechem.OEGraphMol()
    oechem.OESmilesToMol(mol, smi)
    oedepict.OEPrepareDepiction(mol)
    mols.append(mol)

# Create grid layout
rows, cols = 2, 2
image = oedepict.OEImage(800, 600)
grid = oedepict.OEImageGrid(image, rows, cols)

opts = oedepict.OE2DMolDisplayOptions(grid.GetCellWidth(), grid.GetCellHeight(),
                                      oedepict.OEScale_AutoScale)

# Render each molecule to grid cell
for idx, mol in enumerate(mols):
    cell = grid.GetCell(idx + 1)
    disp = oedepict.OE2DMolDisplay(mol, opts)
    oedepict.OERenderMolecule(cell, disp)

oedepict.OEWriteImage("grid.png", image)
```
Use when: Creating compound plates, diversity sets, or multi-molecule comparison images

### Pattern: Custom Atom/Bond Styling
```python
from openeye import oechem, oedepict

mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "c1ccccc1C(=O)O")
oedepict.OEPrepareDepiction(mol)

# Configure custom display options
opts = oedepict.OE2DMolDisplayOptions(400, 300, oedepict.OEScale_AutoScale)
oedepict.OESetBondWidthScaling(opts, 2.0)
oedepict.OESetAtomColorStyle(opts, oedepict.OEAtomColorStyle_WhiteMonochrome)
oedepict.OESetAtomStereoStyle(opts, oedepict.OEAtomStereoStyle_Display_All)

# Render with custom styling
disp = oedepict.OE2DMolDisplay(mol, opts)
image = oedepict.OEImage(400, 300)
oedepict.OERenderMolecule(image, disp)
oedepict.OEWriteImage("styled.png", image)
```
Use when: Creating publication-quality images with specific visual requirements

### Pattern: Interactive SVG with Hover Text
```python
from openeye import oechem, oedepict

mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "c1ccccc1C(=O)O")
oedepict.OEPrepareDepiction(mol)

opts = oedepict.OE2DMolDisplayOptions(400, 300, oedepict.OEScale_AutoScale)
disp = oedepict.OE2DMolDisplay(mol, opts)

# Add hover text to atoms
for atom in mol.GetAtoms():
    label = f"{atom.GetName()}: {oechem.OEGetAtomicSymbol(atom.GetAtomicNum())}"
    oedepict.OEAddSVGHover(disp, atom, label)

# Write interactive SVG
image = oedepict.OEImage(400, 300)
oedepict.OERenderMolecule(image, disp)
oedepict.OEWriteImage("interactive.svg", image)
```
Use when: Creating web-based visualizations with interactive features

### Pattern: Reaction Scheme Depiction
```python
from openeye import oechem, oedepict

# Create reaction from SMIRKS
rxn = oechem.OEUniMolecularRxn()
oechem.OEParseSmirks(rxn, "[C:1](=[O:2])O.[N:3]>>[C:1](=[O:2])[N:3]")
oedepict.OEPrepareDepictionReaction(rxn)

# Setup reaction display
opts = oedepict.OE2DReactionDisplayOptions(800, 400, oedepict.OEScale_AutoScale)
rxndisp = oedepict.OE2DReactionDisplay(rxn, opts)

# Render reaction
image = oedepict.OEImage(800, 400)
oedepict.OERenderReaction(image, rxndisp)
oedepict.OEWriteImage("reaction.png", image)
```
Use when: Visualizing chemical transformations or reaction schemes

### Pattern: Multi-Page PDF Output
```python
from openeye import oechem, oedepict

# Read molecule collection
ifs = oechem.oemolistream("molecules.sdf")
mols = [oechem.OEGraphMol(mol) for mol in ifs.GetOEGraphMols()]

# Setup multi-page layout
rows, cols = 3, 4
image = oedepict.OEImage(800, 600)
opts = oedepict.OE2DMolDisplayOptions()

# Create frames for pagination
frame = oedepict.OEImageFrame(image, 
                              image.GetWidth() / cols,
                              image.GetHeight() / rows,
                              rows, cols)

# Render molecules across pages
for idx, mol in enumerate(mols):
    oedepict.OEPrepareDepiction(mol)
    cell = frame.GetCell(idx % (rows * cols) + 1)
    disp = oedepict.OE2DMolDisplay(mol, opts)
    oedepict.OERenderMolecule(cell, disp)

oedepict.OEWriteImage("multipage.pdf", image)
```
Use when: Creating multi-page reports or catalogs of compounds

### Pattern: Highlighting with Custom Colors
```python
from openeye import oechem, oedepict

mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "c1cc(O)c(O)cc1CCN")
oedepict.OEPrepareDepiction(mol)

opts = oedepict.OE2DMolDisplayOptions(400, 300, oedepict.OEScale_AutoScale)
disp = oedepict.OE2DMolDisplay(mol, opts)

# Create custom highlight overlay
overlay = oedepict.OEHighlightOverlay()
overlay.SetHighlightStyle(oedepict.OEHighlightStyle_BallAndStick)

# Add different colored highlights
for atom in mol.GetAtoms(oechem.OEIsOxygen()):
    overlay.AddHighlight(oechem.OEColor(255, 0, 0), atom)
for atom in mol.GetAtoms(oechem.OEIsNitrogen()):
    overlay.AddHighlight(oechem.OEColor(0, 0, 255), atom)

oedepict.OEAddHighlightOverlay(disp, overlay)

image = oedepict.OEImage(400, 300)
oedepict.OERenderMolecule(image, disp)
oedepict.OEWriteImage("custom_highlight.png", image)
```
Use when: Emphasizing specific atom types or functional groups with distinct colors

### Pattern: Generating Coordinates from 3D
```python
from openeye import oechem, oedepict

# Read 3D structure
ifs = oechem.oemolistream("protein_ligand.pdb")
mol = oechem.OEGraphMol()
oechem.OEReadMolecule(ifs, mol)

# Generate 2D depiction from 3D coordinates
oedepict.OEPrepareDepictionFrom3D(mol)

# Render 2D structure
opts = oedepict.OE2DMolDisplayOptions(400, 300, oedepict.OEScale_AutoScale)
disp = oedepict.OE2DMolDisplay(mol, opts)

image = oedepict.OEImage(400, 300)
oedepict.OERenderMolecule(image, disp)
oedepict.OEWriteImage("from_3d.png", image)
```
Use when: Converting 3D structures (from PDB, docking) to 2D diagrams

### Pattern: MDL Query Feature Depiction
```python
from openeye import oechem, oedepict

# Create query molecule with MDL features
qmol = oechem.OEQMol()
oechem.OEParseSmarts(qmol, "[#6,#7,#8]1~*~*~*~*~1")
oedepict.OEPrepareDepiction(qmol)

# Setup display for query features
opts = oedepict.OE2DMolDisplayOptions(400, 300, oedepict.OEScale_AutoScale)
disp = oedepict.OE2DMolDisplay(qmol, opts)

# Render with MDL query annotations
image = oedepict.OEImage(400, 300)
oedepict.OERenderMolecule(image, disp)
oedepict.OERenderMDLQueryFeatures(image, disp)
oedepict.OEWriteImage("query.png", image)
```
Use when: Visualizing SMARTS patterns or MDL query structures with atom lists

## API Decision Guide

- **For basic molecule images**: use `OEPrepareDepiction()` + `OE2DMolDisplay()` + `OERenderMolecule()`
- **For aligned series**: use `OEPrepareAlignedDepiction()` instead of `OEPrepareDepiction()`
- **For 3D to 2D conversion**: use `OEPrepareDepictionFrom3D()` instead of `OEPrepareDepiction()`
- **For highlighting matches**: use `OEAddHighlighting()` for simple cases, `OEAddHighlightOverlay()` for complex multi-color patterns
- **For grid layouts**: use `OEImageGrid` for simple grids, `OEImageFrame` for multi-page documents
- **For file output**: use `OEWriteImage()` (supports PNG, PDF, SVG based on extension)
- **For interactive features**: use SVG format with `OEAddSVGHover()` and `OEAddInteractiveIcon()`
- **For reactions**: use `OEPrepareDepictionReaction()` + `OE2DReactionDisplay()` + `OERenderReaction()`
- **For custom styling**: configure `OE2DMolDisplayOptions` before creating `OE2DMolDisplay`
- **OEPrepareDepiction() vs OEPrepareAlignedDepiction()**: use basic for standalone images, use aligned for comparing similar structures
- **OEHighlightStyle_Stick vs OEHighlightStyle_BallAndStick**: use Stick for subtle highlighting, BallAndStick for emphasis
- **OEAtomColorStyle_Default vs OEAtomColorStyle_WhiteMonochrome**: use Default for color images, WhiteMonochrome for publications

## Common Parameters & Types

**OE2DMolDisplayOptions**: Configuration object for molecule display settings
  - Create with: `OE2DMolDisplayOptions(width, height, scale_option)`
  - Common in: `OE2DMolDisplay()`, all rendering functions
  - Key settings: width/height (image dimensions), scale (AutoScale, Default), atom/bond styles
  - Gotcha: Must set options before creating OE2DMolDisplay; changes after won't apply

**OE2DMolDisplay**: Prepared molecule display ready for rendering
  - Create with: `OE2DMolDisplay(mol, opts)`
  - Common in: `OERenderMolecule()`, `OEAddHighlighting()`, all rendering operations
  - Represents: Molecule with applied layout and styling, ready to draw
  - Gotcha: Molecule must have 2D coordinates (call OEPrepareDepiction first)

**OEImageBase**: Canvas for drawing (abstract base class)
  - Create with: `OEImage(width, height)` for raster, `OESVGSurface(width, height)` for SVG
  - Common in: All rendering functions, `OEWriteImage()`
  - Typical values: 400x300 for single molecules, 800x600 for grids
  - Gotcha: Coordinate system is (0,0) at top-left, not bottom-left

**OEHighlightStyle**: Enumeration for highlight rendering style
  - Create with: Use constants like `OEHighlightStyle_Stick`, `OEHighlightStyle_BallAndStick`
  - Common in: `OEAddHighlighting()`, `OEHighlightOverlay.SetHighlightStyle()`
  - Typical values: Stick (subtle), BallAndStick (prominent), Color (background only)
  - Gotcha: Different styles work better with different color intensities

**OEAtomBondSet**: Collection of atoms and bonds to highlight
  - Create with: `oechem.OEAtomBondSet()` or from match object
  - Common in: `OEAddHighlighting()`, substructure highlighting
  - Populate with: `AddAtom()`, `AddBond()`, or from `OEMatchBase` object
  - Gotcha: Must include both atoms AND bonds for complete highlighting

**OEImageGrid**: Grid layout manager for multiple molecules
  - Create with: `OEImageGrid(image, rows, cols)`
  - Common in: Multi-molecule layouts, compound plates
  - Access cells: `GetCell(index)` returns sub-image for that grid position
  - Gotcha: Cell indices start at 1, not 0; GetCellWidth()/GetCellHeight() for sizing

**OEScale**: Enumeration for molecule scaling options
  - Create with: Use constants like `OEScale_AutoScale`, `OEScale_Default`
  - Common in: `OE2DMolDisplayOptions` constructor
  - Typical values: AutoScale (fit to image), Default (standard size)
  - Gotcha: AutoScale adjusts per molecule; use Default for consistent sizing across series

**OEAtomColorStyle**: Enumeration for atom coloring schemes
  - Create with: Use constants like `OEAtomColorStyle_Default`, `OEAtomColorStyle_WhiteMonochrome`
  - Common in: `OESetAtomColorStyle()`
  - Typical values: Default (CPK colors), WhiteMonochrome (black on white), Legacy
  - Gotcha: Monochrome styles ignore custom atom colors

## Return Types & Error Handling

```python
# Boolean returns - most functions return success/failure
if not oedepict.OEPrepareDepiction(mol):
    print("Failed to prepare depiction - molecule may have issues")
    # Common causes: invalid molecule, no atoms, coordinate generation failure

# Check before rendering
if oedepict.OERenderMolecule(image, disp):
    oedepict.OEWriteImage("output.png", image)
else:
    print("Rendering failed")

# File writing returns boolean
if not oedepict.OEWriteImage("output.png", image):
    print("Failed to write image - check path and permissions")

# Iterator returns for grid cells
grid = oedepict.OEImageGrid(image, 2, 2)
for idx in range(1, 5):  # Cells numbered 1-4
    cell = grid.GetCell(idx)
    if cell is None:
        print(f"Invalid cell index: {idx}")
        continue
    # Use cell...

# Object returns - check for None/validity
opts = oedepict.OE2DMolDisplayOptions(400, 300, oedepict.OEScale_AutoScale)
disp = oedepict.OE2DMolDisplay(mol, opts)
if disp is None:
    print("Failed to create display")
else:
    # Display is valid, proceed with rendering
    pass

# Scale calculation returns float
scale = oedepict.OEGetMoleculeScale(mol, opts)
if scale <= 0.0:
    print("Invalid scale calculated")