molviewer 0.1.1__py3-none-any.whl

molviewer/__init__.py

@@ -0,0 +1,11 @@
+"""
+molviewer — 2D and 3D molecular visualization for Jupyter, Colab, and Streamlit.
+
+2D drawing with RDKit, 3D viewing with py3Dmol and Speck (ambient occlusion).
+"""
+
+__version__ = "0.1.1"
+
+from .draw2d import draw
+from .view3d import view3d
+from .attribution import draw_attribution

molviewer/_mol.py

@@ -0,0 +1,165 @@
+"""
+Standalone molecule utilities — no dependency on molfp.
+"""
+
+from __future__ import annotations
+
+from rdkit import Chem
+from rdkit.Chem import AllChem, rdMolDescriptors
+
+
+_conformer_cache = {}
+
+
+def ensure_mol(smiles_or_mol):
+    """Convert SMILES to RDKit Mol if needed."""
+    if isinstance(smiles_or_mol, Chem.rdchem.Mol):
+        return smiles_or_mol
+    if isinstance(smiles_or_mol, str):
+        mol = Chem.MolFromSmiles(smiles_or_mol)
+        if mol is None:
+            raise ValueError(f"Invalid SMILES: {smiles_or_mol}")
+        return mol
+    raise TypeError(f"Expected SMILES string or RDKit Mol, got {type(smiles_or_mol)}")
+
+
+def extract_smiles(input_data, column=None):
+    """Extract a list of SMILES from various input types.
+
+    Returns (smiles_list, is_batch) where is_batch=False means single molecule.
+    """
+    if isinstance(input_data, str):
+        return input_data, False
+
+    if isinstance(input_data, Chem.rdchem.Mol):
+        return input_data, False
+
+    try:
+        import pandas as pd
+        if isinstance(input_data, pd.DataFrame):
+            if column is not None:
+                return input_data[column].tolist(), True
+            for col in ["SMILES", "smiles", "Smiles", "canonical_smiles", "CANONICAL_SMILES",
+                        "mol", "Mol", "MOL", "molecule", "smi"]:
+                if col in input_data.columns:
+                    return input_data[col].tolist(), True
+            raise ValueError(
+                "DataFrame has no recognized SMILES column. "
+                "Pass column= or use a column named 'SMILES', 'smiles', or 'canonical_smiles'."
+            )
+        if isinstance(input_data, pd.Series):
+            return input_data.tolist(), True
+    except ImportError:
+        pass
+
+    if hasattr(input_data, '__iter__') and not isinstance(input_data, (str, bytes)):
+        return list(input_data), True
+
+    return input_data, False
+
+
+# ── Conformer generation ──────────────────────────────────────────────────────
+
+_METAL_ATOMIC_NUMS = (
+    set(range(3, 5))
+    | set(range(11, 14))
+    | set(range(19, 31))
+    | set(range(37, 49))
+    | set(range(55, 81))
+    | set(range(87, 104))
+)
+
+_LARGE_MOL_THRESHOLD = 80
+
+
+def _classify_molecule(mol):
+    has_metal = any(a.GetAtomicNum() in _METAL_ATOMIC_NUMS for a in mol.GetAtoms())
+    is_large = mol.GetNumHeavyAtoms() > _LARGE_MOL_THRESHOLD
+    if has_metal and is_large:
+        return "metal_large"
+    if has_metal:
+        return "metal"
+    if is_large:
+        return "large"
+    return "standard"
+
+
+def _estimate_max_iters(mol):
+    """Estimate MMFF iterations from molecular descriptors (MLR on 1,420 FDA drugs)."""
+    n_atoms = mol.GetNumHeavyAtoms()
+    n_rot = rdMolDescriptors.CalcNumRotatableBonds(mol)
+    n_rings = rdMolDescriptors.CalcNumRings(mol)
+    fsp3 = rdMolDescriptors.CalcFractionCSP3(mol)
+    raw = -10 + 9.9 * n_atoms + 6.8 * n_rot - 12.4 * n_rings + 38.3 * fsp3
+    return max(200, min(2000, int(1.5 * raw)))
+
+
+def _ensure_conformer_impl(mol):
+    """Core conformer generation logic."""
+    if mol.GetNumConformers() > 0:
+        return mol
+
+    mol_class = _classify_molecule(mol)
+    mol = Chem.AddHs(mol)
+
+    if mol_class in ("large", "metal_large"):
+        params = AllChem.ETKDGv3()
+        params.randomSeed = 42
+        status = AllChem.EmbedMolecule(mol, params)
+        if status == -1:
+            params.useRandomCoords = True
+            status = AllChem.EmbedMolecule(mol, params)
+    else:
+        status = AllChem.EmbedMolecule(mol, randomSeed=42)
+        if status == -1:
+            status = AllChem.EmbedMolecule(mol, AllChem.ETKDGv3())
+
+    if status == -1:
+        return mol
+
+    estimated = _estimate_max_iters(mol)
+
+    if mol_class in ("metal", "metal_large"):
+        try:
+            for multiplier in [1, 2, 4]:
+                max_iters = min(estimated * multiplier, 4000)
+                result = AllChem.UFFOptimizeMolecule(mol, maxIters=max_iters)
+                if result == 0:
+                    return mol
+        except Exception:
+            pass
+        return mol
+
+    props = AllChem.MMFFGetMoleculeProperties(mol)
+    if props is not None:
+        for multiplier in [1, 2, 4]:
+            max_iters = min(estimated * multiplier, 4000)
+            result = AllChem.MMFFOptimizeMolecule(mol, maxIters=max_iters)
+            if result == 0:
+                return mol
+        return mol
+
+    try:
+        for multiplier in [1, 2, 4]:
+            max_iters = min(estimated * multiplier, 4000)
+            result = AllChem.UFFOptimizeMolecule(mol, maxIters=max_iters)
+            if result == 0:
+                return mol
+    except Exception:
+        pass
+
+    return mol
+
+
+def ensure_conformer(mol):
+    """Add optimized 3D conformer with caching."""
+    try:
+        smi = Chem.MolToSmiles(mol)
+        if smi in _conformer_cache:
+            return _conformer_cache[smi]
+    except Exception:
+        return _ensure_conformer_impl(mol)
+
+    result = _ensure_conformer_impl(mol)
+    _conformer_cache[smi] = result
+    return result

