C3D Module

Interactive 3D molecule viewer for Jupyter and Marimo notebooks.

C3D Class

class cnotebook.c3d.C3D(width=800, height=None, theme='auto')[source]

Bases: object

Interactive 3D molecule viewer for Jupyter and Marimo notebooks.

Provides a builder-style API for constructing a self-contained 3Dmol.js viewer that can be displayed inline in notebook cells.

Example:

from openeye import oechem
from cnotebook.c3d import C3D

mol = oechem.OEMol()
oechem.OESmilesToMol(mol, "c1ccccc1")

viewer = (
    C3D(width=800, height=600)
    .add_molecule(mol, name="benzene")
    .add_style({"chain": "A"}, "cartoon")
    .set_background("#ffffff")
)
viewer.display()
Parameters:

  • width (int)

  • height (int | None)

  • theme (str)

__init__(width=800, height=None, theme='auto')[source]

Create a new C3D viewer instance.

Parameters:

  • width (int) – Viewer width in pixels.

  • height (int | None) – Viewer height in pixels. When None (the default), the height is chosen automatically: 300 px if the largest molecule has at most 1 000 atoms, otherwise 600 px.

  • theme (str) – Color theme. "auto" detects from the host environment, "dark" or "light" sets explicitly.

add_molecule(mol, name=None, disabled=False)[source]

Add an OpenEye molecule to the viewer.

The molecule is converted to SDF format via convert_molecule(). If the molecule lacks 3D coordinates, conformer generation is attempted automatically.

Parameters:

  • mol (Any) – OpenEye molecule (OEMolBase subclass).

  • name (str | None) – Optional display name for the molecule.

  • disabled (bool) – If True, the molecule is hidden when the viewer starts. It can be made visible later via the sidebar.

Returns:

Self, for method chaining.

Raises:

TypeError – If mol is not an OEMolBase.

Return type:

C3D

add_design_unit(du, name=None, disabled=False)[source]

Add an OpenEye design unit to the viewer.

The design unit is converted to PDB format via convert_design_unit().

Parameters:

  • du (Any) – OpenEye design unit (OEDesignUnit).

  • name (str | None) – Optional display name for the design unit.

  • disabled (bool) – If True, the design unit is hidden when the viewer starts. It can be made visible later via the sidebar.

Returns:

Self, for method chaining.

Raises:

TypeError – If du is not an OEDesignUnit.

Return type:

C3D

add_molecules(mols, prefix=None, enable='first')[source]

Add multiple OpenEye molecules to the viewer.

Parameters:

  • mols (Iterable) – Iterable of OpenEye molecules (OEMolBase subclasses).

  • prefix (str | None) – Optional prefix prepended to each entry’s name via f"{prefix}{base_name}".

  • enable (str | Sequence[bool]) – Controls which entries are visible on load. "all" enables all, "first" enables only the first (default), or a Sequence[bool] where True means enabled. If the sequence is shorter than mols, remaining entries are disabled.

Returns:

Self, for method chaining.

Raises:

  • ValueError – If enable is an unrecognized string.

  • TypeError – If enable is not a string or Sequence.

Return type:

C3D

add_design_units(dus, prefix=None, enable='first')[source]

Add multiple OpenEye design units to the viewer.

Parameters:

  • dus (Iterable) – Iterable of OpenEye design units (OEDesignUnit).

  • prefix (str | None) – Optional prefix prepended to each entry’s name via f"{prefix}{base_name}".

  • enable (str | Sequence[bool]) – Controls which entries are visible on load. "all" enables all, "first" enables only the first (default), or a Sequence[bool] where True means enabled. If the sequence is shorter than dus, remaining entries are disabled.

Returns:

Self, for method chaining.

Raises:

  • ValueError – If enable is an unrecognized string.

  • TypeError – If enable is not a string or Sequence.

Return type:

C3D

add_style(style, selection=None, color=None)[source]

