Commands

The graphics commands create graphical objects that are rendered according to the graphics state at the point in the input file where the command is given. The commands need different arguments, usually an atom or residue selection, and sometimes also some explicit values.

directionallight vector ;
directionallight from vector to vector ;

Define a directional light source shining in the direction given by the vector, which is either given explicitly, or in the 'from, to' form. The light source has the colour defined by the lightcolour parameter, and the intensity given by the lightintensity parameter.

See the lighting and appearance overview for more information about lighting.

Parameters: lightcolour, lightambientintensity, lightintensity, lighting.

pointlight vector ;

Define a light source with a position, given by the vector, in the coordinate system. The light source has the colour defined by the lightcolour parameter, and the intensity given by the lightintensity parameter. The attenuation function of the light source is determined by the lightattenuation parameter.

See the lighting and appearance overview for more information about lighting.

Parameters: lightambientintensity, lightattenuation, lightcolour, lightintensity, lightradius, lighting.

spotlight vector vector number ;
spotlight vector from vector to vector number ;

Define a light source, a spotlight, with a position and a direction in the coordinate system, emitting a cone of light. The position of the light source is given by the first vector in both forms of the command.

In the first form of the command, the direction of the light is given by an explicit direction vector. In the second form of the command, the direction is given by a 'from, to' specification. The angle of the cone of light is given by the final number, in units of degrees. This must a value in the range 0 to 180.

The light source has the colour defined by the lightcolour parameter, and the intensity given by the lightintensity parameter. The attenuation function of the light source is given by the lightattenuation parameter.

See the lighting and appearance overview for more information about lighting.

Parameters: lightambientintensity, lightattenuation, lightcolour, lightintensity, lightradius, lighting.

anchor string [ description string ] [ parameter string ]
'{' basic-commands '}' ;

The anchor command is useful only for the VRML 2.0 output mode. It specifies that all the graphics objects created within the curly brackets '{' '}' constitute a Web link for the VRML browser to act upon when the user clicks on it.

The first string after the anchor keyword is the URL of the Web link. The optional description item is a string that is supposed to be presented in some way by the VRML browser when the user points to, but does not click on, the Web link object. The optional parameter item is a string that contains additional information for the browser, such as the name of a frame (a target) for the link contents to be displayed in.

The graphics objects that constitute the Web link are given by the commands within the curly brackets '{' '}'. This is just a way to allow specifying more than one graphical object to form one single Web link. The grouping within the curly brackets '{' '}' in the anchor command has no deeper implication.

In all other (non-VRML) output modes, the commands within the curly brackets '{' '}' are executed as usual; the anchor keyword and its attendant string values are just ignored.

The commands that are allowed within the anchor commands group (basic-commands) include all atom graphics commands, all residue graphics commands, the graphics state commands (set, push and pop) and the utility commands comment and debug.

Note: currently the level-of-detail command cannot be used within the level-of-detail command.

Note: this is a more restricted set of commands than was allowed in v2.0.

Parameters: none

level-of-detail { number '{' basic-commands '}' } '{' basic-commands '}' ;