molviewer/attribution.py

@@ -0,0 +1,221 @@
+"""
+2D structural attribution maps — requires molfp for SHAP/explain.
+
+Green = active-driving atoms, Red = inactive-driving atoms.
+Two styles: 'highlight' (solid atom/bond circles) and 'contour' (gaussian contour map).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from rdkit import Chem
+from rdkit.Chem import AllChem
+
+from ._mol import ensure_mol
+
+
+def _bit_shap_to_atom_weights(mol, smiles, fp_type, shap_per_bit):
+    """Aggregate bit-level SHAP values to per-atom weights via explain()."""
+    try:
+        from molfp.explain import explain
+    except ImportError:
+        raise ImportError(
+            "molfp is required for draw_attribution(). "
+            "Install it with: pip install molfp"
+        )
+
+    bit_atoms = explain(smiles, fp_type)
+    n_atoms = mol.GetNumAtoms()
+    weights = np.zeros(n_atoms)
+    for bit, shap_val in shap_per_bit.items():
+        if bit not in bit_atoms:
+            continue
+        for atom_info in bit_atoms[bit]:
+            if isinstance(atom_info, (list, tuple)):
+                atom_indices = [a for a in atom_info if isinstance(a, int)]
+            elif isinstance(atom_info, int):
+                atom_indices = [atom_info]
+            else:
+                continue
+            if atom_indices:
+                share = shap_val / len(atom_indices)
+                for idx in atom_indices:
+                    if 0 <= idx < n_atoms:
+                        weights[idx] += share
+    return weights
+
+
+def draw_attribution(smiles, interpret_result, *,
+                     class_active="active", class_inactive="inactive",
+                     size=(400, 400), alpha=0.5, style="highlight", save=None):
+    """Draw 2D structure colored by class-specific SHAP attribution.
+
+    Green regions drive the active prediction, red regions drive inactive.
+    Intensity is proportional to SHAP magnitude. Neutral atoms are uncolored.
+
+    Requires molfp: pip install molfp
+
+    Args:
+        smiles: SMILES string of the molecule to visualize.
+        interpret_result: dict returned by molfp.interpret().
+        class_active: name of the active class in interpret_result.
+        class_inactive: name of the inactive class in interpret_result.
+        size: (width, height) in pixels.
+        alpha: transparency of the heatmap overlay.
+        style: "highlight" (solid atom/bond circles) or "contour" (gaussian contour map).
+        save: file path to save the image. If None, image is not saved.
+
+    Returns:
+        PIL.Image.Image
+    """
+    try:
+        from molfp.fingerprints import FINGERPRINTS
+    except ImportError:
+        raise ImportError(
+            "molfp is required for draw_attribution(). "
+            "Install it with: pip install molfp"
+        )
+
+    mol = ensure_mol(smiles)
+    AllChem.Compute2DCoords(mol)
+    fp_type = interpret_result["fp_type"]
+    model = interpret_result["model"]
+    label_set = interpret_result["label_set"]
+
+    fn = FINGERPRINTS[fp_type][0]
+    fp = np.array([fn(smiles)], dtype=np.int32)
+
+    active_idx = label_set.index(class_active) if class_active in label_set else 0
+    inactive_idx = label_set.index(class_inactive) if class_inactive in label_set else -1
+
+    import shap
+    explainer = shap.TreeExplainer(model)
+    sv = explainer.shap_values(fp)
+
+    if isinstance(sv, np.ndarray) and sv.ndim == 3:
+        mol_shap_active = sv[0, :, active_idx]
+        mol_shap_inactive = sv[0, :, inactive_idx] if inactive_idx >= 0 else -sv[0, :, active_idx]
+    elif isinstance(sv, list):
+        mol_shap_active = sv[active_idx][0]
+        mol_shap_inactive = sv[inactive_idx][0] if inactive_idx >= 0 else -sv[active_idx][0]
+    else:
+        mol_shap_active = sv[0]
+        mol_shap_inactive = -sv[0]
+
+    fp_vec = fn(smiles)
+    on_bits = [i for i, v in enumerate(fp_vec) if v > 0]
+
+    active_bit_shap = {b: float(mol_shap_active[b]) for b in on_bits}
+    inactive_bit_shap = {b: float(mol_shap_inactive[b]) for b in on_bits}
+
+    active_weights = _bit_shap_to_atom_weights(mol, smiles, fp_type, active_bit_shap)
+    inactive_weights = _bit_shap_to_atom_weights(mol, smiles, fp_type, inactive_bit_shap)
+
+    # ── Contour style ─────────────────────────────────────────────────────
+    def _render_contour(weights, cmap):
+        import matplotlib
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+        from rdkit.Chem.Draw import SimilarityMaps, rdMolDraw2D
+        from PIL import Image as PILImage
+        from io import BytesIO
+
+        max_w = max(abs(weights.max()), abs(weights.min()), 1e-8)
+        normalized = list(weights / max_w)
+
+        try:
+            d2d = rdMolDraw2D.MolDraw2DCairo(size[0], size[1])
+        except Exception:
+            d2d = rdMolDraw2D.MolDraw2DSVG(size[0], size[1])
+        d2d.drawOptions().bondLineWidth = 2.0
+
+        result_d2d = SimilarityMaps.GetSimilarityMapFromWeights(
+            mol, normalized, colorMap=cmap, alpha=alpha, size=size,
+            draw2d=d2d, contourLines=10
+        )
+        result_d2d.FinishDrawing()
+        png = result_d2d.GetDrawingText()
+        return PILImage.open(BytesIO(png)).copy()
+
+    # ── Highlight style ───────────────────────────────────────────────────
+    def _render_highlight(weights, color_pos, color_neg):
+        from rdkit.Chem.Draw import rdMolDraw2D
+        from PIL import Image as PILImage
+        from io import BytesIO
+
+        max_w = max(abs(weights.max()), abs(weights.min()), 1e-8)
+        norm = weights / max_w
+
+        def _color_for_weight(w):
+            if abs(w) < 0.05:
+                return None
+            color = color_pos if w > 0 else color_neg
+            intensity = min(abs(w), 1.0)
+            r = color[0] + (1 - color[0]) * (1 - intensity)
+            g = color[1] + (1 - color[1]) * (1 - intensity)
+            b = color[2] + (1 - color[2]) * (1 - intensity)
+            return (r, g, b)
+
+        highlight_atoms = []
+        highlight_colors = {}
+        for i, w in enumerate(norm):
+            c = _color_for_weight(w)
+            if c is not None:
+                highlight_atoms.append(i)
+                highlight_colors[i] = c
+
+        highlight_bonds = []
+        highlight_bond_colors = {}
+        highlight_atom_set = set(highlight_atoms)
+        for bond in mol.GetBonds():
+            a1 = bond.GetBeginAtomIdx()
+            a2 = bond.GetEndAtomIdx()
+            if a1 in highlight_atom_set or a2 in highlight_atom_set:
+                bond_idx = bond.GetIdx()
+                highlight_bonds.append(bond_idx)
+                avg_w = (norm[a1] + norm[a2]) / 2
+                c = _color_for_weight(avg_w)
+                if c is None:
+                    c = (0.95, 0.95, 0.95)
+                highlight_bond_colors[bond_idx] = c
+
+        try:
+            drawer = rdMolDraw2D.MolDraw2DCairo(size[0], size[1])
+        except Exception:
+            drawer = rdMolDraw2D.MolDraw2DSVG(size[0], size[1])
+        drawer.drawOptions().clearBackground = True
+
+        highlight_radii = {i: 0.4 for i in highlight_atoms}
+        drawer.DrawMolecule(
+            mol,
+            highlightAtoms=highlight_atoms,
+            highlightAtomColors=highlight_colors,
+            highlightAtomRadii=highlight_radii,
+            highlightBonds=highlight_bonds,
+            highlightBondColors=highlight_bond_colors,
+        )
+        drawer.FinishDrawing()
+        png = drawer.GetDrawingText()
+        return PILImage.open(BytesIO(png)).copy()
+
+    green = (0.13, 0.55, 0.13)
+    red = (0.8, 0.1, 0.1)
+
+    active_pos = np.clip(active_weights, 0, None)
+    inactive_pos = np.clip(-inactive_weights, 0, None)
+    dual_weights = active_pos - inactive_pos
+
+    if style == "contour":
+        from matplotlib.colors import LinearSegmentedColormap
+        cmap_dual = LinearSegmentedColormap.from_list("dual", [red, (1, 1, 1), green])
+        img = _render_contour(dual_weights, cmap_dual)
+    elif style == "highlight":
+        img = _render_highlight(dual_weights, green, red)
+    else:
+        raise ValueError(f"Unknown style: {style}. Use 'highlight' or 'contour'.")
+
+    if save:
+        img.save(save)
+    return img

molviewer/draw2d.py

@@ -0,0 +1,97 @@
+"""
+2D molecular drawing for Jupyter, Colab, and Streamlit.
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+from rdkit import Chem
+from rdkit.Chem import Draw
+
+from ._mol import ensure_mol, extract_smiles
+
+
+def draw(input_data, *, highlight_bits=None, fp_type=None, legends=None,
+         size=(300, 300), mols_per_row=3, column=None):
+    """Draw 2D molecular structure(s).
+
+    Works in Jupyter, Colab, and Streamlit (pass returned image to st.image()).
+
+    Args:
+        input_data: SMILES string, list of SMILES, RDKit Mol, pd.Series, or pd.DataFrame.
+        highlight_bits: list of fingerprint bit indices to highlight (requires fp_type and molfp).
+        fp_type: fingerprint type for bit highlighting (e.g. "ecfp4", "maccs").
+        legends: list of labels for each molecule in grid mode.
+        size: (width, height) per molecule in pixels.
+        mols_per_row: molecules per row in grid mode.
+        column: column name for DataFrame input.
+
+    Returns:
+        PIL.Image.Image
+    """
+    data, is_batch = extract_smiles(input_data, column=column)
+
+    if not is_batch:
+        mol = ensure_mol(data)
+        highlight_atoms = _get_highlight_atoms(mol, highlight_bits, fp_type)
+        img = Draw.MolToImage(mol, size=size, highlightAtoms=highlight_atoms)
+        return img
+
+    smiles_list = data
+    mols = []
+    for s in smiles_list:
+        try:
+            mols.append(ensure_mol(s))
+        except (ValueError, TypeError):
+            mols.append(None)
+
+    if legends is None:
+        legends = [s if isinstance(s, str) else "" for s in smiles_list]
+
+    if highlight_bits and fp_type:
+        highlight_atom_lists = []
+        for mol in mols:
+            if mol is not None:
+                highlight_atom_lists.append(
+                    _get_highlight_atoms(mol, highlight_bits, fp_type)
+                )
+            else:
+                highlight_atom_lists.append([])
+    else:
+        highlight_atom_lists = None
+
+    img = Draw.MolsToGridImage(
+        mols,
+        molsPerRow=mols_per_row,
+        subImgSize=size,
+        legends=legends,
+        highlightAtomLists=highlight_atom_lists,
+    )
+    return img
+
+
+def _get_highlight_atoms(mol, highlight_bits, fp_type):
+    """Get atom indices to highlight for given fingerprint bits."""
+    if not highlight_bits or not fp_type:
+        return []
+
+    try:
+        from molfp.explain import explain
+    except ImportError:
+        return []
+
+    smiles = Chem.MolToSmiles(mol)
+    bit_info = explain(smiles, fp_type)
+
+    atoms = set()
+    for bit in highlight_bits:
+        if bit in bit_info:
+            for atom_info in bit_info[bit]:
+                if isinstance(atom_info, (list, tuple)):
+                    for a in atom_info:
+                        if isinstance(a, int):
+                            atoms.add(a)
+                elif isinstance(atom_info, int):
+                    atoms.add(atom_info)
+    return list(atoms)