Add a visual style to apply to selected atoms.

Parameters:

  • style (str | Dict[str, Any]) – Either a preset name ("cartoon", "stick", "sphere", "line", "cross", "surface") or a raw 3Dmol.js style dict that is passed through verbatim.

  • selection (str | Dict[str, Any] | None) – Atoms to style. Can be None to style all atoms, a selection expression string (e.g. "chain A", "resn LIG"), an entry name to target a specific molecule, or a raw 3Dmol.js selection dict (e.g. {"chain": "A"}).

  • color (str | None) – Optional color string. When style is a preset name, this is set as the color key in the style spec. Ignored when style is a dict.

Returns:

Self, for method chaining.

Raises:

ValueError – If style is a string that is not a recognized preset name.

Return type:

C3D

Example:

viewer = C3D()
viewer.add_molecule(mol, name="benzene")

# Style everything
viewer.add_style("stick")

# Style by selection expression
viewer.add_style("cartoon", "chain A")

# Style a specific entry
viewer.add_style("sphere", "benzene")

# Style with a 3Dmol.js dict
viewer.add_style("stick", {"chain": "A"}, color="green")
set_color(selection, color, hets=True)[source]

Set the color for atoms matching a selection.

Operations are applied in the order they are called, so colors set after a preset will override the preset’s coloring.

Parameters:

  • selection (str | Dict[str, Any]) – Atoms to color. Can be a selection expression string (e.g. "chain A", "resn LIG"), an entry name to target a specific molecule, or a raw 3Dmol.js selection dict (e.g. {"chain": "A"}).

  • color (str) – CSS color string (e.g. "green", "#00ff00").

  • hets (bool) – If True (default), all atoms in the selection are recolored. If False, only carbon atoms are recolored, preserving element coloring for heteroatoms (N, O, S, etc.).

Returns:

Self, for method chaining.

Return type:

C3D

Example:

viewer = C3D()
viewer.add_molecule(mol, name="protein")
viewer.set_preset("sites")
viewer.set_color("chain A", "blue")
viewer.set_color("resn V4M", "magenta", hets=False)
set_ui(sidebar=True, menubar=True, terminal=True)[source]

Configure which UI panels are visible.

Parameters:

  • sidebar (bool) – Show the sidebar panel.

  • menubar (bool) – Show the menubar panel.

  • terminal (bool) – Show the terminal panel.

Returns:

Self, for method chaining.

Return type:

C3D

set_background(color)[source]

Set the viewer background color.

Parameters:

color (str) – CSS color string (e.g. "#ffffff" or "white").

Returns:

Self, for method chaining.

Return type:

C3D

set_theme(theme='auto')[source]

Set the GUI color theme.

Controls the overall UI appearance (panel backgrounds, text color, borders) and the viewer background color when no explicit background has been set via set_background().

Parameters:

theme (str) – "auto", "light", or "dark".

Returns:

Self, for method chaining.

Raises:

ValueError – If theme is not "auto", "light", or "dark".

Return type:

C3D

zoom_to(selection=None)[source]

Set the zoom target after loading.

Parameters:

selection (str | Dict[str, Any] | None) – Selection to zoom into. Can be a selection expression string (e.g. "resn 502", "chain A"), a raw 3Dmol.js selection dict (e.g. {"chain": "A"}), or None to fit all molecules in view.

Returns:

Self, for method chaining.

Return type:

C3D

orient(selection=True)[source]

Orient the view by aligning principal axes with the screen.

Uses PCA to align the longest molecular dimension horizontally, the second-longest vertically, and the shortest perpendicular to the screen, then zooms to fit. When used, this replaces any zoom_to() setting.

Parameters:

selection (bool | str | Dict[str, Any]) – Atoms to orient on. True orients on all atoms. A string selection expression (e.g. "chain A") or a raw 3Dmol.js selection dict (e.g. {"chain": "A"}) restricts orientation to the matching atoms.

Returns:

