Callout

Connect an image label to a selected region with a line.

View source Guide and examplesInherits Annotation

from proteinmotion import Callout

Constructor

Callout(
    region,
    text,
    *,
    subtitle=None,
    position=(0.73, 0.25),
    font_size=32,
    font='semibold',
    color='#edf3fc',
    subtitle_color='#a3b3c7',
    line_color=None,
    line_width=1.5,
    tip='dot',
    clamp=True,
    follow_opacity=True,
    opacity=1.0,
)

Parameters

Parameter	Default	Description
`region`	Required	Region selection attached to a protein.
`text`	Required	Text to display.
`subtitle`keyword only	`None`	Optional second line of text.
`position`keyword only	`(0.73, 0.25)`	Image coordinates (x, y), with (0, 0) at the top-left and (1, 1) at the bottom-right.
`font_size`keyword only	`32`	Font size in pixels at a 1080-pixel image height.
`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

The label uses a fixed image position. Its line follows the selected region as coordinates or the camera move.

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)
helix = p.select(residues=(23, 34), atoms="CA")
note = helix.callout(
    "α helix",
    subtitle="Residues 23–34",
    position=(0.07, 0.38),
    font_size=48,
    color="#f2ba67",
    tip="arrow",
)
box = helix.highlight(style="box", color="#f2ba67")
self.play(Write(note), FadeIn(box), run_time=2)
self.play(self.camera.animate.orbit(0.5), run_time=3)
self.wait(1)

Output Preview · 6.0 s · 60 fps

Region callout

A line follows the selected helix as the camera moves.

Full source: Callout 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	Set or animate text position in normalized image coordinates.
shift()method · inherited from Annotation	Translate the object by an offset.
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

Callout.glyph_count

Number of shaped glyphs used for writing animation.

text_progress

View source

Callout.text_progress

Current reveal progress for glyphs and annotation lines.

layout()

View source

Callout.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.