 Jmol can generate a large variety of objects using the method of isosurfaces. Many of these surfaces can be color-mapped. Two Jmol commands (isosurface and mo) render isosurfaces. The isosurface command itself provides ultimate control over these surface renderings. Before using the isosurface command, if you are interested in rendering molecular orbitals, you should first take a look at the mo command.
The general syntax of the isosurface command is as follows:
isosurface ID [object id] [construction/mapping parameters] [surface object] [additional mapping-only parameters] MAP [color mapping dataset] [display options] .
The isosurface command is complex, and while the order of parameters is flexible within these groups, parameters in different groups should not be swapped in terms of order within the command, or the result is unpredictable or will cause an error message to be displayed. While the id is optional, it is highly recommended. Specifically for the options ON, OFF, and DELETE, the id may include a wildcard character (asterisk). Thus, isosurface pl* on turns on all isosurface objects having an ID starting with "pl".
Data for these surfaces can be from several sources (see below). In addition, atom-based data from a variety of sources can be mapped onto an isosurface.
The isosurface itself represents the points in space where scalar values cross a specified "cutoff" value. Inside the surface, values are greater or equal to a specified positive cutoff or less than or equal to a specified negative cutoff. The default cutoff depends upon the type of object displayed. Note that positive and negative surfaces may be created separately, or, using the SIGN keyword, they can be generated together.
Color mapping of one object onto another is a simple as listing both an object and a dataset within the same isosurface command. Several keywords affecting the mapping are allowed. The default color scheme uses a red-->orange-->yellow-->green-->blue rainbow, where red represents minimum values and blue represents maximum values, but several other schemes are available (see below). Mapped data can be expressed as a series of contour lines.
ID [object id] back
The optional identifier allows you to refer back to this isosurface later for turning the surface on or off, deleting the surface, or changing display options. It must be either the first parameter or the second, just after DELETE. If the identifier is missing, behavior depends upon version. The ID keyword is optional but recommended, because then one can use any name for the ID; otherwise the name must not be one of the many Jmol command or keyword names. Leaving off the ID when creating an isosurface replaces the current isosurface with the new one.
[construction/mapping parameters] -- molecular/solvent surfaces back
| ADDHYDROGENS | For a solvent or sasurface object, accounts for missing hydrogens on carbon atoms only just prior to generating the surface. A simple sp3 model is used, and for that reason this option is not recommended. Instead, use set pdbAddHydrogens to load a PDB file and automatically add hydrogen atoms to ATOM and HETATM records. | | IGNORE {atom expression} | Specifies a set of atoms to completely ignore when generating a solvent-related surface (SOLVENT or SASURFACE). Typically these might be solvent molecules or atoms: IGNORE {solvent}. Note that SASURFACE and SOLVENT surfaces by default ignore solvent molecules; VDW and MOLECULAR do not. | | IONIC radius | Atom radius relative to the ionic radius. Options include:
| x.x | specific absolute number of Angstroms for every atom | | +/-x.x | offset greater(+) or less(-) than the ionic radius | | nn% | percent of the ionic radius | | +/-nn% | percent offset from the ionic radius |
| | SELECT {atom_exp} | Selects a specific subset of the atoms for this surface. Same as select atom_exp; isosurface.... except the atoms are selected only within the isosurface command, not the overall script. | | SELECT {atom_exp} ONLY | Selects a specific subset of the atoms for this surface and also applies IGNORE {not atom_exp}. | | VDW radius | Atom radius relative to the van der Waals radius. Options include:
| x.x | specific absolute number of Angstroms for every atom | | +/-x.x | offset greater(+) or less(-) than the van der Waals radius | | nn% | percent of the van der Waals radius | | +/-nn% | percent offset from the van der Waals radius |
| | WITHIN x.xx {atomExpression or point} | only creates a surface within the specified distance in Angstroms from the specified atoms or point. |
[construction/mapping parameters] -- molecular orbitals back
| COLOR color1 color2 | Specifically for molecular orbitals. (for CUBE and other volume data files, use SIGN.) Specifies the two colors to use for the positive and negative lobes of a molecular orbital. Note that this and all other options in this classification must be given prior to the option that actually generates the surface. | | IGNORE {atom expression} | Specifies a set of atoms to completely ignore when generating a molecular orbital, thus showing only selected atomic contributions. | | SCALE x.xxx | In the case of molecular orbitals, scales the volume around the orbital. It may be useful in cases where Jmol misjudges the full extent of an orbital, thus truncating it. | | SELECT {atom expression} | Selects a specific subset of the atoms for this molecular orbital. (Essentially the opposite of IGNORE.) | | SIGN | For molecular orbitals derived from cube files, indicates that the data have both positive and negative values and that they should both be displayed. | | SQUARED | Data are to be squared prior to surface generation. |
[construction/mapping parameters] -- general shapes and volumetric (cube file) data back
| ANISOTROPY {a b c} | Sets the anisotropic distortion of an object in the x, y, and z directions. | | CACHE | Caches the isosurface in memory and replaces it with its JVXL equivalent. The CACHE option along with isosurface creation or alone instructs Jmol to immediately create JVXL data for the specified surface and to load that data instead. The surface remains in memory and can be used again, even after a new file is loaded using cache://isosurface_ where is the isosurface ID such as "isosurface1". The command ISOSURFACE CACHE alone will cache the current isosurface. If the cache is no longer needed, then RESET CACHE will release the memory used to hold the JVXL data for the isosurface. The result should be essentially equivalent to the original command. (It is recommended that the original be a relatively simple command, because not all nuances of an isosurface may be stored in the JVXL data.) Note that this option is not compatible with saving the state as an SPT file. Instead, use WRITE PNGJ or WRITE JMOL, in which case the cached isosurface will be saved in JVXL format within the PNGJ or JMOL zip directory. | | CENTER {x y z} | Centers an atomic orbital, sphere, ellipsoid, or lobe at a specific point in molecular space. In the case of crystal structures, these may be fractional coordinates. | | CENTER (atom_exp) | Centers an atomic orbital, sphere, ellipsoid, or lobe on a certain atom or at the geometric center of this set of atoms. | | CENTER $object | Centers an atomic orbital, sphere, ellipsoid, or lobe on a certain drawn object such as a point, line, or plane. | ECCENTRICITY
{cx cy cz f_ab} | Sets the eccentricity of a sphere, ellipsoid, atomic orbital, or lobe. The first three numbers define the "principal" axis; the fourth parameter defines the ratio of the other two perpendicular axes to this main axis. | | PHASE "type" | Indicates that an orbital or other object is to be colored based on the position of the voxel in space. With an atomic orbital and no parameters, indicates regions of (+) and (-) oribital value with different colors. Valid types include "x", "y", "z", "xy", "xz", "yz", "z2", and "x2-y2". | | SCALE x.xxx | In the case of objects for which eccentricity can apply (spheres, ellipsoids, atomic orbitals, lobes, and volumetric data), scales the object (default 1.0). |
[construction/mapping parameters] -- general file loading back
| ANGSTROMS | For a cube file or user-defined function f(x,y), indicates that the volumetric definitions are in Angstroms instead of Bohr (default). | | BLOCKDATA | Indicates that data for surfaces in multiple-surface CUBE files are in sequential blocks rather than the Gaussian standard of being interspersed, where all data values for a coordinate point are listed together. | | BOUNDBOX | Specifies that the surface to be generated must be within the currently defined boundbox. | | BOUNDBOX {atomExpression or point} {atomExpression or point} | Specifies that the surface to be generated must be within a volume defined by the specified two diagonal end points. | | COLOR DENSITY | Allowing rendering of the actual grid of numbers (volume rendering) of the data rather than an isosurface. With CUTOFF 0.0, this setting delivers the entire set of data points. It is recommended that the BOUNDBOX parameter be used with a relatively small boundbox setting or the WITHIN parameter is used in order to not have an out-of-memory condition resulting from this option. For example: boundbox scale 1.2 {tyr};isosurface color density cutoff 1.6 boundbox "3hyd_map.ccp4.gz" mesh nofill If a range of values is desired, use CUTOFF [min, max] to indicate the minimum and the maximum values to be included; for example: isosurface color density cutoff [-5,10] within 4.0 {*} "apbs.dx". | | CUTOFF x.xxx | Sets the cutoff value defining an isosurface. Typically, smaller values correspond to a larger object. Cutoffs can be either positive or negative. In the case of a molecular orbital, a positive number indicates to use both positive and negative cutoffs. Adding an explicit "+" sign before the number indicates that only the positive part of the surface is desired. (See also RMSD, below.) | | CUTOFF [min,max] | see COLOR DENSITY, above | | DEBUG | Produces voluminous detail for program debugging. | | DOWNSAMPLE n | "Downsampling" is the process by which an image or other data set is selectively sampled, producing a result that is grainier and has less resolution than the original data set. This option for the isosurface command indicates that only a portion of the data for a file should be used for the surface, creating an isosurface with lower resolution but with the full range of the original data. n is an integer -- downSample 2 uses only every other data point; downSample 3 takes only every third data point, etc. Supported for cube-based data sets only. | | FIXED/MODELBASED | Sets whether the surface generated is to be associated with the fixed window -- and thus appear with all frames/models -- or is to be associated with the currently displayed model (the default). | | FULLPLANE | for PLANE objects, indicates that color mapping should be extended to complete the plane. | | GRIDPOINTS | Adds the specific gridpoints used by the "marching cubes" algorithm for the calculation of the isosurface. Primarily for discussion and debugging of the isosurface algorithm. | | INSIDEOUT | For certain datasets it sometimes happens that the surface rendered appears inside-out (dark on the outside and bright on the inside). If this is the case, add INSIDEOUT to the isosurface command prior to specification of the file to load. Jmol will reverse the sense of what is inside and what is outside the surface. This flag only affects rendering in Jmol, not export to PovRay. | | MODEL n | Sets the identity of the model with which this isosurface is to be associated. (Defaults to the currently displayed model.) | | RESOLUTION x.x | Sets the resolution of a constructed isosurface three-dimensional grid of "voxels", in points per Angstrom. Does not apply to CUBE or JVXL files, which have a resolution defined by internal file parameters. | | RMSD x.x | Sets the cutoff based on the root mean square deviation of the data. (MRC/CCP4 file format; equivalent to SIGMA in Jmol 14.4; previous versions require SIGMA instead of RMSD, which is technically not a correct term.) | | SIGN c1 c2 | Indicates that cube data have both positive and negative values, and that they should both be displayed using the value given for CUTOFF and its negative. The two colors to use may be given optionally. | | SIGMA x.x | See RMSD, above. | | SQUARED | Data are to be squared prior to surface generation. | | SYMMETRY | Applies file-based symmetry operators to isosurface creation, resulting in more efficient creation and rendering. The default selection is {symop=1} ONLY, and default coloring is to color by symop based on the current setting of propertyColorScheme. For example: load =1stp filter "biomolecule 1";color property symop;isosurface ID sa RESOLUTION 0.8 SYMMETRY SASURFACE 0. | | WITHIN x.xx {atomExpression or point} | only creates the portion of the surface within the specified distance in Angstroms of the specified atoms or point. | | WITHIN x.xx {atomExpression or point} | only creates a surface within the specified distance in Angstroms from the specified atoms or point. | | WITHIN -x.xx {atomExpression or point} | a negative value for the WITHIN distance indicates not within x.xx Angstroms of the specified atoms or point. |
[sets and slabbing options] back
In the case of isosurfaces with artifacts or fragments or multiple independent sets of triangles in general, options MINSET, MAXSET, SET, and SUBSET specify which sets of triangles to include. CAP and SLAB allow slicing of the isosurface based on the current boundbox or unit cell, the proximity to a point, or side of a plane. Each slab or cap creates a new fragment that can be selected or unselected using the various SET options. These commands are reversible, SET 0 specifying "all sets" again, and SLAB NONE specifying "no slabbing or capping." All of these options can be given anywhere in an ISOSURFACE command or as part of any number of additional ISOSURFACE commands. They can be strung together with no punctuation: ISOSURFACE MOLECULAR;ISOSURFACE slab none slab plane x=0 cap plane y=0 cap plane z=0.
MINSET n
MAXSET n | Discard subsets of the surface that have at least n (MINSET) or fewer than n (MAXSET) triangles. | | SET n | The SET option specifies a single set of triangles composing one specific surface fragment, where n is the 1-based set number, in decreasing order of number of triangles. | | SET 0 | Reset to display all sets. | | SUBSET [i,j,k,...] | Display only the specified sets, where the numbers i, j, k, ... indicate the 1-based index of the set, in order of decreasing number of triangles. So, for example, SUBSET [1] is the same as SET 1. | | | | CAP/SLAB BOUNDBOX | CAP or SLAB along the boundaries of the current boundbox. | | CAP/SLAB UNITCELL | CAP or SLAB along the boundaries of the current unit cell. | | CAP/SLAB [plane definition] | CAP or SLAB based on a standard Jmol plane description, such as "x=3" or "xy". | | SLAB within x.y {point} | SLAB within a give distance in Angstroms from a specified point, such as or {1 0 0 -3}, or an atom, such as @10 or {protein}. | | SLAB WITHIN RANGE x.x y.y | SLAB based on the value of a mapped parameter. | | SLAB nn | SLAB dynamically at nn% of the distance from the back to the front of the isosurface. This special slab dynamically changes as the model is rotated, always slabbing based on the plane of the screen, producing a dramatic view into an isosurface regardless of the orientation of the model. | | SLAB NONE | Reset the slab, removing all results of SLAB or CAP. |
[color and contour options] back
Jmol can color isosurfaces in a wide variety of ways, from simple single colors to mapped contours based on a second data set. See also the color ISOSURFACE command for additional options and changing the color of an isosurface after creation.
| COLOR <color> | Colors an isosurface the specified color name or value, such as [xFF0000]. | | COLOR "c1 c2 c3..." | Where c1, c2, etc. are color names or values, such as red or [xFF0000] within double quotes, this option allows specification of descrete colors to be used for contour mapping. | | COLOR c1 TO c2 n | (also color isosurface ......) colors an isosurface with a range of n colors from color c1 to color c2. For example, color isosurface red to white 30. | COLOR RANGE
x.xxx y.yyy | (or color absolute) Indicates to color the specified range of value from one end to the other end of the color scheme. If numbers are not included or COLOR RANGE ALL is specified, then the minimum and maximum data values in the file are used. | | COLORSCHEME "xxx" | Sets the color scheme to one of "roygb" (default rainbow), "bgyor" (reverse rainbow), "bw" (black/white), "bwr" (blue-white-red), "rwb" (red-white-blue), "wb" (white/black), "low" (red-green), or "high" (green-blue). An optional parameter TRANSLUCENT prior to the color scheme name creates a gradient of translucency from transparent to opaque across the color scheme. An additional scheme "sets" colors the isosurface different colors for different surface fragments (for example, internal cavities). | | CONTOUR n | Specifies to display the object as a set of contour lines. Then number of lines is optional; 9 contour lines are shown by default. Using the CONTOUR keyword sets the default display to be CONTOURLINES NOFILL. Note that isosurface contour 0 "t.jvxl" will override contour selected in JVXL file. | | CONTOUR n i | Same as CONTOUR n but draws only the ith contour line. | | CONTOUR -n | With a negative number, specifies for a plane or f(x,y) object the specific single contour to depict. | CONTOUR DISCRETE
[a,b,c,d,e,...] | Sets the contour levels to discrete values. In addition, see the COLOR option, above, for the discrete coloring option. | CONTOUR INCREMENT
{from,to,step} | Sets the contour values starting with the from value to the to value in increments of step. In addition, see the COLOR option, above, for the discrete coloring option. | | REVERSECOLOR | For colorschemes in particular, the REVERSECOLOR option switches the direction of the color scheme. This parameter should be given just prior to the COLORSCHEME parameter. | | SCALE3D x.x | generates a 3D plot of the desired scale from a mapped plane. It can be introduced either with the original definition of the isosurface or later, after the plane has been created and displayed. Negative numbers invert the graph (forming valleys instead of mountains); 0 removes the 3D scaling. Note that this rendering can be combined with CONTOUR to form a 3D "topo map". |
[surface object] -- molecular/solvent surfaces back
Several isosurface options relate specifically to molecular or solvent-related surfaces.
CAVITY
cr er | Renders a depiction of a molecular cavity. The optional parameters cr and er determine the overall properties of the cavity. cr (cavity radius, default 1.2) sets the radius in Angstroms of the "probe" molecule that would fit into the cavity. er (envelope radius, default 10) sets the radius of the probe used to define the outer limits of the molecule. Smaller numbers for the cavity radius lead to more detailed cavities; smaller numbers for the envelope radius lead to cavities that are more internal and extend less toward the outer edge of the molecule. Qualifier INTERIOR CAVITY creates isosurfaces only for cavities that do not extend to the outer surface of the molecule. Qualifier POCKET CAVITY creates isosurfaces only for pockets that extend to the outer surface of the model, showing them more as troughs or open "pockets". Qualifiers MINSET , MAXSET, SET and SUBSET can all be given prior to CAVITY. | | MEP | Depicts the molecular electrostatic potential, as calculated by SUM(q_i/r_i), where q_i is the partial charge on atom i (as found in the loaded model file) and r_i is the distance from atom i to a particular point in space. The molecular electrostatic potential is not typically displayed itself. Rather, it is usually mapped onto a molecular surface. For example: isosurface resolution 6 SOLVENT map MEP produces a smooth surface at the van der Waals distance around the molecule colored by the molecular electrostatic potential. | | MOLECULAR | Same as SOLVENT 1.4, but solvent moleules are not ignored. | | SASURFACE radius | Depicts the "solvent-accessible" surface based on the currently selected atom set. This surface is described by the center of the solvent probe as it rolls along the surface. It is larger than the "molecular" surface. The radius is optional. Solvent molecules are ignored by default. If either the VDW or the IONIC keywords are present, sasurface 0 is assumed, but solvent is not ignored. | | SOLVENT radius | Depicts the "solvent-excluded" or "molecular" surface around the currently selected atoms (or the entire model if no atoms are selected). If only a subset of the atoms is selected, then only the corresponding subset of the molecular surface is depicted. This surface is defined as the surface formed by rolling a spherical solvent "probe" around the molecule at the distance of the van der Waals radii of the atoms. The specification of the radius of this probe is optional; its default setting is determined by the set radius command (Jmol default 1.2). Solvent molecules are ignored by default. |
[surface object] -- atomic and molecular orbitals back
Both atomic orbitals and molecular orbitals can be displayed in Jmol. Note that molecular orbitals in particular can be generated more effectively using the mo command rather than the isosurface command. Alternatively, the "LCAO cartoon" option creates the sort of dumbbell-shaped cartoonish orbitals seen in textbooks in discussion of pi bonding and hybridization.
ATOMICORBITAL
n l m Zeff | The Schroedinger solution to the hydrogen atom wavefunction. The three quantum numbers n, l, and m, must be such that abs(m) <= l < n. For solutions with imaginary roots, the two m values simply designate the two real linear combinations of these imaginary solutions. The optional effective nuclear charge, Zeff, determines the overall size of the orbital (default is 6, carbon). Add the keyword PHASE for a two-color orbital, which can be colored using the SIGN keyword followed by two color names or values. | ATOMICORBITAL
n l m Zeff POINTS nPoints radius seed | Creates a "pointilist" probability-based visualization of an atomic orbital using the specified number of points and optional radius extent and random seed. The radius parameter, if present, must be a decimal number. The integer setting DOTSCALE can be increased from its default value of 1 to increase the size of the displayed points. | LCAOCARTOON
"type" (atom_exp) | Draws a lobe or p orbital (two lobes) centered at the FIRST atom of the specified expression. (Typically this would be an expression for a single, specific atom, such as atomno=3). See the lcaoCartoon command for a discussion of the possible types of LCAO cartoons (as well as a simpler way to create them). | LOBE
{cx cy cz f_ab} | Draws a single tear-drop shaped object (an xy-compressed center lobe of a dz2 orbital) anywhere at any size in any direction with any amount of distortion. The first three numbers define the axis of the lobe; the fourth parameter defines its eccentricity -- the ratio of the other two perpendicular axes to this main axis. | | MO n | Denotes the n-th molecular orbital described in the file that is currently loaded. Adjusting the CUTOFF to suit the situation is recommended. Molecular orbitals are automatically bicolor; color them one specific color using COLOR and just one color name or value. RESOLUTION can be used to good effect to increase or decrease the precision of the rendering. Note that only the atom-based orbitals for the currently selected atoms are utilized. Thus, one can selectively see how atomic orbitals from each atom in the molecule are contributing to any given molecular orbital. | | MO HOMO/LUMO +/-n | Selects for display a molecular orbital based on energy-proximity to the highest-occupied or lowest-unoccupied molecular orbital. For example, isosurface MO HOMO or isosurface MO LUMO +3. | | MO ... POINTS nPoints seed | Produces a "pointilist" probability-based visualization of a molecular orbital using the specified number of points and an optional random seed. |
[surface object] -- general shapes back
There are several general shapes that can be created as "isosurfaces". These include:
ELLIPSOID
{cx cy cz f_ab} | Draws an ellipsoid having a single unique axis. The first three numbers define the "principal" axis; the fourth parameter defines the eccentricity of the ellipsoid -- the ratio of the other two perpendicular axes to this main axis. | | HKL {h k l} | Creates a plane through a crystal based on the Miller indices hkl. Adding map molecular creates a slice through the crystal highlighting atomic positions. | | PLANE | Indicates that what is desired is not really an isosurface but rather a planar slice through the data set. Using RESOLUTION 0.001 with planes allows for minimum number of triangles. Using COLOR RANGE, the range of mapped values can be changed. The range -0.008 0.008 is recommended for molecular orbitals. Planes, like other surface objects, can be mapped or left unmapped and just colored. Planes are designated using one of the methods for plane expressions. If a BOUNDBOX keyword is given prior to PLANE (see above), then the plane will be created within that box. | | SPHERE radius | Draws a sphere of the given radius in Angstroms. |
[surface object] -- file-derived isosurfaces back
Isosurfaces can be created in Jmol using external file-based "volume" or "polygon" data. Note that any of the formats that are volume data (APBS, CUBE, Chem3D, DSN6/OMAP, MRC/CCP4, XPLOR/CNS) can all be used either to generate the surface itself or (after the MAP keyword) to color a surface.
FILE "filename" n can be used in either case to depict the n-th isosurface from the specified file. Empty quotes indicate that the loaded structure file already has surface data present (CUBE files, for example, contain coordinates), and that that data should be used for construction of the surface. Thus, for example, load test.cube.gz;isosurface FILE "" will load the coordinates from the GZIPped cube file, then display its first isosurface. A default directory can be set using set defaultDirectory, and for applets a proxy server can be set for non-host file loading using set appletProxy. The keyword FILE is not required. The optional number "n" specifies which volume or surface should be used in the case of a CUBE file with multiple orbitals with multiple surfaces. All files read by Jmol may be gzip-compressed.
Isosurfaces can be created as linear combinations of volume data, provided all grids are identical. This is done using ISOSURFACE [f1, filename1, f2, filename2, ...], described below.
[surface object] -- PDB x-ray diffraction and cyro-EM surfaces back
Jmol can import x-ray diffraction and cyro-EM volume data maps from the European Bioinformatics Institute Density Server, either for full structures or for localized sets of atoms. For x-ray diffraction maps, use prefixes "=" or "*" and the PDB ID, ISOSURFACE "=2gc2", for standard (2fo-fc) maps. Use "==" or "**" for difference (fo-fc) maps -- ISOSURFACE "==2gc2". (There is no difference between "=" and "*" here; "=" and "==" are legacies from when the Uppsala server was active.) If the surface is for the currently loaded PDB model, the PDB id may be omitted or the keywords eds and edsdiff may be used directly: ISOSURFACE "=" or ISOSURFACE eds. An empty string file name also is the same as eds. Default RMSD (sigma) values for x-ray diffraction maps are +1.0 for 2fo-fc maps and +/-3.0 for fo-fc maps. The difference map option automatically sets the SIGN option, returning positive and negative differences in two colors.
Cryo-electron microscopy maps are available from EBI starting with Jmol 14.31.51. To access cryo-EM maps, use the prefix "=emdb/nnnn", where nnnn is the EMDB id number. For example: ISOSURFACE "=emdb/9357" (the cryo-EM map for 6nef). A default SIGMA 10.0 will used, which is only a guess. For a specific PDB ID, use the prefix "=em/=" and the PDB ID for the EMDB id: ISOSURFACE "=em/=6nef". This queries the EMDB for the author-suggested cutoff value and uses that as the default CUTOFF. You can override that default cutoff, though, using SIGMA or CUTOFF: ISOSURFACE CUTOFF 0.03 =em/=6nef. As for x-ray volume data, use "=em/=", "=em/", or just "=em" to indicate the volume data for the current PDB model.
The DENSITY option, ISOSURFACE DENSITY, allows either cryo-EM or x-ray diffraction data to be used, first checking if cryo-EM data is available and, if not found, then checking for x-ray data. Use ISOSURFACE "=density/=xxxx", where xxxx is a PDB ID, for a model other than the current model. Which type of map was used will be indicated in the Jmol Script Console. It is also available using the GETPROPERTY ISOSURFACE command or the getproperty("isosurfaceInfo") function or, more specifically, getProperty("isosurfaceInfo.jvxlFileTitle"), which will report the type of isosurface (2FO-FC, FO-FC, or EM) as, for example, for 6NEF, "BCifDensity reader type=EM".
A default WITHIN 2.0 {...} isosurface option is automatically applied in all of these case. These requests use a very efficient Density Server API to retrieve just the data for the volume containing the atoms specified by WITHIN (or the full current model, if WITHIN is not specified), resulting in significant speed and bandwidth improvements. If the full set of volume data is desired -- for example, the full unit cell data for x-ray diffraction, add the suffix "/full" to the filename. For example: ISOSURFACE "=em/full" or ISOSURFACE "=em/=6nef/full".
[surface object] -- volume file-derived isosurfaces back
Current volume file formats supported include:
| APBS | APBS DX volume data files | | CASTEP | CASTEP density files | | BCIF | Binary CIF volume data maps in MessagePack format served from the European Bioinformatics Institute density server. | | CUBE | Gaussian cube format volume data files. Units of Bohr are assumed unless the keyword ANGSTROMS precedes the FILE keyword. | | Chem3D | chem3d 3dxml structure files may contain volume data | | DSN6/OMAP (CCP4) | binary files used, for example, to deliver x-ray defraction and cryo-EM map data. | | GRASP/DELPHI | GRASP grid files. | | Jaguar PLT | Jaguar plt orbital files | | NCI | Jmol has support for displaying results of NCIPLOT "noncovalent interactions" calculations. See "Revealing Noncovalent Interactions", Erin R. Johnson, Shahar Keinan, Paula Mori-Sanchez, Julia Contreras-Garcia, Aron J. Cohen, and Weitao Yang, J. Am. Chem. Soc., 2010, 132, 6498-6506 and "NCIPLOT: A Program for Plotting Noncovalent Interaction Regions" Julia Contreras-Garcia, Erin R. Johnson, Shahar Keinan, Robin Chaudret, Jean-Philip Piquemal, David N. Beratan, and Weitao Yang, J. of Chemical Theory and Computation, 2011, 7, 625-632. For consistency with the mapping colors of these articles, the specific color scheme shown below is recommended. Without reading any files, the NCI keyword specifies to carry out an NCI promolecular calculation. However, if the output files from NCIPLOT are available, they can be used as well, for example: ISOSURFACE parameters [0 0 0 0 0 0.01] NCI dens.cube. Note that only the density file is required; Jmol can generate the reduced density gradient data from that density file alone. Any CUBEGEN or other format density file that Jmol can read can be used here. (The 0.01 parameter is required only when reading the density file created by NCIPLOT, because that file is scaled up by a factor of 100 relative to standard density files. If using both NCIPLOT output files, then the command is simply: ISOSURFACE parameters [0.5] grad.cube MAP dens.cube fullylit.Parameters are [cutoff, p1, p2, p3, p4, p5], described below. Zero for any parameter specifies to use the default value.
| p1 | -2 to 2 | 0(all, default), 1(intramolecular), 2(intermolecular), -1(intramolecular NCIPLOT grad/dens filtering), -2(intermolecular NCIPLOT grad/dens filtering). | | p2 | rhoMin | (min rho cutoff to remove very low density points) | | p3 | rhoPlot | (cutoff used to remove covalent density, default 0.07 for promolecular, 0.05 for SCF) | | p4 | rhoParam | (fraction of total rho that defines intramolecular, default 0.95) | | p5 | dataScaling | (default 1, but set to 0.01 to read back in NCIPLOT -dens.cube file) |
For more information, see misc/iso-nci.txt. | | MRC/CCP4 | binary AMI MAP files have the advantage that they contain information about the root mean square deviation for the data set, allowing use of the SIGMA keyword . In some cases the keyword MRC just precede the FILE keyword in order to force MRC format reading because the file does not have the expected identifying characters M A P in the proper location. | | NFF | neutral file format for electron microscopy data exported from IMOD using the ISOSURFACE command | | UHBD | University of Houston Brownian Dynamics files. | | XPLOR/CNS | XPLOR MAP files |
[surface object] -- surface data-derived isosurfaces back
Current surface file formats supported include:
| EFVET | eF-site EFVET format surface files. Indicating a number from 0-5 after the file name specifies which type of data to map onto the surface:
| 0 | color indicated in file | | 1 | electrostatic_potential | | 2 | hydrophobicity | | 3 | temperature_factor | | 4 | minimum_curvature | | 5 | maximum_curvature |
| | JVXL | Jmol Voxel format files are highly compressed surface files created by Jmol using the write command. The JVXL format allows for saving the data for a selection of a specific surface cutoff from a volume file in a way that can be delivered very efficiently over the web and loaded very quickly into Jmol. | | KINEMAGE | Jmol reads contact-point Kinemage files created by MolProbity See misc/kinemage.txt for details. | | MSMS | Jmol can read an isosurface from a set of MSMS output files. Both the .vert and the .face files must be in the same directory, or only dots will be generated. The keyword MSMS must precede the FILE keyword -- MSMS FILE "xxx.vert" -- because these files do not contain identifying information. | | OBJ | AutoDesk Wavefront Advanced Visualizer OBJ surface data files. (See also Wavefront Object format. In this case the keyword OBJ must precede the FILE keyword or the first line of the file must start with #pmesh. Jmol uses the vertex and face records of this file in order to create a set of polygons that are colored using the name of the group record, which is assumed to have the hexidecimal format g kRRGGBB. Note that Jmol does not read material (.mtl) files and so instead relies on this simpler method of assigning colors. Polygons are limited to triangles and quadrilaterals. An optional number after the file name --OBJ FILE "filename" n -- specifies a group from the OBJ file. isosurface OBJ "sample.obj" 3, for instance, reads only the third group of faces. | | PMESH | Jmol can read and write both ASCII and binary JmolPmesh surface formats. This format does not allow for colored vertices and does not shade by vertex, so it is generally appropriate for polyhedra, meshes, and contours only, not filled triangulated arbitrary surfaces. In the case of an ASCII JmolPmesh file with no header line (see below), the PMESH keyword is required. Otherwise Jmol can discern the data type from the first bytes of the file contents. A "pmesh" is a surface data set consisting of a set of vertices and a set of polygons defining the "facets" of the surface. Polygons are limited to triangles and quadrilaterals. See also PMESH INLINE, below. File formats readable by Jmol include:
| numeric pmesh | This relatively simple format can be found in 10x10pmesh.txt. Jmol reads this file in free format -- values simply need to be separated by some sort of white space.#JmolPmesh
100
3.0000 3.0000 1.0000
2.3333 3.0000 1.0000
...(98 more like this)
81
5
0
10
11
1
0
...(80 more sets like this)
- The first line identifies the file as a Jmol Pmesh file. It is optional but recommended.
- The second line defines the number of grid points defining the surface (integer, n)
- The next n lines define the Cartesian coordinates of each of the grid points (n lines of x, y, z floating point data points)
- The next line specifies the number of polygons, m, to be drawn (81 in this case). Setting this number to -1 indicates that some number of polygons follows, terminated by a polygon with 0 points indicated.
- The next m sets of numbers define the polygons. In each set, the first number, p, specifies the number of points and format for the polygon. This number may be 0 (end of polygon list), 1 (point), 2 (edge), 3 (triangle), 4 (triangle with edges marked) or 5 (quadrilateral with edges marked) or its negative. If negative, the polygon is followed by a color written as a hexadecimal or decimal integer (0xFF00FF or 16711935). The next p numbers specify indexes into the list of data points (starting with 0). The first and last of these numbers must be identical for formats 4 and 5, in order to "close" the polygon.
| | binary pmesh | A more compact binary pmesh format is described in pmesh.bin.txt. The format has the following specification:
4 bytes: P M \1 \0
4 bytes: (int) 1 (test for bigEndian)
4 bytes: (int) vertexCount
4 bytes: (int) polygonCount
64 bytes: reserved
---then for each vertex:
12 bytes: (float) x,(float) y,(float) z
---then for each polyhedron,
the number of vertices (from 1 to 4)
followed by the index of the vertex
in the vertex list, starting with 0:
[(int)nVertices,(int)v1,(int)v2,...,(int)vn]
|
|
[surface object] -- additional surface sources back
 Several additional sources of surfaces besides external files are available. For functionXY and functionXYZ, the extent and resolution of the grid can be set using the keywords ORIGIN, STEPS, and POINTS. For example, isosurface origin {-5 -5 -5} steps {0.2 0.2 0.2} points {50 50 50} functionxy = "x * y * cos(x * 100)" or isosurface cutoff 2.0 origin {-5 -5 -5} steps {0.2 0.2 0.2} points {50 50 50} functionxyz = "x * y * cos(z*100)" map functionxy = "x * y" (shown here on the right.
| FUNCTIONXY = "..." | graphs a function of x and y with a default range in x and y from -10 to 10 every 0.25 Angstroms. For example, isosurface functionXY = "x * y" | FUNCTIONXY
"functionName"
{originXYZ}
{ni xi yi zi}
{nj xj yj zj}
{nk xk yk zk} | The FUNCTIONXY keyword specifies that the Z-value at a given X,Y coordinate will be provided via a JavaScript function in the case of the applet or via a JmolStatusListener call in an application or, if the function name begins with file:, the numbers will be read from that file (relative to the current directory). The parameters mirror the parameters in the header of a CUBE file. Units of ANGSTROMS are assumed. Thus, we require an origin of the voxel space and for each nominal direction x, y, and z, the number of grid points and the direction of the unit vector along that edge. These four quantities must be in braces. In the case of the Jmol applet, there are three reading options.
| ni>0 and nj>0 | functionName(app, ix, iy) | one point is returned for each call to the function. | | ni<0 and nj>0 | functionName(app, ni, nj) | an entire set of z values separated by white space will be returned as a string. Data are read from low to high coordinates, with X changing in the outer loop (slowly) and Y changing in the inner loop: a11, a12, a13,...,a21, a22, a23,..., etc. | | ni<0 and nj<0 | functionName(app, ni, nj, Fxy) | the Fxy[-ni][-nj] array will be filled with z values in the case of the applet or functionXY(functionName, ni, nj, Fxy) will be called in the case of the application. |
If the functionName starts with the string "file:", then Z value data will be loaded from a file instead of a JavaScript function in the order described above for reading data from a returned string. | | FUNCTIONXYZ = "..." | Graphs an isosurface through a block of data defaulting to -10 to 10 Angstroms range in x, y, and z with step every 0.25 Angstroms. For example: FUNCTIONXYZ = "x * x + y + z" . | FUNCTIONXYZ
"functionName"
{originXYZ}
{ni xi yi zi}
{nj xj yj zj}
{nk xk yk zk} | Similar to FUNCTIONXY, except that in this case the X,Y,Z cube data will be provided in the order (for x = 1 to ni)(for y = 1 to nj)(for z = 1 to nk). The first two options listed for FUNCTIONXY are not available, and the signs of ni and nj are ignored. The data structure Fxyz[ni][nj][nk] must be filled with data by the function call functionName(app, ni, nj, nk, Fxyz) in the case of the applet or functionXYZ(functionName, ni, nj, nz, Fxyz) in the case of the application. | | INLINE @varName | The isosurface data may be in a variable already. For example: x = load("mydata.dat"); isosurface INLINE @x first loads the data into the variable x, then displays the isosurface from that data, possibly giving the opportunity to peek at the data first. It is advisable to reset the variable after use to improve performance, however note that the state will only be preserved if the value of the variable is left unchanged. | | PMESH INLINE "pmesh-data" | The INLINE keyword can be used with PMESH to directly create a small isosurface. Numeric pmesh data may be specified "in-line" without reference to a separate file. This is particularly useful for pmesh objects with few vertices. Note that the draw command also can be used for this purpose. |
[additional mapping-only parameters] back
If any parameters spefically relate to the mapping of the surface, not the generation of it, then they can come after the specification of the surface object. Keywords such as COLOR RANGE, CONTOUR, DEBUG, FIXED, FULLPLANE, MODELBASED, MAP, REVERSECOLOR, SCALE3D, and SELECT (when it relates to the color mapping) fall into this category.
MAP [color mapping dataset] back
Except for SPHERE, ELLIPSOID, LOBE, and LCAOCARTOON, which have no CUBE-file equivalent, all the other surface types (including FUNCTIONXY) can be used as CUBE-type data sets in order to color map another surface, because they all involve the intermediate generation of voxel data within Jmol. Used with PLANE as a surface object, a slice through a set of data can be color-contoured.The keyword MAP is optional, recommended for readability. The set isosurfacekey option displays a vertical color key that can be hovered over with the mouse to display the values associated with mapped colors and contours. Existing isosurfaces can be mapped or remapped. To do this, simply start the isosurface command with the MAP keyword (with optional ID). The keyword set MAP SQUARED indicates that the values should be squared prior to mapping . The Jmol parameter isosurfacePropertySmoothing (default TRUE) determines whether the property is smoothed out over the isourface or assigned specifically to the nearest atom.
Atom based-properties can be mapped onto a surface using one of the following options. If MEP or MEP functionType is followed by PROPERTY xxx or property_xxx or variable..., that data will be used instead of partialCharge data.
| MEP | molecular electrostatic potential, using partial charge data within the file or assigned to atoms using the {...}.partialCharge = ... or data command syntax. A standard Coulomb function is used (1/d). | | MEP functionType | allows setting the function used for the mapping as for Chime, where functionType is the number 0, 1, 2, or 3:
| 0 | 1/d | Coulomb's law distance function (same as rasmol potential distance function) | | 1 | e^(-d/2) | Gaillard, P., Carrupt, P.A., Testa, B. and Boudon, A., J.Comput.Aided Mol.Des. 8, 83-96 (1994) | | 2 | 1/(1+d) | Audry, E.; Dubost, J. P.; Colleter, J. C.; Dallet, P. A new approach to structure-activity relations: the "molecular lipophilicity potential". Eur. J. Med. Chem. 1986, 21, 71-72 | | 3 | e^(-d) | Fauchere, J. L.; Quarendon, P.; Kaetterer, L. Estimating and representing hydrophobicity potential. J. Mol. Graphics 1988, 6, 203-206. |
These additional functions thus allow Jmol to use isosurface...MAP MEP to visualize molecular lipophilic potential (MLP) as well. | | PROPERTY xxx | where xxx is an atom-based property value such as partialCharge or temperature or vanderwaals. The COLOR option applies atom-based color to an isosurface, as commonly done in PyMOL. | | property_xxxx | The linking underscore signifies that the property was provided separately using the DATA command and is not model-file based. A previous SELECT ...; DATA "property_xxxx"....end "property_xxxx" or, if the data are from a variable, SELECT...; DATA "property_xxxx @x", must have already been issued. Note that when data is created in this way, only the selected atoms are assigned data values. Atoms thus selected need not be contiguous, but the data will be read from the variable or DATA command line contiguously, disregarding spaces, tabs, line ends, and any string that would not evaluate to a number. This allows for targeting just a specific set of atoms for an isosurface and associated data. After the property name the keyword WITHIN and a distance in Angstroms can be added to speed the calculation. The default for set isosurfacePropertySmoothing FALSE is 5.0 Angstroms. | | VARIABLE x | The property is in a varible named "x", possibly from a command such as x = load("mydata.txt"). In this case, the variable must contain a value for every atom in the model, even if only a subset of the atoms is being used for the surface. |
[display options] back
Display options are indicated in the following table. These may be given at the end of the definition of the surface or in a later command having just these keywords and the identifier (or "ALL") of the desired isosurface.
| BACKSHELL/NOBACKSHELL | Opposite of FRONTONLY; displays only the back of the isosurface. | | CONTOURLINES/NOCONTOURLINES | turns on and off contour lines generated using the CONTOUR option (see bove). | | DOTS/NODOTS | Display dots at each mesh vertex point. The integer setting DOTSCALE can be increased from its default value of 1 to increase the size of these dots. | | FILL/NOFILL | Display the isosurface as a smoothly filled surface. | | FRONTONLY/NOTFRONTONLY | Display only the front half of the surface. This can be useful when the options mesh nofill are used. | | FRONTLIT /BACKLIT /FULLYLIT | In some cases the isosurface may appear flat. Using BACKLIT will fix this; FULLYLIT makes exterior and interior surfaces bright; FRONTLIT is the default setting. | | MESH/NOMESH | Display a mesh of lines intersecting at the vertexes used to construct the isosurface. | | OFFSET {x y z} | Offset the isosurface by the specified absolute amount. | | ROTATE quaternion/NONE | Rotate the isosurface by a given amount around a given axis. Rotations are about {0 0 0} and are cumulative; ROTATE NONE returns the isosurface to its original orientation. For example: isosurface s1 ROTATE @{quaternion({1 0 0}, 90)} | | ON/OFF | Turn the isosurface ON or OFF, but do not delete it. | | OPAQUE/TRANSLUCENT n | Display the isosurface as an opaque or translucent object. Several translucent options are available; see the color command. | | TRIANGLES/NOTRIANGLES | Display separated triangles (primarily for debugging purposes). |
|
Search 
View Full Database 
Index