moleculekit.viewer.molstar.render module#

Headless Mol* rendering: turn a Molecule into a PNG with no display.

A singleton chromium is started on first use and reused, driven over the devtools protocol (see cdp.py). The scene comes from build_scene (see scene.py), the same description the interactive viewer builds from, and the browser applies it with applyScene (see viewer-frontend/src/scene.ts) so a render matches what view() shows. This path never imports molviewspec.

Rendering runs on the GPU when one is reachable and falls back to a software rasteriser when it is not, which is what lets the same code work inside containers that expose no graphics device. MOLECULEKIT_RENDER_GL pins the choice. The fallback is not free: a 1200x900 “fast” render measured 0.16s on a GPU against 1.2s on a 20-core software rasteriser, and software time scales with pixels and with how many cores it has.

This module is not thread-safe: the singleton browser’s devtools session has one socket and one frame reader, so concurrent render() calls from different threads can consume each other’s responses. Call render() from one thread at a time.

moleculekit.viewer.molstar.render.find_chromium()#

Locate a chromium or chrome binary to render with.

Resolution order is the MOLECULEKIT_CHROMIUM environment variable, then chromium, chromium-browser, google-chrome and chrome on PATH.

Returns:

path – Path to the browser executable.

Return type:

str

Raises:

RuntimeError – If no usable browser is found.

moleculekit.viewer.molstar.render.render(mol, output=None, *, size=(1200, 900), quality='fast', center=None, rotate=None, zoom=None, background='white', transparent=False, fog=None, clip=None, server=None, timeout=300.0)#

Render mol to a PNG with no display and no browser window.

The scene is the one view() would show: representations come from mol.reps, and the frame rendered is mol.frame.

Parameters:

  • mol (moleculekit.molecule.Molecule or Volume or list) – The object to render, or several to draw together in one picture. Each keeps its own representations, so objects loaded separately stay separate. A moleculekit.volume.Volume draws its isosurfaces alongside the molecules; at least one molecule is needed, since a volume has no atoms for the camera to frame.

  • output (str | None) – Path to write the PNG to. When None the PNG bytes are returned.

  • size (tuple[int, int]) – Image width and height in pixels.

  • quality (str) – One of the keys of QUALITY_PRESETS. "high" enables ambient occlusion, which is close to free on a GPU and costs roughly three times the render time on the software fallback.

  • center (str | ndarray | None) – Atom selection to frame the camera on. None frames the whole structure.

  • rotate (str or tuple of float or None, optional) – Camera orientation, as a preset name or (rx, ry, rz) in degrees.

  • zoom (float | None) – Camera tightness. Larger values move the camera closer.

  • background (str) – Background colour as an SVG colour name or hex string.

  • transparent (bool) – Render onto a transparent background, ignoring background.

  • fog (float | None) – Depth cueing strength, from 0 for none to 100 for the strongest. Fog fades distant geometry into the background colour, which reads as depth on a crowded structure. None uses Mol*’s own strength.

  • clip (float | None) – Half-thickness in Angstrom of the slab drawn around what the camera frames: geometry nearer to or further from the camera than this is cut away, which is how you see into a buried pocket. None draws the whole structure.

  • server (str | None) – Base URL of a render server, such as "http://gpuhost:8080", to draw the image on instead of starting a browser here. None falls back to the MOLECULEKIT_RENDER_SERVER environment variable, and then to rendering locally.

  • timeout (float) – Seconds to allow for a single render before giving up.

Returns:

result – The PNG bytes when output is None, otherwise output.

Return type:

bytes | str

Raises:

  • ValueError – If quality names no known preset, if size is not at least one pixel in each dimension, if center matches no atoms, if zoom is not positive, if rotate is a string that names no known orientation preset, if fog falls outside 0 to 100, or if clip is not positive.

  • RuntimeError – If no browser is found, if WebGL is unavailable, if the page fails, or if the rendered image does not match the requested size.

moleculekit.viewer.molstar.render.render_png(payload, *, width, height, quality='fast', transparent=False, timeout=300.0)#

Draw one already-built scene in the local browser.

This is the half of render() that needs a browser. Everything above it, turning a Molecule into a structure and a scene description, is plain Python, which is what lets a render run on another machine: the render server (see renderserver.py) calls this with what a client sent it.

Parameters:

  • payload (dict) – What to draw: structure and scene for one object, or objects and globals for several drawn together.

  • width (int) – Image width in pixels.

  • height (int) – Image height in pixels.

  • quality (str) – One of the keys of QUALITY_PRESETS.

  • transparent (bool) – Render onto a transparent background.

  • timeout (float) – Seconds to allow before giving up.

Returns:

png – The rendered image.

Return type:

bytes

Raises:

RuntimeError – If the rendered image does not match the requested size.

moleculekit.viewer.molstar.render.shutdown_for_tests()#

Stop the singleton browser if one is running.

Return type:

None