ResidueLabel

Label one amino acid at its projected Cα position.

View source Guide and examplesInherits Callout

from proteinmotion import ResidueLabel

Constructor

ResidueLabel(
    region,
    text=None,
    *,
    offset=(24, -36),
    format='three_letter',
    include_chain=True,
    font_size=26,
    **kwargs,
)

Parameters

Parameter	Default	Description
`region`	Required	Region selection attached to a protein.
`text`	`None`	Custom text, or None to use the residue name and author number.
`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.
`**kwargs`	—	Additional keyword options described below or in the linked constructor.

Additional keyword arguments

Parameter	Default	Description
`subtitle`keyword only	`None`	Optional second line of text.
`font`keyword only	`'semibold'`	Bundled "regular" or "semibold", or a path to a TTF/OTF font.
`color`keyword only	`'#edf3fc'`	Hex color or RGB values. For tint setters, None restores the representation’s base palette.
`subtitle_color`keyword only	`'#a3b3c7'`	Subtitle color.
`line_color`keyword only	`None`	Callout line color; None uses the main text color.
`line_width`keyword only	`1.5`	Line width in design pixels at 1080p for overlays; ångströms for 3D highlight boxes.
`tip`keyword only	`'dot'`	Callout endpoint marker: "dot", "arrow", or "none".
`clamp`keyword only	`True`	Keep callout text inside the image bounds.
`follow_opacity`keyword only	`True`	Multiply annotation opacity by its selected atom opacity.
`opacity`keyword only	`1.0`	Opacity in [0, 1], from transparent to opaque.

Notes

If the residue has no Cα, the label uses the selected atoms’ centroid. The selection must contain exactly one residue. Additional style options go to Callout.

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
set_offset()method	Set or animate a residue label’s offset from its projected atom.
glyph_countproperty · inherited from Callout	Number of shaped glyphs used for writing animation.
text_progressproperty · inherited from Callout	Current reveal progress for glyphs and annotation lines.
layout()method · inherited from Callout	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().

set_offset()

View source

ResidueLabel.set_offset(offset)

Set or animate a residue label’s offset from its projected atom.

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

Returns: The label or animation builder.

glyph_count

View source

Inherited from annotations.Callout.

ResidueLabel.glyph_count

Number of shaped glyphs used for writing animation.

text_progress

View source

Inherited from annotations.Callout.

ResidueLabel.text_progress

Current reveal progress for glyphs and annotation lines.

layout()

View source

Inherited from annotations.Callout.

ResidueLabel.layout(camera, width, height, *, offset=None, progress=None)

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.
`offset`keyword only	`None`	Offset (x, y) in design pixels at 1080p for residue labels; normalized image units for text shifts.
`progress`keyword only	`None`	Optional reveal progress in [0, 1]; None uses the annotation’s current progress.