The graphics state

The graphics state controls the appearance of the graphics objects. When a graphics object, such as a helix, is created, its appearance is determined by the graphics state at that point in the input file. If relevant parameters are changed at some point in the file, then this will affect only graphics objects created after that point in the input file. Objects created prior to the change are not affected. This allows a high degree of control for the user to fine-tune the image.

set command

The set command changes the graphics state. The command is given with the parameter to change and its new value. More than one parameter may be changed in one single set command, using the comma ',' character as delimiter between the specifications. As usual, the command is ended with a semi-colon ';':
set parameter-specification { , parameter-specification } ;

For example, to change the colour of lines to a reddish purple (using an rgb specification):

set linecolour rgb 1 0 0.2;
To set the residue colours for amino-acids according to the B-factor value (of the CA atom) from blue (low B-factor) to red (high), and switch on colouring per residue in the schematic representations: 
set residuecolour amino-acids b-factor 5 45 from blue to red,
    colourparts on;

push and pop commands

The graphics state can be saved and restored during the execution of the input file, using a stack-based mechanism. This is useful when a graphics object needs some unusual parameter values, which then need to be reset for the subsequent objects in the input file.

The push and pop commands have no parameters, and must (as usual) be ended with a semi-colon ';':

push ;
pop ;

The push command creates a copy of the current graphics state, and pushes the copy onto the stack. Any number of state copies may be pushed onto the stack. The pop command removes the state copy off the top of the stack and sets it as the current state.

The graphics state stack is initially empty. It is an error to attempt a pop when the stack is empty. The stack is automatically cleared when the plot is finished.

Note: The parameters atomcolour, atomradius and residuecolour are currently not saved or restored by the push and pop commands.

atomcolour atom-selection colour-specification
atomcolour atom-selection b-factor number number colour-ramp

Change the colour for the selected atoms. Each atom can in principle be given a distinct colour different from all other atoms.

In the second form of the command, the colour for each atom is determined by a linear interpolation in the given colour ramp based on the B-factor for the atom. The two numbers are the low and high B-factor values that correspond to the end-points of the given colour ramp.

Note: This parameter is not saved or restored by the push and pop commands.

Defaults: atom C* grey 0.2, atom N* blue, atom O* red, atom H* white, atom S* yellow, atom P* purple, others grey 0.8
Applies to: cpk, ball-and-stick, bonds.
Used for: all output modes
See also: colourparts

atomradius atom-selection number

Change radius for the selected atoms. Each atom can in principle be given a distinct radius different from all other atoms. The radii are used directly for cpk spheres, while the atom spheres in ball-and-stick use the radii after dividing by 4. The unit is Ångström.

The atom radius may be set to exactly 0.0; such atoms are never output when cpk or ball-and-stick are used.

Note: This parameter is not saved or restored by the push and pop commands.

Defaults: atom C* 1.7, atom N* 1.7, atom O* 1.35, atom H* 1.0, atom S* 1.8, atom P* 1.8, others 1.7
Required: >= 0.0
Applies to: cpk, ball-and-stick.
Used for: all output modes

bonddistance number

Set the maximum bond distance. Atoms that are closer than this distance will have bonds or sticks drawn between them, otherwise not, when selected in the respective command. The unit is Ångström.

Default: 1.9
Applies to: bonds, ball-and-stick.
Used for: all output modes

bondcross number

Set the size of crosses drawn for non-bonded atoms selected in the bonds command. The value is the length of the lines used in the cross. No crosses are drawn if the parameter value is 0.0.

Default: 0.4
Required: >= 0.0
Applies to: bonds
Used for: all output modes

coilradius number

Change the radius of the coils, turns and double-helices. If the value is less than 0.01, then a line is drawn instead. The width of helices at the terminii is twice the value of this parameter. The unit is Ångström.

Default: 0.2
Required: >= 0.0
Applies to: coil, double-helix, helix, turn
Used for: all output modes

colourparts < on | off >

When set to on, the residue graphics objects (helix, strand and so on) are coloured by the residuecolour parameter, and bonds and the sticks in ball-and-stick objects are split in half and coloured according to the atomcolour parameter for the bonded atoms.

When this parameter is off the colours are taken from the planecolour, plane2colour and linecolour parameters.

Default: off
Applies to: ball-and-stick, bonds, coil, double-helix helix, strand, trace, turn.
Used for: all output modes

colourramp < hsb | rgb >

Determine in which colour space the colour ramp interpolation is performed when setting residuecolour and atomcolour using the B-factor mapping.

Default: hsb
Used for: all output modes

cylinderradius number

