Command: color, rainbow

Depending on the type of coloring, color may apply to different sets of items:

• Simple Coloring – atomic models, volume data (maps), 2D labels
• Sequential Coloring (Rainbow) – atomic models
• Color Modification – lightening, hue shift, etc. for atomic models
• Coloring by Value (see also the Color Key tool or key command):
  • Attribute – color by attribute values of atoms, residues, or structures (atomic models); color bfactor
  • Map (sample, electrostatic, gradient) – surfaces, molecular and nonmolecular
  • Distance (radial, cylindrical, height) – surfaces
• Coloring by Zone – color surfaces to match nearby atoms or markers
• Removing Coloring by Value or Zone
• Coloring from Image File – paste an image from a file onto a surface; perform texture mapping

See also: transparency, coulombic , mlp , measure convexity, surface, volume, Color Actions, Surface Color, Basic Actions, Selection Inspector, the Actions... Color menu, color schemes, color specification, palettes, limitations of transparency

Additional subcommands manage the set of named colors:

• color name – define color names
• color delete – forget user-defined color names
• color list – show color names and swatches in the Log
• color show – report RGB definitions of color names in the Log

[back to top: color]

Simple Coloring

Usage: color  spec   colorname  [ what | target  string ] [ halfbond  true | false ] [ transparency  percent ]

Simple coloring applies to atomic models, including cartoon and molecular surface representations, volume data (map) displays, and 2D labels. The colorname can be:

• a color specification by name, hexadecimal color code, or component values
• byelement or byatom – a color-by-element scheme; only applies to atomic representations and per-atom patches of molecular surfaces
• byhet or byhetero – same as byelement, except leaving carbon atoms unchanged
• fromatoms – color molecular surface patches to match the corresponding atoms
• fromcartoons or fromribbons – color molecular surface patches to match the cartoon segments of the corresponding residues
• bynucleotide – a built-in scheme by nucleotide base type
• bychain – a built-in scheme by chain ID
• byidentity or bypolymer – a random color per unique biopolymer chain (macromolecular entity); the chain sequence is used to initialize the random number generator for choosing red, green, and blue color components, so the same sequence will always give the same color
• bymodel – the initial colors of atomic models
• random – random color per atom and residue

The target option allows coloring only a subset of the possible displays of a given atom, residue, etc. The string can be any combination of the following letters, without commas or spaces:

• a – atoms/bonds (coloring shown for bonds in halfbond mode)
• b – bonds-only (coloring shown for bonds not in halfbond mode)
• c  or  r – cartoons (ribbons) (divisible to per-residue segments)
• s – surfaces (molecular surfaces divisible to per-atom patches, other surface models such as volume isosurfaces, and for simple coloring only, solid volume displays)
• p – pseudobonds-only (coloring shown for pseudobonds not in halfbond mode)
• f – ring fill and nucleotide representations
• l – labels (3D and 2D)

Alternatively, for certain types of coloring, the targets (what to act upon) can be specified with one or more of the following keywords as a comma-separated list:

• atoms – equivalent to target a
• bonds – equivalent to target b
• cartoons or ribbons – equivalent to target c or target r
• surfaces – equivalent to target s
• pseudobonds – equivalent to target p
• rings – equivalent to target f
• labels – equivalent to target l
• All – equivalent to target abcspfl

• for simple or attribute coloring, before any other optional arguments
• for color modification, at the end of the command

By default, bonds are shown in halfbond mode, with color and transparency settings from the flanking atoms. Setting halfbond false for a bond (or pseudobond) reveals its own color/transparency settings independent of the atoms. This option can be used to toggle halfbond mode regardless of whether the command colors any bonds. It affects only the specified bonds (not pseudobonds), except obeying the target setting when it includes p.

The transparency option sets transparency to the specified percent, where 0% is completely opaque and 100% is completely transparent. Existing transparency is not changed unless this option is used or the colorname explicitly specifies alpha (opacity); if both, the transparency option wins out. See also: transparency

Examples (Simple)

color /d & helix  sky blue  target c
– or –
color /d & helix  sky blue  cartoons

color /A,B:12,260-275  hot pink  target a
– or –
color /A,B:12,260-275  hot pink  atoms

color pbonds  yellow

color C  bymodel  targ a

color #4  medium violet

[back to top: color]

Sequential Coloring (Rainbow)

Usage: color  sequential  atom-spec  [ level ] [ target  string ] [ palette  palette ] [ transparency  percent ]
– or –
Usage: rainbow  atom-spec  [ level ] [ target  string ] [ palette  palette ] [ transparency  percent ]

