Reference navigation

On this page

CLASS · v0.9.1

ColorLegend

A horizontal color bar with numeric limits and measurement units.

from proteinmotion import ColorLegend

Constructor

ColorLegend(scale, *, title='', unit='', position=(0.06, 0.82), size=(0.3, 0.12))

Parameters

Parameter	Default	Description
`scale`	Required	ColorScale shared by the structure, plots, and legend. None derives limits from finite values.
`title`keyword only	`''`	Text displayed above the plot or color bar.
`unit`keyword only	`''`	Displayed distance unit: "Å", "nm", or an empty suffix. The distance property uses ångströms.
`position`keyword only	`(0.06, 0.82)`	Image coordinates (x, y), with (0, 0) at the top-left and (1, 1) at the bottom-right.
`size`keyword only	`(0.3, 0.12)`	Plot (width, height) as fractions of the viewport.

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

"""Map 1UBQ Cα B factors to residue color and cartoon thickness."""

from pathlib import Path

from proteinmotion import (
    ColorByProperty,
    ColorLegend,
    ColorScale,
    Protein,
    ProteinScene,
    Representation,
    ResidueValues,
    Rotate,
    Text,
)

DATA = Path(__file__).parent / "data"


class NumericalProperties(ProteinScene):
    def construct(self):
        protein = Protein.from_file(DATA / "1ubq.cif").center()
        values = ResidueValues.b_factors(protein)
        scale = ColorScale(0, 40)
        self.add(protein)
        self.camera.frame(protein, margin=1.08)
        self.add(Text("Residue properties", position=(0.06, 0.07), font_size=42))
        self.add(Text("Ubiquitin · Cα B factors", position=(0.06, 0.13), font_size=25))
        self.add(ColorLegend(scale, title="B factor", unit="Å²", position=(0.06, 0.8)))
        self.play(
            ColorByProperty(protein, values, scale=scale, thickness=(0.6, 1.8), residue_delay=0.012),
            Rotate(protein, 0.25),
            run_time=2.5,
        )
        self.wait(0.5)
        self.play(Representation(protein, "ball_and_stick"), run_time=1.5)
        self.play(Rotate(protein, 0.3), run_time=1)
        self.play(Representation(protein, "surface"), run_time=1.5)
        self.play(Rotate(protein, 0.25), run_time=1.5)

Output Preview · 8.5 s · 60 fps

B factors across representations

1UBQ B factors control residue color and cartoon thickness.

Full source: NumericalProperties Download MP4

Methods and properties

Name	Description
layout()method	Project text and line geometry for the renderer at the current frame.
snapshot()method · inherited from _Plot	Capture the current state for deterministic timeline evaluation.
glyph_countproperty · inherited from _Plot	Number of shaped glyphs used for writing animation.
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.
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().
text_progressproperty · inherited from Annotation	Current reveal progress for glyphs and annotation lines.

layout()

View source

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

snapshot()

View source

Inherited from plots._Plot.

ColorLegend.snapshot()

Capture the current state for deterministic timeline evaluation.

Returns: State dictionary.

glyph_count

View source

Inherited from plots._Plot.

ColorLegend.glyph_count

Number of shaped glyphs used for writing animation.

set_opacity()

View source

Inherited from annotations.Annotation.

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

ColorLegend.move_to(position)

Set or animate text position in normalized image coordinates.

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

Returns: The annotation or animation builder.

shift()

View source

Inherited from annotations.Annotation.

ColorLegend.shift(offset)

Translate the object by an offset.

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

Returns: The object or animation builder.

restore()

View source

Inherited from annotations.Annotation.

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

ColorLegend.animate

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

text_progress

View source

Inherited from annotations.Annotation.

ColorLegend.text_progress

Current reveal progress for glyphs and annotation lines.