Set the radius of the cylinder object. The unit is Ångström.

Default: 2.3
Required: > 0.0
Applies to: cylinder
Used for: all output modes

depthcue number

Set the degree of depth-cue effects. Line widths (including lines drawn at edges of plane segments and spheres), label sizes and coil and turn radii will be reduced the farther away they are from the viewer. Coil and turn radii are affected only if slab has been set explicitly. The number ranges from 0.0 (no effect) to 1.0 (full effect).

The default value is appropriate for line width and coil and turn radii, but probably too high for labels.

Default: 0.75
Required: >= 0.0, <= 1.0
Applies to: line, bonds, label, trace, coil, turn, helix, strand, cpk, ball-and-stick
Used for: PostScript only

emissivecolour colour-specification

Set the emissive colour for objects with surfaces. The emissive component of surface lighting is independent of any light sources in the scene. This parameter together with shininess, specularcolour and the inherent colour of the object (planecolour, atomcolour and so on) determine the surface properties when lit.

Default: black (i.e. no emissive colour)
Applies to: coil, cylinder, double-helix, turn, helix, strand, cpk, ball-and-stick
Used for: VRML 2.0, OpenGL
See also: lightcolour, specularcolour, shininess, lighting

helixthickness number

Change the thickness of the helix ribbon. The unit is Ångström.

Default: 0.3
Required: >= 0.0
Applies to: helix
Used for: Raster3D only

helixwidth number

Change the width of the helix ribbon. The unit is Ångström. The width of the helix at the terminii is twice the value of the parameter coilradius.

Default: 2.4
Applies to: helix
Used for: all output modes

hsbreverseramp < on | off >

Set the direction of the colour ramp when the hsb colour ramp is used. If the value is off the ramp is in the positive direction.

Default: off

labelbackground number

Set the amount of background for the labels. A non-zero value will create an area of the background colour extending uniformly from the characters. This may be useful to distinguish labels agains dark objects.

Default: 0.0
Required: >= 0.0
Applies to: label
Used for: PostScript only

labelcentre < on | off >

When switched on, the labels are centered on the given coordinate or atom positions. Otherwise the left lower corner of the labels are positioned on the given coordinate or atom positions.

Default: on
Applies to: label
Used for: PostScript only

labelclip < on | off >

When switched on, labels are clipped against other graphics objects as usual. Otherwise they are rendered on top of the other graphics objects as if they were all in front of them.

Default: off
Applies to: label
Used for: PostScript only

labelmask string

Set the mask to be applied to label strings before output. This is described in the label command.

Default: "rrr..." (Roman characters), " ..." (no change of character case)
Applies to: label
Used for: character case: all output modes; Greek/Roman: PostScript only

labeloffset vector

Set the translation vector to be added to the position given for labels before placing them in the coordinate system. The unit is Ångström.

Default: 0.0 0.0 0.0
Applies to: label
Used for: all output modes

labelrotation < on | off >

When switched on, the labels are rotated by 90 degrees. This is intended for PostScript plots in landscape orientation.

Default: off
Applies to: label
Used for: PostScript only

labelsize number

Set the size, in PostScript units, of label characters. In the PostScript output mode, the actual character size of a label also depends on the depthcue parameter.

For non-PostScript output modes, the size value is mapped into something sensible, but may require modifications, and may also depend on the window size.

Default: 20.0
Required: >= 1.0
Applies to: label
Used for: all output modes

lightambientintensity number

Set the intensity for ambient-light contribution to a scene that a subsequently created light source provides.

Default: 0.0
Required: >= 0.0, <= 1.0
Applies to: directionallight, pointlight, spotlight
Used for: VRML 2.0, OpenGL
See also: lighting

lightattenuation number number number

Set the attenuation function coefficients for a subsequently created positional light source (pointlight or spotlight). The attenuation function is used in the calculation of how much a specific positional light source contributes to the lighting of a given surface, depending on the distance between them. It is given by:
attenuation = 1.0 / max (n1 + n2 * d + n3 * d2)
where n1, n2 and n3 are the three numbers given for the parameter, and d is the distance (in Ångström) between the light source and the surface.

Default: 1.0 0.0 0.0 (i.e. no attenuation)
Required: all components >= 0.0
Applies to: pointlight, spotlight
Used for: VRML 2.0, OpenGL
See also: lighting

lightcolour colour-specification

Set the colour of a subsequently created light source.

For the OpenGL output mode, both the specular and the diffuse component of the light source are set to the given colour. In the VRML 2.0 output mode, there is no distinction between these two.