The color sequential command (synonym rainbow) applies a series of colors to atomic models at the specified level:

• residues (default) – a different color for each residue in a biopolymer chain; other residues such as ligand are not affected
• chains – a different color for each biopolymer chain in an atomic model; non-biopolymer residues are not affected
• polymers – a different color for each unique biopolymer chain (macromolecular entity) in an atomic model, based on sequence; non-biopolymer residues are not affected (see also color bypolymer)
• structures – a different color for each atomic model

The transparency option sets transparency to the specified percent, where 0% is completely opaque and 100% is completely transparent. Existing transparency is not changed unless this option is used or the palette is defined with transparency (any of its colors have alpha < 1); if both, the transparency option wins out. See also: transparency

Examples (Sequential)

color seq res
– or –
rainbow res
– or –
rainbow

rainbow :1-50

color seq polymers  targ c  palette cornflowerblue:red:gold
– or –
rainbow polymers  targ c  palette cornflowerblue:red:gold

open 1qmv; rainbow chain palette paired-10

[back to top: color]

Color Modification

Usage: color modify  spec   hue  [ + | − ]  angle  [ what | target  string ]
Usage: color modify  spec  ( saturation | lightness | whiteness | blackness | red | green | blue ) [ + | − | * ]  percent  [ what | target  string ]
Usage: color modify  spec  contrast [ percent ] [ what | target  string ]

Color modification adjusts existing colors. It applies to atomic models, including cartoon and molecular surface representations. The color component to modify must be specified, with choices:

• hue – hue angle (0-360°) in the hue-saturation-lightness (HSL; see interactive calculator) and hue-whiteness-blackness (HWB) color spaces
• saturation – saturation percent in the HSL color space
• lightness – lightness percent in the HSL color space
• whiteness – whiteness percent in the HWB color space
• blackness – blackness percent in the HWB color space
• red – red percent in the red-green-blue (RGB) color space
• green – green percent in the RGB color space
• blue – blue percent in the RGB color space
• contrast – contrast percent from a reference color related to the current color (0) to a maximally contrasting color (100). The default is 100, either white or black depending on the current color.

For saturation, lightness, whiteness, blackness, red, green, or blue, the percent can be added to (+), subtracted from (−), or multiplied by (*) the current value, or simply set as the current value if no operator symbol is given (or the space after the operator symbol is omitted; the space is needed to indicate a change from the current value rather than an absolute value). For hue, the angle can be added to or subtracted from the current value, or simply set as the current value.

Example image and script: Potassium Channel-Calmodulin Complex

[back to top: color]

Coloring by Attribute Value

Usage: color  byattribute  [a:][r:][m:]attribute-name   atom-spec  [ what | target  string ] [ key  true | false ] [ average  residues ]  palette-options  [ transparency  percent ] [ noValueColor  color-spec ]

Atomic models can be colored to show the values of numerical attributes. Several attributes are present automatically, but others can be defined by the user arbitrarily or created by various ChimeraX tools and commands (details...). For example, the values of a map at atom positions can be assigned as an attribute with measure mapvalues. Examples of coloring by bfactor, an attribute automatically read from mmCIF/PDB, are given below. For coloring by a user-defined attribute, see the custom preset example. For coloring by segmentation region, see segmentation. The graphical interface to color byattribute is Render by Attribute. See also size byattribute, cartoon byattribute (worm), the tutorial Coloring by Sequence Conservation and the video Coloring Aligned Proteins by Cα RMSD.

An a:, r:, or m: immediately preceding the attribute name can be used to indicate the attribute level as atom, residue, or (atomic) model, but this is only needed when the name exists at multiple levels. The color-to-value mapping is specified with palette options (default over the full range).

Transparency (alpha < 1) can be inherent in the colors of the palette, or the separate transparency option can be used to specify it as a percent, where 0% is completely opaque and 100% is completely transparent. If both, the transparency option wins out. See also: transparency

Items without an assignment for the specified attribute will be left unchanged unless another color is specified with the noValueColor option.

When color byattribute is run interactively (in gui mode and not via a script), the key true option can be used to start Color Key and draw a color key with the corresponding colors and values.

The coloring applies to atomic models, including cartoons and molecular surfaces, but can be restricted to certain representations with the target option. If an atom attribute is used, cartoons are colored by the average value of the atoms in each residue. Atoms (and their corresponding molecular surface patches) are colored by the atomic values unless average residue is given to indicate they should be colored by the average per residue.

