view release on metacpan or  search on metacpan

Ace/Graphics/Panel.pm  view on Meta::CPAN

thistle              D8           BF            D8
tomato               FF           63            47
turquoise            40           E0            D0
violet               EE           82            EE
wheat                F5           DE            B3
whitesmoke           F5           F5            F5
yellow               FF           FF            00
yellowgreen          9A           CD            32
__END__

=head1 NAME

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

=head1 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;

=head1 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.

=head1 METHODS

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

=head2 CONSTRUCTORS

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

=over 4

=item $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);

Ace/Graphics/Panel.pm  view on Meta::CPAN

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);

=item $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.

B<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);

=item $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.

=item $png = $panel->png

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

=item $boxes = $panel->boxes

=item @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.

=back

=head2 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

=head2 INTERNAL METHODS

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

=over 4

=item @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.

=item @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.

=item $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.