Bio::Graphics::Glyph - Base class for Bio::Graphics::Glyph objects


See Bio::Graphics::Panel.


Bio::Graphics::Glyph is the base class for all glyph objects. Each glyph is a wrapper around an Bio:SeqFeatureI object, knows how to render itself on an Bio::Graphics::Panel, and has a variety of configuration variables.

End developers will not ordinarily work directly with Bio::Graphics::Glyph objects, but with Bio::Graphics::Glyph::generic and its subclasses. Similarly, most glyph developers will want to subclass from Bio::Graphics::Glyph::generic because the latter provides labeling and arrow-drawing facilities.


This section describes the class and object methods for Bio::Graphics::Glyph.


Bio::Graphics::Glyph objects are constructed automatically by an Bio::Graphics::Glyph::Factory, and are not usually created by end-developer code.

$glyph = Bio::Graphics::Glyph->new(-feature=>$feature,-factory=>$factory)

Given a sequence feature, creates an Bio::Graphics::Glyph object to display it. The -feature argument points to the Bio:SeqFeatureI object to display, and -factory indicates an Bio::Graphics::Glyph::Factory object from which the glyph will fetch all its run-time configuration information. Factories are created and manipulated by the Bio::Graphics::Panel object.

A standard set of options are recognized. See OPTIONS.


Once a glyph is created, it responds to a large number of methods. In this section, these methods are grouped into related categories.

Retrieving glyph context:

$factory = $glyph->factory

Get the Bio::Graphics::Glyph::Factory associated with this object. This cannot be changed once it is set.

$panel = $glyph->panel

Get the Bio::Graphics::Panel associated with this object. This cannot be changed once it is set.

$feature = $glyph->feature

Get the sequence feature associated with this object. This cannot be changed once it is set.

$feature = $glyph->add_feature(@features)

Add the list of features to the glyph, creating subparts. This is most common done with the track glyph returned by Ace::Graphics::Panel->add_track().

$feature = $glyph->add_group(@features)

This is similar to add_feature(), but the list of features is treated as a group and can be configured as a set.

Retrieving glyph options:

$fgcolor = $glyph->fgcolor
$bgcolor = $glyph->bgcolor
$fontcolor = $glyph->fontcolor
$fontcolor = $glyph->font2color
$fillcolor = $glyph->fillcolor

These methods return the configured foreground, background, font, alternative font, and fill colors for the glyph in the form of a GD::Image color index.

$color = $glyph->tkcolor

This method returns a color to be used to flood-fill the entire glyph before drawing (currently used by the "track" glyph).

$width = $glyph->width([$newwidth])

Return the width of the glyph, not including left or right padding. This is ordinarily set internally based on the size of the feature and the scale of the panel.

$width = $glyph->layout_width

Returns the width of the glyph including left and right padding.

$width = $glyph->height

Returns the height of the glyph, not including the top or bottom padding. This is calculated from the "height" option and cannot be changed.

$font = $glyph->font

Return the font for the glyph.

$option = $glyph->option($option)

Return the value of the indicated option.

$index = $glyph->color($color)

Given a symbolic or #RRGGBB-form color name, returns its GD index.

$level = $glyph->level

The "level" is the nesting level of the glyph. Groups are level -1, top level glyphs are level 0, subparts (e.g. exons) are level 1 and so forth.

Setting an option:


You may change a glyph option after it is created using set_option(). This is most commonly used to configure track glyphs.

Retrieving information about the sequence:

$start = $glyph->start
$end = $glyph->end

These methods return the start and end of the glyph in base pair units.

$offset = $glyph->offset

Returns the offset of the segment (the base pair at the far left of the image).

$length = $glyph->length

Returns the length of the sequence segment.

Retrieving formatting information:

$top = $glyph->top
$left = $glyph->left
$bottom = $glyph->bottom
$right = $glyph->right

These methods return the top, left, bottom and right of the glyph in pixel coordinates.

$height = $glyph->height

Returns the height of the glyph. This may be somewhat larger or smaller than the height suggested by the GlyphFactory, depending on the type of the glyph.

$scale = $glyph->scale

Get the scale for the glyph in pixels/bp.

$height = $glyph->labelheight

Return the height of the label, if any.

$label = $glyph->label

Return a human-readable label for the glyph.

