Ribbonjr reads a Protein Data Bank (PDB) file and generates a ribbon representation of the molecule. The ribbon position and orientation are controlled by two atoms per residue: the guide atom and the twist atom. For amino acids, the guide atom is the alpha-carbon, CA, and the twist atom is the carbonyl oxygen, O. This choice of atoms makes the ribbon run approximately parallel to the peptide plane. For nucleotides, the guide atom is C5* and the twist atom is C1*. This choice makes DNA ribbons approximately perpendicular to the helical axis.
The PDB file may carry extra atom information such as color and radius in the same fashion described in the conic manual page (see COLORING THE MOLECULE). The color of the ribbon is the same as the color of the guide atoms.
*Note that when ribbonjr is used from within Chimera, the PDB-file and output-file arguments should be omitted, unless PDB-file is specified as - (which indicates standard input).
PDB files generated by some programs may not conform to the PDB standard. The utility dnacheck corrects many of the common problems found in such files. Also, for proteins, ribbonjr requires the information contained in HELIX and SHEET PDB records in order to correctly display secondary structure. The command ksdssp can be used to generate secondary structure information when it is missing.
Unless their display is explicitly suppressed with -a, non-mainchain atoms and bonds are shown as balls and sticks. Mainchain atoms are not individually depicted unless they are connected to a displayed non-mainchain atom. The mainchain atoms for amino acids are N, CA, C and O. The mainchain atoms for nucleotides are P, O1P, O2P, O3P, C5*, O5*, O3* and C3*.
The ribbon representation from ribbonjr may be in one of several formats: midas, inventor, rayshade, pov, screen, and tiff. The default is screen, even if output-file is given. To specify other formats, use -f. Screen is not actually a file format; instead, the ribbon representation is displayed directly on the screen (there is no output file). The midas format can be displayed with Midas and consists of simple commands describing objects of arbitrary connectivity. Inventor is a standard Silicon Graphics format and may be viewed using ivview, SceneViewer, or showcase. Rayshade and pov output are for use with raytracers of the same names. The midas, inventor, rayshade, and pov formats are written to output-file or sent to standard output (if output-file has not been given). Specification of output-file is required for tiff format, but the image will also be displayed on the screen.
-a
Do not display any atoms using balls and sticks. By default, all non-mainchain atoms and bonds are displayed.
-b r,g,b[,r,g,b[,r,g,b]]
Set the background color in RGB format (each component ranges from 0 to 1). If one set of RGB values is given, then the entire background is set to that color. If two sets are given, the background color is interpolated from the first to the second color starting at the top going downwards. If three sets are specified, the background color interpolates from the first color at the top of the image to the second color in the middle, to the third color at the bottom. This option is only meaningful when the output format is screen (the default; see -f for a discussion of output formats). The default background color is black (0,0,0).
-c color-scheme
Select the color scheme to use for the ribbon. Possible values of color-scheme are residue, structure, and xsection. In the residue scheme, the ribbon corresponding to a residue will have the same color as the residue's guide atom. In the structure scheme, the color is determined by the secondary structure type (helix, strand or turn); the actual colors are specified using -H -S, and -T. In the xsection scheme, the color is determined by the residue cross-section type (see -x). The default color-scheme is residue.
-d r,g,b
Set the RGB color of any dashed lines; the default is yellow (1,1,0).
-e shell-command
Execute the shell command when the image has finished drawing. Ribbonjr will not exit after executing the shell command (see -p).
-f output-format
Select the output format. The supported formats are midas, inventor, rayshade, pov, screen, and tiff. The default is screen, even if output-file is given. To specify other formats, use -f. Screen is not actually a file format; instead, the ribbon representation is displayed directly on the screen (there is no output file). The midas format can be displayed with Midas and consists of simple commands describing objects of arbitrary connectivity. Inventor is a standard Silicon Graphics format and may be viewed using ivview, SceneViewer, or showcase. Rayshade and pov output are for use with raytracers of the same names; unfortunately, due to the large triangles used to render the bicubic patches, shadows generated by these raytracers look wrong in certain places. Due to this limitation, the pov output actually turns off shadow computation. See -x for changing the cross-section file to improve the result with rayshade and pov formats. The midas, inventor, rayshade, and pov formats are written to output-file or sent to standard output (if output-file has not been given). Specification of output-file is required for tiff format, but the image will also be displayed on the screen.
-g
Display guide atoms at their true Cartesian coordinates. Normally, when atoms are displayed, guide atoms are displayed at interpolated locations on the ribbon rather than at their Cartesian coordinates, which may not be on the ribbon since the ribbon is not guaranteed to pass through the guide atom. Displaying guide atoms on the ribbon typically makes the image look better because side chains are attached to the ribbon itself rather than hanging in space.
-h
Turn off half-bond mode. Normally, bonds are drawn as two cylinders, each with the color of the closer atom. Turning off half-bond mode makes ribbonjr use half as many cylinders and speeds up calculation of the image.
-l ambient,diffuse,specular,shininess
Set the lighting parameters of ribbons, balls, and sticks. The values are the ambient, diffuse and specular reflectance, and shininess of the material, respectively. The values each range from 0 to 1 and should be separated by commas only, not spaces. The default values are 0.5, 0.5, 0.5 and 0.5.
-m draw-mode
Select the ribbon representation. Possible values of draw-mode are 3D and flat. The default, 3D, produces a Richardson-type ribbon representation. The flat mode produces two curves corresponding to the edges of a fixed-width flat ribbon and regularly spaced line segments connecting the curves.
-n
Do not draw a border around the image.
-o
Do not display any objects; by default, objects are displayed. The lines composing an object are rendered in ribbonjr as cylinders with half-spheres capping the ends. The cylinder radius can be controlled with -O.
-p
When output is in screen or tiff format (see -f) do not wait for the user to click the left mouse button on the ribbonjr window to dismiss it; instead, close the window as soon as the image is completed.
-r level
Sets the refinement level to level. The refinement level affects the output image quality and must be an integer; possible values range from 0 (the default) to 10. A higher level indicates better image quality. Increasing level causes finer sphere subdivisions, and values greater than 5 also cause the image to be antialiased using the accumulation buffer. In the process of using the accumulation buffer, the image will be drawn to the screen several times before the final image is displayed.
-s count
The ribbon is divided into count segments per residue (default 10). For interactive use in inventor format, this number should probably be set lower.
-t
Make the background color transparent. This adds an alpha channel to a tiff output file (see -f) so that the resulting image can be composited onto other backgrounds. This option may not work on some systems.
-x filename
Read cross-section information from filename in addition to the default system file. Cross-section specifications in file filename will override those from the system file. If there is no file named filename in the current directory, ribbonjr will search for the file in the system directory. The file format is described under CROSS-SECTION FILE. Several cross-section files are provided:
- xs.default - the default when no cross-section file is specified; it produces a ribbon with an elongated-ellipsoid cross-section that is smooth along the ribbon's width and length.
- xs.rayshade - appropriate for use when generating output that will then be used in a raytracer program such as rayshade or pov (see -f). The polygonal sections used to render the ribbon are much more finely subdivided than normal.
- xs.rect - describes a rectangular cross-section with sharp edges, which produces a ribbon with flat faces and sides.
- xs.ribbed - a "novelty" cross-section file. Uses an elongated ellipsoid cross-section that, instead of being smooth, is composed of a series of short flat segments. The ribbon appears similar to the default ribbon but with ribs running down the ribbon's length.
-A ball-factor
Specify the scaling factor between the VDW radius of an atom and the radius of the sphere that represents the atom in ball-and-stick mode. The default ball-factor is 0.2. For some images, -r may be needed to increase the sphere subdivision and give better-looking "balls."
-B stick-factor
Specify the scaling factor between the VDW radius of a bond's atoms and the radius of the cylinder that represents the bond in ball-and-stick mode. The default stick-factor is 0.2.
-D width,height
Specify the output window dimensions when the format is screen or tiff (see -f). The default dimensions are obtained from USER records in PDB-file (which are set to the dimensions of the graphics window when ribbonjr is used from within Chimera), or if not present in PDB-file, are set to width 645 and height 484.
-E helix-extension
When ribbonjr constructs the ribbon representation, it uses the guide atom coordinates as the basis of its control points. When using B-splines, the ribbon corresponding to a helix tends to be very slender, because the spline does not interpolate through the control points. To produce helices of a reasonable radius, the coordinates of helical guide atoms are translated a short distance away from the helical axis. When using other types of splines, the helices are not as compressed as with B-splines. The default helix-extension depends on the type of spline used to produce the ribbon (B-spline by default; see -R); it is 1.5 angstroms for B-splines and 0.5 angstroms for all other types.
-F
Use fullscreen mode. Set the image size to use the entire screen.
-G guide-fraction
When ribbonjr constructs the ribbon representation, it uses the guide atom coordinates as the basis of its control points, one per residue. For each residue, the control point is between its guide atom and the guide atom of the following residue. Normally, the control point is exactly halfway between the two guide atoms (guide-fraction 0.5). This option is most useful when the ribbon must go through the guide atoms. In this case, guide-fraction should be set to 0, helix-extension should be set to 0 (see -E), and an interpolating spline type should be selected (see -R).
-H red,green,blue
Set the helix color in the structure color scheme. The default helix color is (1,0,0). Use of this flag implicitly sets the color scheme to structure (see -c).
-J scale_factor
When using the na_sugar option (see -P), the oxygen atom in the sugar ring is artificially enlarged by scale_factor. The default scale_factor is 1.5.
-L x,y
Specify the window location when output format is screen or tiff (see -f). 0,0 is the lower left corner. If no location is specified, the user sets the screen location using the mouse when the window is created.
-N
Show normals if the output is in midas format (see -f).
-O radius
Specify the radius in angstroms of cylinders used to render certain objects (see -o). By default, these cylinders have an extremely small radius, so that they look like lines.
-P polygon_option
Display special polygons in addition to atoms, bonds, and ribbons. Two types of polygon_option are supported: na_base and na_sugar. The na_base polygons are drawn above and below the rings of the bases in nucleotides. When this option is selected, the atoms in the rings are automatically constrained to lie in a plane, in order to avoid nonplanar ring surfaces. The colors of the polygons are the same as the colors of the N1 and N9 atoms. The na_sugar polygons are drawn around the sugar rings in nucleotides. Because the five-membered sugar rings are nonplanar, each ring is covered by three triangles on either side. All three triangles have as one vertex the oxygen atom in the sugar. The oxygen can be highlighted further by artificially increasing its radius (see -J). The polygon color is the same as that of atom C1*.
-R spline-type
Ribbonjr constructs ribbons using splines that pass near or through control points, whose coordinates are based on the positions of guide atoms. Different types of splines may be used. Possible values of spline-type are bspline (default), hermite, bezier, and cardinal. See -E for more information about helical representations.
-S red,green,blue
Set the strand color in the structure color scheme. The default strand color is (0,1,0). Use of this flag implicitly sets the color scheme to structure (see -c).
-T red,green,blue
Set the turn color in the structure color scheme. The default turn color is (0,0,1). Use of this flag implicitly sets the color scheme to structure (see -c).
-W
Force Chimera to wait until ribbonjr has exited before continuing.
-Z debug-level
Specify the debug level. The output is probably somewhat cryptic.
PDB-file
PDB-file is the name of the PDB input file. See the note above. If PDB-file is not specified or is given as -, then standard input is used.
output-file
output-file is the name of the output file. See the note above. See -f for a discussion of the possible formats. If the output format is screen, output-file (if given) will be empty. If one of the other formats has been specified but no output-file has been given, the information will be sent to standard output.
The Jane Richardson-type ribbon representation uses different shapes for different secondary structure types. For example, turns are commonly represented as thin tubes, and helices and strands are represented as wide ribbons. In this case, the cross-section of a turn is a small circle, and those of helices and strands are elongated ovals. Ribbonjr reads the standard cross-section descriptions from a default file, but the user may override them by supplying a different cross-section file (see -x). Cross-sections must be defined for the types helix, strand, and turn; an arrow cross-section is optional.
The grammar for two forms of cross-section definition and the description of interfaces (between regions of different secondary structure) are shown below. Optional elements are surrounded by square brackets and user-specified values are in italics.
[ faceted | edged | segmented ] path name = {x1, y1 [ (r1, g1, b1) ]}
x2, y2 [ (r2, g2, b2) ]
...
xN, yN [ (rN, gN, bN) ]
[ faceted | edged | segmented ] spline kind(count) name = {x1, y1 [ (r1, g1, b1) ]}
x2, y2 [ (r2, g2, b2) ]
...
xN, yN [ (rN, gN, bN) ]
interpolate name1 name2
point name1 name2
The first form describes a cross-section using a connected, closed path. The name is the cross-section type, and x and y coordinates are supplied for points along the path. Each point can have a color specified by the r, g, b values on the same line (for use with the color scheme xsection; see -c). The last point of a cross-section is automatically connected to the first. Ribbonjr uses the arrow cross-section, if defined, for creating arrows at the end of strands. The cross-section file xs.rect is an example of the path form.
The second form describes a cross-section using a series of spline control points. The type of spline is given by kind, which may be one of bspline, bezier, hermite, or cardinal. The number of intermediate points generated on the spline is given by count. The name, coordinates, and colors are as described for the path form. The cross-section file xs.default is an example of the spline form.
Either form of cross-section specification may start with one of three keywords: faceted, edged, or segmented. A faceted ribbon will not be smooth along its length. As it curves, there will be edges across its width to accommodate the curvature. An edged ribbon will not be smooth around its circumference; there will be edges along its length. A segmented ribbon will combine the features of a faceted and edged ribbon. It would seem more descriptively natural to interchange the the faceted and segmented keywords, but unfortunately (due to backwards compatibility issues) the keywords are as described.
When ribbonjr reads in the PDB file, it automatically assigns residue cross-section types based on secondary structure. The user may override these cross-section type assignments by supplying USER XSECTION records in the PDB input.
The third form in the grammar specifies how the cross-section changes from name1 to name2 (for example, from turn to strand). Unless otherwise specified, the change is abrupt. Interpolate indicates a linear change from the name1 cross-section to the name2 cross-section. Note that the name1 and name2 cross-sections must have the same number of (x,y) points in their definitions. Point indicates a linear interpolation from the name1 cross-section to the turn cross-section and then an abrupt change to the name2 cross-section. This method is usually used for arrow-to-strand and arrow-to-helix transitions.
ribbonjr interprets several USER records, including FLIP, XSECTION and NORIBBON. The FLIP record specifies a residue whose orientation should not be computed in the standard way. Ribbonjr orients a residue by defining both a direction and a normal vector. The direction is defined by the vector from the guide atom of the previous residue to the guide atom of the next residue. The normal vector is defined as perpendicular to the direction and in the peptide plane defined by the previous residue and the current one; the normal vector is also constrained to be less than 90 degrees from the normal vector of the previous residue. If the current residue is FLIPped, however, its normal vector is replaced by the opposite vector. The XSECTION record specifies the cross-section type for a range of residues. For further information about cross-section types, see -x and the description under CROSS-SECTION FILE. The NORIBBON record specifies a range of residues which should be drawn as balls and sticks rather than ribbon.
The alignment of the residue information in these USER records is the same as in a standard HELIX record:
HELIX 1 A PHE 6 LEU 26 1 USER FLIP PHE 6 USER XSECTION PHE 6 LEU 26 helix USER NORIBBON PHE 6 LEU 26