rdkit-dof 0.2.0

RDKit molecule drawing with Depth of Field (DOF) effects.

rdkit-dof

简体中文

rdkit-dof is a lightweight Python package for rendering RDKit molecules with a depth-of-field (DOF) or fog effect. It uses 3D conformer depth to fade distant atoms and bonds, producing clearer visual depth in 2D molecular depictions.

Highlights

• Single-molecule and grid rendering with RDKit-compatible APIs.
• SVG and PNG output, including direct file saving.
• Atom and bond highlighting with saturated colors while the rest keeps DOF fading.
• Preset styles: default, nature, jacs, and dark.
• Local or global configuration through standard-library dataclasses.
• Optional Jupyter/IPython integration for RDKit Mol display.

Comparison

Single Molecule

Default RDKit	rdkit-dof Effect

Grid Mode

Default RDKit	rdkit-dof Effect

Highlighting

Single Highlighting	Grid Highlighting

Installation

pip install rdkit-dof

Quick Start

from rdkit import Chem
from rdkit.Chem.rdDistGeom import EmbedMolecule
from rdkit.Chem.rdForceFieldHelpers import MMFFOptimizeMolecule
from rdkit_dof import MolToDofImage, dofconfig

mol = Chem.MolFromSmiles("CCO")
mol = Chem.AddHs(mol)
EmbedMolecule(mol, randomSeed=42)
MMFFOptimizeMolecule(mol)

dofconfig.use_style("nature")

MolToDofImage(
    mol,
    size=(600, 500),
    legend="Ethanol",
    filename="ethanol.svg",
)

Examples

Open the executed notebook for concrete examples with rendered output:

• Quickstart Notebook: single molecule, style presets, highlighting, grid rendering, configuration, notebook integration, and raw SVG/PNG output.
• 中文 Notebook: Chinese version with the same runnable examples.

Molecules with 3D conformers get true depth-based fading. Molecules without conformers are still supported; 2D coordinates are computed automatically and the depth effect is flat.

Documentation

• Usage Guide: workflow notes for single molecules, grids, highlighting, notebook integration, and custom RDKit drawing.
• API Reference: signatures and parameter behavior for MolToDofImage, MolsToGridDofImage, and DofDrawSettings.
• Configuration: global config, local settings, .env, environment variables, and style presets.

Compatibility

• Python 3.8+
• RDKit 2023.09+
• Linux, macOS, and Windows

Python 3.8 installs are constrained to the last compatible RDKit line (<2024.3.6).

Development

uv sync --all-extras --dev
uv run pytest
uv run ruff check .
uv run mypy src
uv run pyright

To open the notebook examples:

uv run notebook examples/rdkit_dof_quickstart.en.ipynb

To regenerate README showcase images:

python scripts/_generate_comparison_images.py

License

This project is distributed under the MIT License. See LICENSE for details.