Regions & focus

The rendered excerpts use docs_examples.py. Its ubiquitin() helper loads PDB 1UBQ, and frame() adds the model and sets the camera. Run each excerpt inside construct(); the full script includes the imports and setup. Run the full script from a repository checkout, which includes the input structures.

Select a region once, then reuse it for camera focus, annotations, or alignment:

p = ubiquitin()
frame(self, p)
helix = p.select(chain="A", residues=(23, 34))
marker = helix.highlight(
    style="box",
    color="#f2ba67",
    padding=1.5,
)
self.play(FadeIn(marker), run_time=0.6)
self.focus(helix, margin=1.6, run_time=1.5)
self.play(self.camera.animate.orbit(0.4), run_time=2)
self.play(FadeOut(marker), run_time=0.6)
self.focus(p, run_time=1.5)

Selections use PDB author residue numbers. A tuple (23, 34) selects the inclusive range; a list [8, 44, 70] selects those three residues. residues=23 selects one residue.

Use atoms="CA" or atoms=["N", "CA", "C", "O"] to filter by atom name. chain accepts one chain ID or a list. All supplied filters must match. An empty selection raises an error.

Combine selections from the same protein with region_a | region_b. Residues that share an author number but have different insertion codes are selected together. For exact atom selection, use Region(p, atom_indices).

Three highlight styles are available:

p = ubiquitin()
frame(self, p)
helix = p.select(residues=(23, 34))
for style in ("sphere", "box", "atoms"):
    marker = helix.highlight(
        style=style,
        color="#f2ba67",
        padding=1.0,
        opacity=0.3,
    )
    self.play(FadeIn(marker), run_time=0.6)
    self.wait(1.2)
    self.play(FadeOut(marker), run_time=0.6)

All highlight styles accept color="#RRGGBB". Padding and line width are in ångströms. Highlights are 3D shapes that move with the selected region. Nearby atoms can hide parts of them.

The highlight resizes as the region changes shape. Animate its opacity with FadeIn, FadeOut, or .animate.set_opacity(...). Its position follows the parent protein; its opacity is independent. Highlight geometry updates on the CPU, and coordinate interpolation runs on the GPU.

self.focus(region, ...) moves the camera to a region with easing and uses the scene’s aspect ratio. By default, the camera then follows the region’s center at a fixed zoom. Increase margin for a region that expands during playback. Use follow=False to keep the camera at the position fitted when the animation starts.

For immediate placement, use self.camera.focus(region, aspect=self.width/self.height). Use self.camera.frame(p, ...) to fit the whole protein and stop region tracking.

For concurrent focus, playback, or fades, use Focus explicitly:

self.play(
    Focus(self.camera, helix, margin=1.6, aspect=self.width / self.height),
    PlayTrajectory(p, start=0, end=20, state_easing=smooth),
    run_time=4,
)

Focus updates after molecular motion in the same play() call and preserves the camera angles and field of view. self.camera.animate.focus(region, ...) is also available. Put camera focus and orbit or zoom in separate calls because each changes the camera state.

Text labels and callouts#

Use region.callout("α helix") to place a label with a line to a selected region. Use region.label() for one amino acid, or protein.label_residues(residues=[8, 44, 70]) for several names. Write and Unwrite animate these labels. See text and labels.

Lens focus with EEVEE#

Set depth of field independently of camera position and zoom:

self.camera.set_focus(protein, chain="A", residues=5)
self.camera.set_focus(protein, chain="A", residues=(10, 20), atoms="CA", fstop=4)

These calls focus on the mean position of the selected atoms. follow=True keeps focus on that region through motion and deformation. Use follow=False to keep the initial world point fixed. A range sets one focus plane through its center; residues far from that plane can still blur.

See EEVEE and lens focus for animated focus pulls and rendered output.