Molecular Visualization#

The boltz_data.draw module creates 2D and 3D visualizations of molecular structures, exported as SVG files.

3D Ball-and-Stick Models#

../_images/63e3e3af1edb62855bee06b2748ac5d808becaa97e31c27caadc432350833ff3.svg — Ball-and-stick visualization of caffeine#

Multiple Molecules#

../_images/095d874f4c5efdab18f027ed20440c875bd01fad6b694d8fbff4138f6b756e7b.svg — Comparison of ethanol and methanol structures#

2D Structural Diagrams#

from boltz_data.draw import draw_rdmol
from boltz_data.mol import bzmol_from_smiles, rdmol_from_bzmol

# Create molecule
mol = bzmol_from_smiles("CC(=O)O")  # Acetic acid

# Convert to RDKit for 2D drawing
rdmol = rdmol_from_bzmol(mol)

# Draw as SVG
svg = draw_rdmol(rdmol)

# Save to file
with open("molecule.svg", "w") as f:
    f.write(svg)

BZMol Visualization#

from boltz_data.mol import bzmol_from_smiles, bzmol_to_svg, save_bzmol_svg

mol = bzmol_from_smiles("c1ccccc1")  # Benzene

# Generate SVG string
svg = bzmol_to_svg(mol)

# Or save directly to file
save_bzmol_svg(mol, "benzene.svg")

Primitives#

The 3D rendering uses geometric primitives (Sphere, Cylinder, LineSegment, Text):

from boltz_data.draw.mol3d import draw_3d_svg
from boltz_data.draw.mol3d._primitive import Sphere, Cylinder
import numpy as np

# Create custom primitives
primitives = [
    # Atom at origin (red sphere)
    Sphere(center=np.array([0.0, 0.0, 0.0]), radius=0.5, color="#FF0000"),

    # Atom at (1.5, 0, 0) (blue sphere)
    Sphere(center=np.array([1.5, 0.0, 0.0]), radius=0.5, color="#0000FF"),

    # Bond connecting them (gray cylinder)
    Cylinder(
        start=np.array([0.0, 0.0, 0.0]),
        end=np.array([1.5, 0.0, 0.0]),
        radius=0.1,
        color="#888888"
    ),
]

# Render
svg = draw_3d_svg(*primitives)

Colors#

Default CPK coloring: C (gray), H (white), N (blue), O (red), S (yellow), P (orange).

Custom colors:

from boltz_data.draw.mol3d._primitive import Sphere
import numpy as np

# Create atoms with custom colors
custom_primitives = [
    Sphere(
        center=np.array([0.0, 0.0, 0.0]),
        radius=0.6,
        color="#FF1493"  # Hot pink
    ),
    Sphere(
        center=np.array([1.5, 0.0, 0.0]),
        radius=0.6,
        color="#00CED1"  # Dark turquoise
    ),
]

Grid Layout#

from boltz_data.draw.mol3d import grid, ball_and_stick, draw_3d_svg
from boltz_data.mol import bzmol_from_smiles, generate_depiction

# Create multiple molecules
molecules = [
    generate_depiction(bzmol_from_smiles(smiles))
    for smiles in ["CCO", "CC", "C", "CO"]
]

# Create ball-and-stick for each
mol_primitives = [ball_and_stick(mol) for mol in molecules]

# Arrange in grid
primitives = grid(*mol_primitives)

# Render
svg = draw_3d_svg(*primitives, padding=5)

Rendering Options#

Control padding around molecules:

svg = draw_3d_svg(*primitives, padding=0)  # Tight
svg = draw_3d_svg(*primitives, padding=10)  # More space

Depth shading is applied automatically.

Common Workflows#

CCD Components#

from boltz_data.ccd import CCD_REMOTE
from boltz_data.mol import bzmol_from_chemical_component, generate_depiction
from boltz_data.draw.mol3d import ball_and_stick, draw_3d_svg

# Load and visualize
component = CCD_REMOTE["HEM"]  # Heme
mol = bzmol_from_chemical_component(component)
mol = generate_depiction(mol)

primitives = ball_and_stick(mol)
svg = draw_3d_svg(*primitives)

with open("heme.svg", "w") as f:
    f.write(svg)

Protein Structures#

from boltz_data.mol import bzmol_from_mmcif, subset_bzmol
from boltz_data.draw.mol3d import ball_and_stick, draw_3d_svg
import numpy as np

# Load structure
bzmol = bzmol_from_mmcif("protein.cif")

# Extract just the CA atoms (backbone trace)
ca_mask = bzmol.atom_name == "CA"
ca_only = subset_bzmol(bzmol, ca_mask)

# Visualize
primitives = ball_and_stick(ca_only)
svg = draw_3d_svg(*primitives)

Comparing Molecules#

from boltz_data.mol import bzmol_from_smiles, generate_depiction
from boltz_data.draw.mol3d import ball_and_stick, grid, draw_3d_svg

# Create a series of related molecules
alcohols = ["CO", "CCO", "CCCO", "CCCCO"]
molecules = [generate_depiction(bzmol_from_smiles(s)) for s in alcohols]

# Visualize in a grid
primitives = grid(*[ball_and_stick(m) for m in molecules])
svg = draw_3d_svg(*primitives)

Tips#

Generate coordinates before visualizing:

mol = generate_depiction(bzmol_from_smiles("CCO"))

For large structures, subset to heavy atoms:

mol_no_h = subset_bzmol(mol, mol.atom_element > 1)

Jupyter Integration#

from IPython.display import SVG, display
display(SVG(draw_3d_svg(*primitives)))

API Reference#

For detailed API documentation, see:

Molecular Visualization

Contents