ChimeraX docs icon

Command: label

label  atom-spec  [ atoms | residues | bonds | pseudobonds ] color  color-spec | default ] [ height  h | fixed ]  other-options

label delete  atom-spec  [ atoms | residues | bonds | pseudobonds ]
– or –
~label  atom-spec  [ atoms | residues | bonds | pseudobonds ]

label listfonts

The label command shows labels that move along with the associated atoms, residues, bonds, or pseudobonds in 3D, with default contents: atom name, residue name and number, and bond or pseudobond length. See also: label settings, distance, 2dlabels, measurements

These “3D” (although flat in appearance) labels can be of multiple colors and sizes, and both atom and residue labels can be shown for the same atom at the same time. A label is automatically hidden, however, when the corresponding item (atom, residue, bond, or pseudobond) is hidden.

Adding new labels with the label command requires a non-blank atom-spec. For label with a non-blank atom-spec, the default is to add (or change, if pre-existing) labels of residues, although labels of atoms, bonds, or pseudobonds can be specified instead. For label with a blank atom-spec, or label delete regardless of whether the atom-spec is blank, the default is all types of 3D labels unless explicitly limited to one of atoms, residues, bonds, or pseudobonds. The command ~label is the same as label delete.

The command label listfonts lists the possible fonts in the Log.

3D labels can also be added/deleted by clicking in the graphics window with the label mouse mode . To add text and symbols at any X,Y position in the window for presentation-quality images and movies, see the 2dlabels command instead. Both kinds of labels can be repositioned with the move label mouse mode .


Parameters that are not specified retain their current values.

text  label-contents | default
Specify text contents of the label, which can be an arbitrary string or default information based on the object type being labeled: Arbitrary label-contents can include letters, numbers, symbols from the keyboard; additional symbols can be copied and pasted into the command line, or indicated with unicode character codes or character names. (See 2dlabels for Unicode examples.) Spaces and quote marks can be included by enclosing the entire label-contents in single or double quote marks. Carriage returns are indicated with \n.
color  color-spec | default
Set label color (default white or black depending on the color of the label background, or if there is no label background, depending on the color of the window background).
bgColor  color-spec | none
Show a rectangular background of the specified color behind the label text (default none, no background).
height  h | fixed
Set label height in Å (default h specified in the Labels preferences or with label defaultHeight) or keep label size fixed relative to the screen. The related size option sets label quality, or if height is fixed, the label pixel size. See also: label orient
size  font-size | default
Set label quality or pixel size (default 48). Larger values give smoother edges, or if height is fixed, larger labels.
font  font-type | default
Specify label font (default Arial); the command label listfonts lists the possible values of font-type in the Log. Those containing spaces must be enclosed in quotation marks.
offset  x,y,z | default
Specify an absolute offset for a label as three comma-separated values x,y,z representing distances along the X-, Y-, and Z-axes in the screen coordinate system. Negative values can be given. The default offset is (display_radius + 0.2),0,0.5.
onTop  true | false
Whether to draw the labels on top of other objects regardless of their relative positions in 3D (default true); can be set differently for different models. Labels that are not on top will not show through a transparent surface unless all of the labels displayed for that model have a background.

Label Settings

Usage: label defaultHeight  h

The command label defaultHeight sets the Labels preference for 3D label height in distance units.

Usage: label orientupdate-angle ]

The command label orient specifies what change in viewing direction should trigger redrawing labels to face the viewer. The default update-angle is 0.0°, constant label reorientation. In virtual reality, however, it is automatically set to 45° to reduce the frequency of label updates that could slow rendering. If update-angle is omitted, the current value is reported in the Log. This setting only applies to labels with heights set in distance units; those with fixed heights always face the viewer.

UCSF Resource for Biocomputing, Visualization, and Informatics / November 2019