ChimeraX docs icon

Command: label

label  atom-spec  [ atoms | residues | bonds | pseudobonds ]  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: 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.

Using a blank atom-spec with the label command indicates acting on all existing 3D labels, optionally restricted with the atoms, residues, bonds, or pseudobonds keyword; if atom-spec is not blank, the default is to act on labels for residues only. A non-blank atom-spec is required to create new labels. For label delete (regardless of whether the atom-spec is blank), the default is to act on all types of 3D labels unless narrowed with the atoms, residues, bonds, or pseudobonds keyword. 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 (see mousemode). For adding titles and other text at fixed positions in the window for presentation-quality images and movies, see the 2dlabels command.


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  label-color | default
Set label color, where label-color can be any color name that specifies a single color (default white or black depending on the color of the label background, if any, otherwise the window background ).
background  background-color | none
Show a rectangular background behind the label text (default none, no background), where background-color can be any color name that specifies a single color.
size  font-size | default
Set label size, where font-size must be an integer greater than zero (default 24). If a height h is specified, labels will have a constant physical size instead of a fixed size relative to the screen; however, the size parameter will still affect the number of pixels in the rasterized text, with larger values giving smoother edges.
height  h | fixed
Set label height in the distance units of the data (typically Å) so that labels will scale along with the scene, or keep label size fixed relative to the screen (default). The related size option can be used to adjust the number of pixels used to draw the 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 with 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.
orient  update-angle
Specify what change in viewing direction causes labels to be redrawn to face the viewer (default 0.0°, constant label reorientation); a larger angle gives less frequent label updates, which may be useful for maintaining a rapid frame rate, such as in virtual reality. The update-angle can be set differently for different models.
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.

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