view release on metacpan or  search on metacpan

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

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.

=back

To use this method effectively, you will need a web server and an
image directory in the document tree that is writable by the web
server user.  For example, if your web server's document root is
located at /var/www/html, you might want to create a directory named
"tmpimages" for this purpose:

  mkdir /var/www/html/tmpimages
  chmod 1777 /var/www/html/tmpimages

The 1777 privilege will allow anyone to create files and
subdirectories in this directory, but only the owner of the file will
be able to delete it.

When you call image_and_map(), you must provide it with two vital
pieces of information: the URL of the image directory and the physical
location of the web server's document tree.  In our example, you would
call:

  $panel->image_and_map(-root => '/var/www/html',-url=>'/tmpimages');

If you are working with virtual hosts, you might wish to provide the
hostname:portnumber part of the URL.  This will work just as well:

  $panel->image_and_map(-root => '/var/www/html',
                        -url  => 'http://myhost.com:8080/tmpimages');

If you do not provide the -root argument, the method will try to
figure it out from the DOCUMENT_ROOT environment variable.  If you do
not provide the -url argument, the method will assume "/tmp".

During execution, the image_and_map() method will generate a unique
name for the image using the Digest::MD5 module.  You can get this
module on CPAN and it B<must> be installed in order to use
image_and_map().  The imagename will be a long hexadecimal string such
as "e7457643f12d413f20843d4030c197c6.png".  Its URL will be
/tmpimages/e7457643f12d413f20843d4030c197c6.png, and its physical path
will be /var/www/html/tmpimages/e7457643f12d413f20843d4030c197c6.png

In addition to providing directory information, you must also tell
image_and_map() how to create outgoing links for each graphical
feature, and, optionally, how to create the "hover title" (the popup
yellow box displayed by most modern browsers), and the name of the
window or frame to link to when the user clicks on it.

There are three ways to specify the link destination:

=over 4

=item 1.

By configuring one or more tracks with a -link argument.

=item 2.

By configuring the panel with a -link argument.

=item 3.

By passing a -link argument in the call to image_and_map().

=back

The -link argument can be either a string or a coderef.  If you pass a
string, it will be interpreted as a URL pattern containing runtime
variables.  These variables begin with a dollar sign ($), and are
replaced at run time with the information relating to the selected
annotation.  Recognized variables include:

     $name        The feature's name (display name)
     $id          The feature's id (eg, PK from a database)
     $class       The feature's class (group class)
     $method      The feature's method (same as primary tag)
     $source      The feature's source
     $ref         The name of the sequence segment (chromosome, contig)
                     on which this feature is located
     $description The feature's description (notes)
     $start       The start position of this feature, relative to $ref
     $end         The end position of this feature, relative to $ref
     $length      Length of this feature
     $segstart    The left end of $ref displayed in the detailed view
     $segend      The right end of $ref displayed in the detailed view

For example, to link each feature to a Google search on the feature's
description, use the argument:

  -link => 'http://www.google.com/search?q=$description'

Be sure to use single quotes around the pattern, or Perl will attempt
to perform variable interpretation before image_and_map() has a chance
to work on it.

You may also pass a code reference to -link, in which case the code
will be called every time a URL needs to be generated for the
imagemap.  The subroutine will be called with two arguments, the
feature and the Bio::Graphics::Panel object, and it should return the
URL to link to, or an empty string if a link is not desired. Here is a
simple example:

  -link => sub {
         my ($feature,$panel) = @_;
         my $type = $feature->primary_tag;
         my $name = $feature->display_name;
         if ($primary_tag eq 'clone') {
            return "http://www.google.com/search?q=$name";
         } else {
            return "http://www.yahoo.com/search?p=$name";
         }

The -link argument cascades. image_and_map() will first look for a
-link option in the track configuration, and if that's not found, it
will look in the Panel configuration (created during
Bio::Graphics::Panel-E<gt>new). If no -link configuration option is found
in either location, then image_and_map() will use the value of -link
passed in its argument list, if any.

The -title and -target options behave in a similar manner to -link.
-title is used to assign each feature "title" and "alt" attributes.
The "title" attribute is used by many browsers to create a popup hints
box when the mouse hovers over the feature's glyph for a preset length
of time, while the "alt" attribute is used to create navigable menu
items for the visually impaired.  As with -link, you can set the title
by passing either a substitution pattern or a code ref, and the -title
option can be set in the track, the panel, or the method call itself
in that order of priority.

If not provided, image_and_map() will autogenerate its own title in
the form "E<lt>methodE<gt> E<lt>display_nameE<gt> E<lt>seqidE<gt>:start..end".

The -target option can be used to specify the window or frame that
clicked features will link to.  By default, when the user clicks on a
feature, the loaded URL will replace the current page.  You can modify
this by providing -target with the name of a preexisting or new window
name in order to create effects like popup windows, multiple frames,
popunders and the like.  The value of -target follows the same rules
as -title and -link, including variable substitution and the use of
code refs.

NOTE: Each time you call image_and_map() it will generate a new image
file.  Images that are identical to an earlier one will reuse the same
name, but those that are different, even by one pixel, will result in
the generation of a new image.  If you have limited disk space, you
might wish to check the images directory periodically and remove those
that have not been accessed recently.  The following cron script will
remove image files that haven't been accessed in more than 20 days.

30 2 * * * find /var/www/html/tmpimages -type f -atime +20 -exec rm {} \;

=head1 BUGS

Please report them.

=head1 SEE ALSO

L<Bio::Graphics::Glyph>,
L<Bio::Graphics::Glyph::arrow>,
L<Bio::Graphics::Glyph::cds>,
L<Bio::Graphics::Glyph::crossbox>,
L<Bio::Graphics::Glyph::diamond>,
L<Bio::Graphics::Glyph::dna>,
L<Bio::Graphics::Glyph::dot>,
L<Bio::Graphics::Glyph::ellipse>,
L<Bio::Graphics::Glyph::extending_arrow>,
L<Bio::Graphics::Glyph::generic>,
L<Bio::Graphics::Glyph::graded_segments>,
L<Bio::Graphics::Glyph::heterogeneous_segments>,
L<Bio::Graphics::Glyph::line>,
L<Bio::Graphics::Glyph::pinsertion>,
L<Bio::Graphics::Glyph::primers>,
L<Bio::Graphics::Glyph::rndrect>,
L<Bio::Graphics::Glyph::segments>,
L<Bio::Graphics::Glyph::redgreen_box>,
L<Bio::Graphics::Glyph::ruler_arrow>,
L<Bio::Graphics::Glyph::toomany>,
L<Bio::Graphics::Glyph::transcript>,
L<Bio::Graphics::Glyph::transcript2>,
L<Bio::Graphics::Glyph::translation>,
L<Bio::Graphics::Glyph::triangle>,
L<Bio::Graphics::Glyph::xyplot>,
L<Bio::Graphics::Glyph::whiskerplot>,
L<Bio::SeqI>,
L<Bio::SeqFeatureI>,
L<Bio::Das>,
L<GD>
L<GD::SVG>
L<glyph_help.pl>

=head1 AUTHOR

Lincoln Stein E<lt>lstein@cshl.orgE<gt>

Copyright (c) 2001 Cold Spring Harbor Laboratory

This library is free software; you can redistribute it and/or modify