rdkit-dof 0.1.0__py3-none-any.whl

rdkit_dof/__init__.py

@@ -0,0 +1,11 @@
+from .config import DofDrawSettings, dofconfig
+from .core import MolGridToDofImage, MolToDofImage
+
+__all__ = [
+    "MolGridToDofImage",
+    "MolToDofImage",
+    "DofDrawSettings",
+    "dofconfig"
+]
+
+__version__ = "0.1.0"

rdkit_dof/config.py

@@ -0,0 +1,119 @@
+"""
+Author: TMJ
+Date: 2025-12-01 12:38:03
+LastEditors: TMJ
+LastEditTime: 2025-12-01 15:48:00
+Description: 请填写简介
+"""
+
+from typing import Literal, Union
+
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from rdkit.Chem import Mol, RWMol
+from typing_extensions import Self
+
+from .palettes import DARK_NEON_STYLE, DEFAULT_STYLE, JACS_STYLE, NATURE_STYLE
+
+StyleName = Literal["default", "nature", "jacs", "dark"]
+
+
+class DofDrawSettings(BaseSettings):
+    """
+    Logic:
+    1. load preset style
+    2. if dark mode, and fog color is default, set fog color to (0.1, 0.1, 0.1)
+    3. override specific atoms with user-provided atom_colors
+    """
+
+    preset_style: StyleName = "default"
+
+    fog_color: tuple[float, float, float] = (0.95, 0.95, 0.95)
+    min_alpha: float = 0.4
+    default_size: tuple[int, int] = (800, 800)
+
+    enable_ipython: bool = True
+
+    atom_colors: dict[int, tuple[float, float, float]] = Field(default_factory=dict)
+
+    model_config = SettingsConfigDict(
+        env_file=".env", env_prefix="MOL_DOF_", extra="ignore"
+    )
+
+    @model_validator(mode="after")
+    def _init_merge_configuration(self) -> Self:
+        self._apply_style_logic(self.preset_style)
+        return self
+
+    def _apply_style_logic(self, style: str):
+        style_map = {
+            "default": DEFAULT_STYLE,
+            "nature": NATURE_STYLE,
+            "jacs": JACS_STYLE,
+            "dark": DARK_NEON_STYLE,
+        }
+        # If preset_style is specified, use it; otherwise, use default
+        base_colors = style_map.get(style, DEFAULT_STYLE).copy()
+
+        if self.preset_style == "dark":
+            if self.fog_color == (0.95, 0.95, 0.95):
+                self.fog_color = (0.1, 0.1, 0.1)
+
+        if self.atom_colors:
+            base_colors.update(self.atom_colors)
+
+        self.atom_colors = base_colors
+
+    def get_atom_color(self, atomic_num: int) -> tuple[float, float, float]:
+        return self.atom_colors.get(
+            atomic_num, self.atom_colors.get(6, (0.2, 0.2, 0.2))
+        )
+
+    def use_style(self, style: StyleName):
+        """
+        Switch to a different preset style, resetting any custom atom colors.
+        """
+        self.preset_style = style
+        self.atom_colors = {}
+        self._apply_style_logic(style)
+
+    def enable_ipython_integration(self, enable: bool = True):
+        """
+        Toggle whether to use the DOF effect drawer as the default renderer
+        for RDKit Mol objects in Jupyter/IPython.
+
+        Args:
+            enable (bool): True to enable DOF rendering, False to restore RDKit default.
+        """
+        try:
+            from IPython.core.getipython import get_ipython
+        except ImportError:
+            return
+        ip = get_ipython()
+        if ip is None:
+            return
+        svg_formatter = ip.display_formatter.formatters["image/svg+xml"]  # type: ignore
+
+        if enable:
+            from .core import MolToDofImage
+
+            def _dof_drawer_hook(mol: Union[Mol, RWMol]) -> str:
+                return MolToDofImage(
+                    mol,
+                    use_svg=True,
+                    return_image=False,  # 必须为 False，返回 SVG 源码字符串
+                    settings=self,  # 绑定当前配置实例
+                )
+
+            svg_formatter.for_type(Mol, _dof_drawer_hook)
+            svg_formatter.for_type(RWMol, _dof_drawer_hook)
+        else:
+            if Mol in svg_formatter.type_printers:
+                svg_formatter.type_printers.pop(Mol)
+            if RWMol in svg_formatter.type_printers:
+                svg_formatter.type_printers.pop(RWMol)
+
+
+dofconfig = DofDrawSettings()
+if dofconfig.enable_ipython:
+    dofconfig.enable_ipython_integration(True)

