Color-by-Value Manpage Mockup (Exploratory)

• Chimera2 commands needed for initial release (wiki)
• Chimera2 command guidelines
• red - will this be in Chimera2?
• olive - other notes

Usage:
( vcolor | vcolour )  spec  method  options

Vcolor (color-by-value) maps colors to value ranges, with gradual shading between the specified colors. Still not settled where the spec should go.

The method can be any of the following, each with its own arguments (described below):

• sequential - sequentially per residue, secondary structure element, chain, or model
• attribute - by atom, residue, model, or surface piece numerical attribute value
• volume - by volume (grid) data value interpolated to atom centers and/or surface vertices
• gradient - by volume data gradient interpolated to atom centers and/or surface vertices
• radial - by distance from a point
• cylindrical - by distance from an axis
• topographic - by distance from a plane

Min, mid, and max values will be reported. Atomic values only? What about residue values derived from atomic values, and values at surface vertices?

Keywords can be truncated to unique strings, and their case does not matter. Synonyms for true: True, 1. Synonyms for false: False, 0. A vertical bar “|” designates mutually exclusive options, and default settings are indicated with bold.

Color sequentially according to the specified level:

• residue along each chain (default); with the default color mapping, this rainbow-colors residues from blue at the N-terminus to red at the C-terminus
• helix along each peptide chain, ignoring other residues
• strand along each peptide chain, ignoring other residues
• SSE (secondary structure element, i.e., helix or strand) along each peptide chain, ignoring other residues
• chain within each model
• model in order of model number

I reversed the “rainbow” cmap relative to Chimera1 and made it the default so that vcolor seq would be equivalent to Chimera1 rainbow.

Color by the values of a numerical attribute. An atom attribute can be used to color atoms/bonds, cartoons (based on the average over atomic values per residue), and per-atom patches in a molecular surface. A residue attribute can be used to color atoms/bonds, cartoons, and per-residue patches in a molecular surface. A surface piece attribute can be used to color surface pieces, and a model attribute to color models of any type.

Color by volume data such as electron density or electrostatic potential interpolated to the positions of atoms and/or surface vertices (details), where volume-model is the model number (preceded by #) of the volume data set. The perPixel option indicates whether to determine color separately for each surface pixel instead of interpolating across surface triangles. details). Per-pixel coloring tends to give smoother color gradations. The colorOutsideVolume option specifies how to color for surface vertices that fall outside the volume data grid. The color_name can be any color name that specifies a single color; the default is #800080008000 (a dark gray). The offset option specifies how far out from each surface vertex, along its normal, to evaluate the data (default 0.0):

• d - a single offset distance
• start,end,N (three values separated by commas only) - starting distance, ending distance, and how many offsets to evaluate within that range, respectively. For example, offset 1.5,3.0,3 specifies offsets of 1.5, 2.25, and 3.0. Values from multiple offsets are averaged per surface vertex. Specifying multiple offsets turns off any per-pixel coloring.

When the coloring target includes atoms and/or cartoons, the atomic values can be assigned as a new atom attribute with name attr-name using newAttr.

Color by volume data gradient norm interpolated to the positions of atoms and/or surface vertices (details), where volume-model is the model number (preceded by #) of the volume data set. The colorOutsideVolume and offset options are as described above for volume.

Color by distance from a point. The point can be specified with center, where center can be:

• x,y,z (three values separated by commas only) - an arbitrary point
• an atom-spec of any combination of atoms and surface pieces. The center of the bounding sphere of the specified items will be used.

The default is the center of the bounding box of the surface. The coordinateSystem option indicates that x,y,z specifications of center should be interpreted in the coordinate system of a reference model. N is the reference model number preceded by #. The default coordinate system is that of the surface being colored.

Color by distance from an axis. The axis is defined by any point on the axis and a direction. The point can be specified with center and the direction with axis, where axis can be:

• x - X-axis
• y - Y-axis
• z - Z-axis
• x,y,z (three values separated by commas only) - an arbitrary vector
• an atom-spec of exactly two atoms (not necessarily bonded or in the same model) or one bond. A bond can only be specified by selecting it and using the word selected, sel, or picked; any atoms also selected at the time will be ignored.

The default is the Z-axis in the coordinate system of the surface. The coordinateSystem option indicates that specifications of center and/or axis should be interpreted in the coordinate system of a reference model. N is the reference model number preceded by #. The default coordinate system is that of the surface being colored.

Color by distance from a plane, or topographic height. The plane is defined by any point on the plane and a vector normal to the plane. The point can be specified with center and the vector with axis. The coordinateSystem option indicates that specifications of center and/or axis should be interpreted in the coordinate system of a reference model. N is the reference model number preceded by #. The default coordinate system is that of the surface being colored.

target  string
The string indicates which representations of the specified atoms/surfaces should be colored, and can be any combination of the following letters, without commas or spaces:

• a - atoms/bonds
• c - cartoons
• m - models
• s - surfaces (entire models or specified pieces)
• l - labels (3D)

cmap  palette | value1,color1:value2,color2:...
Use the specified color mapping, which can be either a pre-defined palette (colors listed in ascending value order):

• rainbow (default) - blue, cyan, green, yellow, red
• redblue - red, white, blue
• cyanmaroon - #0f1bc7adcf5b (a dark cyan), white, #9eb820005eb8 (a dark maroon)
• gray - black, white

(will there be user-defined gradients/palettes?)
...or a series of value,color pairs (no spaces) separated by colons only. Values can be expressed directly on the scale of the data (cmapRange not used) or as fractional values 0.0-1.0 across a range of data specified with cmapRange. Values below the lowest given 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 (shaded gradually) 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.” A color can be any color name that specifies a single color. In the case of attribute coloring only, the following terms can be substituted for the corresponding values:

min	minimum value among the specified atoms
max	maximum value among the specified atoms
mid	average of min and max
novalue	no value assigned for the attribute

A pair specified with novalue does not contribute toward the minimum of two value-color pairs because the corresponding color is not involved in any ranges; it is only used to color items without a value for the specified attribute.

residueValue min | max | average | sum | primary
Cartoons are divisible into per-residue segments. When a cartoon is colored by atom attribute, volume, gradient, or distance, the cartoon segment for each residue will be colored based on a per-residue value derived from the atomic values. The residueValue option specifies how per-residue values should be derived: the minimum, maximum, average (default), or sum of the constituent atom values, or simply taken from each residue's primary atom (for example, the CA atom in an amino acid). A worm-by-value command (worm?) could work similarly.

– when we have Color Key –
key true | false
Whether to start the Color Key tool, filled in with the appropriate colors and values, and set to Use mouse for key placement for creating/positioning the color key in the graphics window. The mouse setting can be toggled to allow moving models with the mouse.

cmapRange  low,high | full
What data values should map to the extremes of the cmap palette, or to values 0.0 and 1.0 when cmap value,color pairs are used. The low and high values should be separated by a comma only (no spaces). The full keyword indicates using the minimum and maximum values found at surface vertices (default for pre-defined palettes). When multiple surfaces are colored in a single command, the full range is determined separately for each surface.

reverseColors true | false
Whether to reverse the order of the colors in the palette.

capOnly true | false
Whether to color only surface caps and not the rest of a surface.

autoUpdate true | false
Whether to update the coloring of a surface automatically when its shape changes. For example, the shape of a surface cap changes as clipping is adjusted, and a molecular surface changes shape when it is recomputed with a different probe radius. This updating only accounts for changes in the shape of a surface, not changes in its position or orientation relative to other models.