The command color bfactor   is shorthand for color byattribute bfactor. For example, to color chain A atoms by B-factor and cartoons by the average B-factor per residue, spreading blue-white-red coloring across value range 2-30:

color by bfactor /A range 2,30
– or –
color bfactor /A range 2,30

Regardless of whether the range of values over which to spread the coloring is specified, the full range of atomic values (or per-residue values if average residue is used) is reported in the Log.

If no range for colormapping is specified, the full range over all specified atoms is used for atom coloring and the full range of per-residue averages (over that same set of atoms) is used for cartoon coloring. Importantly, the value ranges will include solvent, ions, and ligands unless the specification excludes them, or they have been deleted beforehand. For example, to rainbow-color chain A atoms etc. by the average B-factor per residue, spreading the coloring across the full range of values from protein only:

color bfactor (/A & protein) palette rainbow ave residue

To apply attribute coloring to a surface cap (from clipping), it is necessary to first color the atoms by attribute, then use color zone to make the cap match the nearby atoms.

[back to top: color]

Coloring Surfaces by Map Value

Usage: color ( sample | electrostatic | gradient )  surf-spec  [ map  map-model ] [ offset  d ] [ key  true | false ] [ update  true | false ] [ palette  palette ] [ range  low,high | full ] [ transparency  percent ]

The sample, electrostatic, and gradient coloring options color surfaces by volume data (map) values. To color atoms by map values, instead use measure mapvalues followed by color byattribute. Surface coloring by map value is also implemented in the Surface Color tool. The color-to-value mapping is specified with palette options, where the palette default is red-white-blue and the range default depends on the specific type of map coloring, explained below.

When the coloring command is run interactively (in gui mode and not via a script), the key true option can be used to start Color Key and draw a color key with the corresponding colors and values. The update option (default true) indicates whether to update the coloring automatically when the shape of the surface changes. For coloring by segmentation region, see segmentation. The coulombic command colors molecular surfaces by Coulombic electrostatic potential without requiring an input map. See also: mlp , surface cap, per-model clipping, the Protein-Ligand Binding Sites tutorial, ChimeraX videos: coloring by electrostatic potential, coloring a map by local resolution

• color sample colors by map value. The value for each surface vertex is found by trilinear interpolation from the eight corners of the enclosing data grid cell. The offset d is how far out from each surface vertex, along its normal, to evaluate the data (default 0.0 Å). The range specifies what data values the palette colors should span (default full, the full range of values found at the surface).
  
  
• color electrostatic is the same as color sample except with default offset 1.4 Å and default range -10,10. An offset of 1.4 Å is typically used for coloring a molecular surface by electrostatic potential, to show the values that any atoms binding to the outside of the surface would “see” at their centers. A molecular surface in ChimeraX is the solvent-excluded surface where the surface of a spherical probe can lie. The default probe radius is 1.4 Å, so an offset of 1.4 Å approximates the solvent-accessible surface, as close as the center of the probe can get to the molecule. **However, an offset of 0.0 may be preferred for coloring the cap of a clipped surface, and a zero or negative offset for coloring the surface of one structure by the potential from another.**
  
  
• color gradient colors by map gradient norm with default offset 0.0 Å and default range full. The gradient at each volume grid point is computed by taking the difference in data values between the next and preceding grid points along each axis and dividing by twice the grid spacing, and then the gradient at a surface vertex is found by trilinear interpolation from the eight corners of the enclosing data grid cell. The norm of the interpolated gradient (the length of the gradient vector) is used for assigning colors. The map specification can be omitted when it is the same model as the surface being colored.

Examples (Map)

color electrostatic #1 map #2 palette redblue  range -10,10

color elec #1 map #2 palette -10,red:0,white:10,royalblue

[back to top: color]

Coloring by Distance

Usage: color  radial  surf-spec  [ center  point-spec ] [ coordinateSystem  model-spec ] [ key  true | false ] [ update  true | false ]  palette-options  [ transparency  percent ]

Usage: color ( cylindrical | height )  surf-spec  [ center  point-spec ] [ axis  vector-spec ] [ coordinateSystem  model-spec ] [ key  true | false ] [ update  true | false ]  palette-options  [ transparency  percent ]

Coloring by distance applies to surfaces only, both molecular and nonmolecular (such as volume isosurfaces). It is also implemented in the Surface Color tool. The color-to-distance mapping is specified with palette options (default across the full range).

