Reference navigation

On this page

CLASS · v0.9.1

ResidueLabels

Label several residues and adjust their positions to reduce overlap.

View source Guide and examplesInherits Annotation

from proteinmotion import ResidueLabels

Constructor

ResidueLabels(region, *, offsets=None, avoid_overlap=True, **kwargs)

Parameters

Parameter	Default	Description
`region`	Required	Region selection attached to a protein.
`offsets`keyword only	`None`	Map residue numbers or (chain, number, insertion_code) keys to label offsets.
`avoid_overlap`keyword only	`True`	Adjust labels in the group to reduce overlap.
`**kwargs`	—	Additional keyword options described below or in the linked constructor.

Additional keyword arguments

Parameter	Default	Description
`offset`keyword only	`(24, -36)`	Offset (x, y) in design pixels at 1080p for residue labels; normalized image units for text shifts.
`format`keyword only	`'three_letter'`	Automatic residue name style: "three_letter" or "one_letter".
`include_chain`keyword only	`True`	Include the chain identifier in automatic residue names.
`font_size`keyword only	`26`	Font size in pixels at a 1080-pixel image height.

Notes

Options in kwargs go to ResidueLabel. Overlap adjustment applies within this group. Review label positions in the rendered scene. Residues without a Cα are skipped.

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, margin=1.05)
labels = p.label_residues(
    chain="A",
    residues=[8, 44, 70],
    font_size=40,
    color="#f2ba67",
    offsets={8: (-270, -90), 44: (440, -100), 70: (380, 150)},
)
self.play(Write(labels, lag_ratio=0.08), run_time=2)
self.play(self.camera.animate.orbit(0.35), run_time=2)
self.wait(1)

Output Preview · 5.0 s · 60 fps

Amino acid labels

Ubiquitin residues 8, 44, and 70.

Full source: ResidueLabels Download MP4

Methods and properties

Name	Description
glyph_countproperty	Number of shaped glyphs used for writing animation.
text_progressproperty	Current reveal progress for glyphs and annotation lines.
layout()method	Project text and line geometry for the renderer at the current frame.
set_opacity()method · inherited from Annotation	Set or animate opacity in [0, 1].
move_to()method · inherited from Annotation	This inherited method raises ValueError because residue labels follow their atoms. Set label offsets to change placement.
shift()method · inherited from Annotation	This inherited method raises ValueError because residue labels follow their atoms. Set label offsets to change placement.
snapshot()method · inherited from Annotation	Capture the current state for deterministic timeline evaluation.
restore()method · inherited from Annotation	Restore a state produced by snapshot().
animateproperty · inherited from Annotation	Create a builder for fluent animation calls. Pass the result to scene.play().

glyph_count

View source

ResidueLabels.glyph_count

Number of shaped glyphs used for writing animation.

text_progress

View source

ResidueLabels.text_progress

Current reveal progress for glyphs and annotation lines.

layout()

View source

ResidueLabels.layout(camera, width, height)

Project text and line geometry for the renderer at the current frame.

Parameter	Default	Description
`camera`	Required	Camera used to project or frame objects.
`width`	Required	Image width in pixels.
`height`	Required	Image height in pixels.

Returns: AnnotationLayout containing glyph placements and line paths.

set_opacity()

View source

Inherited from annotations.Annotation.

ResidueLabels.set_opacity(opacity)

Set or animate opacity in [0, 1].

Parameter	Default	Description
`opacity`	Required	Opacity in [0, 1], from transparent to opaque.

Returns: The object or animation builder.

move_to()

View source

Inherited from annotations.Annotation.

ResidueLabels.move_to(position)

This inherited method raises ValueError because residue labels follow their atoms. Set label offsets to change placement.

Parameter	Default	Description
`position`	Required	Image coordinates (x, y), with (0, 0) at the top-left and (1, 1) at the bottom-right.

shift()

View source

Inherited from annotations.Annotation.

ResidueLabels.shift(offset)

This inherited method raises ValueError because residue labels follow their atoms. Set label offsets to change placement.

Parameter	Default	Description
`offset`	Required	Offset (x, y) in design pixels at 1080p for residue labels; normalized image units for text shifts.

snapshot()

View source

Inherited from annotations.Annotation.

ResidueLabels.snapshot()

Capture the current state for deterministic timeline evaluation.

Returns: State dictionary.

restore()

View source

Inherited from annotations.Annotation.

ResidueLabels.restore(state)

Restore a state produced by snapshot().

Parameter	Default	Description
`state`	Required	State returned by snapshot().

Returns: None

animate

View source

Inherited from annotations.Annotation.

ResidueLabels.animate

Create a builder for fluent animation calls. Pass the result to scene.play().