ChimeraX docs icon

Command: distance

distance  object1   object2  [ signed  true | false ] [ monitor  true | false ] [ display-options ]

distance delete  atom-spec 
– or –
~distance  atom-spec 

distance style  atom-spec  [ setDefaults  true | false ] [ display-options ]

distance save  distance-file

The distance command measures distances between two objects, which can be:

The current distance is reported in the Log. For click-to-measure, see selection context menus and the distance mouse mode . The tape measure mouse mode adds a different type of distance measurement with markers and links (details...). See also: angle, bond, getcrd, color, style, size, label, clashes/contacts, hbonds, pbond, crosslinks histogram, select by pseudobond length, Axes/Planes/Centroids, measurements

In the case of two atoms, unless monitor false is given, a distance monitor pseudobond (see also the Distances graphical interface) is added and labeled according to the display options. Although subsequent changes in distance are not logged, distance labels on a distance monitor and the values shown in the Distances tool will update automatically.

No distance monitors are added for distances to axes or planes. The signed option (default false) allows reporting positive and negative distances for objects on opposite sides of a plane.

Distance-monitor pseudobonds are added to a model named distances, with properties matching the first monitor in the model unless different values are given. The defaults can be changed in the Distances preferences or by using the distance style command with setDefaults true.

The distance delete or ~distance command removes any distance monitors between specified atoms, or if nothing is specified, all distance monitors.

The distance style command changes the style of existing distance monitors, and setDefaults true (default false) indicates saving the specified values in the Distances preferences as defaults for subsequently created monitors.

The distance save command writes all current distance information (sorted from shortest to longest) to a text file with pathname distance-file. The word browse can be substituted for distance-file to raise a file browser window for specifying the name and location interactively.

Display Options

color  color-spec
Color to use for the pseudobonds (initial default gold
radius  r
Radius in Å to use for the pseudobonds (initial default 0.1).
dashes  N
Number of dashes per pseudobond (initial default 9). Only whole numbers are accepted, with 0 indicating solid sticks. Currently, odd numbers are rounded down to give an even number of dashes.
decimalPlaces  N
Number of digits after the decimal point (initial default 3); affects all distance monitors and is instantly saved as the default.
symbol  true | false
Whether to show the angstrom symbol Å (initial default true); affects all distance monitors and is instantly saved as the default. Distances are assumed to be in Å.

Distance-monitor pseudobonds can also be adjusted with the commands color, style, and size, and distance labels can also be adjusted with color and label. For smoother distance-label text in high-resolution images, see the label command size option.

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