You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit cd57cff
Browse filesBrowse the repository at this point in the historyBrowse files
Passing no path returns the PNG bytes instead, which suits writing to a stream:
20
+
Leave out the file name and you get the image data back instead, which is handy
21
+
for writing it somewhere else:
20
22
21
23
```python
22
24
png = mol.render(size=(800, 600))
23
25
```
24
26
25
-
## Parameters
27
+
## Options
26
28
27
-
|Parameter|Meaning|
29
+
|Option|What it does|
28
30
| --- | --- |
29
-
|`output`| Path to write. Omit to get the PNG bytes back. |
30
-
|`size`|`(width, height)` in pixels. |
31
-
|`quality`|`"fast"` or `"high"`. `"high"` adds ambient occlusion, which is close to free on a GPU and costs roughly three times the time on the software fallback. |
32
-
|`center`| Atom selection to frame the camera on. |
33
-
|`rotate`|`"front"`, `"back"`, `"left"`, `"right"`, `"top"`, `"bottom"`, or `(rx, ry, rz)` in degrees. |
34
-
|`zoom`| Larger values move the camera closer. |
35
-
|`clip`| Half-thickness in Angstrom of the slab drawn around what the camera frames, cutting away what is in front of and behind it. Omit to draw the whole structure. |
36
-
|`fog`| Depth cueing strength, `0` to `100`. Fog fades distant geometry into the background colour. Omit for Mol\*'s own strength. |
37
-
|`background`| Colour name or hex string. Ignored when `transparent=True`. |
38
-
|`transparent`| Render onto a transparent background, ignoring `background`. |
39
-
|`timeout`| Seconds allowed for one render. |
31
+
|`output`| File to write. Leave it out to get the image data back. |
32
+
|`size`| Width and height of the image in pixels. |
33
+
|`quality`|`"fast"` or `"high"`. `"high"` adds soft shading in the crevices and smoother edges, and takes noticeably longer without a graphics card. |
34
+
|`center`| Atom selection to point the camera at, such as `"resname BEN"`. |
35
+
|`rotate`|`"front"`, `"back"`, `"left"`, `"right"`, `"top"`, `"bottom"`, or your own `(x, y, z)` rotation in degrees. |
36
+
|`zoom`| How close the camera sits. Larger is closer. |
37
+
|`clip`| Show only a slab this many Angstrom thick around what the camera is pointed at, cutting away what is in front and behind. Leave it out to show the whole structure. |
38
+
|`fog`| How much distant parts fade into the background, from `0` for none to `100` for the most. |
39
+
|`background`| Background colour, by name or as `#rrggbb`. |
40
+
|`transparent`| Give the image a transparent background instead of a colour. |
41
+
|`timeout`| How many seconds to allow for one image before giving up. |
42
+
43
+
## Choosing what is drawn
44
+
45
+
Representations come from `mol.reps`, exactly as for
46
+
{py:meth}`~moleculekit.molecule.Molecule.view`, so a molecule renders the way
47
+
you would see it on screen. Leave `mol.reps` empty and you get a sensible
48
+
default picture: a cartoon for the protein or nucleic acid, with ligands, ions
49
+
and waters drawn as ball-and-stick.
50
+
51
+
Adding a representation replaces that default picture rather than adding to it,
52
+
so if you only want to change one thing, start from the default with
53
+
{py:meth}`~moleculekit.representations.Representations.addDefaults` and edit
54
+
it:
40
55
41
-
## Requirements
42
-
43
-
Rendering needs a chromium binary and the optional `molviewspec` dependency:
44
-
45
-
```
46
-
pip install moleculekit[notebook]
56
+
```python
57
+
mol.reps.addDefaults()
58
+
mol.reps.remove(1) # drop the waters, ligand and ions
59
+
mol.reps.add("resname BEN", "VDW", "Name")
47
60
```
48
61
49
-
moleculekit looks for `chromium`, `chromium-browser`, `google-chrome` or
50
-
`chrome` on your PATH. To use a specific binary, set `MOLECULEKIT_CHROMIUM` to
51
-
its path. No network connection is needed: the Mol* bundle ships with
52
-
moleculekit and the structure never leaves the machine.
53
-
54
-
## Choosing the graphics backend
62
+
See [Choose representations and colours](choose-representations.md) for the
63
+
available styles, colours, sizes and transparency.
55
64
56
-
Rendering uses your GPU when one is reachable and falls back to a software
57
-
rasteriser when it is not, which is what makes it work unchanged inside
58
-
containers that expose no graphics device. The difference is large: a 1200x900
59
-
render measured 0.5 seconds on a GPU against 6.9 seconds in software.
65
+
## Requirements
60
66
61
-
The choice is automatic. To pin it, set `MOLECULEKIT_RENDER_GL`:
67
+
Rendering uses the Chromium browser behind the scenes, so it needs Chromium
68
+
(or Chrome) installed, plus one optional package:
62
69
63
70
```
64
-
MOLECULEKIT_RENDER_GL=hardware # require the GPU, fail if it is unavailable
65
-
MOLECULEKIT_RENDER_GL=software # always use the software rasteriser
66
-
MOLECULEKIT_RENDER_GL=auto # the default
71
+
pip install moleculekit[notebook]
67
72
```
68
73
69
-
Forcing `hardware` is useful when a render unexpectedly falls back and you want
70
-
the failure to be loud rather than slow. Forcing `software` is useful for
71
-
reproducing what a GPU-less machine will produce.
72
-
73
-
## Gotchas
74
-
75
-
-**Representations come from `mol.reps`**, the same ones {py:meth}`~moleculekit.molecule.Molecule.view` uses, and
76
-
they replace the automatic scene rather than adding to it. Setting any
77
-
representation means you are describing the whole picture, which matches how
78
-
the VMD backend behaves. Leave `mol.reps` empty to get the automatic scene of
79
-
a cartoon polymer with ball-and-stick ligands, or call {py:meth}`~moleculekit.representations.Representations.addDefaults` to start
80
-
from it and edit. See
81
-
[Choose representations and colours](choose-representations.md) for the
82
-
styles, colour modes, size and transparency.
83
-
-**A representation whose selection matches no atoms is dropped with a
84
-
warning.** If every representation matches nothing, `render()` raises rather
85
-
than writing an empty image.
86
-
-**A representation's `frames` argument is ignored.** {py:meth}`~moleculekit.representations.Representations.add`'s `frames`
87
-
selects frames for the interactive viewer's trajectory playback; a render is a
88
-
single still, so `frames` has nothing to act on.
89
-
-**The frame rendered is `mol.frame`.** For a trajectory, set `mol.frame = n`
90
-
first. `render()` produces a single still, not a movie.
91
-
-**`center` must match at least one atom.** A selection that matches nothing
92
-
raises `ValueError`, rather than silently falling back to the default view.
93
-
-**`center` is also what `rotate` orbits and what `zoom` scales.** Framing a
94
-
ligand and stepping `rotate` through angles gives a turntable around it.
95
-
-**The framing follows the requested `size`.** A wider image shows more around
96
-
the structure rather than the same picture stretched.
97
-
-**The first call is slower** because it starts the browser. Later calls reuse
98
-
it, so rendering many images in one process costs the startup once.
99
-
-**Speed depends on whether a GPU is available.** With one, a 1200x900 render
100
-
takes well under a second. Without one, rendering falls back to a software
101
-
rasteriser that fills every pixel on the CPU, which costs several seconds and
102
-
scales with pixel count, so a 4K image costs roughly four times a 1080p one.
103
-
See "Choosing the graphics backend" below.
104
-
-**Call {py:meth}`~moleculekit.molecule.Molecule.render` from one thread at a time.** The headless browser is a
105
-
singleton with a single devtools connection, so concurrent calls from
106
-
different threads (a multi-threaded service handling several requests at
107
-
once, for example) can read each other's responses. Serialise calls to
108
-
`render()`, for example behind a lock, if more than one thread might call it.
74
+
moleculekit finds `chromium`, `chromium-browser`, `google-chrome` or `chrome`
75
+
on your PATH by itself. To point it at a particular one, set the
76
+
`MOLECULEKIT_CHROMIUM` environment variable to that program's location.
77
+
78
+
Nothing is uploaded anywhere: no internet connection is needed and your
79
+
structure never leaves your machine.
80
+
81
+
## If rendering feels slow
82
+
83
+
With a graphics card, an image takes well under a second. Without one the work
84
+
falls to the processor and takes a few seconds, or longer on a machine with few
85
+
cores, which is common inside containers and on cloud notebooks.
86
+
87
+
Three things help, in order of effect:
88
+
89
+
-**Ask for a smaller image.** The time scales with the number of pixels, so
90
+
halving the width and height makes it roughly four times faster.
91
+
-**Use `quality="fast"`**, which is the default. `"high"` is worth it for a
92
+
final figure and wasteful for a quick look.
93
+
-**Render several images in one script.** The first one is slower because the
94
+
browser has to start; every image after that reuses it.
95
+
96
+
## Good to know
97
+
98
+
-**The picture shows the current frame**, `mol.frame`. For a trajectory, set
99
+
`mol.frame = n` first and render again for another frame. Each call makes one
100
+
still image, not a movie.
101
+
-**`center` is also what `rotate` turns around and what `zoom` scales.**
102
+
Pointing at a ligand and stepping `rotate` through several angles gives you a
0 commit comments