Mastering Perl for Bioinformatics [Electronic resources] نسخه متنی

8.3 Adding GD Graphics to Restrictionmap.pm

Now that you''ve seen an overview of the
GD.pm Perl module, let''s enhance
the Restrictionmap.pm module that
you''ve seen previously in Chapter 5, Chapter 6, and Chapter 7 so it can output PNG graphics files.

Reviewing how the Restrictionmap.pm module works,
you can see that its
get_graphic method examines the
_graphictype attribute to determine what graphics
drawing method to call. Following is the
get_graphic method again, along with the
attributes the class defines. (Recall that this class inherits from
the class Restriction.pm, so many things are
defined there):

# Class data and methods
{
# A list of all attributes with default values.
my %_attributes = (
#    key   = restriction enzyme name
#    value = space-separated string of recognition sites => regular expressions
_rebase      => { },    # A Rebase.pm object
_sequence    => '''',     # DNA sequence data in raw format (only bases)
_enzyme      => '''',     # space separated string of one or more enzyme names
_map         => { },    # a hash: enzyme names => arrays of locations 
_graphictype => ''text'', # one of ''text'' or ''png'' or some other
_graphic     => '''',     # a graphic display of the restriction map
);
# Return a list of all attributes
sub _all_attributes {
keys %_attributes;
}
}
sub get_graphic {
my($self) = @_;
# If the graphic is not stored, calculate and store it
unless($self->{_graphic}) {
unless($self->{_graphictype}) {
croak ''Attribute graphictype not set (default is "text")'';
}
# if graphictype is "xyz", method that makes the graphic is "_drawmap_xyz"
my $drawmapfunctionname = "_drawmap_" . $self->{_graphictype};
# Calculate and store the graphic
$self->{_graphic} = $self->$drawmapfunctionname;
}
# Return the stored graphic
return $self->{_graphic};
}

As you recall, the get_graphic method requires
that some graphic type be defined in the
_graphictype attribute. It then tries to call a
method whose name incorporates the name of the graphic type; for
instance, if the graphic type is
"png", the
get_graphic method tries to call a graphic drawing
method called _drawmap_png.

How might you design such a get_graphic method?

8.3.1 Designing Graphics

There are several ways to construct a PNG
graphic
to draw a restriction map. You can extract the data necessary using
_drawmap_text and its helper methods,
_initialize_annotation_text,
_add_annotation_text, and
_formatmaptext. These methods use the methods of
the Restriction class to get the locations of
restriction sites for each enzyme and then make a text version of an
annotated sequence string that shows the names of the restriction
enzymes above their respective restriction sites in the sequence.

Having found the locations of the restriction sites in the sequence,
there are many ways you can visually represent the map. You can
incorporate a design of double-stranded DNA, for instance, to serve
as a background to the actual sequence you can draw on top of the
double helical design. You can use colors and different sizes and
choices of fonts to make the restriction sites stand out. You can
draw the annotation in various ways, perhaps giving the restriction
enzyme and the location in some visually appealing way near the
restriction site. You may or may not want to draw the entire
sequence; perhaps you could truncate long stretches of sequence that
have no restriction sites, for instance, to make the relevant
information (the restriction site locations) fit better into a
smaller, more easily grasped space, ideally on one screen.

The following _drawmap_png
method uses the output of the _drawmap_text method
and makes a PNG graphic out of it.

#
# Method to output graphics in PNG format
#
sub _drawmap_png {
my($self) = @_;
# Get text version of graphic
my @maptext = split( /\n+/, $self->_drawmap_text);
# Now make a PNG graphic from the text version
use GD;
#
# Layout information: fonts, margins, image size
#
# Use built-in GD fixed-width font ''gdMediumBoldFont'' (could use TrueType fonts)
#
# Font character size in pixels
my ($fontwidth, $fontheight) = (gdMediumBoldFont->width, 
gdMediumBoldFont->height);
# Margins top, bottom, right, left, and between lines
my ($tmarg, $bmarg, $rmarg, $lmarg, $linemarg) = (10, 10, 10, 10, 5);
# Image width is length of line times width of a character, plus margins
my ($imagewidth) = (length($maptext[0]) * $fontwidth) + $lmarg + $rmarg;
# Image height is height of font plus margin times number of lines, plus margins
my ($imageheight) = (($fontheight + $linemarg) * (scalar @maptext)) + $tmarg 
+ $bmarg;
my $image = new GD::Image($imagewidth, $imageheight);
# First one becomes background color
my $white = $image->colorAllocate(255, 255, 255);
my $black = $image->colorAllocate(0, 0, 0);
my $red = $image->colorAllocate(255, 0, 0);
# Origin at upper left hand corner
my ($x, $y) = ($lmarg, $tmarg);
#
# Draw the lines on the image
#
foreach my $line (@maptext) {
chomp $line;
# Draw annotation in red
if($line =~ / /) { #annotation has spaces
$image->string(gdMediumBoldFont, $x, $y, $line, $red);
# Draw sequence in black
}else{ #sequence
$image->string(gdMediumBoldFont, $x, $y, $line, $black);
}
$y += ($fontheight + $linemarg);
}
return $image->png;
}

_drawmap_png has a fairly straightforward logic,
given that I just drew the same text as is formatted in the
_drawmap_text method. So, it''s no
surprise that the first step of the _drawmap_png
method is to get the formatted text. Recall that the lines of the
text are joined into a string so the graphic can be stored in a
scalar variable. So, the scalar string is split on
newlines back into an array @maptext:

# Get text version of graphic
my @maptext = split( /\n+/, $self->_drawmap_text);

Now, the GD module is loaded:

# Now make a PNG graphic from the text version
use GD;

Next, various layout dimensions are calculated:

#
# Layout information: fonts, margins, image size
#
# Use built-in GD fixed-width font ''gdMediumBoldFont'' (could use TrueType fonts)
#
# Font character size in pixels
my ($fontwidth, $fontheight) = (gdMediumBoldFont->width, gdMediumBoldFont->height);
# Margins top, bottom, right, left, and between lines
my ($tmarg, $bmarg, $rmarg, $lmarg, $linemarg) = (10, 10, 10, 10, 5);
# Image width is length of line times width of a character, plus margins
my ($imagewidth) = (length($maptext[0]) * $fontwidth) + $lmarg + $rmarg;
# Image height is height of font plus margin times number of lines, plus margins
my ($imageheight) = (($fontheight + $linemarg) * 
(scalar @maptext)) + $tmarg + $bmarg;

GD includes a handful of built-in, fixed-width fonts. It also permits
the use of TrueType fonts; however, although they are freely
available, high quality, very extensive, and probably available on
your system, they are nevertheless not available everywhere. As a
result, I''ve decided to use a built-in font
that''s always available with GD.

However, as a result, the method has the font name hardcoded in a few
places. (See the exercises at the end of the chapter.) For instance,
GD built-in font names are objects with methods associated with them,
in particular, methods that return the width and height of the font
in pixels, which my _drawmap_png method saves in
the variables $fontwidth and
$fontheight.

Various margins are then set for the page as a whole and for the
spacing between lines.

Finally, the overall dimensions of the image are calculated:

# Image width is length of line times width of a character, plus margins
my ($imagewidth) = (length($maptext[0]) * $fontwidth) + $lmarg + $rmarg;
# Image height is height of font plus margin times number of lines, plus margins
my ($imageheight) = (($fontheight + $linemarg) * 
(scalar @maptext)) + $tmarg + $bmarg;

The comments explain the logic. Recall that
@maptext is the array that contains the text to be
formatted. $maptext[0] is the first line, which is
either a full line and thus the maximum width, or
it''s less than a full line but is the only line, and
thus the maximum width. (scalar @maptext) returns
the number of lines in the @maptext array (because
an array in scalar context returns the size of the array).

After those preliminary calculations, the constructor for the GD
class can be called to create a new image object
$image of the correct dimensions:

my $image = new GD::Image($imagewidth, $imageheight);

8.3.1.1 Applying color

The colors I use can now be allocated
for the image object. In GD, the first call to the
colorAllocate method determines the background
color for the entire image. The triples of numbers are the red, blue,
and green values that are combined to form the various possible
colors:

# First one becomes background color
my $white = $image->colorAllocate(255, 255, 255);
my $black = $image->colorAllocate(0, 0, 0);
my $red = $image->colorAllocate(255, 0, 0);

Next, the x and y (horizontal and vertical) positions are initialized
at the origin of the image to be drawn. In GD, the origin of the
picture is 0,0 at the upper left corner. Increasing values of x move
from left to right across the image; increasing values of y move from
top to bottom down the image. Given that I want to have top and left
margins, I set the image origin at the upper left corner, offset by
the values of the margins:

# Origin at upper left corner
my ($x, $y) = ($lmarg, $tmarg);

Now, everything is set up, and it''s time to draw the
image. The text to be drawn is processed line-by-line; after each
line is drawn, the vertical position $y is
increased by the height of the font plus the interline margin.

There are two kinds of lines: sequence and annotation. I assume that
each annotation line contains some spaces (this
won''t always be true; see the exercises). Annotation
lines are printed as strings in the color red, and sequence lines are
printed in the color black.

#
# Draw the lines on the image
#
foreach my $line (@maptext) {
chomp $line;
# Draw annotation in red
if($line =~ / /) { #annotation has spaces
$image->string(gdMediumBoldFont, $x, $y, $line, $red);
# Draw sequence in black
}else{ #sequence
$image->string(gdMediumBoldFont, $x, $y, $line, $black);
}
$y += ($fontheight + $linemarg);
}

8.3.1.2 Calling the method

Finally, after all the text lines have been formatted and added to
the image, the png GD method is called on the
image. This produces a PNG image, which is returned from my
_drawmap_png method:

return $image->png;

Because that method was called by the method
_getgraphic, the PNG graphic is both saved in the
_graphic attribute and sent off to the
user''s browser, which knows how to display a PNG
image.

In other circumstances you might want to save the image to a file,
which you can do by opening a file, assigning it a filehandle (say
IMG), and printing the $image->png output to
the file:

print IMG $image->png;

8.3.2 Adding JPEG Output to Restrictionmap.pm

Let''s consider how to add
JPEG output to Restrictionmap.pm. I need a
_drawmap_jpg method to handle
the case when a JPEG image is requested by the programmer setting the
_graphictype attribute to
"jpg".

Looking over the GD documentation and the
_drawmap_png method I''ve just
written, I see that the last line of my
_drawmap_png method:

return $image->png;

can be replaced by:

return $image->jpeg;

in order to output a JPEG format. So, here''s my new
_drawmap_jpg method, almost an exact duplicate of
_drawmap_png (see the exercises at the end of the
chapter).

#
# Method to output graphics in JPEG format
#
sub _drawmap_jpg {
my($self) = @_;
# Get text version of graphic
my @maptext = split( /\n+/, $self->_drawmap_text);
# Now make a JPEG graphic from the text version
use GD;
#
# Layout information: fonts, margins, image size
#
# Use built-in GD fixed-width font ''gdMediumBoldFont'' (could use TrueType fonts)
#
# Font character size in pixels
my ($fontwidth, $fontheight) = (gdMediumBoldFont->width, 
gdMediumBoldFont->height);
# Margins top, bottom, right, left, and between lines
my ($tmarg, $bmarg, $rmarg, $lmarg, $linemarg) = (10, 10, 10, 10, 5);
# Image width is length of line times width of a character, plus margins
my ($imagewidth) = (length($maptext[0]) * $fontwidth) + $lmarg + $rmarg;
# Image height is height of font plus margin times number of lines, plus margins
my ($imageheight) =
(($fontheight + $linemarg) * 
(scalar @maptext)) + $tmarg + $bmarg;
my $image = new GD::Image($imagewidth, $imageheight);
# First one becomes background color
my $white = $image->colorAllocate(255, 255, 255);
my $black = $image->colorAllocate(0, 0, 0);
my $red = $image->colorAllocate(255, 0, 0);
# Origin at upper left hand corner
my ($x, $y) = ($lmarg, $tmarg);
#
# Draw the lines on the image
#
foreach my $line (@maptext) {
chomp $line;
# Draw annotation in red
if($line =~ / /) { #annotation has spaces
$image->string(gdMediumBoldFont, $x, $y, $line, $red);
# Draw sequence in black
}else{ #sequence
$image->string(gdMediumBoldFont, $x, $y, $line, $black);
}
$y += ($fontheight + $linemarg);
}
return $image->jpeg;
}

To use this new method from the webrebase1 CGI
Perl script, I''d have to change the requested
graphictype attribute to jpeg;
I''d also have to change the HTML header line that
gets printed out just before printing the image data. Now, that line
is set to:

print "Content-type: image/png\n\n";

but I''d have to change that to:

print "Content-type: image/jpeg\n\n";

You''ll notice if you try that out, the JPEG graphic
seems a bit blurry around the edges of the letters. This is a result
of the compression algorithm that JPEGs use. They tend to work very
well with photographic images, but the kind of text and line images
that webrebase1 creates do not fare as well under
JPEG compression.