rdkit_dof/core.py

@@ -0,0 +1,384 @@
+import io
+import math
+from collections.abc import Sequence
+from functools import lru_cache
+from typing import Any, Literal, Optional, Union, overload
+
+import numpy as np
+from PIL import Image
+from rdkit import Chem
+from rdkit.Chem.Draw import (
+    IPythonConsole,  # type: ignore
+    MolDrawOptions,
+    rdMolDraw2D,
+)
+from rdkit.Chem.rdDepictor import Compute2DCoords
+
+from .config import DofDrawSettings, dofconfig
+
+try:
+    from IPython.display import SVG
+except ImportError:
+    svg_support = False
+else:
+    svg_support = True
+
+
+@lru_cache(maxsize=4096)
+def _get_atom_dof_color_cached(
+    base_color: tuple[float, float, float],
+    proximity: float,
+    min_alpha: float,
+    fog_color: tuple[float, float, float],
+) -> tuple[float, float, float, float]:
+    """Calculate the RGBA color of an atom with depth-of-field effect."""
+    base_rgb = np.array(base_color)
+    fog_rgb = np.array(fog_color)
+    dark_color_rgba = np.array([*base_rgb, 1.0])
+    light_rgb = base_rgb * 0.2 + fog_rgb * 0.8
+    light_color_rgba = np.array([*light_rgb, min_alpha])
+    final_color = light_color_rgba + proximity * (dark_color_rgba - light_color_rgba)
+    return tuple(final_color.tolist())
+
+
+def _apply_rdkit_global_options(target_dopts: MolDrawOptions):
+    """Reflect global options from IPythonConsole.drawOptions."""
+    if IPythonConsole is None or not hasattr(IPythonConsole, "drawOptions"):
+        return
+    source_dopts: MolDrawOptions = IPythonConsole.drawOptions
+    if source_dopts is None:
+        return
+    for attr in dir(source_dopts):
+        if attr.startswith("_"):
+            continue
+        try:
+            val = getattr(source_dopts, attr)
+            if callable(val):
+                continue
+            if hasattr(target_dopts, attr):
+                setattr(target_dopts, attr, val)
+        except Exception:
+            pass
+
+
+def _prepare_mol_data(
+    mol: Union[Chem.Mol, Chem.RWMol],
+    settings: DofDrawSettings,
+    keep_key_atom_colors: bool = True,
+) -> tuple[
+    Chem.Mol,
+    dict[int, tuple[float, float, float, float]],
+    dict[int, tuple[float, float, float, float]],
+]:
+    """
+    Internal Helper: Process a single molecule for DOF drawing.
+    Returns: (Prepared Molecule, Atom Colors Dict, Bond Colors Dict)
+    """
+    if not mol:
+        raise ValueError("Invalid molecule")
+
+    mol_copy = Chem.Mol(mol)
+
+    if mol_copy.GetNumConformers() == 0:
+        Compute2DCoords(mol_copy)
+
+    conf = mol_copy.GetConformer()
+    pos = conf.GetPositions()
+    z_coords = pos[:, 2]
+
+    if z_coords.size > 1 and z_coords.max() != z_coords.min():
+        norm_z = (z_coords - z_coords.min()) / (z_coords.max() - z_coords.min())
+        proximity = norm_z
+    else:
+        proximity = np.full(z_coords.shape, 1.0)
+
+    highlight_atom_colors: dict[int, tuple[float, float, float, float]] = {}
+    carbon_base_color = settings.get_atom_color(6)
+
+    for i in range(mol_copy.GetNumAtoms()):
+        atom = mol_copy.GetAtomWithIdx(i)
+        atomic_num = atom.GetAtomicNum()
+        base_color = settings.get_atom_color(atomic_num)
+        target_color = base_color if keep_key_atom_colors else carbon_base_color
+
+        highlight_atom_colors[i] = _get_atom_dof_color_cached(
+            base_color=target_color,
+            proximity=proximity[i],
+            min_alpha=settings.min_alpha,
+            fog_color=settings.fog_color,
+        )
+
+    highlight_bond_colors: dict[int, tuple[float, float, float, float]] = {}
+    for i in range(mol_copy.GetNumBonds()):
+        bond = mol_copy.GetBondWithIdx(i)
+        atom1_idx = bond.GetBeginAtomIdx()
+        atom2_idx = bond.GetEndAtomIdx()
+        c1 = _get_atom_dof_color_cached(
+            carbon_base_color,
+            proximity[atom1_idx],
+            settings.min_alpha,
+            settings.fog_color,
+        )
+        c2 = _get_atom_dof_color_cached(
+            carbon_base_color,
+            proximity[atom2_idx],
+            settings.min_alpha,
+            settings.fog_color,
+        )
+        bond_color_arr = (np.array(c1) + np.array(c2)) / 2
+        highlight_bond_colors[i] = tuple(bond_color_arr.tolist())
+
+    return mol_copy, highlight_atom_colors, highlight_bond_colors
+
+
+# =============================================================================
+# Single Molecule Drawer
+# =============================================================================
+
+
+@overload
+def MolToDofImage(
+    mol: Union[Chem.Mol, Chem.RWMol],
+    size: Optional[tuple[int, int]] = None,
+    legend: str = "",
+    use_svg: Literal[True] = True,
+    return_image: Literal[True] = True,
+    *,
+    settings: Optional[DofDrawSettings] = None,
+    **kwargs: Any,
+) -> "SVG": ...
+@overload
+def MolToDofImage(
+    mol: Union[Chem.Mol, Chem.RWMol],
+    size: Optional[tuple[int, int]] = None,
+    legend: str = "",
+    use_svg: Literal[False] = False,
+    return_image: Literal[True] = True,
+    *,
+    settings: Optional[DofDrawSettings] = None,
+    **kwargs: Any,
+) -> Image.Image: ...
+@overload
+def MolToDofImage(
+    mol: Union[Chem.Mol, Chem.RWMol],
+    size: Optional[tuple[int, int]] = None,
+    legend: str = "",
+    use_svg: Literal[True] = True,
+    return_image: Literal[False] = False,
+    *,
+    settings: Optional[DofDrawSettings] = None,
+    **kwargs: Any,
+) -> str: ...
+@overload
+def MolToDofImage(
+    mol: Union[Chem.Mol, Chem.RWMol],
+    size: Optional[tuple[int, int]] = None,
+    legend: str = "",
+    use_svg: Literal[False] = False,
+    return_image: Literal[False] = False,
+    *,
+    settings: Optional[DofDrawSettings] = None,
+    **kwargs: Any,
+) -> bytes: ...
+
+
+def MolToDofImage(  # noqa: N802
+    mol: Union[Chem.Mol, Chem.RWMol],
+    size: Optional[tuple[int, int]] = None,
+    legend: str = "",
+    use_svg: bool = True,
+    return_image: bool = True,
+    *,
+    settings: Optional[DofDrawSettings] = None,
+    **kwargs: Any,
+) -> Union["SVG", str, Image.Image, bytes]:
+    """Draw a single molecule with DOF effect."""
+    if settings is None:
+        settings = dofconfig
+
+    draw_size = size if size else settings.default_size
+
+    ready_mol, atom_colors, bond_colors = _prepare_mol_data(mol, settings)
+
+    if use_svg:
+        drawer = rdMolDraw2D.MolDraw2DSVG(draw_size[0], draw_size[1])
+    else:
+        drawer = rdMolDraw2D.MolDraw2DCairo(draw_size[0], draw_size[1])
+
+    dopts = drawer.drawOptions()
+    _apply_rdkit_global_options(dopts)
+    dopts.continuousHighlight = False
+    dopts.circleAtoms = False
+    for k, v in kwargs.items():
+        if hasattr(dopts, k):
+            setattr(dopts, k, v)
+
+    drawer.DrawMolecule(
+        ready_mol,
+        legend=legend,
+        highlightAtoms=list(atom_colors.keys()),
+        highlightAtomColors=atom_colors,
+        highlightBonds=list(bond_colors.keys()),
+        highlightBondColors=bond_colors,
+    )
+    drawer.FinishDrawing()
+
+    if use_svg:
+        svg_text: str = drawer.GetDrawingText()
+        if return_image:
+            if not svg_support:
+                raise ImportError("IPython required for SVG.")
+            return SVG(svg_text)
+        return svg_text
+    else:
+        png_data: bytes = drawer.GetDrawingText()  # type: ignore
+        if return_image:
+            return Image.open(io.BytesIO(png_data))
+        return png_data
+
+
+# =============================================================================
+# Grid Drawer
+# =============================================================================
+
+
+@overload
+def MolGridToDofImage(
+    mols: Sequence[Union[Chem.Mol, Chem.RWMol, None]],
+    molsPerRow: int = 3,  # noqa: N803
+    subImgSize: tuple[int, int] = (300, 300),  # noqa: N803
+    legends: Optional[Sequence[Union[str, None]]] = None,
+    use_svg: Literal[True] = True,
+    return_image: Literal[True] = True,
+    *,
+    settings: Optional[DofDrawSettings] = None,
+    **kwargs: Any,
+) -> "SVG": ...
+@overload
+def MolGridToDofImage(
+    mols: Sequence[Union[Chem.Mol, Chem.RWMol, None]],
+    molsPerRow: int = 3,  # noqa: N803
+    subImgSize: tuple[int, int] = (300, 300),  # noqa: N803
+    legends: Optional[Sequence[Union[str, None]]] = None,
+    use_svg: Literal[False] = False,
+    return_image: Literal[True] = True,
+    *,
+    settings: Optional[DofDrawSettings] = None,
+    **kwargs: Any,
+) -> Image.Image: ...
+@overload
+def MolGridToDofImage(
+    mols: Sequence[Union[Chem.Mol, Chem.RWMol, None]],
+    molsPerRow: int = 3,  # noqa: N803
+    subImgSize: tuple[int, int] = (300, 300),  # noqa: N803
+    legends: Optional[Sequence[Union[str, None]]] = None,
+    use_svg: Literal[True] = True,
+    return_image: Literal[False] = False,
+    *,
+    settings: Optional[DofDrawSettings] = None,
+    **kwargs: Any,
+) -> str: ...
+@overload
+def MolGridToDofImage(
+    mols: Sequence[Union[Chem.Mol, Chem.RWMol, None]],
+    molsPerRow: int = 3,  # noqa: N803
+    subImgSize: tuple[int, int] = (300, 300),  # noqa: N803
+    legends: Optional[Sequence[Union[str, None]]] = None,
+    use_svg: Literal[False] = False,
+    return_image: Literal[False] = False,
+    *,
+    settings: Optional[DofDrawSettings] = None,
+    **kwargs: Any,
+) -> bytes: ...
+def MolGridToDofImage(  # noqa: N802
+    mols: Sequence[Union[Chem.Mol, Chem.RWMol, None]],
+    molsPerRow: int = 3,  # noqa: N803
+    subImgSize: tuple[int, int] = (300, 300),  # noqa: N803
+    legends: Optional[Sequence[Union[str, None]]] = None,
+    use_svg: bool = True,
+    return_image: bool = True,
+    *,
+    settings: Optional[DofDrawSettings] = None,
+    **kwargs: Any,
+) -> Union["SVG", str, Image.Image, bytes]:
+    """
+    Draw a grid of molecules with DOF effect.
+    Compatible with RDKit's Chem.Draw.MolsToGridImage arguments.
+    """
+    if settings is None:
+        settings = dofconfig
+
+    valid_mols = []
+    valid_legends = []
+
+    all_atom_colors = []
+    all_bond_colors = []
+    all_highlight_atoms = []
+    all_highlight_bonds = []
+
+    for i, m in enumerate(mols):
+        if m is None:
+            m = Chem.Mol()
+
+        try:
+            ready_mol, atom_cols, bond_cols = _prepare_mol_data(m, settings)
+        except Exception:
+            ready_mol = m
+            atom_cols, bond_cols = {}, {}
+
+        valid_mols.append(ready_mol)
+
+        if legends and i < len(legends) and legends[i]:
+            valid_legends.append(str(legends[i]))
+        else:
+            valid_legends.append("")
+
+        all_atom_colors.append(atom_cols)
+        all_bond_colors.append(bond_cols)
+        all_highlight_atoms.append(list(atom_cols.keys()))
+        all_highlight_bonds.append(list(bond_cols.keys()))
+
+    n_mols = len(valid_mols)
+    n_rows = math.ceil(n_mols / molsPerRow)
+    full_width = subImgSize[0] * molsPerRow
+    full_height = subImgSize[1] * n_rows
+
+    if use_svg:
+        drawer = rdMolDraw2D.MolDraw2DSVG(
+            full_width, full_height, subImgSize[0], subImgSize[1]
+        )
+    else:
+        drawer = rdMolDraw2D.MolDraw2DCairo(
+            full_width, full_height, subImgSize[0], subImgSize[1]
+        )
+
+    dopts = drawer.drawOptions()
+    _apply_rdkit_global_options(dopts)
+    dopts.continuousHighlight = False
+    dopts.circleAtoms = False
+
+    for k, v in kwargs.items():
+        if hasattr(dopts, k):
+            setattr(dopts, k, v)
+
+    drawer.DrawMolecules(
+        valid_mols,
+        legends=valid_legends,
+        highlightAtoms=all_highlight_atoms,
+        highlightAtomColors=all_atom_colors,
+        highlightBonds=all_highlight_bonds,
+        highlightBondColors=all_bond_colors,
+    )
+    drawer.FinishDrawing()
+    if use_svg:
+        svg_text: str = drawer.GetDrawingText()
+        if return_image:
+            if not svg_support:
+                raise ImportError("IPython required for SVG.")
+            return SVG(svg_text)
+        return svg_text
+    else:
+        png_data: bytes = drawer.GetDrawingText()  # type: ignore
+        if return_image:
+            return Image.open(io.BytesIO(png_data))
+        return png_data