When the coloring command is run interactively (in gui mode and not via a script), the key true option can be used to start Color Key and draw a color key with the corresponding colors and values. The update option (default true) indicates whether to update the coloring automatically when the shape of the surface changes.

• color radial colors by distance from a point given with the center option (default 0,0,0).
• color cylindrical colors by distance from an axis. The axis is defined by a point on the axis (given with center) and its direction (a vector given with axis, default z).
• color height colors by topographic height, or distance from a plane. The plane is defined by a point on the plane (given with center) and a vector normal to the plane (given with axis).

[back to top: color]

Coloring by Zone

Usage: color  zone  surf-spec  near  atom-spec  [ distance  cutoff ] [ sharpEdges  true | false ] [ bondPointSpacing s ] [ farColor  color-spec | keep ] [ update  true | false ]

Coloring by zone to match nearby atoms or markers applies to surfaces only. The distance cutoff is specified in physical units, typically Å (default 2.0). The corresponding Map icon uses a distance value six times the grid spacing of the map. The graphical implementation, Color Zone, includes a slider for adjusting the cutoff distance.

For coloring a molecular surface (and/or its caps where sliced by clipping) to match the underlying atoms, a cutoff of at least the diameter of the surface-calculation probe (which defaults to 2.8 Å) is recommended. When multiple specified atoms fall within the cutoff distance of a surface vertex, the vertex will be colored to match the closest one. If bondPointSpacing is specified, points spaced s Å apart along bonds will be used in addition to the atoms to define the zone. The farColor option indicates how to color vertices that are not within the cutoff distance of any of the atoms: either a specific color or keep to retain their current colors. If the farColor option is not given, the single-color setting of the surface model will be used.

The sharpEdges option (default false) subdivides surface triangles to create sharp boundaries between the different colored regions. The update option (default true) indicates whether to update the coloring automatically when the shape of the surface changes.

A map that has been colored by zone can be split accordingly with volume splitbyzone. For coloring by segmentation region, see segmentation. See also: ChimeraX video: coloring each protein in an EM map

[back to top: color]

Removing Coloring by Value or Zone

Usage: color  single  surf-model 

The color single command removes surface per-vertex colors such as from coloring by value (attribute, map, distance, coulombic, or mlp), by zone, or by the atomic patches in a molecular surface. The surface model is returned to its single-color setting.

[back to top: color]

Coloring from Image File

Usage: color  image  surf-spec  [ file  none | input-image-file [ modulate  true | false ]] [ coords  pole | south | sphere | vertexcolors ] [ writeColors  output-image-file ]

Coloring by image applies to surfaces only. In this technique, also known as texture mapping, surface vertices are associated with U,V coordinates that map to the X,Y coordinates in an image. The file option specifies an image from a file to paste onto the surface (image format indicated by the filename suffix), or none, which clears any previous image coloring (since coloring by image does not work with undo). Omitting the file option keeps using the previously specified image, if any, for texture mapping. The modulate option indicates whether the image in the file should modulate rather than replace the current surface coloring (default false, which changes the underlying surface color to white so that the resulting coloring will come from the image only).

An image is rectangular, with XY coordinates (0,0) at the lower left corner and (1,1) at the top right. The coords setting indicates how UV coordinates should be assigned to surface vertices:

• pole – surface north pole at the middle of the image (U,V = 0.5,0.5) and the south pole on a circle touching the image edges
• south – as above, except reversing north and south
• sphere – UV coordinates are the latitude and longitude of a vertex on a sphere centered at 0,0,0 in the surface model coordinate system
• vertexcolors – UV coordinates are determined from the existing vertex colors, a unique U,V pair for each color; this would be used without specifying an input image. The writeColors option can then be used to save the corresponding XY image file (with format indicated by the filename suffix). This allows saving texture coloring for import into other programs that do not use vertex colors directly, and is most useful for surfaces with a handful of distinct colors rather than many color gradations.

If the coords option is not used, UV coordinates are not assigned (for example, to allow using Python to assign them in some other way).

[back to top: color]

Palette Options

A palette is an ordered set of colors or value,color pairs used for sequential coloring or coloring by value (map, distance, or attribute). See also: coulombic, mlp, alphafold contacts, measure convexity

palette  palette
The palette can be specified as one of the following (or as ^palette to reverse the order of the colors):