molviewer/view3d.py

@@ -0,0 +1,213 @@
+"""
+3D molecular viewing for Jupyter, Colab, and Streamlit.
+
+Supports py3Dmol styles (stick, sphere, line, cartoon, ball_and_stick)
+and Speck ambient-occlusion renderer with presets.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from rdkit import Chem
+from rdkit.Chem import AllChem
+
+from ._mol import ensure_mol, ensure_conformer
+
+
+def _detect_env():
+    """Detect runtime environment: 'jupyter', 'streamlit', or 'script'."""
+    if "streamlit" in sys.modules:
+        return "streamlit"
+    try:
+        shell = get_ipython().__class__.__name__
+        if shell in ("ZMQInteractiveShell", "Shell"):
+            return "jupyter"
+    except NameError:
+        pass
+    return "script"
+
+
+def view3d(input_data, *, style="stick", size=(600, 400), spin=False,
+           background="white", preset=None,
+           atom_scale=None, bond_scale=None, ao=None, brightness=None,
+           outline=None, bonds=None):
+    """Interactive 3D molecular viewer.
+
+    Auto-detects environment:
+      - Jupyter/Colab: renders inline interactive widget
+      - Streamlit: renders via st.components.v1.html()
+      - Script: returns HTML string (py3Dmol) or widget (speck)
+
+    Args:
+        input_data: SMILES string or RDKit Mol.
+        style: py3Dmol styles ("stick", "sphere", "line", "cartoon", "ball_and_stick")
+               or "speck" for the Speck ambient-occlusion renderer.
+        size: (width, height) in pixels.
+        spin: if True, auto-rotate the molecule.
+        background: background color (default "white", py3Dmol only).
+        preset: Speck preset. molviewer presets: "ball_and_stick" (default look),
+                "toon" (flat shading + outlines), "licorice" (stick model),
+                "houkmol" (matte + outlines, Houk group style approximation).
+                ipyspeck presets: "default", "matte", "glossy", "cover",
+                "metal", "glass", "goodsell".
+        atom_scale: Speck atom radius (0.0-1.0).
+        bond_scale: Speck bond radius (0.0-1.0).
+        ao: Speck ambient occlusion strength (0.0-1.0).
+        brightness: Speck brightness (0.0-1.0).
+        outline: Speck depth-aware outline strength (0.0-1.0).
+        bonds: Speck show bonds (True/False).
+
+    Returns:
+        In script mode: HTML string (py3Dmol) or Speck widget.
+        In notebook/Streamlit: displays inline.
+    """
+    if style == "speck":
+        return _view3d_speck(input_data, size=size, spin=spin, preset=preset,
+                             atom_scale=atom_scale, bond_scale=bond_scale,
+                             ao=ao, brightness=brightness, outline=outline,
+                             bonds=bonds)
+
+    try:
+        import py3Dmol
+    except ImportError:
+        raise ImportError(
+            "py3Dmol is required for 3D viewing. "
+            "Install it with: pip install py3Dmol"
+        )
+
+    mol = ensure_mol(input_data)
+    mol = ensure_conformer(mol)
+    mol_block = Chem.MolToMolBlock(mol)
+
+    viewer = py3Dmol.view(width=size[0], height=size[1])
+    viewer.addModel(mol_block, "mol")
+
+    style_spec = _build_style(style)
+    viewer.setStyle(style_spec)
+    viewer.setBackgroundColor(background)
+    if spin:
+        viewer.spin(True)
+    viewer.zoomTo()
+
+    env = _detect_env()
+
+    if env == "jupyter":
+        return viewer.show()
+    elif env == "streamlit":
+        import streamlit.components.v1 as components
+        html = viewer._make_html()
+        components.html(html, height=size[1] + 20, width=size[0] + 20)
+    else:
+        return viewer._make_html()
+
+
+# ── Speck presets ─────────────────────────────────────────────────────────────
+
+_MOLVIEWER_PRESETS = {
+    "ball_and_stick": {
+        "atomScale": 0.24, "relativeAtomScale": 0.64, "atomShade": 0.5,
+        "bonds": True, "bondScale": 0.5, "bondShade": 0.5,
+        "ao": 0.75, "brightness": 0.5, "outline": 0.0,
+        "dofStrength": 0.0,
+    },
+    "toon": {
+        "atomScale": 0.24, "relativeAtomScale": 0.64, "atomShade": 0.5,
+        "bonds": True, "bondScale": 0.5, "bondShade": 0.5,
+        "ao": 0.0, "brightness": 0.5, "outline": 1.0,
+        "dofStrength": 0.0,
+    },
+    "licorice": {
+        "atomScale": 0.1, "relativeAtomScale": 0.0, "atomShade": 0.5,
+        "bonds": True, "bondScale": 1.0, "bondShade": 0.5,
+        "ao": 0.75, "brightness": 0.5, "outline": 0.0,
+        "dofStrength": 0.0,
+    },
+    "houkmol": {
+        "atomScale": 0.24, "relativeAtomScale": 0.64, "atomShade": 0.5,
+        "bonds": True, "bondScale": 0.5, "bondShade": 0.1,
+        "ao": 0.5, "brightness": 0.65, "outline": 1.0,
+        "outlineColor": "#000000", "outlineWidth": 2.5,
+        "outlineMode": "depth",
+        "gloss": 0.0, "metallic": 0.0, "specular": 0.1,
+        "saturation": 0.7, "dofStrength": 0.0, "fog": 0.0,
+        "fxaa": 1, "shadows": 0.0, "rim": 0.0,
+    },
+}
+
+
+def _view3d_speck(input_data, *, size=(600, 400), spin=False, preset=None,
+                  atom_scale=None, bond_scale=None, ao=None, brightness=None,
+                  outline=None, bonds=None):
+    """Render molecule with the Speck ambient-occlusion renderer."""
+    try:
+        from ipyspeck import Speck
+    except ImportError:
+        raise ImportError(
+            "ipyspeck is required for style='speck'. "
+            "Install it with: pip install ipyspeck"
+        )
+
+    mol = ensure_mol(input_data)
+    mol = Chem.AddHs(mol)
+    mol = ensure_conformer(mol)
+
+    w = Speck.from_rdkit(mol)
+    w.layout.width = f"{size[0]}px"
+    w.layout.height = f"{size[1]}px"
+
+    # Apply preset (default to ball_and_stick if none specified)
+    active_preset = preset if preset else "ball_and_stick"
+    if active_preset in _MOLVIEWER_PRESETS:
+        for key, value in _MOLVIEWER_PRESETS[active_preset].items():
+            setattr(w, key, value)
+    else:
+        try:
+            w.apply_preset(active_preset)
+        except (ValueError, Exception):
+            pass
+
+    # Apply user-specified parameters (override preset/defaults)
+    if atom_scale is not None:
+        w.atomScale = atom_scale
+    if bond_scale is not None:
+        w.bondScale = bond_scale
+    if ao is not None:
+        w.ao = ao
+    if brightness is not None:
+        w.brightness = brightness
+    if outline is not None:
+        w.outline = outline
+    if bonds is not None:
+        w.bonds = bonds
+    if spin:
+        w.autoRotate = True
+
+    env = _detect_env()
+    if env == "streamlit":
+        try:
+            import stspeck
+            mol_block = Chem.MolToMolBlock(mol)
+            kwargs = {"data": mol_block}
+            if preset:
+                kwargs["preset"] = preset
+            stspeck.speck(**kwargs, height=size[1])
+            return
+        except ImportError:
+            pass
+
+    return w
+
+
+def _build_style(style):
+    """Convert style name to py3Dmol style dict."""
+    styles = {
+        "stick": {"stick": {}},
+        "sphere": {"sphere": {"radius": 0.4}},
+        "line": {"line": {}},
+        "cartoon": {"cartoon": {}},
+        "ball_and_stick": {"stick": {}, "sphere": {"radius": 0.3}},
+    }
+    if style in styles:
+        return styles[style]
+    return {"stick": {}}

molviewer-0.1.1.dist-info/METADATA

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: molviewer
+Version: 0.1.1
+Summary: 2D and 3D molecular visualization for Jupyter, Colab, and Streamlit
+Author: Chanin Nantasenamat
+License: MIT
+Project-URL: Homepage, https://github.com/dataprofessor/molviewer
+Project-URL: Repository, https://github.com/dataprofessor/molviewer
+Keywords: cheminformatics,molecular-visualization,drug-discovery,RDKit,py3Dmol,speck,jupyter,streamlit
+Classifier: Development Status :: 3 - Alpha
+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: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: rdkit>=2023.03
+Requires-Dist: py3Dmol>=2.0
+Requires-Dist: ipyspeck>=0.8
+Requires-Dist: molfp>=0.3.4
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# molviewer
+
+**2D and 3D molecular visualization for Jupyter, Colab, and Streamlit.**
+
+## Install
+
+```bash
+pip install molviewer
+```
+
+## Quick Start
+
+```python
+import molviewer
+
+# 2D drawing
+molviewer.draw("CC(=O)Oc1ccccc1C(=O)O")
+molviewer.draw(["CCO", "c1ccccc1"], legends=["Ethanol", "Benzene"])
+
+# 3D viewing — py3Dmol
+molviewer.view3d("CC(=O)Oc1ccccc1C(=O)O", style="stick")
+molviewer.view3d("CC(=O)Oc1ccccc1C(=O)O", style="ball_and_stick", spin=True)
+
+# 3D viewing — Speck (ambient occlusion)
+molviewer.view3d("CC(=O)Oc1ccccc1C(=O)O", style="speck")
+molviewer.view3d("CC(=O)Oc1ccccc1C(=O)O", style="speck", preset="houkmol")
+molviewer.view3d("CC(=O)Oc1ccccc1C(=O)O", style="speck", preset="toon")
+molviewer.view3d("CC(=O)Oc1ccccc1C(=O)O", style="speck", preset="licorice")
+```
+
+## Speck Presets
+
+| Preset | Description |
+|--------|-------------|
+| `ball_and_stick` | Default — atoms + bonds with ambient occlusion |
+| `toon` | Flat shading with depth-aware outlines |
+| `licorice` | Thick bonds, small atoms |
+| `houkmol` | Houk group style — matte, outlines, bright atoms |
+| `metal` | Metallic material (ipyspeck) |
+| `glass` | Transparent glass (ipyspeck) |
+| `glossy` | Shiny surface (ipyspeck) |
+| `goodsell` | David Goodsell style (ipyspeck) |
+
+## Custom Parameters
+
+```python
+molviewer.view3d("CCO", style="speck", atom_scale=0.6, ao=0.9, outline=1.0)
+```
+
+Parameters: `atom_scale`, `bond_scale`, `ao`, `brightness`, `outline`, `bonds`.
+
+## Attribution Maps
+
+```python
+import molfp
+import molviewer
+
+result = molfp.interpret(smiles, activities, fp_type="maccs")
+molviewer.draw_attribution("CC(=O)Oc1ccccc1C(=O)O", result, style="highlight", save="attr.png")
+molviewer.draw_attribution("CC(=O)Oc1ccccc1C(=O)O", result, style="contour", save="attr.png")
+```
+
+## License
+
+MIT

molviewer-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+molviewer/__init__.py,sha256=uBGS6VbzptfTKb4EpUm_gQB_Y3hKfly-9YyKlA_o_uY,288
+molviewer/_mol.py,sha256=-m4-43T8EmoroyY8GmwygVfPWmOgs1PqZG55crZ-npk,5148
+molviewer/attribution.py,sha256=zWjTes1y40lCWiQsmZoiKtH5bCy8TLT6iyIRz3rq9Yk,8325
+molviewer/draw2d.py,sha256=U2x-4L6lK_JhTZFPry0GgPm2lABGMWOSr2qHjeuarsU,2945
+molviewer/view3d.py,sha256=2iz17y3Y335dQw1LkisO6ph_6PS_S4x2nLrfNoUIyK4,7212
+molviewer-0.1.1.dist-info/licenses/LICENSE,sha256=ZeG6sH00neNTW8T5LmF3zovcUKtvxT0DPnAxr6eaajc,1076
+molviewer-0.1.1.dist-info/METADATA,sha256=MyzN5mnRMvEKWtOjoIBpbqT_TyPqidapIeXpUtvXT2k,3076
+molviewer-0.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+molviewer-0.1.1.dist-info/top_level.txt,sha256=q2i-26f56uC9AYWtrJqrhPbw4FWIOHKZbnMK6-l4vG4,10
+molviewer-0.1.1.dist-info/RECORD,,

molviewer-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

molviewer-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chanin Nantasenamat
+
+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.

molviewer-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+molviewer