The level-of-detail command is useful only for the VRML 2.0 output mode. With this command, it is possible to create representations at different degrees of complexity for the same molecule. Depending on the current distance of the viewer to the graphical objects, the browser chooses the appropriate representation. Thus, it is possible to show simplified representations when the viewer is at a far distance (when the detail isn't visible anyway), and let the browser handle when to switch for the increasingly detailed representations as the viewer moves closer to the object.

The representation for each level is created by the group of basic commands given within the curly brackets '{' '}'. The number given before all such groups (except the last) is the distance value within which that particular representation is to be used. The values must in ascending order for each representation. This means that the most detailed representation is given first, and the less detailed ones after that. The last group of commands has no distance range, and gives the representation at infinite distance. Any number of such distance-and-commands constructs may be used. Note that the last group of commands, having no specified distance value, must be present. However, a group of commands may be empty.

In all other (non-VRML) output modes, the commands within the curly brackets '{' '}' are executed as usual; the level-of-detail keyword and its attendant numbers are just ignored. This means that all the different representations are created; this is a bug, and may change in future versions of MolScript.

The commands that are allowed within the level-of-detail commands groups (basic-commands) include all atom graphics commands, all residue graphics commands, the graphics state commands (set, push and pop) and the utility commands comment and debug.

Note: currently the anchor command cannot be used within the level-of-detail command.

Parameters: none

label vector string ;
label atom-selection string ;

The first form of the label command outputs a single label to the given position. The second form of the command outputs labels at the positions of the given atoms in the selection.

The colour of the label characters is determined by the linecolour parameter. In the atom selection variant of the label command, the colours are taken from the atomcolour parameter if the parameter colourparts is switched on.

The size of the label characters is determined by labelsize, which is given in PostScript units. In other output formats, this size is converted into Ångström using a reasonable conversion factor. However, the label size may require adjustment in such cases.

The parameter labelclip determines whether the strings will be hidden by other graphical objects, or will appear as if rendered on top of the rest of the image.

The position of the string can be fine-tuned by the labeloffset parameter. This vector is added to the position (explicit or that of the atoms) before the label is actually put into the image.

In the PostScript output mode, the depthcue parameter applies; labels farther away from the viewer will be smaller. Two other parameters are currently implemented only in the PostScript output mode: The labelcentre parameter defines which point in the string is put at the coordinate: If switched on, the middle of the string is used, otherwise the lower-left point of the string is used. The orientation of the string is controlled by the labelrotation parameter. The labelbackground parameter sets the extent of an area around the edge of the label characters that is filled with the background colour. This makes labels more visible when in cluttered regions.

The string itself is processed in several steps before output as the label. If the command with an atom selection is used, then special format codes in the string are replaced by data from each specified atom. The format codes are: 

   %r  name of the residue the atom is in (6 chars)
   %t  type of the residue the atom is in (4 chars)
   %c  one-letter code for res type, X if non-amino acid (1 char)
   %a  atom name (4 chars)
Each of these items can appear only once in the string. The character case of the items are taken as they are in the coordinate file (almost certainly uppercase). This, however, may be changed by the label mask, see below. Any characters that are not format codes in the string will be part of the finally output string, including any space characters. The percent character '%' cannot be output as such in labels generated by the atom selection variant of the label command.

The string thus produced by replacing format codes (if any) is passed through a step that uses a mask to determine whether to change the case of some characters or not, and if they are to be output as Greek characters. The mask is set by the labelmask parameter, and consists of a string where a flag is set for each character position.

The available label mask flags are: 

   r  Roman characters (default)
   g  Greek characters
  ' ' (blank) no change of character case (default)
   l  change character to lowercase
   u  change character to uppercase
The 'r' and 'g' flags are independent of the ' ', 'l' and 'u' flags. When setting the labelmask parameter, note that a character flag has to be in exactly the correct position in the string for correct processing. Note that to get the Greek characters normally used for amino-acid residue atoms, the characters will have to be changed to lowercase as well.

The final processing step consists of squeezing out space characters that were part of the residue name or type, or the atom name, derived from format codes. Note the order of operations: The label mask is applied first, and only afterwards are blanks removed. Otherwise it would be impossible to predict the effect of the label mask.

Two examples of string processing: 

  'LABEL'
  'lABEL'   after applying mask 'l'

  '%r.%a'        in an atom selection label command (dot means blank)
  '123....CA..'  after replacing the format codes for an atom
  '123....Ca..'  after applying mask '........l..'
  '123.Ca'       after squeezing out of spaces from format code items

Parameters: atomcolour, colourparts, depthcue, linecolour, labelbackground, labelcentre, labelclip, labelmask, labeloffset, labelrotation, labelsize.

line vector { to vector } ;

Draw a connected line from the first vector to the following vectors. Any number of vectors may be given.

Note that the coordinates will not be transformed in any way; they are in the fixed coordinate space of MolScript. See object for a way of drawing lines that are affected by a given transformation.

In the PostScript output mode, the lines are recursively subdivided into pieces smaller than the value for the segmentsize parameter.

Parameters: linecolour, linedash, linewidth, segmentsize, transparency.

object string ;
object inline ;

The object command is the interface for importing graphical objects into the MolScript image. The graphical objects are defined using a simple file format.

The first form of the command is for objects specified in an external file, the name of which is given by the string.

The second form allows the objects to be specified in the MolScript input file itself. The format of this inline object specification is the same as for the external object file. Similarly as for the 'inline-PDB' form of the coordinate read command, the usual syntax rules of the MolScript input file are temporarily inhibited until the end of the inline part of the input file. Note that in this form of the command, the semi-colon ';' ending the command itself must appear before the object specifications are given. There is no semi-colon after the final piece of data in the object specification, which for the inline form must be a 'Q' character (see the object file format description).

The graphical objects that may be specified in the object file are: points, lines, triangles, and triangle strips. The format of the object file is described separately.

The point and line objects are affected by the various line parameters: The linewidth parameter determines the size of the points and the width of the lines (if implemented for the output mode). The linedash parameter affects the lines. The linecolour parameter affects the points and lines, unless there are explicit colours specified in the object file.

The triangle and triangle strip objects are double-sided surfaces (i.e. visible from both sides), which may have surface normals and vertex colours defined explicitly. If no explicit colours are defined, then the planecolour parameter is used. The usual lighting parameters apply to these objects, as does the transparency parameter.

If the objecttransform parameter is switched on, then the coordinates of the objects are transformed by the matrix specified in the latest transform command. This is necessary for objects created in the coordinate system of the original atomic coordinates (i.e. almost all objects) to be displayed in a sensible way together with the graphics objects derived from the view-transformed molecule coordinates. For this to work, the view transformation applied to the molecule coordinates must be defined in one single transform command.

In the PostScript output mode, the lines and triangles are recursively subdivided into pieces smaller than the value for the segmentsize parameter.

Parameters: linecolour, linedash, linewidth, objecttransform, segmentsize, transparency, lighting.

viewpoint string from vector to vector [ number ] ;
viewpoint string origin vector number ;

The viewpoint command is useful only for the VRML 2.0 output mode. It specifies a viewpoint, presented in some way by the VRML browser, that helps the user to navigate through the scene under guidance. The string in both forms of the command is a descriptive designation for the viewpoint, which is presented in some way by the VRML browser.

The first form of the command specifies the viewpoint in terms of the position where the user is located (the 'from' vector), and the position towards which the user looks (the 'to' vector).

The second form of the command specifies a viewpoint where the origin of the fixed coordinate system is in the centre, and the position given by the vector is located between the position of the user and the origin. The viewpoint is located at the distance from the position given by the single number.

MolScript always defines a default viewpoint called "overall default". The view direction is along a vector anti-parallel to the z axis of the fixed coordinate system, looking towards the approximate center of the entire set of graphics objects. The position of the viewer is at such a distance so that almost all graphics objects are visible.

Parameters: none

comment string ;

Write the given string as a comment to the output file, using the syntax appropriate for that format. This may be helpful for navigating in the output file in cases when it needs post-editing of some kind. It has no effect on the image.

This is meaningful only for some output modes, currently only VRML 2.0 and Raster3D.

Parameters: none

debug string ;

Output the given string as a run-time diagnostic message to stderr. This has no effect on the image.

Parameters: none

Top page