Provided by: libace-perl_1.92-7_amd64 bug

NAME

       Ace::Graphics::Panel - PNG graphics of Ace::Sequence::Feature objects

SYNOPSIS

         use Ace::Sequence;
         use Ace::Graphics::Panel;

         my $db     = Ace->connect(-host=>'brie2.cshl.org',-port=>2005) or die;
         my $cosmid = Ace::Sequence->new(-seq=>'Y16B4A',
                                         -db=>$db,-start=>-15000,-end=>15000) or die;

         my @transcripts = $cosmid->transcripts;

         my $panel = Ace::Graphics::Panel->new(
                                             -segment => $cosmid,
                                             -width  => 800
                                            );

         $panel->add_track(arrow => $cosmid,
                         -bump => 0,
                         -tick=>2);

         $panel->add_track(transcript => \@transcripts,
                           -fillcolor =>  'wheat',
                           -fgcolor   =>  'black',
                           -key       => 'Curated Genes',
                           -bump      =>  +1,
                           -height    =>  10,
                           -label     =>  1);

         my $boxes = $panel->boxes;
         print $panel->png;

DESCRIPTION

       The Ace::Graphics::Panel class provides drawing and formatting services for
       Ace::Sequence::Feature objects or Das::Segment::Feature objects.

       Typically you will begin by creating a new Ace::Graphics::Panel object, passing it the
       width of the visual display and the length of the segment.

       You will then call add_track() one or more times to add sets of related features to the
       picture.  When you have added all the features you desire, you may call png() to convert
       the image into a PNG-format image, or boxes() to return coordinate information that can be
       used to create an imagemap.

       Note that this modules depends on GD.