rdkit_dof/palettes.py

@@ -0,0 +1,59 @@
+"""
+Author: TMJ
+Date: 2025-12-01 12:45:28
+LastEditors: TMJ
+LastEditTime: 2025-12-01 14:13:11
+Description: 请填写简介
+"""
+
+AtomColorMap = dict[int, tuple[float, float, float]]
+
+# Basic RDKit-style color map
+DEFAULT_STYLE: AtomColorMap = {
+    1: (0.55, 0.55, 0.55),  # H (Gray)
+    6: (0.2, 0.2, 0.2),  # C (Dark Gray)
+    7: (0.0, 0.0, 1.0),  # N (Blue)
+    8: (1.0, 0.0, 0.0),  # O (Red)
+    9: (0.2, 0.8, 0.8),  # F
+    15: (1.0, 0.5, 0.0),  # P
+    16: (0.8, 0.8, 0.0),  # S
+    17: (0.0, 0.8, 0.0),  # Cl
+    35: (0.5, 0.3, 0.1),  # Br
+    53: (0.63, 0.12, 0.94),  # I
+}
+
+# Nature-style color map: distinct, with blue and red more modern
+NATURE_STYLE: AtomColorMap = {
+    1: (0.9, 0.9, 0.9),  # H (Light Gray)
+    6: (0.25, 0.25, 0.25),  # C (Dark Gray, not pitch black)
+    7: (0.19, 0.51, 0.74),  # N (Nature Blue - slightly lighter)
+    8: (0.89, 0.10, 0.11),  # O (Nature Red - less neon)
+    9: (0.50, 0.70, 0.90),  # F (Sky Blue)
+    15: (1.0, 0.6, 0.0),  # P (Orange)
+    16: (0.9, 0.8, 0.2),  # S (Yellow)
+    17: (0.1, 0.7, 0.3),  # Cl (Green)
+    35: (0.6, 0.2, 0.2),  # Br (Dark Red/Brown)
+}
+
+# JACS-style color map: deep, close to print colors, high contrast
+JACS_STYLE: AtomColorMap = {
+    1: (1.0, 1.0, 1.0),  # H (White)
+    6: (0.1, 0.1, 0.1),  # C (Almost Black)
+    7: (0.05, 0.20, 0.60),  # N (Navy Blue)
+    8: (0.75, 0.05, 0.05),  # O (Crimson Red)
+    9: (0.4, 0.8, 0.4),  # F (Pale Green)
+    15: (0.8, 0.4, 0.0),  # P (Dark Orange)
+    16: (0.8, 0.8, 0.0),  # S (Standard Yellow)
+    17: (0.0, 0.5, 0.0),  # Cl (Dark Green)
+}
+
+# dark neon-style color map: high contrast, pop with black background
+DARK_NEON_STYLE: AtomColorMap = {
+    1: (0.8, 0.8, 0.8),  # H (Light Gray)
+    6: (0.9, 0.9, 0.9),  # C (White/Light Gray to pop on black)
+    7: (0.3, 0.6, 1.0),  # N (Bright Blue)
+    8: (1.0, 0.4, 0.4),  # O (Bright Red/Pink)
+    9: (0.2, 1.0, 1.0),  # F (Cyan)
+    15: (1.0, 0.7, 0.2),  # P (Bright Orange)
+    16: (1.0, 1.0, 0.4),  # S (Bright Yellow)
+}

