Distance

Draw a distance line between two atom or residue selections.

View source Guide and examplesInherits Annotation

from proteinmotion import Distance

Constructor

Distance(
    start,
    end,
    *,
    mode='3d',
    anchor='ca',
    space='model',
    color='#f2ba67',
    label_color=None,
    font_size=27,
    precision=1,
    unit='Å',
    prefix='',
    show_distance=True,
    style='dashed',
    line_width=1.7,
    radius=0.09,
    dash_count=12,
    dash_ratio=0.6,
    follow_opacity=True,
    opacity=1,
)

Parameters

Parameter	Default	Description
`start`	Required	Region for the first endpoint.
`end`	Required	Region for the second endpoint.
`mode`keyword only	`'3d'`	"3d" draws lines within the model; "2d" draws lines over the image.
`anchor`keyword only	`'ca'`	"ca" uses the Cα of a single residue when available; "centroid" averages selected coordinates.
`space`keyword only	`'model'`	"model" uses local coordinates; "world" includes display transforms.
`color`keyword only	`'#f2ba67'`	Hex color or RGB values. For tint setters, None restores the representation’s base palette.
`label_color`keyword only	`None`	Distance text color; None inherits the line color.
`font_size`keyword only	`27`	Font size in pixels at a 1080-pixel image height.
`precision`keyword only	`1`	Number of decimal places in a distance label, from 0 to 6.
`unit`keyword only	`'Å'`	Displayed distance unit: "Å", "nm", or an empty suffix. The distance property uses ångströms.
`prefix`keyword only	`''`	Text placed before the distance value.
`show_distance`keyword only	`True`	Display the distance value at the line midpoint.
`style`keyword only	`'dashed'`	"dashed" or "solid".
`line_width`keyword only	`1.7`	Line width in design pixels at 1080p for overlays; ångströms for 3D highlight boxes.
`radius`keyword only	`0.09`	3D line cylinder radius in ångströms.
`dash_count`keyword only	`12`	Number of line segments.
`dash_ratio`keyword only	`0.6`	Filled fraction of each dashed segment.
`follow_opacity`keyword only	`True`	Multiply annotation opacity by its selected atom opacity.
`opacity`keyword only	`1`	Opacity in [0, 1], from transparent to opaque.

Notes

Single-atom selections use that atom. A single-residue selection uses its Cα when available; larger selections use a centroid. In 3D mode, atoms can hide the line. Labels are drawn over the image. Use space="world" for endpoints on separate proteins, and preserve a shared coordinate frame for physical distances.

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 = helix_view(self)
a = p.select(residues=23, atoms="CA")
b = p.select(residues=34, atoms="CA")
for mode in ("3d", "2d"):
    ruler = Distance(
        a,
        b,
        mode=mode,
        font_size=42,
        color="#50e0d0",
        prefix="Cα · ",
    )
    title = Text(f"{mode.upper()} line", font_size=48)
    self.play(Write(ruler), Write(title), run_time=1.5)
    self.play(self.camera.animate.orbit(0.35), run_time=2)
    self.play(FadeOut(ruler), FadeOut(title), run_time=0.5)

Output Preview · 8.0 s · 60 fps

3D and 2D distance lines

Distance between Cα23 and Cα34 in PDB 1UBQ.

Full source: DistanceModes Download MP4

Methods and properties

Name	Description
distanceproperty	Current endpoint distance in ångströms, regardless of the label unit.
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().