Explicit values

Explicit values such as numbers, colours and 3D vectors are used as part of commands or state changes. The specifications described here are therefore just syntax fragments, not complete commands.

Logical specifications

on off

The logical (or boolean) explicit values are used to set some parameters and in a few commands.

String specifications

" string-contents "

String values are used in the label command, the read command and a few others. A string value is enclosed by double-quote '"' characters. It cannot contain the newline character (line breaks), which means that a string cannot be split into more than one line in the input file. The maximum length of a string is currently 2047 characters. The double-quote character '"' itself may be included in a string by escaping it with the backslash character: '\"'.


As a special case, a string which contains no blank characters, such as tabs or spaces, may be used without the double-quotes. This kind of string is called an identifier. There are several restrictions on it: there must be no blank characters in it, it must not contain characters that are special in a MolScript input file (semi-colon ';', curly brackets '{' '}'), and it cannot be equal to a command keyword. Typically, file names are identifiers.

Number specifications

Any item that is a valid numerical value for the standard library routines in the C programming language is also a valid number in MolScript. Some examples:
Some invalid numbers:
Note that in contrast to previous versions of MolScript (v1.4 and older), it is now allowed to give an integer value when a floating-point value is expected. The integer is automatically converted into a floating-point value. However, when an integer is expected, a floating point value is invalid.

Vector specifications

A vector (or coordinate) can be specified either by an explicit triplet of numbers, or by the keyword position given with an atom selection.

number number number

A vector specified by explicit x, y and z values, is given by three numbers without separating commas. The values in a vector must be valid numbers. For example, the labeloffset parameter is a vector parameter, so to change it give the following command:
set labeloffset 0 0.5 -0.8;

position atom-selection

A vector may be specified by giving an atom selection after the keyword position. This will compute the geometrical centre-of-gravity of the atoms as the vector value. All atoms in the selection have the same weight. Note that in the transform command, this computation is done before any of the transformations have been applied.

Note that the atom selection must contain at least one atom, or an error will result.

Colour specifications

Colours can be specified by a name, by greyscale, by the RGB (red, green, blue) system, or by the HSB (hue, saturation, brightness) system.

The colour system within MolScript unfortunately cannot guarantee that the appearance of a given colour specification will be the same in different output formats when displayed on different hardware.

grey number
gray number

The value in the greyscale specification ranges from 0.0 (black) to 1.0 (white), inclusive.

rgb number number number

The values in the RGB specification denote the amount of red, green and blue, respectively, colour components to use in the colour. Each value ranges from 0.0 to 1.0, inclusive.

hsb number number number

The values in the HSB specification denote the hue, saturation and brightness values for a colour. These values must all be within the range from 0.0 to 1.0, inclusive.
  1. The hue is defined in a circular fashion from 0.0 = red, 0.2 = yellow, 0.333 = green, 0.667 = blue, 0.8 = violet, 1.0 = red again.
  2. The saturation can be described as the whiteness of the colour, where 0.0 is completely white and 1.0 is full colour.
  3. The brightness (loosely, intensity) goes from 0.0 = black to 1.0 = full intensity.

Colour names

There are a total of 164 colour names defined in MolScript. They are just symbolic constants for ordinary colour specifications in the greyscale (white and black) or RGB systems (all others).

An alphabetical list of defined colour names is given here .

Note: the colour purple is no longer the same as magenta.

Colour ramp specifications

A colour ramp defines a continuously changing scale of colours. Colour ramps are used for the atomcolour and residuecolour parameters.

The ramp is defined by the two end-point colours. The actual result is crucially dependent on the colour space in which the ramp is defined. This is determined by the colourramp parameter. The reason for this is that the ramp is computed by linear interpolation of each colour component in the end-point colours. When the interpolation is done using the red, green and blue components (RGB), the result will be different compared to an interpolation using the hue, saturation, brightness components (HSB) even though the two end-point colours have the same visual appearance.

The HSB colour space is conceptually a colour-wheel. It is therefore possible to interpolate in two opposite directions in the HSB colour space. The hsbreverseramp parameter determines which direction is used. If the two end-point colours are hsb 0 1 1 (red) and hsb 0.667 1 1 (blue), then interpolation with hsbreverseramp off (the default) will be in the forward direction, and will go through hsb 0.333 1 1 (green). If the parameter is on, then the interpolation will instead go through hsb 0.8 1 1 (purple).

Note that it does not matter which colour space is used in the specifications for the ramp end-point colours. The interpolation is determined by the colourramp and hsbreverseramp parameters, not by how the end-point colours are specified.

from colour-specification to colour-specification

Defines the colour ramp by two explicit end-point colour values. The lower end of the colour ramp is given by the first colour. The interpolation calculation is affected by the colourramp parameter, and if this parameter is hsb, then the hsbreverseramp parameter also comes into play.


This defines a colour ramp in the HSB colour space from blue to red via cyan, green, and yellow, i.e. in the reverse direction.

Note that, currently, this colour ramp specification will automatically set the colourramp parameter to hsb and the hsbreverseramp parameter to on. This is really a bug.

Top page