ProteinMotion
Reference navigation
On this page

TorsionMarker

A live protractor for one torsion: its bond, an arc around the bond, and the current angle.

python
from proteinmotion import TorsionMarker

Constructor

python
TorsionMarker(
    target,
    torsion='phi',
    *,
    radius=1.25,
    color='#f5d477',
    font_size=30,
    precision=0,
    label=None,
    show_value=True,
    line_width=2.6,
    follow_opacity=True,
    backing='#0b1220',
    opacity=1.0,
)

Parameters

ParameterDefaultDescription
targetRequiredSingle-residue Region.
torsion'phi'phi, psi, omega, or chi1–chi5.
radiuskeyword only1.25Arc radius in ångströms.
colorkeyword only'#f5d477'Line and label color.
font_sizekeyword only30Font size in pixels at a 1080-pixel image height.
precisionkeyword only0Decimal places in the angle label, from 0 to 3.
labelkeyword onlyNoneText before the value; None uses the torsion's symbol.
show_valuekeyword onlyTrueShow the angle after the symbol.
line_widthkeyword only2.6Arc width in design pixels at 1080p.
follow_opacitykeyword onlyTrueMultiply annotation opacity by its selected atom opacity.
backingkeyword only'#0b1220'Color of the translucent card behind the label; None removes it.
opacitykeyword only1.0Opacity in [0, 1], from transparent to opaque.

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 Full script
python
"""Turn one ψ angle, then wind a whole peptide into an α helix.

A 12-residue alanine peptide is built as an extended β strand. ψ of Ala6 turns to
−45° with its atoms shown over the cartoon; then every residue moves to φ = −57°,
ψ = −47°, starting at the N terminus. DSSP assigns the helix from the final
coordinates, and the cartoon blends from coil to helix as the angles change.
"""

from proteinmotion import (
    FadeIn,
    Protein,
    ProteinScene,
    RamachandranPlot,
    SetTorsions,
    Text,
    Unwrite,
    Write,
)


class TorsionBasics(ProteinScene):
    def construct(self):
        peptide = Protein.build("AAAAAAAAAAAA", "strand").cartoon()
        middle = peptide.select(residues=6)
        middle.show_atoms()
        self.add(peptide)
        self.camera.frame(peptide, margin=1.0, aspect=self.width / self.height, screen_position=(0.32, 0.55))
        self.camera.phi = 0.3
        plot = RamachandranPlot(peptide, highlight=middle, position=(0.62, 0.14), size=(0.35, 0.7))
        self.add(Text("Torsion angles", font_size=48, font="semibold", position=(0.05, 0.07)))
        marker = middle.torsion_marker("psi", radius=1.6)
        self.play(FadeIn(plot), Write(marker), run_time=1.5)
        self.play(SetTorsions(middle, psi=-45, anchor="n"), run_time=2.5)
        self.play(Unwrite(marker), run_time=0.6)
        self.play(SetTorsions(peptide, conformation="helix", stagger=0.5), run_time=5)
        self.play(self.camera.animate.orbit(0.8), run_time=2.5)
Output Preview · 12.1 s · 60 fps
Torsion angles

A 12-residue alanine peptide: ψ of Ala6 turns, then every residue moves to α-helix angles.

Methods and properties

NameDescription
valuepropertyThe current torsion in degrees.
glyph_countpropertyNumber of shaped glyphs used for writing animation.
text_progresspropertyCurrent reveal progress for glyphs and annotation lines.
layout()methodProject text and line geometry for the renderer at the current frame.
set_opacity()method · inherited from AnnotationSet or animate opacity in [0, 1].
move_to()method · inherited from AnnotationSet or animate text position in normalized image coordinates.
shift()method · inherited from AnnotationTranslate the object by an offset.
snapshot()method · inherited from AnnotationCapture the current state for deterministic timeline evaluation.
restore()method · inherited from AnnotationRestore a state produced by snapshot().
animateproperty · inherited from AnnotationCreate a builder for fluent animation calls. Pass the result to scene.play().
python
TorsionMarker.value

The current torsion in degrees.

python
TorsionMarker.glyph_count

Number of shaped glyphs used for writing animation.

python
TorsionMarker.text_progress

Current reveal progress for glyphs and annotation lines.

python
TorsionMarker.layout(camera, width, height)

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

ParameterDefaultDescription
cameraRequiredCamera used to project or frame objects.
widthRequiredImage width in pixels.
heightRequiredImage height in pixels.

Returns: AnnotationLayout containing glyph placements and line paths.

Inherited from annotations.Annotation.

python
TorsionMarker.set_opacity(opacity)

Set or animate opacity in [0, 1].

ParameterDefaultDescription
opacityRequiredOpacity in [0, 1], from transparent to opaque.

Returns: The object or animation builder.

Inherited from annotations.Annotation.

python
TorsionMarker.move_to(position)

Set or animate text position in normalized image coordinates.

ParameterDefaultDescription
positionRequiredImage coordinates (x, y), with (0, 0) at the top-left and (1, 1) at the bottom-right.

Returns: The annotation or animation builder.

Inherited from annotations.Annotation.

python
TorsionMarker.shift(offset)

Translate the object by an offset.

ParameterDefaultDescription
offsetRequiredOffset (x, y) in design pixels at 1080p for residue labels; normalized image units for text shifts.

Returns: The object or animation builder.

Inherited from annotations.Annotation.

python
TorsionMarker.snapshot()

Capture the current state for deterministic timeline evaluation.

Returns: State dictionary.

Inherited from annotations.Annotation.

python
TorsionMarker.restore(state)

Restore a state produced by snapshot().

ParameterDefaultDescription
stateRequiredState returned by snapshot().

Returns: None

Inherited from annotations.Annotation.

python
TorsionMarker.animate

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