Provided by: libbio-graphics-perl_2.40-2_all bug

NAME

       Bio::Graphics::Glyph::image - A glyph that draws photographs & other images

SYNOPSIS

        use Bio::Graphics;
        use Bio::Seq;
        use Bio::SeqFeature::Generic;

        my $bsg = 'Bio::SeqFeature::Generic';

        my $seq    = Bio::Seq->new(-length=>1000);

        my $whole  = $bsg->new(-display_name => 'Clone82',
                               -start        => 1,
                               -end          => $seq->length);

        my $image1 = $bsg->new(-start        => 100,
                               -end          => 300,
                               -display_name => 'Excretory System',
                               -tag=>{
                                     image=>"http://www.flybase.org/anatomy/image-browser_files/excretory-system.gif"
                                     }
                              );

        my $image2 = $bsg->new(-start        => 500,
                               -end          => 800,
                               -display_name => 'Expression Pattern',
                               -tag=>{
                                     image=>"http://www.flybase.org/anatomy/image-browser_files/embryonic-expression-pattern.gif"
                                     }
                              );

        my $panel = Bio::Graphics::Panel->new(-length    => $seq->length,
                                              -width     => 800,
                                              -truecolor => 1,
                                              -key_style => 'between',
                                              -pad_left  => 10,
                                              -pad_right => 10,
                                             );

        $panel->add_track($whole,
                          -glyph    => 'arrow',
                          -double   => 1,
                          -tick     => 2,
                          -label    => 1,
                          );

        $panel->add_track([$image1,$image2],
                          -glyph    => 'image',
                          -label    => 1,
                          -key       => 'Example images');

        binmode STDOUT;
        print $panel->png;

DESCRIPTION

       This glyph inserts an image into the track at the indicated feature coordinates. The image
       can be in PNG, JPEG, GIF or GD format, and can be either 8-bit or 24-bit ("truecolor").
       The image can be located on the local filesystem or located at a remote URL (provided that
       you have the LWP module installed).

       When working with photographic images, you may wish to have Bio::Graphics::Panel create
       24-bit (truecolor) images in order to avoid running out of colors. The symptom of this is
       that images appear posterized. To turn on truecolor images, pass the -truecolor option to
       Bio::Graphics::Panel as shown in the synopsis.

   OPTIONS
       The following options are standard among all Glyphs.  See Bio::Graphics::Glyph for a full
       explanation.

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

         -fgcolor      Foreground color               black

         -outlinecolor Synonym for -fgcolor

         -bgcolor      Background color               turquoise

         -fillcolor    Synonym for -bgcolor

         -linewidth    Line width                     1

         -height       Height of glyph                10

         -font         Glyph font                     gdSmallFont

         -connector    Connector type                 0 (false)

         -connector_color
                       Connector color                black

         -label        Whether to draw a label        0 (false)

         -description  Whether to draw a description  0 (false)

         -hilite       Highlight color                undef (no color)

       The following additional options are available to the "image" glyph:

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

         -image            Specify the image path or URL     none
                           to use for this feature.

         -image_prefix     String to prepend to              none
                           each image path. You may prepend
                           a directory or a partial URL.

         -vertical_spacing Vertical distance from the box    20
                           that shows the physical span of
                           of the feature to the top of
                           the picture (in pixels).

         -glyph_delegate   Glyph to use for the part of      'generic'
                           the glyph that shows the physical
                           span of the feature.

       Set -vertical_spacing to 0 to completely suppress the diagonal lines that connect the
       physical span of the feature to the image.

   Specifying the Image
       The path to the image can be specified in two ways. First, you can place it in the feature
       itself using a tag named "image". Second, you can specify it as a track option using a
       callback:

         $panel->add_track(\@features,
                           -glyph=>'image',
                           -image => sub { my $feature = shift;
                                           my $image_path = do_something();
                                           return $image }
                           );

       You can of course give -image a constant string, in which case each feature will show the
       same image.

       The image can be a file on the local operating system or a URL. However, URL fetching will
       only work if the LWP module is installed on your system. Otherwise the glyph will fail
       with an error message.

       If the image is a relative path (it does not begin with a slash or a URL protocol), then
       the contents of -image_prefix will be prepended to it. This allows you to specify images
       that are relative to a particular directory or a partial URL. Example:

         $panel->add_track(\@features,
                           -glyph => 'image',
                           -image_prefix => 'http://www.flybase.org/anatomy/image-browser_files',
                          );

       This specifies that each feature's "image" tag is to be appended to the partial FlyBase
       URL, thereby saving space.

   Glyph Delegation
       The image glyph consists of two parts: an upper part that shows the extent of the feature
       in base pair coordinates, and a lower part that shows the image. No scaling of the image
       is done; its height and width are fixed.

       By default the upper part uses the "generic" glyph, which is a simple rectangle filled
       with the bgcolor and outlined with the fgcolor. To use a different glyph in the upper
       part, specify the -glyph_delegate option, giving the name of the glyph you wish to use.
       For instance, to use the "span" glyph:

         $panel->add_track(\@features,
                           -glyph          => 'image',
                           -glyph_delegate => 'span'
                          );

       This feature does not work with all glyphs, and in particular requires a recent CVS
       checkout of Bio::Perl to work properly with the "arrow", "span" and "primers" glyphs
       (support for the feature did not make it into version 1.5).

BUGS AND LIMITATIONS

       This glyph does not work with GD::SVG. If you try to render it onto a GD::SVG panel, the
       image will be shown as a gray box. This will be fixed in a future version of GD::SVG.

SEE ALSO

       Bio::Graphics::Panel, Bio::Graphics::Glyph, Bio::Graphics::Glyph::arrow,
       Bio::Graphics::Glyph::cds, Bio::Graphics::Glyph::crossbox, Bio::Graphics::Glyph::diamond,
       Bio::Graphics::Glyph::dna, Bio::Graphics::Glyph::dot, Bio::Graphics::Glyph::ellipse,
       Bio::Graphics::Glyph::extending_arrow, Bio::Graphics::Glyph::generic,
       Bio::Graphics::Glyph::graded_segments, Bio::Graphics::Glyph::heterogeneous_segments,
       Bio::Graphics::Glyph::line, Bio::Graphics::Glyph::pinsertion,
       Bio::Graphics::Glyph::primers, Bio::Graphics::Glyph::rndrect,
       Bio::Graphics::Glyph::segments, Bio::Graphics::Glyph::ruler_arrow,
       Bio::Graphics::Glyph::toomany, Bio::Graphics::Glyph::transcript,
       Bio::Graphics::Glyph::transcript2, Bio::Graphics::Glyph::translation,
       Bio::Graphics::Glyph::triangle, Bio::DB::GFF, Bio::SeqI, Bio::SeqFeatureI, Bio::Das, GD

AUTHOR

       Lincoln Stein <lstein@cshl.org>, Todd Harris <harris@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.