These methods are called by Bio::Graphics::Track during the layout process:


Move the glyph in pixel coordinates by the indicated delta-x and delta-y values.

($x1,$y1,$x2,$y2) = $glyph->box

Return the current position of the glyph.

These methods are intended to be overridden in subclasses:


Calculate the height of the glyph.


Calculate the left side of the glyph.


Calculate the right side of the glyph.


Optionally offset the glyph by the indicated amount and draw it onto the GD::Image object.


Draw the label for the glyph onto the provided GD::Image object, optionally offsetting by the amounts indicated in $left and $right.

These methods are useful utility routines:

$pixels = $glyph->map_pt($bases);

Map the indicated base position, given in base pair units, into pixels, using the current scale and glyph position.


Draw a filled rectangle with the appropriate foreground and fill colors, and pen width onto the GD::Image object given by $gd, using the provided rectangle coordinates.


As above, but draws an oval inscribed on the rectangle.


The following options are standard among all Glyphs. See individual glyph pages for more options.

  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                black

  -strand_arrow Whether to indicate            0 (false)

  -label        Whether to draw a label        0 (false)

  -description  Whether to draw a description  0 (false)

For glyphs that consist of multiple segments, the -connector option controls what's drawn between the segments. The default is 0 (no connector). Options include "hat", an upward-angling conector, "solid", a straight horizontal connector, and "dashed", for a horizontal dashed line. The -connector_color option controls the color of the connector, if any.

The label is printed above the glyph. You may pass an anonymous subroutine to -label, in which case the subroutine will be invoked with the feature as its single argument. The subroutine must return a string to render as the label. Otherwise, you may return the number "1", in which case the feature's info(), seqname() and primary_tag() methods will be called (in that order) until a suitable name is found.

The description is printed below the glyph. You may pass an anonymous subroutine to -label, in which case the subroutine will be invoked with the feature as its single argument. The subroutine must return a string to render as the label. Otherwise, you may return the number "1", in which case the feature's source_tag() method will be invoked.

In the case of ACEDB Ace::Sequence feature objects, the feature's info(), Brief_identification() and Locus() methods will be called to create a suitable description.

The -strand_arrow option, if true, requests that the glyph indicate which strand it is on, usually by drawing an arrowhead. Not all glyphs can respond appropriately to this request.

SUBCLASSING Bio::Graphics::Glyph

By convention, subclasses are all lower-case. Begin each subclass with a preamble like this one:

 package Bio::Graphics::Glyph::crossbox;

 use strict;
 use vars '@ISA';
 @ISA = 'Bio::Graphics::Glyph';

Then override the methods you need to. Typically, just the draw() method will need to be overridden. However, if you need additional room in the glyph, you may override calculate_height(), calculate_left() and calculate_right(). Do not directly override height(), left() and right(), as their purpose is to cache the values returned by their calculating cousins in order to avoid time-consuming recalculation.

A simple draw() method looks like this:

 sub draw {
  my $self = shift;
  my $gd = shift;

  # and draw a cross through the box
  my ($x1,$y1,$x2,$y2) = $self->calculate_boundaries(@_);
  my $fg = $self->fgcolor;

This subclass draws a simple box with two lines criss-crossed through it. We first call our inherited draw() method to generate the filled box and label. We then call calculate_boundaries() to return the coordinates of the glyph, disregarding any extra space taken by labels. We call fgcolor() to return the desired foreground color, and then call $gd->line() twice to generate the criss-cross.

For more complex draw() methods, see Bio::Graphics::Glyph::transcript and Bio::Graphics::Glyph::segments.


Please report them.


Bio::DB::GFF::Feature, Ace::Sequence, Bio::Graphics::Panel, Bio::Graphics::Track, Bio::Graphics::Glyph::anchored_arrow, Bio::Graphics::Glyph::arrow, Bio::Graphics::Glyph::box, Bio::Graphics::Glyph::dna, Bio::Graphics::Glyph::graded_segments, Bio::Graphics::Glyph::primers, Bio::Graphics::Glyph::segments, Bio::Graphics::Glyph::toomany, Bio::Graphics::Glyph::transcript, Bio::Graphics::Glyph::transcript2, Bio::Graphics::Glyph::wormbase_transcript


Lincoln Stein <>

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.