METHODS

       This section describes the class and object methods for Ace::Graphics::Panel.

   CONSTRUCTORS
       There is only one constructor, the new() method.

       $panel = Ace::Graphics::Panel->new(@options)
           The new() method creates a new panel object.  The options are a set of tag/value pairs
           as follows:

             Option      Value                                Default
             ------      -----                                -------

             -length     Length of sequence segment, in bp    0

             -segment    An Ace::Sequence or Das::Segment     none
                         object, used to derive length if
                         not provided

             -offset     Base pair to place at extreme left   $segment->start
                         of image.

             -width      Desired width of image, in pixels    600

             -spacing    Spacing between tracks, in pixels    5

             -pad_top    Additional whitespace between top    0
                         of image and contents, in pixels

             -pad_bottom Additional whitespace between top    0
                         of image and bottom, in pixels

             -pad_left   Additional whitespace between left   0
                         of image and contents, in pixels

             -pad_right  Additional whitespace between right  0
                         of image and bottom, in pixels

             -keycolor   Background color for the key printed 'cornsilk'
                         at bottom of panel (if any)

             -keyspacing Spacing between key glyphs in the    10
                         key printed at bottom of panel
                         (if any)

           Typically you will pass new() an object that implements the Bio::RangeI interface,
           providing a length() method, from which the panel will derive its scale.

             $panel = Ace::Graphics::Panel->new(-segment => $sequence,
                                                -width   => 800);

           new() will return undef in case of an error. If the specified glyph name is not a
           valid one, new() will throw an exception.

   OBJECT METHODS
       $track = $panel->add_track($glyph,$features,@options)
           The add_track() method adds a new track to the image.

           Tracks are horizontal bands which span the entire width of the panel.  Each track
           contains a number of graphical elements called "glyphs", each corresponding to a
           sequence feature. There are different glyph types, but each track can only contain a
           single type of glyph.  Options passed to the track control the color and size of the
           glyphs, whether they are allowed to overlap, and other formatting attributes.  The
           height of a track is determined from its contents and cannot be directly influenced.

           The first two arguments are the glyph name and an array reference containing the list
           of features to display.  The order of the arguments is irrelevant, allowing either of
           these idioms:

             $panel->add_track(arrow => \@features);
             $panel->add_track(\@features => 'arrow');

           The glyph name indicates how each feature is to be rendered.  A variety of glyphs are
           available, and the number is growing.  Currently, the following glyphs are available:

             Name        Description
             ----        -----------

             box         A filled rectangle, nondirectional.

             ellipse     A filled ellipse, nondirectional.

             arrow       An arrow; can be unidirectional or bidirectional.
                         It is also capable of displaying a scale with
                         major and minor tickmarks, and can be oriented
                         horizontally or vertically.

             segments    A set of filled rectangles connected by solid lines.
                         Used for interrupted features, such as gapped
                         alignments.

             transcript  Similar to segments, but the connecting line is
                         a "hat" shape, and the direction of transcription
                         is indicated by a small arrow.

             transcript2 Similar to transcript, but the arrow that indicates
                         the direction of transcription is the last exon
                         itself.

             primers     Two inward pointing arrows connected by a line.
                         Used for STSs.

             toomany     A "cloud", to indicate too many features to show
                         individually.  This is a placeholder that will be
                         replaced by something more clever, such as a histogram
                         or density plot.

             group       A group of related features connected by a dashed line.
                         This is used internally by the Track class and should
                         not be called explicitly.

           If the glyph name is omitted from add_track(), the "box" glyph will be used by
           default.

           The @options array is a list of name/value pairs that control the attributes of the
           track.  The options are in turn passed to the glyphs.  Each glyph has its own
           specialized subset of options, but some are shared by all glyphs:

             Option      Description               Default
             ------      -----------               -------

             -glyph      Glyph to use              none

             -fgcolor    Foreground color          black

             -outlinecolor                         black
                         Synonym for -fgcolor

             -bgcolor    Background color          white

             -fillcolor  Interior color of filled  turquoise
                         images

             -linewidth  Width of lines drawn by   1
                               glyph

             -height     Height of glyph           10

             -font       Glyph font                gdSmallFont

             -label      Whether to draw a label   false

             -bump       Bump direction            0

             -connect_groups                       false
                         Connect groups by a
                         dashed line (see below)

             -key        Show this track in the    undef
                         key

           Colors can be expressed in either of two ways: as symbolic names such as "cyan" and as
           HTML-style #RRGGBB triples.  The symbolic names are the 140 colors defined in the
           Netscape/Internet Explorer color cube, and can be retrieved using the
           Ace::Graphics::Panel->color_names() method.

           The background color is used for the background color of the track itself.  The
           foreground color controls the color of lines and strings.  The interior color is used
           for filled objects such as boxes.

           The -label argument controls whether or not the ID of the feature should be printed
           next to the feature.  It is accepted by most, but not all of the glyphs.

           The -bump argument controls what happens when glyphs collide.  By default, they will
           simply overlap (value 0).  A -bump value of +1 will cause overlapping glyphs to bump
           downwards until there is room for them.  A -bump value of -1 will cause overlapping
           glyphs to bump upwards.

           The -key argument declares that the track is to be shown in a key appended to the
           bottom of the image.  The key contains a picture of a glyph and a label describing
           what the glyph means.  The label is specified in the argument to -key.

           If present, the -glyph argument overrides the glyph given in the first or second
           argument.

           add_track() returns an Ace::Graphics::Track object.  You can use this object to add
           additional features or to control the appearance of the track with greater detail, or
           just ignore it.  Tracks are added in order from the top of the image to the bottom.
           To add tracks to the top of the image, use unshift_track().

           Typical usage is:

            $panel->add_track( thistle    => \@genes,
                               -fillcolor =>  'green',
                               -fgcolor   =>  'black',
                               -bump      =>  +1,
                               -height    => 10,
                               -label     => 1);

       $track = unshift_track($glyph,$features,@options)
           unshift_track() works like add_track(), except that the new track is added to the top
           of the image rather than the bottom.

           Adding groups of features: It is not uncommon to add a group of features which are
           logically connected, such as the 5' and 3' ends of EST reads.  To group features into
           sets that remain on the same horizontal position and bump together, pass the sets as
           an anonymous array.  To connect the groups by a dashed line, pass the -connect_groups
           argument with a true value.  For example:

             $panel->add_track(segments => [[$abc_5,$abc_3],
                                            [$xxx_5,$xxx_3],
                                            [$yyy_5,$yyy_3]],
                               -connect_groups => 1);

       $gd = $panel->gd
           The gd() method lays out the image and returns a GD::Image object containing it.  You
           may then call the GD::Image object's png() or jpeg() methods to get the image data.

       $png = $panel->png
           The png() method returns the image as a PNG-format drawing, without the intermediate
           step of returning a GD::Image object.

       $boxes = $panel->boxes
       @boxes = $panel->boxes
           The boxes() method returns the coordinates of each glyph, useful for constructing an
           image map.  In a scalar context, boxes() returns an array ref.  In an list context,
           the method returns the array directly.

           Each member of the list is an anonymous array of the following format:

             [ $feature, $x1, $y1, $x2, $y2 ]

           The first element is the feature object; either an Ace::Sequence::Feature, a
           Das::Segment::Feature, or another Bioperl Bio::SeqFeatureI object.  The coordinates
           are the topleft and bottomright corners of the glyph, including any space allocated
           for labels.

   ACCESSORS
       The following accessor methods provide access to various attributes of the panel object.
       Called with no arguments, they each return the current value of the attribute.  Called
       with a single argument, they set the attribute and return its previous value.

       Note that in most cases you must change attributes prior to invoking gd(), png() or
       boxes().  These three methods all invoke an internal layout() method which places the
       tracks and the glyphs within them, and then caches the result.

          Accessor Name      Description
          -------------      -----------

          width()            Get/set width of panel
          spacing()          Get/set spacing between tracks
          length()           Get/set length of segment (bp)
          pad_top()          Get/set top padding
          pad_left()         Get/set left padding
          pad_bottom()       Get/set bottom padding
          pad_right()        Get/set right padding

   INTERNAL METHODS
       The following methods are used internally, but may be useful for those implementing new
       glyph types.

       @names = Ace::Graphics::Panel->color_names
           Return the symbolic names of the colors recognized by the panel object.  In a scalar
           context, returns an array reference.

       @rgb = $panel->rgb($index)
           Given a GD color index (between 0 and 140), returns the RGB triplet corresponding to
           this index.  This method is only useful within a glyph's draw() routine, after the
           panel has allocated a GD::Image and is populating it.

       $index = $panel->translate($color)
           Given a color, returns the GD::Image index.  The color may be symbolic, such as
           "turquoise", or a #RRGGBB triple, as in #F0E0A8.  This method is only useful within a
           glyph's draw() routine, after the panel has allocated a GD::Image and is populating
           it.

       $panel->set_pen($width,$color)
           Changes the width and color of the GD drawing pen to the values indicated.  This is
           called automatically by the GlyphFactory fgcolor() method.

BUGS

       Please report them.

SEE ALSO

       Ace::Sequence,Ace::Sequence::Feature, Ace::Graphics::Track,Ace::Graphics::Glyph, GD

AUTHOR

       Lincoln Stein <lstein@cshl.org>.

       Copyright (c) 2001 Cold Spring Harbor Laboratory

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.  See DISCLAIMER.txt for disclaimers of warranty.