rdkit-dof is a Python toolkit that uses RDKit to generate beautiful 2D images of molecules with a "Depth of Field" (DOF) or "fog" effect. Based on the molecule's 3D conformation, atoms and bonds farther from the viewer are drawn with higher transparency and lower saturation, creating a sense of visual depth in the 2D image.
To better showcase the effect of rdkit-dof, we have compared it with RDKit's default drawing function.
| Default RDKit | rdkit-dof Effect |
|---|---|
| Default RDKit | rdkit-dof Effect |
|---|---|
You can now highlight specific atoms and bonds while maintaining the DOF effect.
| Single Highlighting | Grid Highlighting |
|---|---|
- Core: Python 3.9+
- Cheminformatics: RDKit
- Image Processing: Pillow
- Configuration: Pydantic
pip install rdkit-dofHere is a basic example of how to generate an image with a depth-of-field effect for a molecule.
from rdkit import Chem
from rdkit.Chem.rdDistGeom import EmbedMolecule
from rdkit.Chem.rdForceFieldHelpers import MMFFOptimizeMolecule
from rdkit_dof import MolToDofImage, dofconfig
# 1. Create an RDKit molecule object and generate a 3D conformation
smiles = "CC1=C2[C@@]([C@]([C@H]([C@@H]3[C@]4([C@H](OC4)C[C@@H]([C@]3(C(=O)[C@@H]2OC(=O)C)C)O)OC(=O)C)OC(=O)c5ccccc5)(C[C@@H]1OC(=O)[C@H](O)[C@@H](NC(=O)c6ccccc6)c7ccccc7)C)C"
mol = Chem.MolFromSmiles(smiles)
mol = Chem.AddHs(mol)
EmbedMolecule(mol, randomSeed=42)
MMFFOptimizeMolecule(mol)
# 2. (Optional) Switch to a preset theme
dofconfig.use_style("default")
# 3. Generate and save the image directly
MolToDofImage(
mol,
size=(1000, 800),
legend="Paclitaxel (Taxol)",
filename="paclitaxel.svg"
)
print("Image saved to paclitaxel.svg")
# 4. (Optional) Display the image (in a Jupyter Notebook)
svg_img = MolToDofImage(
mol,
size=(1000, 800),
legend="Paclitaxel (Taxol)",
use_svg=True,
return_image=True, # Set to True to get an IPython/Pillow image object
)
svg_img # Display the imageThis toolkit provides two core drawing functions:
Generates a DOF image for a single molecule.
MolToDofImage(
mol: Chem.Mol,
size: Optional[tuple[int, int]] = None,
legend: str = "",
use_svg: bool = True,
return_image: bool = True,
return_drawer: bool = False,
*,
settings: Optional[DofDrawSettings] = None,
highlightAtoms: Optional[Sequence[int]] = None,
highlightBonds: Optional[Sequence[int]] = None,
highlightColor: tuple[float, float, float, float] = (1.0, 0.0, 0.0, 0.5),
filename: Optional[str] = None,
**kwargs: Any,
) -> Union["SVG", str, Image.Image, bytes, MolDraw2D]mol: RDKit molecule object, which must contain a 3D conformation.size: Image dimensions(width, height).legend: Legend text below the image.use_svg:Truereturns SVG,Falsereturns PNG.return_image:Truereturns an IPython/Pillow image object,Falsereturns raw data (string for SVG, bytes for PNG).highlightAtoms: List of atom indices to highlight.highlightBonds: List of bond indices to highlight.highlightColor: RGBA color for highlighting (0.0-1.0).filename: If provided, the image will be saved to this path.settings: ADofDrawSettingsinstance for local configuration.**kwargs: Other RDKitMolDrawOptionsparameters.
Generates a DOF image for a grid of molecules, with parameters similar to RDKit's MolsToGridImage.
MolsToGridDofImage(
mols: Sequence[Union[Chem.Mol, Chem.RWMol, None]],
molsPerRow: int = 3,
subImgSize: tuple[int, int] = (300, 300),
legends: Optional[Sequence[Union[str, None]]] = None,
use_svg: bool = True,
return_image: bool = True,
return_drawer: bool = False,
*,
settings: Optional[DofDrawSettings] = None,
highlightAtomLists: Optional[Sequence[Sequence[int]]] = None,
highlightBondLists: Optional[Sequence[Sequence[int]]] = None,
highlightColor: tuple[float, float, float, float] = (1.0, 0.0, 0.0, 0.5),
filename: Optional[str] = None,
**kwargs: Any,
) -> Union["SVG", str, Image.Image, bytes, MolDraw2D]You can obtain the drawer instance for further customization.
You can customize the drawing style via a global dofconfig object or environment variables (.env).
Modify the properties of the rdkit_dof.dofconfig object directly in your code.
from rdkit_dof import dofconfig
# Use a preset style
dofconfig.use_style("nature") # Options: 'default', 'nature', 'jacs', 'dark'
# Customize colors and effects
dofconfig.fog_color = (0.1, 0.1, 0.1) # Background fog color (RGB, 0-1)
dofconfig.min_alpha = 0.3 # Minimum alpha for the farthest atoms
dofconfig.default_size = (500, 500) # Default image size
# Override colors for specific atoms (atomic number -> RGB)
dofconfig.atom_colors[8] = (1.0, 0.2, 0.2) # Set Oxygen to bright redYou can also customize the drawing style by setting environment variables. All configuration properties have a corresponding environment variable, named RDKIT_DOF_ plus the property name (in upper snake case).
For example, to set fog_color to dark gray (RGB 0.1, 0.1, 0.1) and min_alpha to 0.2, you can add this to your .env file:
# Set fog color to dark gray
RDKIT_DOF_FOG_COLOR=[0.1, 0.1, 0.1]
# Adjust minimum alpha
RDKIT_DOF_MIN_ALPHA=0.2| Property | Description | Default (Light Theme) |
|---|---|---|
preset_style |
Name of the preset style | "default" |
fog_color |
Fog/background color (RGB, 0-1) | (0.95, 0.95, 0.95) |
min_alpha |
Minimum alpha for the farthest atoms | 0.4 |
default_size |
Default image size (width, height) for MolToDofImage |
(800, 800) |
enable_ipython |
Whether to enable IPython image display | True |
atom_colors |
Atom color map (dict[int, tuple]) |
Based on preset_style |
The script scripts/_generate_comparison_images.py is a complete example for generating all the images in this document. You can run it to reproduce them:
# Generate comparison images
python scripts/_generate_comparison_images.py- OS: This project is OS-independent and runs on Linux, macOS, and Windows.
- Python Version: Requires Python 3.9 or higher.
- RDKit Version: Recommended to use
2023.09or higher.
Contributions of any kind are welcome!
- Fork the repository.
- Create your feature branch (
git checkout -b feature/AmazingFeature). - Commit your changes (
git commit -m 'Add some AmazingFeature'). - Push to the branch (
git push origin feature/AmazingFeature). - Open a Pull Request.
This project is distributed under the MIT License. See the LICENSE file for details.