1Ace::Graphics::Panel(3)User Contributed Perl DocumentatioAnce::Graphics::Panel(3)
2
6 Ace::Graphics::Panel - PNG graphics of Ace::Sequence::Feature objects
7
9 use Ace::Sequence;
10 use Ace::Graphics::Panel;
11 my $db = Ace->connect(-host=>'brie2.cshl.org',-port=>2005) or die;
13 my $cosmid = Ace::Sequence->new(-seq=>'Y16B4A',
14 -db=>$db,-start=>-15000,-end=>15000) or die;
15 my @transcripts = $cosmid->transcripts;
17 my $panel = Ace::Graphics::Panel->new(
19 -segment => $cosmid,
20 -width => 800
21 );
22 $panel->add_track(arrow => $cosmid,
25 -bump => 0,
26 -tick=>2);
27 $panel->add_track(transcript => \@transcripts,
29 -fillcolor => 'wheat',
30 -fgcolor => 'black',
31 -key => 'Curated Genes',
32 -bump => +1,
33 -height => 10,
34 -label => 1);
35 my $boxes = $panel->boxes;
37 print $panel->png;
38
40 The Ace::Graphics::Panel class provides drawing and formatting services
41 for Ace::Sequence::Feature objects or Das::Segment::Feature objects.
42 Typically you will begin by creating a new Ace::Graphics::Panel object,
44 passing it the width of the visual display and the length of the
45 segment.
46 You will then call add_track() one or more times to add sets of related
48 features to the picture. When you have added all the features you
49 desire, you may call png() to convert the image into a PNG-format
50 image, or boxes() to return coordinate information that can be used to
51 create an imagemap.
52 Note that this modules depends on GD.
54
56 This section describes the class and object methods for
57 Ace::Graphics::Panel.
58 CONSTRUCTORS
60 There is only one constructor, the new() method.
61 $panel = Ace::Graphics::Panel->new(@options)
63 The new() method creates a new panel object. The options are a set
64 of tag/value pairs as follows:
65 Option Value Default
67 ------ ----- -------
68 -length Length of sequence segment, in bp 0
70 -segment An Ace::Sequence or Das::Segment none
72 object, used to derive length if
73 not provided
74 -offset Base pair to place at extreme left $segment->start
76 of image.
77 -width Desired width of image, in pixels 600
79 -spacing Spacing between tracks, in pixels 5
81 -pad_top Additional whitespace between top 0
83 of image and contents, in pixels
84 -pad_bottom Additional whitespace between top 0
86 of image and bottom, in pixels
87 -pad_left Additional whitespace between left 0
89 of image and contents, in pixels
90 -pad_right Additional whitespace between right 0
92 of image and bottom, in pixels
93 -keycolor Background color for the key printed 'cornsilk'
95 at bottom of panel (if any)
96 -keyspacing Spacing between key glyphs in the 10
98 key printed at bottom of panel
99 (if any)
100 Typically you will pass new() an object that implements the
102 Bio::RangeI interface, providing a length() method, from which the
103 panel will derive its scale.
104 $panel = Ace::Graphics::Panel->new(-segment => $sequence,
106 -width => 800);
107 new() will return undef in case of an error. If the specified glyph
109 name is not a valid one, new() will throw an exception.
110 OBJECT METHODS
112 $track = $panel->add_track($glyph,$features,@options)
113 The add_track() method adds a new track to the image.
114 Tracks are horizontal bands which span the entire width of the
116 panel. Each track contains a number of graphical elements called
117 "glyphs", each corresponding to a sequence feature. There are
118 different glyph types, but each track can only contain a single
119 type of glyph. Options passed to the track control the color and
120 size of the glyphs, whether they are allowed to overlap, and other
121 formatting attributes. The height of a track is determined from
122 its contents and cannot be directly influenced.
123 The first two arguments are the glyph name and an array reference
125 containing the list of features to display. The order of the
126 arguments is irrelevant, allowing either of these idioms:
127 $panel->add_track(arrow => \@features);
129 $panel->add_track(\@features => 'arrow');
130 The glyph name indicates how each feature is to be rendered. A
132 variety of glyphs are available, and the number is growing.
133 Currently, the following glyphs are available:
134 Name Description
136 ---- -----------
137 box A filled rectangle, nondirectional.
139 ellipse A filled ellipse, nondirectional.
141 arrow An arrow; can be unidirectional or bidirectional.
143 It is also capable of displaying a scale with
144 major and minor tickmarks, and can be oriented
145 horizontally or vertically.
146 segments A set of filled rectangles connected by solid lines.
148 Used for interrupted features, such as gapped
149 alignments.
150 transcript Similar to segments, but the connecting line is
152 a "hat" shape, and the direction of transcription
153 is indicated by a small arrow.
154 transcript2 Similar to transcript, but the arrow that indicates
156 the direction of transcription is the last exon
157 itself.
158 primers Two inward pointing arrows connected by a line.
160 Used for STSs.
161 toomany A "cloud", to indicate too many features to show
163 individually. This is a placeholder that will be
164 replaced by something more clever, such as a histogram
165 or density plot.
166 group A group of related features connected by a dashed line.
168 This is used internally by the Track class and should
169 not be called explicitly.
170 If the glyph name is omitted from add_track(), the "box" glyph will
172 be used by default.
173 The @options array is a list of name/value pairs that control the
175 attributes of the track. The options are in turn passed to the
176 glyphs. Each glyph has its own specialized subset of options, but
177 some are shared by all glyphs:
178 Option Description Default
180 ------ ----------- -------
181 -glyph Glyph to use none
183 -fgcolor Foreground color black
185 -outlinecolor black
187 Synonym for -fgcolor
188 -bgcolor Background color white
190 -fillcolor Interior color of filled turquoise
192 images
193 -linewidth Width of lines drawn by 1
195 glyph
196 -height Height of glyph 10
198 -font Glyph font gdSmallFont
200 -label Whether to draw a label false
202 -bump Bump direction 0
204 -connect_groups false
206 Connect groups by a
207 dashed line (see below)
208 -key Show this track in the undef
210 key
211 Colors can be expressed in either of two ways: as symbolic names
213 such as "cyan" and as HTML-style #RRGGBB triples. The symbolic
214 names are the 140 colors defined in the Netscape/Internet Explorer
215 color cube, and can be retrieved using the
216 Ace::Graphics::Panel->color_names() method.
217 The background color is used for the background color of the track
219 itself. The foreground color controls the color of lines and
220 strings. The interior color is used for filled objects such as
221 boxes.
222 The -label argument controls whether or not the ID of the feature
224 should be printed next to the feature. It is accepted by most, but
225 not all of the glyphs.
226 The -bump argument controls what happens when glyphs collide. By
228 default, they will simply overlap (value 0). A -bump value of +1
229 will cause overlapping glyphs to bump downwards until there is room
230 for them. A -bump value of -1 will cause overlapping glyphs to
231 bump upwards.
232 The -key argument declares that the track is to be shown in a key
234 appended to the bottom of the image. The key contains a picture of
235 a glyph and a label describing what the glyph means. The label is
236 specified in the argument to -key.
237 If present, the -glyph argument overrides the glyph given in the
239 first or second argument.
240 add_track() returns an Ace::Graphics::Track object. You can use
242 this object to add additional features or to control the appearance
243 of the track with greater detail, or just ignore it. Tracks are
244 added in order from the top of the image to the bottom. To add
245 tracks to the top of the image, use unshift_track().
246 Typical usage is:
248 $panel->add_track( thistle => \@genes,
250 -fillcolor => 'green',
251 -fgcolor => 'black',
252 -bump => +1,
253 -height => 10,
254 -label => 1);
255 $track = unshift_track($glyph,$features,@options)
257 unshift_track() works like add_track(), except that the new track
258 is added to the top of the image rather than the bottom.
259 Adding groups of features: It is not uncommon to add a group of
261 features which are logically connected, such as the 5' and 3' ends
262 of EST reads. To group features into sets that remain on the same
263 horizontal position and bump together, pass the sets as an
264 anonymous array. To connect the groups by a dashed line, pass the
265 -connect_groups argument with a true value. For example:
266 $panel->add_track(segments => [[$abc_5,$abc_3],
268 [$xxx_5,$xxx_3],
269 [$yyy_5,$yyy_3]],
270 -connect_groups => 1);
271 $gd = $panel->gd
273 The gd() method lays out the image and returns a GD::Image object
274 containing it. You may then call the GD::Image object's png() or
275 jpeg() methods to get the image data.
276 $png = $panel->png
278 The png() method returns the image as a PNG-format drawing, without
279 the intermediate step of returning a GD::Image object.
280 $boxes = $panel->boxes
282 @boxes = $panel->boxes
283 The boxes() method returns the coordinates of each glyph, useful
284 for constructing an image map. In a scalar context, boxes()
285 returns an array ref. In an list context, the method returns the
286 array directly.
287 Each member of the list is an anonymous array of the following
289 format:
290 [ $feature, $x1, $y1, $x2, $y2 ]
292 The first element is the feature object; either an
294 Ace::Sequence::Feature, a Das::Segment::Feature, or another Bioperl
295 Bio::SeqFeatureI object. The coordinates are the topleft and
296 bottomright corners of the glyph, including any space allocated for
297 labels.
298 ACCESSORS
300 The following accessor methods provide access to various attributes of
301 the panel object. Called with no arguments, they each return the
302 current value of the attribute. Called with a single argument, they
303 set the attribute and return its previous value.
304 Note that in most cases you must change attributes prior to invoking
306 gd(), png() or boxes(). These three methods all invoke an internal
307 layout() method which places the tracks and the glyphs within them, and
308 then caches the result.
309 Accessor Name Description
311 ------------- -----------
312 width() Get/set width of panel
314 spacing() Get/set spacing between tracks
315 length() Get/set length of segment (bp)
316 pad_top() Get/set top padding
317 pad_left() Get/set left padding
318 pad_bottom() Get/set bottom padding
319 pad_right() Get/set right padding
320 INTERNAL METHODS
322 The following methods are used internally, but may be useful for those
323 implementing new glyph types.
324 @names = Ace::Graphics::Panel->color_names
326 Return the symbolic names of the colors recognized by the panel
327 object. In a scalar context, returns an array reference.
328 @rgb = $panel->rgb($index)
330 Given a GD color index (between 0 and 140), returns the RGB triplet
331 corresponding to this index. This method is only useful within a
332 glyph's draw() routine, after the panel has allocated a GD::Image
333 and is populating it.
334 $index = $panel->translate($color)
336 Given a color, returns the GD::Image index. The color may be
337 symbolic, such as "turquoise", or a #RRGGBB triple, as in #F0E0A8.
338 This method is only useful within a glyph's draw() routine, after
339 the panel has allocated a GD::Image and is populating it.
340 $panel->set_pen($width,$color)
342 Changes the width and color of the GD drawing pen to the values
343 indicated. This is called automatically by the GlyphFactory
344 fgcolor() method.
345
347 Please report them.
348
350 Ace::Sequence,Ace::Sequence::Feature,
351 Ace::Graphics::Track,Ace::Graphics::Glyph, GD
352
354 Lincoln Stein <lstein@cshl.org>.
355 Copyright (c) 2001 Cold Spring Harbor Laboratory
357 This library is free software; you can redistribute it and/or modify it
359 under the same terms as Perl itself. See DISCLAIMER.txt for
360 disclaimers of warranty.
361perl v5.12.0 2001-09-17 Ace::Graphics::Panel(3)