Default: white
Applies to: directionallight, pointlight, spotlight
Used for: Raster3D, VRML 2.0, OpenGL
See also: emissivecolour, specularcolour, shininess, lighting

lightintensity number

Set the intensity for a subsequently created light source.

Default: 1.0
Required: >= 0.0, <= 1.0
Applies to: directionallight, pointlight, spotlight
Used for: VRML 2.0, OpenGL
See also: lighting

lightradius number

Set the radius within which a subsequently created point light source has an effect. The unit is Ångström.

Default: 100.0
Required: > 0.0
Applies to: pointlight, spotlight
Used for: Raster3D, VRML 2.0
See also: lighting

linecolour colour-specification

Change the colour of lines and labels.

In PostScript mode, the lines at the edges of planes (in several different kinds of output segments) and spheres are also affected.

Default: black for PostScript, white for Raster3D, VRML 2.0, OpenGL
Applies to: line, bonds, label, trace, coil, turn, helix, strand, cpk, ball-and-stick
Used for: all output modes

linedash number

Change the dash pattern applied to lines. A value of 0.0 gives solid lines, otherwise the value gives the length of each dash in PostScript units. A value of 6.0 gives reasonable results.

For non-PostScript output modes, the value is mapped into something sensible, but may require modifications, and may also depend on the window size.

Default: 0.0
Required: >= 0.0
Applies to: line, bonds, trace, coil, turn, helix, strand, cpk, ball-and-stick
Used for: PostScript, Raster3D, OpenGL

linewidth number

Change the width of lines, in PostScript units. The lines at the edges of planes (in several different kinds of output segments) and spheres are also affected.

For non-PostScript output modes, the value is mapped into something sensible, but may require modifications, and may also depend on the window size.

Default: 1.0
Required: >= 0.0
Applies to: line, bonds, trace, coil, turn, helix, strand, cpk, ball-and-stick
Used for: PostScript, Raster3D, OpenGL

objecttransform < on | off >

Determine whether the coordinates for the subsequently rendered objects are to be transformed by the matrix defined by the latest transform command.

Default: on
Applies to: object
Used for: all output modes

planecolour colour-specification

Change the colour of the main surfaces: these are the outer surface of helices, the main surfaces of strands, the surfaces of coils and turns and also the surface of sticks (in ball-and-stick).

This parameter is used if the colourparts parameter is switched off, otherwise the residuecolour and atomcolour parameters are used.

Default: white
Applies to: coil, turn, helix, strand, ball-and-stick, double-helix
Used for: all output modes
See also: colourparts

plane2colour colour-specification

Change the colour of the secondary surfaces: these are the inner surfaces of helices and the side surfaces of strands.

This parameter is used if the colourparts parameter is switched off, otherwise the residuecolour and atomcolour parameters are used.

Default: grey 0.5
Applies to: helix, strand
Used for: all output modes
See also: colourparts

regularexpression < on | off >

Determine which syntax is used to specify the regular expressions used in name comparisons. By default, the syntax is similar to that used in the X-PLOR program (Brünger 1992). When switched on, the syntax is similar to the one used in many common UNIX utilities. See name comparisons for more information.

Default: off
Used for: all output modes
See also: name comparisons

residuecolour residue-selection colour-specification
residuecolour residue-selection b-factor number number colour-ramp
residuecolour residue-selection colour-ramp

Change the colour for the selected residues. Each residue can in principle be given a distinct colour different from all other residues. The colours are used for the schematic residue representations, such as coil and helix, when the colourparts parameter is switched on. By default it is switched off, in which case the planecolour and plane2colour parameters determine the colour of the schematic graphics objects.

In the second form of the command, the colour for each residue is determined by a linear interpolation in the given colour ramp based on the B-factor for the residue. If the residue is an amino-acid (according the the residue type), then its B-factor is taken to be the B-factor for the CA atom, otherwise an average of the B-factors for all atoms in the residue is used. The two numbers are the low and high B-factor values that correspond to the end-points of the given colour ramp.

In the third form of the command, the selected residues are coloured in linear fashion in the order they appeared in the coordinate file, along the given colour ramp.

Note: This parameter is not saved or restored by the push and pop commands.

Default: white
Applies to: coil, turn, helix, strand, double-helix
Used for: all output modes
See also: colourparts

segments integer

Change the number of graphical segments to create between each CA atom point for the schematic residue objects. More segments give smoother graphics objects, at the price of larger files or longer display times. For strands, the number of segments between each CA atom point is actually (number / 2) + 1, where the division is integer division.

The subdivision of the cylinder object is also controlled by this parameter.

In the OpenGL output mode, this parameter controls the tesselation of spheres used by the cpk and ball-and-stick commands.

