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

- NAME
- SYNOPSIS
- DESCRIPTION

- OPTIONS
- Specifying the Image
- Glyph Delegation

- BUGS AND LIMITATIONS
- SEE ALSO
- AUTHOR

# 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 the Bio::Graphics::Glyph manpage 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

the Bio::Graphics::Panel manpage, the Bio::Graphics::Glyph manpage, the Bio::Graphics::Glyph::arrow manpage, the Bio::Graphics::Glyph::cds manpage, the Bio::Graphics::Glyph::crossbox manpage, the Bio::Graphics::Glyph::diamond manpage, the Bio::Graphics::Glyph::dna manpage, the Bio::Graphics::Glyph::dot manpage, the Bio::Graphics::Glyph::ellipse manpage, the Bio::Graphics::Glyph::extending_arrow manpage, the Bio::Graphics::Glyph::generic manpage, the Bio::Graphics::Glyph::graded_segments manpage, the Bio::Graphics::Glyph::heterogeneous_segments manpage, the Bio::Graphics::Glyph::line manpage, the Bio::Graphics::Glyph::pinsertion manpage, the Bio::Graphics::Glyph::primers manpage, the Bio::Graphics::Glyph::rndrect manpage, the Bio::Graphics::Glyph::segments manpage, the Bio::Graphics::Glyph::ruler_arrow manpage, the Bio::Graphics::Glyph::toomany manpage, the Bio::Graphics::Glyph::transcript manpage, the Bio::Graphics::Glyph::transcript2 manpage, the Bio::Graphics::Glyph::translation manpage, the Bio::Graphics::Glyph::triangle manpage, the Bio::DB::GFF manpage, the Bio::SeqI manpage, the Bio::SeqFeatureI manpage, the Bio::Das manpage, 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.

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