FocusPull

Animate lens focus to a protein, residue selection or world point.

View source Guide and examplesInherits Animation

from proteinmotion import FocusPull

Constructor

FocusPull(
    camera,
    target,
    *,
    chain=None,
    residues=None,
    atoms=None,
    fstop=None,
    follow=True,
    **kwargs,
)

Parameters

Parameter	Default	Description
`camera`	Required	Camera used to project or frame objects.
`target`	Required	Protein, Region, or three world coordinates in ångströms.
`chain`keyword only	`None`	Author chain ID or a collection of IDs; None selects all chains.
`residues`keyword only	`None`	Author residue number, inclusive (first, last) tuple, or list of individual numbers.
`atoms`keyword only	`None`	Atom name or list of names, such as "CA"; None selects all atom names.
`fstop`keyword only	`None`	Destination f-number, or None to keep the current aperture.
`follow`keyword only	`True`	Follow the selected atoms through motion. False fixes the destination at the start of the clip.
`**kwargs`	—	Additional keyword options described below or in the linked constructor.

Additional keyword arguments

Parameter	Default	Description
`rate_func`keyword only	`smooth`	Callable that maps progress in [0, 1] to a finite value in [0, 1].

Notes

Uses an independent lens animation channel, so it can run with camera orbit or zoom. Requires the EEVEE renderer to show depth of field.

Example and output

This excerpt runs inside a scene’s construct() method. The full example file includes imports, structure loading, and camera setup. Run it from a repository checkout.

Code Full script

"""Calmodulin 1CLL: select a helix, fade its context, then pull lens focus.

Render with:
    proteinmotion render examples/eevee_focus.py HelixFocus --renderer eevee \
        --width 960 --height 540 --fps 60 -o helix-focus.mp4

Requires Blender 4.5+. The camera motion illustrates the deposited structure.
"""

from pathlib import Path

from proteinmotion import FocusPull, Protein, ProteinScene, SetOpacity, Text, Write

DATA = Path(__file__).resolve().parent / "data"


class HelixFocus(ProteinScene):
    def construct(self):
        protein = Protein.from_file(DATA / "1cll.cif", chains="A").cartoon(color="#7299b4").center()
        protein.rotate(0.9, axis=(0, 0, 1))
        helix = protein.select(chain="A", residues=(5, 19))
        helix.set_color("#ffb34c")
        # The context selection includes every atom outside the highlighted helix.
        context = protein.select(chain="A", residues=[4, *range(20, 149)])
        far_region = protein.select(chain="A", residues=(82, 92), atoms="CA")
        self.add(protein)
        self.camera.frame(protein, aspect=self.width / self.height).zoom(1.5)
        self.camera.set_focus(protein, chain="A", residues=(5, 19), atoms="CA", fstop=4)
        self.add(Text("Calmodulin · 1CLL", position=(0.055, 0.9), font_size=30))
        label = helix.callout(
            "Alpha helix",
            subtitle="Chain A · residues 5–19",
            position=(0.68, 0.13),
            color="#ffb34c",
            font_size=38,
        )
        self.play(Write(label), run_time=0.8)
        self.play(SetOpacity(context, 0.06), run_time=1)
        self.play(self.camera.animate.orbit(theta=0.28), run_time=2)
        self.wait(0.4)
        self.play(FocusPull(self.camera, far_region, fstop=2.8), SetOpacity(context, 0.35), run_time=1.4)
        self.wait(0.4)
        self.play(FocusPull(self.camera, helix, fstop=4), SetOpacity(context, 0.06), run_time=1.2)
        self.wait(0.8)

Output Preview · 8.0 s · 60 fps

EEVEE lens focus

Calmodulin: highlight residues 5–19, fade the surrounding cartoon, and change lens focus.

Full source: HelixFocus Download MP4

Methods and properties

Name	Description
bind()method	Capture starting values when the scene schedules the animation.
apply()method	Evaluate the animation at eased progress alpha. Called by the timeline.
targetsproperty · inherited from Animation	Objects whose state this animation changes.