rdkit_dof-0.1.0.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: rdkit-dof
+Version: 0.1.0
+Summary: RDKit molecule drawing with Depth of Field (DOF) effects.
+Project-URL: Homepage, https://github.com/gentle1999/rdkit-dof
+Project-URL: Bug Tracker, https://github.com/gentle1999/rdkit-dof/issues
+Project-URL: Repository, https://github.com/gentle1999/rdkit-dof.git
+Author-email: Miao-Jiong Tang <mj_t@zju.edu.cn>
+License: MIT
+License-File: LICENSE
+Keywords: DOF,cheminformatics,chemistry,drawing,molecule,rdkit,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pydantic-settings>=2.11.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: rdkit>=2023.9.6
+Description-Content-Type: text/markdown
+
+# rdkit-dof
+
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+[简体中文](README_zh.md)
+
+`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.
+
+## Comparison
+
+To better showcase the effect of `rdkit-dof`, we have compared it with RDKit's default drawing function.
+
+### Single Molecule Comparison
+
+|                        Default RDKit                        |                  rdkit-dof Effect                   |
+| :---------------------------------------------------------: | :-------------------------------------------------: |
+| ![Paclitaxel Default](assets/comparison_single_default.svg) | ![Paclitaxel DOF](assets/comparison_single_dof.svg) |
+
+### Grid Mode Comparison
+
+|                    Default RDKit                    |              rdkit-dof Effect               |
+| :-------------------------------------------------: | :-----------------------------------------: |
+| ![Grid Default](assets/comparison_grid_default.svg) | ![Grid DOF](assets/comparison_grid_dof.svg) |
+
+## Tech Stack
+
+- **Core:** Python 3.9+
+- **Cheminformatics:** RDKit
+- **Image Processing:** Pillow
+- **Configuration:** Pydantic
+
+## Installation
+
+```bash
+pip install rdkit-dof
+```
+
+## Usage
+
+Here is a basic example of how to generate an image with a depth-of-field effect for a molecule.
+
+```python
+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. Call the core function to generate the image (returns SVG text)
+svg_data = MolToDofImage(
+    mol,
+    size=(1000, 800),
+    legend="Paclitaxel (Taxol)",
+    use_svg=True,
+    return_image=False, # Set to False to get raw data (str or bytes)
+)
+
+# 4. Save to a file
+with open("paclitaxel.svg", "w") as f:
+    f.write(svg_data)
+
+print("Image saved to paclitaxel.svg")
+
+# 5. (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 image
+```
+
+## API
+
+This toolkit provides two core drawing functions:
+
+### `MolToDofImage`
+
+Generates a DOF image for a single molecule.
+
+```python
+MolToDofImage(
+    mol: Chem.Mol,
+    size: Optional[tuple[int, int]] = None,
+    legend: str = "",
+    use_svg: bool = True,
+    return_image: bool = True,
+    *,
+    settings: Optional[DofDrawSettings] = None,
+    **kwargs: Any,
+) -> Union["SVG", str, Image.Image, bytes]
+```
+
+- **`mol`**: RDKit molecule object, which must contain a 3D conformation.
+- **`size`**: Image dimensions `(width, height)`.
+- **`legend`**: Legend text below the image.
+- **`use_svg`**: `True` returns SVG, `False` returns PNG.
+- **`return_image`**: `True` returns an IPython/Pillow image object, `False` returns raw data (string for SVG, bytes for PNG).
+- **`settings`**: A `DofDrawSettings` instance for local configuration.
+- **`**kwargs`**: Other RDKit `MolDrawOptions` parameters.
+
+### `MolGridToDofImage`
+
+Generates a DOF image for a grid of molecules, with parameters similar to RDKit's `MolsToGridImage`.
+
+```python
+MolGridToDofImage(
+    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,
+    *,
+    settings: Optional[DofDrawSettings] = None,
+    **kwargs: Any,
+) -> Union["SVG", str, Image.Image, bytes]
+```
+
+## Configuration
+
+You can customize the drawing style via a global `dofconfig` object or environment variables (`.env`).
+
+### Global Config Object
+
+Modify the properties of the `rdkit_dof.dofconfig` object directly in your code.
+
+```python
+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 red
+```
+
+### Environment Variables
+
+You can also customize the drawing style by setting environment variables. All configuration properties have a corresponding environment variable, named `MOL_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:
+
+```env
+# Set fog color to dark gray
+MOL_DOF_FOG_COLOR=[0.1, 0.1, 0.1]
+# Adjust minimum alpha
+MOL_DOF_MIN_ALPHA=0.2
+```
+
+### Main Configuration Properties
+
+| 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` |
+
+## Running the Examples
+
+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:
+
+```bash
+# Generate comparison images
+python scripts/_generate_comparison_images.py
+```
+
+## Compatibility
+
+- **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.09` or higher.
+
+## Contribution Guide
+
+Contributions of any kind are welcome!
+
+1. Fork the repository.
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`).
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`).
+4. Push to the branch (`git push origin feature/AmazingFeature`).
+5. Open a Pull Request.
+
+## License
+
+This project is distributed under the MIT License. See the [LICENSE](LICENSE) file for details.

