The label command shows labels that move along with the associated items in 3D. These “3D” (although flat in appearance) labels can be of multiple colors and sizes. A label is automatically hidden, however, when the corresponding item is hidden. Subcommands include:
See also: label settings, distance, 2dlabels, Actions menu, measurements
The type of items to label can be indicated with one of the following level keywords, with default label contents:
Adding new labels with the label command requires a non-blank atom-spec, although the word all can be used to indicate all applicable 3D data. For label with a non-blank atom-spec, the default level of labels to add (or change) is:
Model-label examples:
label #3-8 models
label all models
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 the types with the corresonding keyword (atoms, residues, etc.). The command ~label is the same as label delete.
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 label contents, which can be an arbitrary string or information on the labeled items. The default information is:For other attributes of the items, see below. 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 quotation marks can be included by enclosing the entire label-contents in single or double quotation marks. Carriage returns are indicated with \n. Since arbitrary text might also start with the letter “d” the entire word default (without truncation) must be given to return to default label contents.
- for atoms, atom name
- for residues (default), residue name, number, and insertion code (if any)
- for models, model name
- for bonds or pseudobonds, length
attribute attribute-name
Atoms and residues can be labeled by the values of an attribute at the same or higher level. The attribute option shows the values of a single attribute with default formatting, whereas the text option can be used to combine the attribute with arbitrary text, label with more than one attribute at a time, and/or include python format specifications. Examples:label ligand atoms attribute idatm_type – same as – label ligand atoms text {0.idatm_type}
label sel atoms attribute bfactor – same as – label sel atoms text {0.bfactor:.3g}
label @ca atoms attr residue.number – same as – label @ca atoms text {0.residue.number}
label @ca residues attr number
label :1 residues attr chain_id height 4
label /A:1 residues attr structure.name height 5 offset 1,1,1
label /A:2-12 residues text "{0.phi:.1f},{0.psi:.1f}"
label sel text "{0.name}{0.number}" height 1.5
color color-spec | default
Set label color. If specified as default or auto, the label color will automatically adjust to 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 label defaultModelHeight) 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 along the X-, Y-, and Z-axes in the screen coordinate system in the distance units of the data (usually Å). The offset is the position of the lower left corner of the label rectangle relative to the center of the labeled item. Negative values can be given. The default offset is:
- (radius + 0.2),0,0.5 for atoms, bonds, and pseudobonds
- 0,0,0 for residues
- –0.25(radius),–radius,0 for models, where the radius of a model is half the length of its bounding box (largest of X, Y, Z dimensions)
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.
Usage: label listfonts
The label listfonts command lists the possible fonts in the Log.
Usage: label missing model-spec maxchains
The label missing command labels missing-structure pseudobonds with the number of biopolymer residues that they represent, according to PDB SEQRES information or the mmCIF equivalent. As per the normal convention, the model-spec may be left blank to indicate all applicable models. A maxchains value is required to specify the maximum number of chains in an atomic model for missing-segment labels to be shown in that model (can be set to 0 to remove all missing-segment labels). The corresponding preference can be set in the Labels preferences.
Usage: label defaultHeight h
The command label defaultHeight sets the Labels preference for 3D label height in distance units.
Usage: label defaultModelHeight h
The command label defaultModelHeight sets the Labels preference for model 3D label height in distance units.
Usage: label orient [ update-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.