Self, for method chaining.

Return type:

C3D

set_preset(name)[source]

Apply a view preset.

Presets are compound styles defined in the 3dmol-js-gui that combine multiple representations into a common visualization. When a preset is set it replaces any styles added via add_style().

Available presets:

  • "simple" – Element-colored cartoon with per-chain carbons and sticks for ligands.

  • "sites" – Like simple, plus stick representation for residues within 5 angstroms of ligands.

  • "ball-and-stick" – Ball-and-stick for ligands only.

Parameters:

name (str) – Preset name (case-insensitive).

Returns:

Self, for method chaining.

Raises:

ValueError – If name is not a recognized preset.

Return type:

C3D

to_html()[source]

Generate a self-contained HTML document for the viewer.

All JavaScript and CSS dependencies are inlined so the document requires no external network requests.

Returns:

Complete HTML document as a string.

Raises:

ValueError – If no molecules have been added.

Return type:

str

display()[source]

Display the viewer in the current notebook environment.

Wraps to_html() in an <iframe> with srcdoc. Automatically detects whether the environment is Marimo or Jupyter and returns the appropriate display object.

Returns:

A displayable object (marimo.Html or a Jupyter-compatible display object with _repr_html_).

Conversion Utilities

Molecule conversion utilities for the C3D 3D viewer.

Converts OpenEye OEMolBase and OEDesignUnit objects into string representations (SDF or PDB) that 3Dmol.js can consume.

class cnotebook.c3d.convert.MoleculeData(name, data, format, source_type, num_atoms=0, disabled=False)[source]

Bases: object

Container for molecule data ready for 3Dmol.js consumption.

Parameters:

  • name (str) – Display name for the molecule.

  • data (str) – String content (SDF or PDB format).

  • format (str) – Format identifier ("sdf" or "pdb").

  • source_type (str) – Origin type ("molecule" or "design_unit").

  • num_atoms (int) – Number of atoms in the molecule.

  • disabled (bool) – If True, the entry is hidden when the viewer starts.

name: str
data: str
format: str
source_type: str
num_atoms: int = 0
disabled: bool = False
__init__(name, data, format, source_type, num_atoms=0, disabled=False)
Parameters:
Return type:

None

cnotebook.c3d.convert.convert_molecule(mol, name=None, disabled=False)[source]

Convert an OpenEye molecule to SDF string data for 3Dmol.js.

If the molecule lacks 3D coordinates, conformer generation is attempted automatically via Omega. A warning is logged when this occurs.

Parameters:

  • mol (OEMolBase) – OpenEye molecule to convert.

  • name (str | None) – Optional display name. Falls back to the molecule title, then to "molecule".

  • disabled (bool)

Returns:

MoleculeData with format="sdf" and source_type="molecule".

Raises:

  • TypeError – If mol is not an oechem.OEMolBase.

  • ValueError – If conformer generation fails.

Return type:

MoleculeData

Example:

from openeye import oechem
mol = oechem.OEMol()
oechem.OESmilesToMol(mol, "c1ccccc1")
data = convert_molecule(mol, name="benzene")
cnotebook.c3d.convert.convert_design_unit(du, name=None, disabled=False)[source]

Convert an OpenEye design unit to PDB string data for 3Dmol.js.

Extracts the full complex (all components) from the design unit and writes it as a PDB string.

Parameters:

  • du (OEDesignUnit) – OpenEye design unit to convert.

  • name (str | None) – Optional display name. Falls back to the design unit title, then to "design_unit".

  • disabled (bool) – bool, if True, the entry will appear as disabled in the entries list.

Returns:

MoleculeData with format="pdb" and source_type="design_unit".

Raises:

TypeError – If du is not an oechem.OEDesignUnit.

Return type:

MoleculeData

Example:

from openeye import oechem
du = oechem.OEDesignUnit()
oechem.OEReadDesignUnit("complex.oedu", du)
data = convert_design_unit(du)