view release on metacpan or  search on metacpan

lib/Bio/Graphics/Panel.pm  view on Meta::CPAN

  -background  An image or callback to use for the   none
               background of the image. Will be
               invoked I<before> drawing the grid.

  -postgrid    An image or callback to use for the   none
               background of the image.  Will be 
               invoked I<after> drawing the grid.

  -truecolor   Create a truecolor (24-bit) image.    false
               Useful when working with the
               "image" glyph.

  -truetype    Render text using scaleable vector    false
               fonts rather than bitmap fonts.

  -image_class To create output in scalable vector
               graphics (SVG), optionally pass the image
               class parameter 'GD::SVG'. Defaults to
               using vanilla GD. See the corresponding
               image_class() method below for details.

  -link, -title, -target
               These options are used when creating imagemaps
               for display on the web.  See L</"Creating Imagemaps">.


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 = Bio::Graphics::Panel->new(-segment => $sequence,
				     -width   => 800);

new() will return undef in case of an error.

Note that if you use the "left" or "right" key styles, you are
responsible for allocating sufficient -pad_left or -pad_right room for
the labels to appear.  The necessary width is the number of characters
in the longest key times the font width (gdMediumBoldFont by default)
plus 3 pixels of internal padding.  The simplest way to calculate this
is to iterate over the possible track labels, find the largest one,
and then to compute its width using the formula:

  $width = gdMediumBoldFont->width * length($longest_key) +3;

In order to obtain scalable vector graphics (SVG) output, you should
pass new() the -image_class=E<gt>'GD::SVG' parameter. This will cause
Bio::Graphics::Panel to load the optional GD::SVG module. See the gd()
and svg() methods below for additional information.

You can tile an image onto the panel either before or after it draws
the grid. Simply provide the filename of the image in the -background
or -postgrid options. The image file must be of type PNG, JPEG, XBM or
GIF and have a filename ending in .png, .jpg, .jpeg, .xbm or .gif.

You can also pass a code ref for the -background or -postgrid option,
in which case the subroutine will be invoked at the appropriate time
with the GD::Image object and the Panel object as its two arguments.
You can then use the panel methods to map base pair coordinates into
pixel coordinates and do some custom drawing.  For example, this code
fragment will draw a gray rectangle between bases 500 and 600 to
indicate a "gap" in the sequence:

  my $panel = Bio::Graphics::Panel->new(-segment=>$segment,
                                        -grid=>1,
                                        -width=>600,
                                        -postgrid=> \&draw_gap);
  sub gap_it {
     my $gd    = shift;
     my $panel = shift;
     my ($gap_start,$gap_end) = $panel->location2pixel(500,600);
     my $top                  = $panel->top;
     my $bottom               = $panel->bottom;
     my $gray                 = $panel->translate_color('gray');
     $gd->filledRectangle($gap_start,$top,$gap_end,$bottom,$gray);
}

The B<-truetype> argument will activate rendering of labels using
antialiased vector fonts. If it is a value of "1", then labels will be
rendered using the default font (Verdana). Pass a font name to use
this font as the default:

  -truetype => 'Times New Roman',

Note that you can change the font on a track-by-track basis simply by
using a truetype font name as add_track()'s -font argument.

=back

=head2 OBJECT METHODS

=over 4

=item $track = $panel-E<gt>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",
corresponding to a sequence feature. 

There are a large number of glyph types.  By default, each track will
be homogeneous on a single glyph type, but you can mix several glyph
types on the same track by providing a code reference to the -glyph
argument.  Other options passed to add_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. You may
omit the glyph name entirely by providing a B<-glyph> argument among
@options, as described below.

lib/Bio/Graphics/Panel.pm  view on Meta::CPAN

=over 4

=item @names = Bio::Graphics::Panel-E<gt>color_names

Return the symbolic names of the colors recognized by the panel
object.  In a scalar context, returns an array reference.

=item ($red,$green,$blue) = Bio::Graphics::Panel-E<gt>color_name_to_rgb($color)

Given a symbolic color name, returns the red, green, blue components
of the color.  In a scalar context, returns an array reference to the
rgb triplet.  Returns undef for an invalid color name.

=item @rgb = $panel-E<gt>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-E<gt>translate_color($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.

=item $panel-E<gt>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.  It returns the GD value gdBrushed, which should be used for
drawing.

=back

=head2 Creating Imagemaps

You may wish to use Bio::Graphics to create clickable imagemaps for
display on the web.  The main method for achieving this is
image_and_map().  Under special circumstances you may instead wish to
call either or both of create_web_image() and create_web_map().

Here is a synopsis of how to use image_and_map() in a CGI script,
using CGI.pm calls to provide the HTML scaffolding:

   print h2('My Genome');

   my ($url,$map,$mapname) =
       $panel->image_and_map(-root => '/var/www/html',
                             -url  => '/tmpimages',
                             -link => 'http://www.google.com/search?q=$name');

   print img({-src=>$url,-usemap=>"#$mapname"});

   print $map;

We call image_and_map() with various arguments (described below) to
generate a three element list consisting of the URL at which the image
can be accessed, an HTML fragment containing the clickable imagemap
data, and the name of the map.  We print out an E<lt>imageE<gt> tag
that uses the URL of the map as its src attribute and the name of the
map as the value of its usemap attribute.  It is important to note
that we must put a "#" in front of the name of the map in order to
indicate that the map can be found in the same document as the
E<lt>imageE<gt> tag.  Lastly, we print out the map itself.

=over 4

=item ($url,$map,$mapname) = $panel-E<gt>image_and_map(@options)

Create the image in a web-accessible directory and return its URL, its
clickable imagemap, and the name of the imagemap.  The following
options are recognized:

 Option        Description
 ------        -----------

 -url          The URL to store the image at.


 -root         The directory path that should be appended to the
               start of -url in order to obtain a physical
               directory path.
 -link         A string pattern or coderef that will be used to
               generate the outgoing hypertext links for the imagemap.

 -title        A string pattern or coderef that will be used to
               generate the "title" tags of each element in the imagemap
               (these appear as popup hint boxes in certain browsers).

 -target       A string pattern or coderef that will be used to
               generate the window target for each element.  This can
               be used to pop up a new window when the user clicks on
               an element.

 -mapname      The name to use for the E<lt>mapE<gt> tag.  If not provided,
               a unique one will be autogenerated for you.

This method returns a three element list consisting of the URL at
which the image has been written to, the imagemap HTML, and the name
of the map.  Usually you will incorporate this information into an
HTML document like so:

  my ($url,$map,$mapname) =
          $panel->image_and_map(-link=>'http://www.google.com/search?q=$name');
  print qq(<img src="$url" usemap="#$mapname">),"\n";
  print $map,"\n";

=item $url = $panel-E<gt>create_web_image($url,$root)

Create the image, write it into the directory indicated by
concatenating $root and $url (i.e. "$root/$url"), and return $url.

=item $map = $panel-E<gt>create_web_map('mapname',$linkrule,$titlerule,$targetrule)

Create a clickable imagemap named "mapname" using the indicated rules
to generate the hypertext links, the element titles, and the window
targets for the graphical elements.  Return the HTML for the map,
including the enclosing E<lt>mapE<gt> tag itself.