Bio::G...::image(3pm)

💖 Bio::G...::image — the manual page, but make it make sense 💖

okay so bestie, welcome to the perl manual page for Bio::G...::image(3pm) — which is the lil doc for Bio::Graphics::Glyph::image, aka the glyph that drops photos and other pics right into your track. it's part of the User Contributed Perl Documentation crew. buckle up, we're rendering pixels. 🎀

---

✨ 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 👑

okay so real talk: this glyph literally inserts an image into the track, right at the feature coordinates you indicate. the tea: the image can be in PNG, JPEG, GIF or GD format, and it can be either 8-bit or 24-bit ("truecolor"). 🖼️ and where can that image live? either on your local filesystem, or sitting pretty at a remote URL — provided you've got the LWP module installed. no LWP, no remote vibes, that's the deal. 🫶

now, when you're working with photographic images, you might wanna have Bio::Graphics::Panel create 24-bit (truecolor) images, because otherwise you can straight up run out of colors 😭. the symptom of that? your images come out posterized. the glow-down nobody asked for. to turn on truecolor images, pass the -truecolor option to Bio::Graphics::Panel like the synopsis shows. periodt.

---

✨ OPTIONS ✨

these next ones are standard among all Glyphs. for a full explanation, go see Bio::Graphics::Glyph. 💅

• -fgcolor — foreground color. default: black
• -outlinecolor — synonym for -fgcolor
• -bgcolor — background color. default: turquoise
• -fillcolor — synonym for -bgcolor
• -linewidth — line width. default: 1
• -height — height of glyph. default: 10
• -font — glyph font. default: gdSmallFont
• -connector — connector type. default: 0 (false)
• -connector_color — connector color. default: black
• -label — whether to draw a label. default: 0 (false)
• -description — whether to draw a description. default: 0 (false)
• -hilite — highlight color. default: undef (no color)

and these extra ones? those are exclusive to the "image" glyph, bestie: 🌈

• -image — specify the image path or URL to use for this feature. default: none
• -image_prefix — string to prepend to each image path. you may prepend a directory or a partial URL. default: none
• -vertical_spacing — vertical distance from the box that shows the physical span of the feature to the top of the picture (in pixels). default: 20
• -glyph_delegate — glyph to use for the part of the glyph that shows the physical span of the feature. default: 'generic'

set -vertical_spacing to 0 to completely suppress the diagonal lines that connect the physical span of the feature to the image. poof, gone. 💨

---

🦋 Specifying the Image 🦋

so there's two ways to tell it where your image is. pick your fighter:

1. drop it in the feature itself using a tag named "image" 🌸
2. 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 }
                  );

and yes, you can of course hand -image a constant string, in which case every single feature will show the same image. lowkey efficient, highkey repetitive, whatever works. 😌

the image can be a file on the local operating system or a URL. HOWEVER — and this is the important part — URL fetching will only work if the LWP module is installed on your system. otherwise the glyph will fail with an error message. no cap. 💀

if the image is a relative path (meaning it does not begin with a slash or a URL protocol), then the contents of -image_prefix get prepended to it. this lets you 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',
                 );

so this specifies that each feature's "image" tag gets appended to the partial FlyBase URL — thereby saving space. iconic behavior, honestly. 👑

---

🧚 Glyph Delegation 🧚

the image glyph is made of two parts:

• an upper part that shows the extent of the feature in base pair coordinates
• a lower part that shows the image

and ngl, no scaling of the image is done — its height and width are fixed. fr fr. 📏

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 up top, 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 it 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). so if it's acting up, that's why, don't blame yourself. 😭

---

💀 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. 🙈 it's giving sad beige. this will be fixed in a future version of GD::SVG — until then, gray box it is.

---

🌈 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.

---

and that's the whole page, bestie!! 🫶 this was perl v5.30.0, dated 2019-11-25, and it lives under the name Bio::G...::image(3pm). go forth and render something gorgeous. slay. ✨💅🎀