• palette-name – the name of an existing palette; the command palette list lists the names of the available palettes in the Log. Predefined palettes include the following, with colors shown in ascending value order:
  • rainbow (default for sequential coloring)
  • red-white-blue or redblue (default for coloring by map value or coloring by distance)
  • blue-white-red or bluered (default for coloring by attribute)
  • cyan-white-maroon or cyanmaroon
  • cyan-gray-maroon (default for measure convexity, along with range -1,1)
  • grayscale or gray
  • lipophilicity (default for the mlp command, along with range -20,20)
  • alphafold

    0

    50

    70

    90

    100

    (used to show the pLDDT confidence measure in the B-factor field of AlphaFold predictions)
  • esmfold

    0.0

    0.5

    0.7

    0.9

    1.0

    (used to show the pLDDT confidence measure in the B-factor field of ESMFold predictions)
  • pae

    0

    5

    10

    15

    20

    25

    30

    (the default for plotting PAE from AlphaFold or from ESMFold)
  • paegreen

    0

    5

    10

    15

    20

    25

    30

  • paecontacts

    0

    5

    10

    15

    20

    (the default for alphafold contacts)
  • ColorBrewer palettes – a default number of colors will be used if the number is omitted from the name. Examples:

    palette pastel2-4
    palette paired-6
    palette piyg
    palette ^piyg

    Users should cite: www.ColorBrewer.org, color specifications and designs by Cynthia A. Brewer, Pennsylvania State University.
  
  
• color1:color2:color3... a series of color specifications separated by colons, collectively enclosed in quotation marks if it contains any spaces (example: palette cornflowerblue:red:gold or palette "cornflower blue:red:gold"). The colors are placed evenly along the range, with the first and last colors at the extremes. Colors for intermediate values are interpolated.
  
  
• value1,color1:value2,color2:value3,color3... a series of value,color pairs separated by colons, collectively enclosed in quotation marks if it contains any spaces (example: palette "0,cornflower blue:1,gold:0.7,red"). For sequential coloring, an entire range (such as the residues in each chain or the chains in each model) is always mapped to fractional values 0.0-1.0. For numerical data, the values can be expressed directly on the scale of the data (range not used) or as fractional values 0.0-1.0 across a range of data specified with range. Values below the lowest given value will map to the same color as the lowest, and values above the highest will map to the same color as the highest. Colors are interpolated between specified value-color pairs; discrete coloring can be achieved by specifying the same color for the upper- and lower-bound values of a “bin.” Reversing the colors in this type of palette specification with ^ is not recommended, as it would disrupt the specified color-value pairing.
  
  
• colourlovers-id – the ID number, name, or name+author of a palette to be fetched from COLOURlovers.com. Examples:

  palette 92095
  palette "Giant Goldfish"
  palette "Giant Goldfish by manekineko"
  palette "^Giant Goldfish"

  The page of a specific palette at COLOURlovers.com shows its name, author, ID number (in the URL), and any licensing stipulations for its use. Palette names with spaces must be enclosed in quotation marks. Palette names are not necessarily unique, and the most-viewed palette of a specified name will be fetched unless by author is appended, as in the example above. Palette and author names must be capitalized as shown on the website. Palettes with “all rights reserved” cannot be fetched. In ChimeraX, the palette colors are used in left-to-right order, spaced equally along the range of values. Web-fetched palettes are cached locally as described for open.

range  low,high | full
For numerical data only (not sequential coloring), what values should map to the extremes of the palette (default full, the minimum and maximum values for the items to be colored). Alternatively, low and high values separated by a comma only can be supplied. When multiple models are colored in a single command, the full range is determined separately for each model.

[back to top: color]

Defining and Listing Colors

Usage:
color name  cname  color-spec

Usage:
color delete ( cname | custom )

Usage:
color list [ all | builtin | custom ]

Usage:
color show  cname

The command color name assigns cname as the name of the specified color. It can be used to define a new color name or redefine an existing one. A built-in color name, however, cannot be redefined. Color names must begin with an alphabetical letter and may contain only lowercase letters, numbers, hyphens, underscores, and spaces. If cname has embedded spaces, it must be enclosed in quotation marks. Examples:

color name tpurple 60,0,80,50
color name tgreen rgba(0%, 80%, 40%, 0.5)

Colors can be defined automatically at ChimeraX startup by including color name commands in the Startup preferences.

The command color delete can be used to “forget” a specific user-defined color or all custom (user-defined) colors. A built-in color name cannot be deleted. User-defined color names are saved in sessions.

The command color list lists color names along with color swatches in the Log, with options:

• all (default)
• builtin – just the built-in colors
• custom – just the user-defined colors

The command “color show cname” reports in the Log the rgba (red, green, blue, opacity) definition of an existing color named cname. See also: palette list