Default: 6 for PostScript, Raster3D, 3 for VRML 2.0, OpenGL
Applies to: coil, turn, helix, strand, cylinder
Used for: all output modes

segmentsize number

Set the maximum size of certain graphical segments for the PostScript output mode. If the graphical segments (lines, triangles and cylinders, see below) are larger than this value, then they are recursively subdivided into smaller pieces. Note that very large numbers of graphical segments may be produced if a small value is used for this parameter.

Default: 2.0
Required: > 0.0
Applies to: line, cylinder, object
Used for: PostScript only

shading number

Change the factor controlling the degree of shading to apply to surface colours. This is relevant only for the PostScript output mode.

A value of 0.0 disables shading, while a value of 1.0 makes plane segments whose normals are nearly parallel to the paper completely black. When plotting large proteins, it may be a good idea to switch off shading altogether; this reduces the apparent clutter of the image.

Default: 0.5
Required: >= 0.0, <= 1.0
Applies to: coil, turn, helix, strand double-helix, cylinder, object
Used for: PostScript only
See also: shadingexponent

shadingexponent number

Change the exponent of the shading function relating the plane segment normal vector to the degree of shading. This is relevant only for the PostScript output mode.

A large exponent makes the shading strong already at a small angle between the viewer and plane segment normal vector, while a small exponent makes the shading appear only at a large angle.

Default: 1.5
Required: >= 0.0
Applies to: coil, turn, helix, strand double-helix, cylinder, object
Used for: PostScript only
See also: shading

shininess number

Set the degree of shininess for the surfaces. This parameter interacts closely with the specularcolour parameter, which must be something other than black for the shininess parameter to have any effect.

Default: 0.2
Required: >= 0.0, <= 1.0
Applies to: coil, turn, helix, strand, double-helix, cylinder, object
Used for: Raster3D, VRML 2.0, OpenGL
See also: emissivecolour, lightcolour, specularcolour, lighting

smoothsteps integer

Change the number of Priestle smoothing steps (Priestle 1988) to apply to the coordinates of the CA atoms in the selected residues for the coil and strand commands.

The higher the value is, the smoother is the path of the coil or strand. The coil command would be the same as the turn command if this parameter were to have the value 0.

Default: 2
Required: >= 1
Applies to: coil, strand
Used for: all output modes

specularcolour colour-specification

Set the specular colour for objects with surfaces. The specular colour is the colour of reflected light from specific light sources.

This parameter together with shininess, emissivecolour and the inherent colour of the object (planecolour, atomcolour and so on) determine the surface properties when lit.

Default: black (i.e. no specular colour) for VRML 2.0, OpenGL, white for Raster3D
Applies to: coil, cylinder, double-helix, turn, helix, strand, cpk, ball-and-stick
Used for: Raster3D, VRML 2.0, OpenGL
See also: emissivecolour, lightcolour, shininess, lighting

splinefactor number

Change the vector length factor used for the Hermite spline curves in coil, turn and strand. A value close to 0.0 gives nearly straight lines between each control point, while larger values give progressively stronger curvature.

Default: 1.0
Required: >= 0.01
Applies to: coil, turn, strand
Used for: all output modes

stickradius number

Change the radius of the sticks in the ball-and-stick representation. The unit is Ångström.

Default: 0.2
Required: > 0.0
Applies to: ball-and-stick
Used for: all output modes

sticktaper number

Change the degree of the tapering effect when a stick points away from the viewer. A too large value can give undesirable pseudo-depth cue effects. The value 0.0 is no effect, and 1.0 is full effect. This is used only for the PostScript output mode.

Default: 0.75
Required: >= 0.0, <= 1.0
Applies to: ball-and-stick
Used for: PostScript only

strandthickness number

Change the thickness of strands. If this parameter is set to less than 0.01, then a strand is output as a single surface without any thickness. The unit is Ångström.

Default: 0.6
Required: >= 0.0
Applies to: strand
Used for: all output modes

strandwidth number

Change the width of strands. The unit is Ångström.

Default: 2.0
Required: >= 0.02
Applies to: strand
Used for: all output modes

transparency number

Set the transparency of surfaces. A value of 0.0 gives no transparency, while a value of 1.0 gives complete transparency.

The quality of the transparency rendering is strongly dependent on the output mode. For VRML 2.0 the quality depends strongly on the browser used to display the output file. This parameter is currently not implemented for PostScript.

Default: 0.0
Required: >= 0.0, <= 1.0
Applies to: all graphics objects
Used for: Raster3D, VRML 2.0, OpenGL

Top page