rdkit_dof-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+rdkit_dof/__init__.py,sha256=atx1GCMVjPBpvmqfoC_O3cRYOVDnDm4I5CCBl_tPKdU,221
+rdkit_dof/config.py,sha256=RijM7_lZksXG8xb_ml--RwTPlDnKFf_8WLngvi2j0Hs,3776
+rdkit_dof/core.py,sha256=DtyTfq2jB_ILKhzhn8mkvGqGsANl862oYokUqkhd4t4,11853
+rdkit_dof/palettes.py,sha256=NZ1FtKmQeSRuCNMJklkUJPHuUdr4zUNQ91sZSlql4S0,1992
+rdkit_dof-0.1.0.dist-info/METADATA,sha256=SFdiUZlULIyVduf9aCNxMvlRWbvELaK7uD4SGs7_SbM,8529
+rdkit_dof-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+rdkit_dof-0.1.0.dist-info/licenses/LICENSE,sha256=GWLWR3AErH2wmYmfIfUuM_pHsqyWgwI7sbNc5PDppbc,1069
+rdkit_dof-0.1.0.dist-info/RECORD,,

rdkit_dof-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

rdkit_dof-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2025 tmj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 
+associated documentation files (the "Software"), to deal in the Software without restriction, including 
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the 
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial 
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT 
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO 
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE 
+USE OR OTHER DEALINGS IN THE SOFTWARE.