Reference navigation

On this page

Camera

A perspective camera with orbit, zoom, framing, depth cueing, and EEVEE lens focus.

from proteinmotion.camera import Camera

Constructor

Camera()

Notes

Each scene creates its own camera at scene.camera. Use frame() for initial setup and Focus or scene.focus() for animated camera movement.

Attributes

Name	Description
`target`	Look-at point in world coordinates.
`distance`	Distance from the camera to its target, initially 70 Å.
`theta, phi`	Horizontal and vertical angles in radians.
`fov`	Vertical field of view in radians; initially 38 degrees.
`depth_cue`	Distance fog strength; 0 disables it.
`radius`	Framing radius used to choose clipping planes.
`dof`	Whether EEVEE depth of field is enabled; initially False.
`fstop`	Lens f-number, initially 5.6. Lower values produce more blur.

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 Scene excerpt

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)

Output Preview · 6.2 s · 60 fps

Camera focus

Ubiquitin residues 23–34.

Full source: RegionFocus Download MP4

Methods and properties

Name	Description
set_focus()method	Set lens focus without moving or zooming the camera.
lens_focus()method	Set lens focus without changing framing.
composition_offset()method	World offset placing the subject at a normalized top-left screen position.
focus_pointproperty	Current lens target in world ångströms, following the selected atoms.
cutaway_geometry()method	Center, kept radius, window radius and outer-surface distance of the open cutaway. The outer distance is measured from the target center along the tunnel axis, to where the tunnel's centerline first reaches open space: atoms of the target's protein within 6 Å of the axis, up to the first gap longer than 8 Å. None when no cutaway is open. The fifth value is that unit axis in world coordinates: toward the eye for a cone, or the tunnel direction.
clearest_view()method	Return (theta, phi) with the fewest atoms between the camera and ``region``. Counts atoms of ``objects`` (default: the region's protein) that project inside the region's silhouette and lie in front of it, from the current distance. Nearby views win ties through ``turn_penalty``, a fractional cost per radian of camera turn. It also decides between views with no atoms in front, so the nearest clear view wins.
frame()method	Frame the supplied proteins or regions immediately and stop previous tracking.
focus()method	Frame a protein or region immediately and optionally track its center.
update_tracking()method	Update the camera target from the tracked region while keeping zoom fixed.
look_along()method	Turn the view to look down an axis, which then points toward the viewer.
orbit()method	Change horizontal and vertical camera angles.
zoom()method	Divide camera distance by factor. Values greater than 1 zoom in.
eyeproperty	Current camera position in world coordinates.
matrix()method	Compute the view-projection matrix for the given image aspect ratio.
animateproperty	Create a builder for orbit, zoom, and focus animations.
snapshot()method	Capture the current state for deterministic timeline evaluation.
restore()method	Restore a state produced by snapshot().

set_focus()

View source

Camera.set_focus(
    target,
    *,
    chain=None,
    residues=None,
    atoms=None,
    fstop=5.6,
    follow=True,
)

Set lens focus without moving or zooming the camera.

Parameter	Default	Description
`target`	Required	Protein, Region, world point, or None to disable DOF.
`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	`5.6`	Lens f-number. Lower values produce a shallower depth of field. Must be positive.
`follow`keyword only	`True`	Track the mean selected position through motion; False fixes the initial world point.

Returns: The camera.

Selectors apply to a Protein target. Ranges use inclusive PDB author numbers. atoms="CA" focuses on the Cα centroid. A region defines one focus plane, rather than making all selected atoms equally sharp.

lens_focus()

View source

Camera.lens_focus(target, *, fstop=5.6, follow=True)

Set lens focus without changing framing.

Parameter	Default	Description
`target`	Required	Object to animate or use as a destination. The supported object type depends on the operation.
`fstop`keyword only	`5.6`	Lens f-number. Lower values produce a shallower depth of field. Must be positive.
`follow`keyword only	`True`	Track the selection’s center after the focus completes.

composition_offset()

View source

Camera.composition_offset(screen_position=None, *, distance=None, aspect=None)

World offset placing the subject at a normalized top-left screen position.

Parameter	Default	Description
`screen_position`	`None`	Normalized subject position; (0, 0) is top-left and (1, 1) bottom-right.
`distance`keyword only	`None`	Distance in ångströms.
`aspect`keyword only	`None`	Image width divided by height.

focus_point

View source

Camera.focus_point

Current lens target in world ångströms, following the selected atoms.

cutaway_geometry()

View source

Camera.cutaway_geometry()

Center, kept radius, window radius and outer-surface distance of the open cutaway. The outer distance is measured from the target center along the tunnel axis, to where the tunnel's centerline first reaches open space: atoms of the target's protein within 6 Å of the axis, up to the first gap longer than 8 Å. None when no cutaway is open. The fifth value is that unit axis in world coordinates: toward the eye for a cone, or the tunnel direction.

clearest_view()

View source

Camera.clearest_view(region, *objects, samples=160, max_elevation=1.1, turn_penalty=0.15)

Return (theta, phi) with the fewest atoms between the camera and ``region``. Counts atoms of ``objects`` (default: the region's protein) that project inside the region's silhouette and lie in front of it, from the current distance. Nearby views win ties through ``turn_penalty``, a fractional cost per radian of camera turn. It also decides between views with no atoms in front, so the nearest clear view wins.

Parameter	Default	Description
`region`	Required	Region selection attached to a protein.
`*objects`	—	Proteins whose atoms can block the view; defaults to the region's protein.
`samples`keyword only	`160`	Samples per density-slice axis; preferred over legacy resolution.
`max_elevation`keyword only	`1.1`	Largest camera elevation to consider, in radians.
`turn_penalty`keyword only	`0.15`	Fractional cost per radian of camera turn, which favors nearby views.

frame()

View source

Camera.frame(*proteins, margin=1.25, aspect=None, screen_position=(0.5, 0.5))

Frame the supplied proteins or regions immediately and stop previous tracking.

Parameter	Default	Description
`*proteins`	—	Protein or annotation objects to add or render.
`margin`keyword only	`1.25`	Positive framing margin; larger values leave more space around the target.
`aspect`keyword only	`None`	Image width divided by height.
`screen_position`keyword only	`(0.5, 0.5)`	Normalized subject position; (0, 0) is top-left and (1, 1) bottom-right.

Returns: The camera.

focus()

View source

Camera.focus(
    target,
    *,
    margin=1.25,
    aspect=None,
    follow=True,
    screen_position=(0.5, 0.5),
)

Frame a protein or region immediately and optionally track its center.

Parameter	Default	Description
`target`	Required	Object to animate or use as a destination. The supported object type depends on the operation.
`margin`keyword only	`1.25`	Positive framing margin; larger values leave more space around the target.
`aspect`keyword only	`None`	Image width divided by height.
`follow`keyword only	`True`	Track the selection’s center after the focus completes.
`screen_position`keyword only	`(0.5, 0.5)`	Normalized subject position; (0, 0) is top-left and (1, 1) bottom-right.

Returns: The camera.

update_tracking()

View source

Camera.update_tracking()

Update the camera target from the tracked region while keeping zoom fixed.

Returns: None

look_along()

View source

Camera.look_along(axis, protein=None)

Turn the view to look down an axis, which then points toward the viewer.

Parameter	Default	Description
`axis`	Required	Direction in world coordinates, or in the protein's model frame when protein is given.
`protein`	`None`	Protein whose orientation converts a model-frame axis, such as a DomainMotion axis.