RIBBONJR(1)
NAME
- ribbonjr - generate ribbon representation of proteins or
nucleic acids
SYNOPSIS
- ribbonjr [ options ] [ PDB-file [ output-file ] ]
DESCRIPTION
- Ribbonjr reads a Protein Data Bank file and generates a
ribbon representation of the molecule. The ribbon position
and orientation are controlled by two atoms: the guide atom
and the twist atom. For amino acids, the guide atom is the
A-carbon and the twist atom is the carbonyl oxygen. 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(1)
manual page (under section ``Coloring the Molecule''). The
color of the ribbon is the same as the color of the guide
atoms. If no PDB file is specified or ``-'' is provided as
the PDB file name, then standard input is used.
- PDB files generated by some programs may not conform to the
PDB standard. The utility dnacheck(1), provided with the
MidasPlus distribution, corrects many of the common problems
found in such files. Consult the dnacheck manual page for
further details. Also, for proteins, ribbonjr requires the
information contained in HELIX and SHEET PDB records in
order to correctly display secondary structure. If a PDB
file lacks such records, the ksdssp(1) utility can be used
to generate the records. The ksdssp manual page contains
further details.
- Unless their display is explicitly suppressed with the -a
command line option, 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 bonds are derived
either from CONECT records if they exist in the PDB file, or
from drawing templates found in MIDAS template directories.
- The ribbon representation from ribbonjr may be in one of
several formats: midas, inventor, rayshade, pov, screen,
and tiff. MIDAS object format is described in detail under
``Non-Molecule Graphics Objects'' in Part III of the
MidasPlus manual. Inventor format is the standard Silicon
Graphics format; inventor output may be viewed using
ivview(1), SceneViewer(1), or showcase(1). Rayshade and pov
output are for use with raytracers of the same name. The
format description may be found with in the raytracer
documentation. Screen is not actually a file format;
instead, the ribbon representation is displayed directly on
screen using the OpenGL or Silicon Graphics GL library:
there is no ``output file.'' Tiff output requires that an
output file be specified (though it needs to use the screen
to calculate the image). The default output format is
screen, even if an output file is specified (except on
NEXTSTEP systems, where neither screen nor tiff formats are
supported). To use other formats, use the -f command line
flag (see below).
- ``Capturing Screen Images'' in Part III of the MidasPlus
manual discusses saving, converting, and printing ribbonjr
images.
COMMAND-LINE FLAGS
- The command-line flags interpreted by ribbonjr are:
- -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 between 0 and 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 background color is black (0,0,0).
- -c color-scheme
- Select the color scheme to use for the ribbon. The
supported color schemes 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 the -H, -S, and -T flags (see below).
In the xsection scheme, the color is determined by the
residue cross-section type (see -x flag below). The
default color scheme is residue.
- -e shell-command
- Execute the shell command when the image has finished
drawing. Ribbonjr will not exit after executing the
shell command (see the -p flag below).
- -f output-format
- Select the output format. The supported formats are
midas, inventor, rayshade, pov, screen, and tiff. The
default output format is screen (or midas if drawing to
the screen is not supported on the system, e.g.,
NEXTSTEP systems). The rayshade and pov formats are
input to widely available raytracers (see also -x
option). 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.
- -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, making interactive performance
considerably better.
- -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.
All values should be between 0 and 1. The default
values are 0.5, 0.5, 0.5 and 0.5 respectively.
- -m draw-mode
- Select the ribbon representation. The supported modes
are 3D and flat. The 3D mode produces Jane
Richardson-type ribbon representation of the molecule.
The flat mode produces two curves corresponding to the
edges of a fixed-width flat ribbon, and regularly
spaced line segments connecting the curves. The
default representation is 3D.
- -n
- Do not draw a border around the image.
- -o
- Do not display any MIDAS graphics objects present in
- the input. By default, MIDAS objects are displayed.
The lines composing the object are rendered in ribbonjr
as cylinders with half-spheres capping the ends. By
default, these cylinders have an extremely small
radius, so that they look like lines. The cylinder
radius can be controlled with the -O flag.
- -p
- When output is in screen or tiff format, do not wait
for the user to click the mouse button. By default,
the user must click the left mouse button before the
ribbonjr window is closed.
- -r level
- Sets the refinement level to level . The refinement
level affects the output quality from ribbonjr. The
level ranges from 0 to 10, with the default being 0.
The higher the level number, the better the quality.
Levels greater than zero increase the sphere
subdivision and levels greater than 5 cause the image
to be antialiased using the accumulation buffer as
well. 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
- Select the number of segments used to represent one
residue. By default, the ribbon for a residue is
divided into 10 segments. For interactive use in
Inventor format, this number should probably be set
lower.
- -t
- Make the background color transparent. This works with
the tiff format to add an alpha channel to the file, so
the resulting image can be composited onto other
backgrounds. This option depends on OpenGL support for
``destination alpha'' and consequently does not work on
all 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 cross-
section file format is described in the CROSS-SECTION
FILE section, below.
- Several cross-section files are provided in the
ribbonjr system directory. They are:
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 - a cross-section file appropriate for use
when generating output that will then be used in a
ray-tracer program such as pov or rayshade. The
polygonal sections used to render the ribbon are much
more finely subdivided than normal.
xs.rect - a rectangular cross-section with sharp edges.
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 scale-factor
- Specify the scale factor between the radius of an atom
and the radius of the sphere that represents the atom
in ball-and-stick mode. The default scale factor is
0.2. For some images, you may also want to use the -r
option to increase the sphere subdivision and thereby
get better-looking ``balls.''
- -B scale-factor
- Specify the scale factor between the radius of a bond's
atoms and the radius of the cylinder that represents
the bond in ball-and-stick mode. The default scale
factor is 0.2. For some images, you may also want to
use the -r option to increase the sphere subdivision
and thereby get better-looking ``balls.''
- -D width,height
- Specify the window dimensions when output format is
screen or tiff. The default dimensions are obtained
from USER records in the PDB input file. If no
dimensions are specified in the PDB file, they are set
to 645x484.
- -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 by a short distance away from the helical
axis. When using other types of splines, the helices
are not as compressed as using B-splines. The default
extension depends on the type of spline used to produce
the ribbon (see -R flag below). The default extension
is 1.5 angstrom for B-splines and 0.5 angstroms for all
other types.
- -F
- Use full screen 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, the guide fraction should be set to zero,
the helix extension (see -E flag above) should be set
to zero, and an interpolating spline type (see -R flag
below) should be selected.
- -H red,green,blue
- Set the helix color in color scheme structure. The
default helix color is (1,0,0). Use of this flag
implicitly sets color-scheme to structure (see the -c
flag).
- -J scale_factor
- When using the na_sugar option (see -P below), 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. 0,0 is the lower left corner. If no
location is specified, the user gets to choose the
screen location using the mouse when the window is
created.
- -N
- Show normals if output is in midas format.
- -O radius
- Specify the radius of cylinders, in angstroms, used to
render MIDAS graphics objects (see the -o flag).
- -P polygon_option
- Display special polygons in addition to atoms, bonds,
and ribbons. Currently two types of special polygons
are supported: na_base and na_sugar. The na_base
polygons are polygons 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 polygons 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 above). 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. The supported types are
bspline, hermite, bezier, and cardinal. The default
spline type is bspline. See the -E flag above for more
information about helical representation.
- -S red,green,blue
- Set the strand color in color scheme structure. The
default strand color is (0,1,0). Use of this flag
implicitly sets color-scheme to structure (see the -c
flag).
- -T red,green,blue
- Set the turn color in color scheme structure. The
default turn color is (0,0,1). Use of this flag
implicitly sets color-scheme to structure (see the -c
flag).
- -W
- Force MIDAS to wait until ribbonjr has exited before
continuing.
- -Z debug-level
- Specify the debug level. The output is probably
somewhat cryptic.
CROSS-SECTION FILE
- 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
his own cross-section file (see the -x command-line flag).
- The grammar for cross-section and interface descriptions is
shown below (optional elements are surrounded by square
brackets and user-selected 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 of the cross-section type is name,
and the list of coordinates are supplied in x and y. Name
must start with an alphabetic character and can only contain
alphanumeric characters, ``_'' (underscore), and ``.''
(period). Each coordinate also optionally has a color,
whose value is specified by r, g, and b, associated with it
(for use with xsection color scheme - see the -c flag). The
last coordinate of a cross-section is automatically
connected to the first coordinate by ribbonjr. 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 the
same as in the path specification.
- Both cross-section specifications may be prefixed by 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.
- Three types of cross-sections must be defined in a cross-
section file: helix, strand, and turn. Ribbonjr also uses
the cross-section type arrow for creating arrows at the end
of strands if it is defined. 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 XSECTION USER
records in the PDB file (see below).
The third form in the grammar specifies how cross-section
type changes from name1 to name2 should take place.
Normally, when the cross-section type changes, the ribbon
abruptly changes from one type to the other. If interpolate
is specified, however, the cross-section linearly changes
from name1 to name2. This is useful for presenting a smooth
transition between different cross-section types, such as
from strand to turn. Note that name1 and name2 cross-
section types must have the same number of coordinates in
their specifications. If point is specified, the cross-
section is linearly interpolated from type name1 to type
turn, and then abruptly changes to type name2. This
transition method is usually used with name1 being arrow and
name2 being strand or helix.
PDB USER RECORDS
In addition to the USER records that MIDAS uses, ribbonjr
also interprets several of its own: 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 its opposite vector. The XSECTION record
specifies the cross-section type for a range of residues.
For further information about cross section types, refer to
the preceding description of the -x command line flag, and
the CROSS-SECTION FILE section of this manual page. The
NORIBBON record specifies a range of residues which should
not have a ribbon representation (i.e., they will be drawn
as balls and sticks).
- The alignment of the residue information in these USER
records are exactly the same as those on a HELIX record.
Examples of these USER records are below, with a standard
HELIX record present as a reference record.
HELIX 1 A PHE 6 LEU 26 1
USER FLIP PHE 6
USER XSECTION PHE 6 LEU 26 xsection-type
USER NORIBBON PHE 6 LEU 26
EXAMPLES
The demonstration images included on the MidasPlus
distribution CD show how to achieve a variety of striking
effects and give detailed instructions on how each image was
made. If these demonstration images have been installed on
your system, they will be found in
/usr/local/midas/demos/images. The README.index file there
has further information. If the demonstration images have
not been installed on your system, you need to mount the
distribution CD-ROM, and you will find the images in the
CD-ROM directory Midas-2.1/demos/images.
SEE ALSO
- Carson, M. and Bugg, C.E., Algorithm for ribbon models of
proteins, Journal of Molecular Graphics, Vol 4 (1986) pp
121-122.
conic(1), dnacheck(1), ksdssp(1), midas(1), showcase(1).
BUGS
- Residues with ring structures on the mainchain may not be
depicted correctly.
FILES
/usr/local/midas/resource/ribbonjr/xs.default - default
cross-section file
/usr/local/midas/resource/midas/models/*.ins - default
residue drawing templates
AUTHORS
- Conrad Huang
- UCSF Computer Graphics Laboratory