Graph.pm

   1 package Imager::Graph;
   2 require 5.005;
   3
   4 =head1 NAME
   5
   6 Imager::Graph - Perl extension for producing Graphs using the Imager library.
   7
   8 =head1 SYNOPSIS
   9
  10   use Imager::Graph::SubClass;
  11   my $chart = Imager::Graph::SubClass->new;
  12   my $img = $chart->draw(data=> \@data, ...)
  13     or die $chart->error;
  14
  15 =head1 DESCRIPTION
  16
  17 Imager::Graph provides style information to its base classes.  It
  18 defines the colors, text display information and fills based on both
  19 built-in styles and modifications supplied by the user to the draw()
  20 method.
  21
  22 =over
  23
  24 =cut
  25
  26 use strict;
  27 use warnings;
  28 use vars qw($VERSION);
  29 use Imager qw(:handy);
  30 use Imager::Fountain;
  31
  32 $VERSION = '0.06';
  33
  34 # the maximum recursion depth in determining a color, fill or number
  35 use constant MAX_DEPTH => 10;
  36
  37 my $NUM_RE = '(?:[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]\d+?)?)';
  38
  39 =item new
  40
  41 This is a simple constructor.  No parameters required.
  42
  43 =cut
  44
  45 sub new {
  46   bless {}, $_[0];
  47 }
  48
  49 =item error
  50
  51 Returns an error message.  Only value if the draw() method returns false.
  52
  53 =cut
  54
  55 sub error {
  56   $_[0]->{_errstr};
  57 }
  58
  59 =item draw
  60
  61 Creates a new image, draws the chart onto that image and returns it.
  62
  63 Typically you will need to supply a C<data> parameter in the format
  64 required by that particular graph, and if your graph will use any
  65 text, a C<font> parameter
  66
  67 You can also supply many different parameters which control the way
  68 the graph looks.  These are supplied as keyword, value pairs, where
  69 the value can be a hashref containing sub values.
  70
  71 The C<style> parameter will selects a basic color set, and possibly
  72 sets other related parameters.  See L</"STYLES">.
  73
  74  my $font = Imager::Font->new(file => 'ImUgly.ttf');
  75  my $img = $chart->draw(
  76                  data    => \@data,
  77                  font    => $font,
  78                  title   => {
  79                                  text  => "Hello, World!",
  80                                  size  => 36,
  81                                  color => 'FF0000'
  82                             }
  83                  );
  84
  85 When referring to a single sub-value this documentation will refer to
  86 'title.color' rather than 'the color element of title'.
  87
  88 Returns the graph image on success, or false on failure.
  89
  90 =back
  91
  92 =head1 STYLES
  93
  94 The currently defined styles are:
  95
  96 =over
  97
  98 =item primary
  99
 100 a light grey background with no outlines.  Uses primary colors for the
 101 data fills.
 102
 103 =item primary_red
 104
 105 a light red background with no outlines.  Uses primary colors for the
 106 data fills.
 107
 108 Graphs drawn using this style should save well as a gif, even though
 109 some graphs may perform a slight blur.
 110
 111 This was the default style, but the red was too loud.
 112
 113 =item mono
 114
 115 designed for monochrome output, such as most laser printers, this uses
 116 hatched fills for the data, and no colors.  The returned image is a
 117 one channel image (which can be overridden with the C<channels>
 118 parameter.)
 119
 120 You can also override the colors used by all components for background
 121 or drawing by supplying C<fg> and/or C<bg> parameters.  ie.  if you
 122 supply C<<fg=>'FF0000', channels=>3>> then the hash fills and anything
 123 else will be drawn in red.  Another use might be to set a transparent
 124 background, by supplying C<<bg=>'00000000', channels=>4>>.
 125
 126 This style outlines the legend if present and outlines the hashed fills.
 127
 128 =item fount_lin
 129
 130 designed as a "pretty" style this uses linear fountain fills for the
 131 background and data fills, and adds a drop shadow.
 132
 133 You can override the value used for text and outlines by setting the
 134 C<fg> parameter.
 135
 136 This is the default style.
 137
 138 =item fount_rad
 139
 140 also designed as a "pretty" style this uses radial fountain fills for
 141 the data and a linear blue to green fill for the background.
 142
 143 =back
 144
 145 =head1 FEATURES
 146
 147 Each graph type has a number of features.  These are used to add
 148 various items that are displayed in the graph area.  Some common
 149 features are:
 150
 151 =over
 152
 153 =item legend
 154
 155 adds a box containing boxes filled with the data filess, with
 156 the labels provided to the draw method.  The legend will only be
 157 displayed if both the legend feature is enabled and labels are
 158 supplied.
 159
 160 =item labels
 161
 162 labels each data fill, usually by including text inside the data fill.
 163 If the text does not fit in the fill, they could be displayed in some
 164 other form, eg. as callouts in a pie graph.  There usually isn't much
 165 point in including both labels and a legend.
 166
 167 =item dropshadow
 168
 169 a simple drop shadow is shown behind some of the graph elements.
 170
 171 =back
 172
 173 Each graph also has features specific to that graph.
 174
 175 =head1 COMMON PARAMETERS
 176
 177 When referring to a single sub-value this documentation will refer to
 178 'title.color' rather than 'the color element of title'.
 179
 180 Normally, except for the font parameter, these are controlled by
 181 styles, but these are the style parameters I'd mostly likely expect
 182 you want to use:
 183
 184 =over
 185
 186 =item font
 187
 188 the Imager font object used to draw text on the chart.
 189
 190 =item back
 191
 192 the background fill for the graph.  Default depends on the style.
 193
 194 =item size
 195
 196 the base size of the graph image.  Default: 256
 197
 198 =item width
 199
 200 the width of the graph image.  Default: 1.5 * size (384)
 201
 202 =item height
 203
 204 the height of the graph image.  Default: size (256)
 205
 206 =item channels
 207
 208 the number of channels in the image.  Default: 3 (the 'mono' style
 209 sets this to 1).
 210
 211 =item line
 212
 213 the color used for drawing lines, such as outlines or callouts.
 214 Default depends on the current style.  Set to undef to remove the
 215 outline from a style.
 216
 217 =item title
 218
 219 the text used for a graph title.  Default: no title.  Note: this is
 220 the same as the title=>{ text => ... } field.
 221
 222 =over
 223
 224 =item halign
 225
 226 horizontal alignment of the title in the graph, one of 'left',
 227 'center' or 'right'. Default: center
 228
 229 =item valign
 230
 231 vertical alignment of the title, one of 'top', 'center' or 'right'.
 232 Default: top.  It's probably a bad idea to set this to 'center' unless
 233 you have a very short title.
 234
 235 =back
 236
 237 =item text
 238
 239 This contains basic defaults used in drawing text.
 240
 241 =over
 242
 243 =item color
 244
 245 the default color used for all text, defaults to the fg color.
 246
 247 =item size
 248
 249 the base size used for text, also used to scale many graph elements.
 250 Default: 14.
 251
 252 =back
 253
 254 =back
 255
 256 =head1 BEYOND STYLES
 257
 258 In most cases you will want to use just the styles, but you may want
 259 to exert more control over the way your chart looks.  This section
 260 describes the options you can use to control the way your chart looks.
 261
 262 Hopefully you don't need to read this.
 263
 264 =over
 265
 266 =item back
 267
 268 The background of the graph.
 269
 270 =item bg
 271
 272 =item fg
 273
 274 Used to define basic background and foreground colors for the graph.
 275 The bg color may be used for the background of the graph, and is used
 276 as a default for the background of hatcheed fills.  The fg is used as
 277 the default for line and text colors.
 278
 279 =item font
 280
 281 The default font used by the graph.  Normally you should supply this
 282 if your graph as any text.
 283
 284 =item line
 285
 286 The default line color.
 287
 288 =item text
 289
 290 defaults for drawing text.  Other textual graph elements will inherit
 291 or modify these values.
 292
 293 =over
 294
 295 =item color
 296
 297 default text color, defaults to the I<fg> color.
 298
 299 =item size
 300
 301 default text size. Default: 14.  This is used to scale many graph
 302 elements, including padding and leader sizes.  Other text elements
 303 will either use or scale this value.
 304
 305 =item font
 306
 307 default font object.  Inherited from I<font>, which should have been
 308 supplied by the caller.
 309
 310 =back
 311
 312 =item title
 313
 314 If you supply a scalar value for this element, it will be stored in
 315 the I<text> field.
 316
 317 Defines the text, font and layout information for the title.
 318
 319 =over
 320
 321 =item color
 322
 323 The color of the title, inherited from I<text.color>.
 324
 325 =item font
 326
 327 The font object used for the title, inherited from I<text.font>.
 328
 329 =item size
 330
 331 size of the title text. Default: double I<text.size>
 332
 333 =item halign
 334
 335 =item valign
 336
 337 The horizontal and vertical alignment of the title.
 338
 339 =back
 340
 341 =item legend
 342
 343 defines attributes of the graph legend, if present.
 344
 345 =over
 346
 347 =item color
 348
 349 =item font
 350
 351 =item size
 352
 353 text attributes for the labels used in the legend.
 354
 355 =item patchsize
 356
 357 the width and height of the color patch in the legend.  Defaults to
 358 90% of the legend text size.
 359
 360 =item patchgap
 361
 362 the minimum gap between patches in pixels.  Defaults to 30% of the
 363 patchsize.
 364
 365 =item patchborder
 366
 367 the color of the border drawn around each patch.  Inherited from I<line>.
 368
 369 =item halign
 370
 371 =item valign
 372
 373 the horizontal and vertical alignment of the legend within the graph.
 374 Defaults to 'right' and 'top'.
 375
 376 =item padding
 377
 378 the gap between the legend patches and text and the outside of it's
 379 box, or to the legend border, if any.
 380
 381 =item outsidepadding
 382
 383 the gap between the border and the outside of the legend's box.  This
 384 is only used if the I<legend.border> attribute is defined.
 385
 386 =item fill
 387
 388 the background fill for the legend.  Default: none
 389
 390 =item border
 391
 392 the border color of the legend.  Default: none (no border is drawn
 393 around the legend.)
 394
 395 =item orientation
 396
 397 The orientation of the legend.  If this is C<vertical> the the patches
 398 and labels are stacked on top of each other.  If this is C<horizontal>
 399 the patchs and labels are word wrapped across the image.  Default:
 400 vertical.
 401
 402 =back
 403
 404 For example to create a horizontal legend with borderless patches,
 405 darker than the background, you might do:
 406
 407   my $im = $chart->draw
 408     (...,
 409     legend =>
 410     {
 411       patchborder => undef,
 412       orientation => 'horizontal',
 413       fill => { solid => Imager::Color->new(0, 0, 0, 32), }
 414     },
 415     ...);
 416
 417 =item callout
 418
 419 defines attributes for graph callouts, if any are present.  eg. if the
 420 pie graph cannot fit the label into the pie graph segement it will
 421 present it as a callout.
 422
 423 =over
 424
 425 =item color
 426
 427 =item font
 428
 429 =item size
 430
 431 the text attributes of the callout label.  Inherited from I<text>.
 432
 433 =item line
 434
 435 the color of the callout lines.  Inherited from I<line>
 436
 437 =item inside
 438
 439 =item outside
 440
 441 the length of the leader on the inside and the outside of the fill,
 442 usually at some angle.  Both default to the size of the callout text.
 443
 444 =item leadlen
 445
 446 the length of the horizontal portion of the leader.  Default:
 447 I<callout.size>.
 448
 449 =item gap
 450
 451 the gap between the callout leader and the callout text.  Defaults to
 452 30% of the text callout size.
 453
 454 =back
 455
 456 =item label
 457
 458 defines attributes for labels drawn into the data areas of a graph.
 459
 460 =over
 461
 462 =item color
 463
 464 =item font
 465
 466 =item size
 467
 468 The text attributes of the labels.  Inherited from I<text>.
 469
 470 =back
 471
 472 =item dropshadow
 473
 474 the attributes of the graph's drop shadow
 475
 476 =over
 477
 478 =item fill
 479
 480 the fill used for the drop shadow.  Default: '404040' (dark gray)
 481
 482 =item off
 483
 484 the offset of the drop shadow.  A convenience value inherited by offx
 485 and offy.  Default: 40% of I<text.size>.
 486
 487 =item offx
 488
 489 =item offy
 490
 491 the horizontal and vertical offsets of the drop shadow.  Both
 492 inherited from I<dropshadow.off>.
 493
 494 =item filter
 495
 496 the filter description passed to Imager's filter method to blur the
 497 drop shadow.  Default: an 11 element convolution filter.
 498
 499 =back
 500
 501 =item outline
 502
 503 describes the lines drawn around filled data areas, such as the
 504 segments of a pie chart.
 505
 506 =over
 507
 508 =item line
 509
 510 the line color of the outlines, inherited from I<line>.
 511
 512 =back
 513
 514 =item fills
 515
 516 a reference to an array containing fills for each data item.
 517
 518 You can mix fill types, ie. using a simple color for the first item, a
 519 hatched fill for the second and a fountain fill for the next.
 520
 521 =back
 522
 523 =head1 HOW VALUES WORK
 524
 525 Internally rather than specifying literal color, fill, or font objects
 526 or literal sizes for each element, Imager::Graph uses a number of
 527 special values to inherit or modify values taken from other graph
 528 element names.
 529
 530 =head2 Specifying colors
 531
 532 You can specify colors by either supplying an Imager::Color object, by
 533 supplying lookup of another color, or by supplying a single value that
 534 Imager::Color::new can use as an initializer.  The most obvious is
 535 just a 6 or 8 digit hex value representing the red, green, blue and
 536 optionally alpha channels of the image.
 537
 538 You can lookup another color by using the lookup() "function", for
 539 example if you give a color as "lookup(fg)" then Imager::Graph will
 540 look for the fg element in the current style (or as overridden by
 541 you.)  This is used internally by Imager::Graph to set up the
 542 relationships between the colors of various elements, for example the
 543 default style information contains:
 544
 545    text=>{
 546           color=>'lookup(fg)',
 547           ...
 548          },
 549    legend =>{
 550              color=>'lookup(text.color)',
 551              ...
 552             },
 553
 554 So by setting the I<fg> color, you also set the default text color,
 555 since each text element uses lookup(text.color) as its value.
 556
 557 =head2 Specifying fills
 558
 559 Fills can be used for the graph background color, the background color
 560 for the legend block and for the fills used for each data element.
 561
 562 You can specify a fill as a L<color value|Specifying colors> or as a
 563 general fill, see L<Imager::Fill> for details.
 564
 565 You don't need (or usually want) to call Imager::Fill::new yourself,
 566 since the various fill functions will call it for you, and
 567 Imager::Graph provides some hooks to make them more useful.
 568
 569 =over
 570
 571 =item *
 572
 573 with hatched fills, if you don't supply a 'fg' or 'bg' parameter,
 574 Imager::Graph will supply the current graph fg and bg colors.
 575
 576 =item *
 577
 578 with fountain fill, you can supply the xa_ratio, ya_ratio, xb_ratio
 579 and yb_ratio parameters, and they will be scaled in the fill area to
 580 define the fountain fills xa, ya, xb and yb parameters.
 581
 582 =back
 583
 584 As with colors, you can use lookup(name) or lookup(name1.name2) to
 585 have one element to inherit the fill of another.
 586
 587 Imager::Graph defaults the fill combine value to C<'normal'>.  This
 588 doesn't apply to simple color fills.
 589
 590 =head2 Specifying numbers
 591
 592 You can specify various numbers, usually representing the size of
 593 something, commonly text, but sometimes the length of a line or the
 594 size of a gap.
 595
 596 You can use the same lookup mechanism as with colors and fills, but
 597 you can also scale values.  For example, 'scale(0.5,text.size)' will
 598 return half the size of the normal text size.
 599
 600 As with colors, this is used internally to scale graph elements based
 601 on the base text size.  If you change the base text size then other
 602 graph elements will scale as well.
 603
 604 =head2 Specifying other elements
 605
 606 Other elements, such as fonts, or parameters for a filter, can also
 607 use the lookup(name) mechanism.
 608
 609 =head1 INTERNAL METHODS
 610
 611 Only useful if you need to fix bugs, add features or create a new
 612 graph class.
 613
 614 =over
 615
 616 =cut
 617
 618 my %style_defs =
 619   (
 620    back=> 'lookup(bg)',
 621    line=> 'lookup(fg)',
 622    text=>{
 623           color => 'lookup(fg)',
 624           font  => 'lookup(font)',
 625           size  => 14,
 626          },
 627    title=>{
 628            color  => 'lookup(text.color)',
 629            font   => 'lookup(text.font)',
 630            halign => 'center',
 631            valign => 'top',
 632            size   => 'scale(text.size,2.0)',
 633           },
 634    legend =>{
 635              color          => 'lookup(text.color)',
 636              font           => 'lookup(text.font)',
 637              size           => 'lookup(text.size)',
 638              patchsize      => 'scale(legend.size,0.9)',
 639              patchgap       => 'scale(legend.patchsize,0.3)',
 640              patchborder    => 'lookup(line)',
 641              halign         => 'right',
 642              valign         => 'top',
 643              padding        => 'scale(legend.size,0.3)',
 644              outsidepadding => 'scale(legend.padding,0.4)',
 645             },
 646    callout => {
 647                color    => 'lookup(text.color)',
 648                font     => 'lookup(text.font)',
 649                size     => 'lookup(text.size)',
 650                line     => 'lookup(line)',
 651                inside   => 'lookup(callout.size)',
 652                outside  => 'lookup(callout.size)',
 653                leadlen  => 'scale(0.8,callout.size)',
 654                gap      => 'scale(callout.size,0.3)',
 655               },
 656    label => {
 657              font          => 'lookup(text.font)',
 658              size          => 'lookup(text.size)',
 659              color         => 'lookup(text.color)',
 660              hpad          => 'lookup(label.pad)',
 661              vpad          => 'lookup(label.pad)',
 662              pad           => 'scale(label.size,0.2)',
 663              pcformat      => sub { sprintf "%s (%.0f%%)", $_[0], $_[1] },
 664              pconlyformat  => sub { sprintf "%.1f%%", $_[0] },
 665              },
 666    dropshadow => {
 667                   fill    => { solid => Imager::Color->new(0, 0, 0, 96) },
 668                   off     => 'scale(0.4,text.size)',
 669                   offx    => 'lookup(dropshadow.off)',
 670                   offy    => 'lookup(dropshadow.off)',
 671                   filter  => { type=>'conv',
 672                               # this needs a fairly heavy blur
 673                               coef=>[0.1, 0.2, 0.4, 0.6, 0.7, 0.9, 1.2,
 674                                      0.9, 0.7, 0.6, 0.4, 0.2, 0.1 ] },
 675                  },
 676    outline => {
 677                line =>'lookup(line)',
 678               },
 679    size=>256,
 680    width=>'scale(1.5,size)',
 681    height=>'lookup(size)',
 682   );
 683
 684 =item _error($message)
 685
 686 Sets the error field of the object and returns an empty list or undef,
 687 depending on context.  Should be used for error handling, since it may
 688 provide some user hooks at some point.
 689
 690 =cut
 691
 692 sub _error {
 693   my ($self, $error) = @_;
 694
 695   $self->{_errstr} = $error;
 696
 697   return;
 698 }
 699
 700
 701 =item _style_defs()
 702
 703 Returns the style defaults, such as the relationships between line
 704 color and text color.
 705
 706 Intended to be over-ridden by base classes to provide graph specific
 707 defaults.
 708
 709 =cut
 710
 711 sub _style_defs {
 712   \%style_defs;
 713 }
 714
 715 # Let's make the default something that looks really good, so folks will be interested enough to customize the style.
 716 my $def_style = 'fount_lin';
 717
 718 my %styles =
 719   (
 720    primary =>
 721    {
 722     fills=>
 723     [
 724      qw(FF0000 00FF00 0000FF C0C000 00C0C0 FF00FF)
 725     ],
 726     fg=>'000000',
 727     bg=>'E0E0E0',
 728     legend=>
 729     {
 730      #patchborder=>'000000'
 731     },
 732    },
 733    primary_red =>
 734    {
 735     fills=>
 736     [
 737      qw(FF0000 00FF00 0000FF C0C000 00C0C0 FF00FF)
 738     ],
 739     fg=>'000000',
 740     bg=>'C08080',
 741     legend=>
 742     {
 743      patchborder=>'000000'
 744     },
 745    },
 746    mono =>
 747    {
 748     fills=>
 749     [
 750      { hatch=>'slash2' },
 751      { hatch=>'slosh2' },
 752      { hatch=>'vline2' },
 753      { hatch=>'hline2' },
 754      { hatch=>'cross2' },
 755      { hatch=>'grid2' },
 756      { hatch=>'stipple3' },
 757      { hatch=>'stipple2' },
 758     ],
 759     channels=>1,
 760     bg=>'FFFFFF',
 761     fg=>'000000',
 762     features=>{ outline=>1 },
 763     pie =>{
 764            blur=>undef,
 765           },
 766    },
 767    fount_lin =>
 768    {
 769     fills=>
 770     [
 771      { fountain=>'linear',
 772        xa_ratio=>0.13, ya_ratio=>0.13, xb_ratio=>0.87, yb_ratio=>0.87,
 773        segments => Imager::Fountain->simple(positions=>[0, 1],
 774                                             colors=>[ NC('FFC0C0'), NC('FF0000') ]),
 775      },
 776      { fountain=>'linear',
 777        xa_ratio=>0, ya_ratio=>0, xb_ratio=>1.0, yb_ratio=>1.0,
 778        segments => Imager::Fountain->simple(positions=>[0, 1],
 779                                             colors=>[ NC('C0FFC0'), NC('00FF00') ]),
 780      },
 781      { fountain=>'linear',
 782        xa_ratio=>0, ya_ratio=>0, xb_ratio=>1.0, yb_ratio=>1.0,
 783        segments => Imager::Fountain->simple(positions=>[0, 1],
 784                                             colors=>[ NC('C0C0FF'), NC('0000FF') ]),
 785      },
 786      { fountain=>'linear',
 787        xa_ratio=>0, ya_ratio=>0, xb_ratio=>1.0, yb_ratio=>1.0,
 788        segments => Imager::Fountain->simple(positions=>[0, 1],
 789                                             colors=>[ NC('FFFFC0'), NC('FFFF00') ]),
 790      },
 791      { fountain=>'linear',
 792        xa_ratio=>0, ya_ratio=>0, xb_ratio=>1.0, yb_ratio=>1.0,
 793        segments => Imager::Fountain->simple(positions=>[0, 1],
 794                                             colors=>[ NC('C0FFFF'), NC('00FFFF') ]),
 795      },
 796      { fountain=>'linear',
 797        xa_ratio=>0, ya_ratio=>0, xb_ratio=>1.0, yb_ratio=>1.0,
 798        segments => Imager::Fountain->simple(positions=>[0, 1],
 799                                             colors=>[ NC('FFC0FF'), NC('FF00FF') ]),
 800      },
 801     ],
 802     back=>{ fountain=>'linear',
 803             xa_ratio=>0, ya_ratio=>0,
 804             xb_ratio=>1.0, yb_ratio=>1.0,
 805             segments=>Imager::Fountain->simple
 806             ( positions=>[0, 1],
 807               colors=>[ NC('6060FF'), NC('60FF60') ]) },
 808     fg=>'000000',
 809     bg=>'FFFFFF',
 810     features=>{ dropshadow=>1 },
 811    },
 812    fount_rad =>
 813    {
 814     fills=>
 815     [
 816      { fountain=>'radial',
 817        xa_ratio=>0.5, ya_ratio=>0.5, xb_ratio=>1.0, yb_ratio=>0.5,
 818        segments => Imager::Fountain->simple(positions=>[0, 1],
 819                                             colors=>[ NC('FF8080'), NC('FF0000') ]),
 820      },
 821      { fountain=>'radial',
 822        xa_ratio=>0.5, ya_ratio=>0.5, xb_ratio=>1.0, yb_ratio=>0.5,
 823        segments => Imager::Fountain->simple(positions=>[0, 1],
 824                                             colors=>[ NC('80FF80'), NC('00FF00') ]),
 825      },
 826      { fountain=>'radial',
 827        xa_ratio=>0.5, ya_ratio=>0.5, xb_ratio=>1.0, yb_ratio=>0.5,
 828        segments => Imager::Fountain->simple(positions=>[0, 1],
 829                                             colors=>[ NC('808080FF'), NC('0000FF') ]),
 830      },
 831      { fountain=>'radial',
 832        xa_ratio=>0.5, ya_ratio=>0.5, xb_ratio=>1.0, yb_ratio=>0.5,
 833        segments => Imager::Fountain->simple(positions=>[0, 1],
 834                                             colors=>[ NC('FFFF80'), NC('FFFF00') ]),
 835      },
 836      { fountain=>'radial',
 837        xa_ratio=>0.5, ya_ratio=>0.5, xb_ratio=>1.0, yb_ratio=>0.5,
 838        segments => Imager::Fountain->simple(positions=>[0, 1],
 839                                             colors=>[ NC('80FFFF'), NC('00FFFF') ]),
 840      },
 841      { fountain=>'radial',
 842        xa_ratio=>0.5, ya_ratio=>0.5, xb_ratio=>1.0, yb_ratio=>0.5,
 843        segments => Imager::Fountain->simple(positions=>[0, 1],
 844                                             colors=>[ NC('FF80FF'), NC('FF00FF') ]),
 845      },
 846     ],
 847     back=>{ fountain=>'linear',
 848             xa_ratio=>0, ya_ratio=>0,
 849             xb_ratio=>1.0, yb_ratio=>1.0,
 850             segments=>Imager::Fountain->simple
 851             ( positions=>[0, 1],
 852               colors=>[ NC('6060FF'), NC('60FF60') ]) },
 853     fg=>'000000',
 854     bg=>'FFFFFF',
 855    }
 856   );
 857
 858 =item $self->_style_setup(\%opts)
 859
 860 Uses the values from %opts to build a customized hash describing the
 861 way the graph should be drawn.
 862
 863 =cut
 864
 865 sub _style_setup {
 866   my ($self, $opts) = @_;
 867   my $style_defs = $self->_style_defs;
 868   my $style;
 869   $style = $styles{$opts->{style}} if $opts->{style};
 870   $style ||= $styles{$def_style};
 871
 872   my @search_list = ( $style_defs, $style, $opts);
 873   my %work;
 874
 875   my @composite = $self->_composite();
 876   my %composite;
 877   @composite{@composite} = @composite;
 878
 879   for my $src (@search_list) {
 880     for my $key (keys %$src) {
 881       if ($composite{$key}) {
 882         $work{$key} = {} unless exists $work{$key};
 883         if (ref $src->{$key}) {
 884           # some keys have sub values, especially text
 885           @{$work{$key}}{keys %{$src->{$key}}} = values %{$src->{$key}};
 886         }
 887         else {
 888           # assume it's the text for a title or something
 889           $work{$key}{text} = $src->{$key};
 890         }
 891       }
 892       else {
 893         $work{$key} = $src->{$key};
 894       }
 895     }
 896   }
 897
 898   # features are handled specially
 899   $work{features} = {};
 900   for my $src (@search_list) {
 901     if ($src->{features}) {
 902       if (ref $src->{features}) {
 903         if (ref($src->{features}) =~ /ARRAY/) {
 904           # just set those features
 905           for my $feature (@{$src->{features}}) {
 906             $work{features}{$feature} = 1;
 907           }
 908         }
 909         elsif (ref($src->{features}) =~ /HASH/) {
 910           if ($src->{features}{reset}) {
 911             $work{features} = {}; # only the ones the user specifies
 912           }
 913           @{$work{features}}{keys %{$src->{features}}} =
 914             values(%{$src->{features}});
 915         }
 916       }
 917       else {
 918         # just set that single feature
 919         $work{features}{$src->{features}} = 1;
 920       }
 921     }
 922   }
 923   #use Data::Dumper;
 924   #print Dumper(\%work);
 925
 926   $self->{_style} = \%work;
 927 }
 928
 929 =item $self->_get_thing($name)
 930
 931 Retrieve some general 'thing'.
 932
 933 Supports the 'lookup(foo)' mechanism.
 934
 935 =cut
 936
 937 sub _get_thing {
 938   my ($self, $name, @depth) = @_;
 939
 940   push(@depth, $name);
 941   my $what;
 942   if ($name =~ /^(\w+)\.(\w+)$/) {
 943     $what = $self->{_style}{$1}{$2};
 944   }
 945   else {
 946     $what = $self->{_style}{$name};
 947   }
 948   defined $what or
 949     return;
 950   if (ref $what) {
 951     return $what;
 952   }
 953   elsif ($what =~ /^lookup\((\w+(?:\.\w+)?)\)$/) {
 954     @depth < MAX_DEPTH
 955       or return $self->_error("too many levels of recursion in lookup(@depth)");
 956     return $self->_get_thing($1, @depth);
 957   }
 958   else {
 959     return $what;
 960   }
 961 }
 962
 963 =item $self->_get_number($name)
 964
 965 Retrieves a number from the style.  The value in the style can be the
 966 number, or one of two functions:
 967
 968 =over
 969
 970 =item lookup(newname)
 971
 972 Recursively looks up I<newname> in the style.
 973
 974 =item scale(value1,value2)
 975
 976 Each value can be a number or a name.  Names are recursively looked up
 977 in the style and the product is returned.
 978
 979 =back
 980
 981 =cut
 982
 983 sub _get_number {
 984   my ($self, $name, @depth) = @_;
 985
 986   push(@depth, $name);
 987   my $what;
 988   if ($name =~ /^(\w+)\.(\w+)$/) {
 989     $what = $self->{_style}{$1}{$2};
 990   }
 991   else {
 992     $what = $self->{_style}{$name};
 993   }
 994   defined $what or
 995     return $self->_error("$name is undef (@depth)");
 996
 997   if (ref $what) {
 998     if ($what =~ /CODE/) {
 999       $what = $what->($self, $name);
1000     }
1001   }
1002   else {
1003     if ($what =~ /^lookup\(([\w.]+)\)$/) {
1004       @depth < MAX_DEPTH
1005         or return $self->_error("too many levels of recursion in lookup (@depth)");
1006       return $self->_get_number($1, @depth);
1007     }
1008     elsif ($what =~ /^scale\(
1009                     ((?:[a-z][\w.]*)|$NUM_RE)
1010                     ,
1011                     ((?:[a-z][\w.]*)|$NUM_RE)\)$/x) {
1012       my ($left, $right) = ($1, $2);
1013       unless ($left =~ /^$NUM_RE$/) {
1014         @depth < MAX_DEPTH
1015           or return $self->_error("too many levels of recursion in scale (@depth)");
1016         $left = $self->_get_number($left, @depth);
1017       }
1018       unless ($right =~ /^$NUM_RE$/) {
1019         @depth < MAX_DEPTH
1020           or return $self->_error("too many levels of recursion in scale (@depth)");
1021         $right = $self->_get_number($right, @depth);
1022       }
1023       return $left * $right;
1024     }
1025     else {
1026       return $what+0;
1027     }
1028   }
1029 }
1030
1031 =item $self->_get_integer($name)
1032
1033 Retrieves an integer from the style.  This is a simple wrapper around
1034 _get_number() that rounds the result to an integer.
1035
1036 =cut
1037
1038 sub _get_integer {
1039   my ($self, $name, @depth) = @_;
1040
1041   my $number = $self->_get_number($name, @depth)
1042     or return;
1043
1044   return sprintf("%.0f", $number);
1045 }
1046
1047 =item _get_color($name)
1048
1049 Returns a color object of the given name from the style hash.
1050
1051 Uses Imager::Color->new to translate normal scalars into color objects.
1052
1053 Allows the lookup(name) mechanism.
1054
1055 =cut
1056
1057 sub _get_color {
1058   my ($self, $name, @depth) = @_;
1059
1060   push(@depth, $name);
1061   my $what;
1062   if ($name =~ /^(\w+)\.(\w+)$/) {
1063     $what = $self->{_style}{$1}{$2};
1064   }
1065   else {
1066     $what = $self->{_style}{$name};
1067   }
1068
1069   defined($what)
1070     or return $self->_error("$name was undefined (@depth)");
1071
1072   unless (ref $what) {
1073     if ($what =~ /^lookup\((\w+(?:\.\w+)?)\)$/) {
1074       @depth < MAX_DEPTH or
1075         return $self->_error("too many levels of recursion in lookup (@depth)");
1076
1077       return $self->_get_color($1, @depth);
1078     }
1079     $what = Imager::Color->new($what);
1080   }
1081
1082   $what;
1083 }
1084
1085 =item _translate_fill($what, $box)
1086
1087 Given the value of a fill, either attempts to convert it into a fill
1088 list (one of C<<color=>$color_value, filled=>1>> or C<<fill=>{ fill
1089 parameters }>>), or to lookup another fill that is referred to with
1090 the 'lookup(name)' mechanism.
1091
1092 This function does the fg and bg initialization for hatched fills, and
1093 translation of *_ratio for fountain fills (using the $box parameter).
1094
1095 =cut
1096
1097 sub _translate_fill {
1098   my ($self, $what, $box, @depth) = @_;
1099
1100   if (ref $what) {
1101     if (UNIVERSAL::isa($what, "Imager::Color")) {
1102       return ( color=>Imager::Color->new($what), filled=>1 );
1103     }
1104     else {
1105       # a general fill
1106       # default to normal combine mode
1107       my %work = ( combine => 'normal', %$what );
1108       if ($what->{hatch}) {
1109         if (!$work{fg}) {
1110           $work{fg} = $self->_get_color('fg')
1111             or return;
1112         }
1113         if (!$work{bg}) {
1114           $work{bg} = $self->_get_color('bg')
1115             or return;
1116         }
1117         return ( fill=>\%work );
1118       }
1119       elsif ($what->{fountain}) {
1120         for my $key (qw(xa ya xb yb)) {
1121           if (exists $work{"${key}_ratio"}) {
1122             if ($key =~ /^x/) {
1123               $work{$key} = $box->[0] + $work{"${key}_ratio"}
1124                 * ($box->[2] - $box->[0]);
1125             }
1126             else {
1127               $work{$key} = $box->[1] + $work{"${key}_ratio"}
1128                 * ($box->[3] - $box->[1]);
1129             }
1130           }
1131         }
1132         return ( fill=>\%work );
1133       }
1134       else {
1135         return ( fill=> \%work );
1136       }
1137     }
1138   }
1139   else {
1140     if ($what =~ /^lookup\((\w+(?:\.\w+)?)\)$/) {
1141       return $self->_get_fill($1, $box, @depth);
1142     }
1143     else {
1144       # assumed to be an Imager::Color single value
1145       return ( color=>Imager::Color->new($what), filled=>1 );
1146     }
1147   }
1148 }
1149
1150 =item _data_fill($index, $box)
1151
1152 Retrieves the fill parameters for a data area fill.
1153
1154 =cut
1155
1156 sub _data_fill {
1157   my ($self, $index, $box) = @_;
1158
1159   my $fills = $self->{_style}{fills};
1160   return $self->_translate_fill($fills->[$index % @$fills], $box,
1161                                 "data.$index");
1162 }
1163
1164 =item _get_fill($index, $box)
1165
1166 Retrieves fill parameters for a named fill.
1167
1168 =cut
1169
1170 sub _get_fill {
1171   my ($self, $name, $box, @depth) = @_;
1172
1173   push(@depth, $name);
1174   my $what;
1175   if ($name =~ /^(\w+)\.(\w+)$/) {
1176     $what = $self->{_style}{$1}{$2};
1177   }
1178   else {
1179     $what = $self->{_style}{$name};
1180   }
1181
1182   defined($what)
1183     or return $self->_error("no fill $name found");
1184
1185   return $self->_translate_fill($what, $box, @depth);
1186 }
1187
1188 =item _make_img()
1189
1190 Builds the image object for the graph and fills it with the background
1191 fill.
1192
1193 =cut
1194
1195 sub _make_img {
1196   my ($self) = @_;
1197
1198   my $width = $self->_get_number('width') || 256;
1199   my $height = $self->_get_number('height') || 256;
1200   my $channels = $self->{_style}{channels};
1201
1202   $channels ||= 3;
1203
1204   my $img = Imager->new(xsize=>$width, ysize=>$height, channels=>$channels);
1205
1206   $img->box($self->_get_fill('back', [ 0, 0, $width-1, $height-1]));
1207
1208   $img;
1209 }
1210
1211 sub _text_style {
1212   my ($self, $name) = @_;
1213
1214   my %work;
1215
1216   if ($self->{_style}{$name}) {
1217     %work = %{$self->{_style}{$name}};
1218   }
1219   else {
1220     %work = %{$self->{_style}{text}};
1221   }
1222   $work{font}
1223       or return $self->_error("$name has no font parameter");
1224
1225   $work{font} = $self->_get_thing("$name.font")
1226     or return $self->_error("invalid font");
1227   UNIVERSAL::isa($work{font}, "Imager::Font")
1228       or return $self->_error("$name.font is not a font");
1229   if ($work{color} && !ref $work{color}) {
1230     $work{color} = $self->_get_color("$name.color")
1231       or return;
1232   }
1233   $work{size} = $self->_get_number("$name.size");
1234   $work{sizew} = $self->_get_number("$name.sizew")
1235     if $work{sizew};
1236
1237   %work;
1238 }
1239
1240 sub _text_bbox {
1241   my ($self, $text, $name) = @_;
1242
1243   my %text_info = $self->_text_style($name);
1244
1245   if (!defined $text_info{font}) {
1246     die "No font or invalid font specified, and we're trying to draw text.\n";
1247   }
1248   my @bbox = $text_info{font}->bounding_box(%text_info, string=>$text,
1249                                             canon=>1);
1250
1251   return @bbox[0..3];
1252 }
1253
1254 sub _align_box {
1255   my ($self, $box, $chart_box, $name) = @_;
1256
1257   my $halign = $self->{_style}{$name}{halign}
1258     or $self->_error("no halign for $name");
1259   my $valign = $self->{_style}{$name}{valign};
1260
1261   if ($halign eq 'right') {
1262     $box->[0] += $chart_box->[2] - $box->[2];
1263   }
1264   elsif ($halign eq 'left') {
1265     $box->[0] = $chart_box->[0];
1266   }
1267   elsif ($halign eq 'center' || $halign eq 'centre') {
1268     $box->[0] = ($chart_box->[0] + $chart_box->[2] - $box->[2])/2;
1269   }
1270   else {
1271     return $self->_error("invalid halign $halign for $name");
1272   }
1273
1274   if ($valign eq 'top') {
1275     $box->[1] = $chart_box->[1];
1276   }
1277   elsif ($valign eq 'bottom') {
1278     $box->[1] = $chart_box->[3] - $box->[3];
1279   }
1280   elsif ($valign eq 'center' || $valign eq 'centre') {
1281     $box->[1] = ($chart_box->[1] + $chart_box->[3] - $box->[3])/2;
1282   }
1283   else {
1284     return $self->_error("invalid valign $valign for $name");
1285   }
1286   $box->[2] += $box->[0];
1287   $box->[3] += $box->[1];
1288 }
1289
1290 sub _remove_box {
1291   my ($self, $chart_box, $object_box) = @_;
1292
1293   my $areax;
1294   my $areay;
1295   if ($object_box->[0] - $chart_box->[0]
1296       < $chart_box->[2] - $object_box->[2]) {
1297     $areax = ($object_box->[2] - $chart_box->[0])
1298       * ($chart_box->[3] - $chart_box->[1]);
1299   }
1300   else {
1301     $areax = ($chart_box->[2] - $object_box->[0])
1302       * ($chart_box->[3] - $chart_box->[1]);
1303   }
1304
1305   if ($object_box->[1] - $chart_box->[1]
1306       < $chart_box->[3] - $object_box->[3]) {
1307     $areay = ($object_box->[3] - $chart_box->[1])
1308       * ($chart_box->[2] - $chart_box->[0]);
1309   }
1310   else {
1311     $areay = ($chart_box->[3] - $object_box->[1])
1312       * ($chart_box->[2] - $chart_box->[0]);
1313   }
1314
1315   if ($areay < $areax) {
1316     if ($object_box->[1] - $chart_box->[1]
1317         < $chart_box->[3] - $object_box->[3]) {
1318       $chart_box->[1] = $object_box->[3];
1319     }
1320     else {
1321       $chart_box->[3] = $object_box->[1];
1322     }
1323   }
1324   else {
1325     if ($object_box->[0] - $chart_box->[0]
1326         < $chart_box->[2] - $object_box->[2]) {
1327       $chart_box->[0] = $object_box->[2];
1328     }
1329     else {
1330       $chart_box->[2] = $object_box->[0];
1331     }
1332   }
1333 }
1334
1335 sub _draw_legend {
1336   my ($self, $img, $labels, $chart_box) = @_;
1337
1338   my $orient = $self->_get_thing('legend.orientation');
1339   defined $orient or $orient = 'vertical';
1340
1341   if ($orient eq 'vertical') {
1342     return $self->_draw_legend_vertical($img, $labels, $chart_box);
1343   }
1344   elsif ($orient eq 'horizontal') {
1345     return $self->_draw_legend_horizontal($img, $labels, $chart_box);
1346   }
1347   else {
1348     return $self->_error("Unknown legend.orientation $orient");
1349   }
1350 }
1351
1352 sub _draw_legend_horizontal {
1353   my ($self, $img, $labels, $chart_box) = @_;
1354
1355   defined(my $padding = $self->_get_integer('legend.padding'))
1356     or return;
1357   my $patchsize = $self->_get_integer('legend.patchsize')
1358     or return;
1359   defined(my $gap = $self->_get_integer('legend.patchgap'))
1360     or return;
1361
1362   my $minrowsize = $patchsize + $gap;
1363   my ($width, $height) = (0,0);
1364   my $row_height = $minrowsize;
1365   my $pos = 0;
1366   my @sizes;
1367   my @offsets;
1368   for my $label (@$labels) {
1369     my @text_box = $self->_text_bbox($label, 'legend');
1370     push(@sizes, \@text_box);
1371     my $entry_width = $patchsize + $gap + $text_box[2];
1372     if ($pos == 0) {
1373       # never re-wrap the first entry
1374       push @offsets, [ 0, $height ];
1375     }
1376     else {
1377       if ($pos + $gap + $entry_width > $chart_box->[2]) {
1378         $pos = 0;
1379         $height += $row_height;
1380       }
1381       push @offsets, [ $pos, $height ];
1382     }
1383     my $entry_right = $pos + $entry_width;
1384     $pos += $gap + $entry_width;
1385     $entry_right > $width and $width = $entry_right;
1386     if ($text_box[3] > $row_height) {
1387       $row_height = $text_box[3];
1388     }
1389   }
1390   $height += $row_height;
1391   my @box = ( 0, 0, $width + $padding * 2, $height + $padding * 2 );
1392   my $outsidepadding = 0;
1393   if ($self->{_style}{legend}{border}) {
1394     defined($outsidepadding = $self->_get_integer('legend.outsidepadding'))
1395       or return;
1396     $box[2] += 2 * $outsidepadding;
1397     $box[3] += 2 * $outsidepadding;
1398   }
1399   $self->_align_box(\@box, $chart_box, 'legend')
1400     or return;
1401   if ($self->{_style}{legend}{fill}) {
1402     $img->box(xmin=>$box[0]+$outsidepadding,
1403               ymin=>$box[1]+$outsidepadding,
1404               xmax=>$box[2]-$outsidepadding,
1405               ymax=>$box[3]-$outsidepadding,
1406              $self->_get_fill('legend.fill', \@box));
1407   }
1408   $box[0] += $outsidepadding;
1409   $box[1] += $outsidepadding;
1410   $box[2] -= $outsidepadding;
1411   $box[3] -= $outsidepadding;
1412   my %text_info = $self->_text_style('legend')
1413     or return;
1414   my $patchborder;
1415   if ($self->{_style}{legend}{patchborder}) {
1416     $patchborder = $self->_get_color('legend.patchborder')
1417       or return;
1418   }
1419
1420   my $dataindex = 0;
1421   for my $label (@$labels) {
1422     my ($left, $top) = @{$offsets[$dataindex]};
1423     $left += $box[0] + $padding;
1424     $top += $box[1] + $padding;
1425     my $textpos = $left + $patchsize + $gap;
1426     my @patchbox = ( $left, $top,
1427                      $left + $patchsize, $top + $patchsize );
1428     my @fill = $self->_data_fill($dataindex, \@patchbox)
1429       or return;
1430     $img->box(xmin=>$left, ymin=>$top, xmax=>$left + $patchsize,
1431                ymax=>$top + $patchsize, @fill);
1432     if ($self->{_style}{legend}{patchborder}) {
1433       $img->box(xmin=>$left, ymin=>$top, xmax=>$left + $patchsize,
1434                 ymax=>$top + $patchsize,
1435                 color=>$patchborder);
1436     }
1437     $img->string(%text_info, x=>$textpos, 'y'=>$top + $patchsize,
1438                  text=>$label);
1439
1440     ++$dataindex;
1441   }
1442   if ($self->{_style}{legend}{border}) {
1443     my $border_color = $self->_get_color('legend.border')
1444       or return;
1445     $img->box(xmin=>$box[0], ymin=>$box[1], xmax=>$box[2], ymax=>$box[3],
1446               color=>$border_color);
1447   }
1448   $self->_remove_box($chart_box, \@box);
1449   1;
1450 }
1451
1452 sub _draw_legend_vertical {
1453   my ($self, $img, $labels, $chart_box) = @_;
1454
1455   defined(my $padding = $self->_get_integer('legend.padding'))
1456     or return;
1457   my $patchsize = $self->_get_integer('legend.patchsize')
1458     or return;
1459   defined(my $gap = $self->_get_integer('legend.patchgap'))
1460     or return;
1461   my $minrowsize = $patchsize + $gap;
1462   my ($width, $height) = (0,0);
1463   my @sizes;
1464   for my $label (@$labels) {
1465     my @box = $self->_text_bbox($label, 'legend');
1466     push(@sizes, \@box);
1467     $width = $box[2] if $box[2] > $width;
1468     if ($minrowsize > $box[3]) {
1469       $height += $minrowsize;
1470     }
1471     else {
1472       $height += $box[3];
1473     }
1474   }
1475   my @box = (0, 0,
1476              $width + $patchsize + $padding * 2 + $gap,
1477              $height + $padding * 2 - $gap);
1478   my $outsidepadding = 0;
1479   if ($self->{_style}{legend}{border}) {
1480     defined($outsidepadding = $self->_get_integer('legend.outsidepadding'))
1481       or return;
1482     $box[2] += 2 * $outsidepadding;
1483     $box[3] += 2 * $outsidepadding;
1484   }
1485   $self->_align_box(\@box, $chart_box, 'legend')
1486     or return;
1487   if ($self->{_style}{legend}{fill}) {
1488     $img->box(xmin=>$box[0]+$outsidepadding,
1489               ymin=>$box[1]+$outsidepadding,
1490               xmax=>$box[2]-$outsidepadding,
1491               ymax=>$box[3]-$outsidepadding,
1492              $self->_get_fill('legend.fill', \@box));
1493   }
1494   $box[0] += $outsidepadding;
1495   $box[1] += $outsidepadding;
1496   $box[2] -= $outsidepadding;
1497   $box[3] -= $outsidepadding;
1498   my $ypos = $box[1] + $padding;
1499   my $patchpos = $box[0]+$padding;
1500   my $textpos = $patchpos + $patchsize + $gap;
1501   my %text_info = $self->_text_style('legend')
1502     or return;
1503   my $patchborder;
1504   if ($self->{_style}{legend}{patchborder}) {
1505     $patchborder = $self->_get_color('legend.patchborder')
1506       or return;
1507   }
1508   my $dataindex = 0;
1509   for my $label (@$labels) {
1510     my @patchbox = ( $patchpos - $patchsize/2, $ypos - $patchsize/2,
1511                      $patchpos + $patchsize * 3 / 2, $ypos + $patchsize*3/2 );
1512     my @fill = $self->_data_fill($dataindex, \@patchbox)
1513       or return;
1514     $img->box(xmin=>$patchpos, ymin=>$ypos, xmax=>$patchpos + $patchsize,
1515                ymax=>$ypos + $patchsize, @fill);
1516     if ($self->{_style}{legend}{patchborder}) {
1517       $img->box(xmin=>$patchpos, ymin=>$ypos, xmax=>$patchpos + $patchsize,
1518                 ymax=>$ypos + $patchsize,
1519                 color=>$patchborder);
1520     }
1521     $img->string(%text_info, x=>$textpos, 'y'=>$ypos + $patchsize,
1522                  text=>$label);
1523
1524     my $step = $patchsize + $gap;
1525     if ($minrowsize < $sizes[$dataindex][3]) {
1526       $ypos += $sizes[$dataindex][3];
1527     }
1528     else {
1529       $ypos += $minrowsize;
1530     }
1531     ++$dataindex;
1532   }
1533   if ($self->{_style}{legend}{border}) {
1534     my $border_color = $self->_get_color('legend.border')
1535       or return;
1536     $img->box(xmin=>$box[0], ymin=>$box[1], xmax=>$box[2], ymax=>$box[3],
1537               color=>$border_color);
1538   }
1539   $self->_remove_box($chart_box, \@box);
1540   1;
1541 }
1542
1543 sub _draw_title {
1544   my ($self, $img, $chart_box) = @_;
1545
1546   my $title = $self->{_style}{title}{text};
1547   my @box = $self->_text_bbox($title, 'title');
1548   my $yoff = $box[1];
1549   @box[0,1] = (0,0);
1550   $self->_align_box(\@box, $chart_box, 'title');
1551   my %text_info = $self->_text_style('title');
1552   $img->string(%text_info, x=>$box[0], 'y'=>$box[3] + $yoff, text=>$title);
1553   $self->_remove_box($chart_box, \@box);
1554   1;
1555 }
1556
1557 sub _small_extent {
1558   my ($self, $box) = @_;
1559
1560   if ($box->[2] - $box->[0] > $box->[3] - $box->[1]) {
1561     return $box->[3] - $box->[1];
1562   }
1563   else {
1564     return $box->[2] - $box->[0];
1565   }
1566 }
1567
1568 =item _composite()
1569
1570 Returns a list of style fields that are stored as composites, and
1571 should be merged instead of just being replaced.
1572
1573 =cut
1574
1575 sub _composite {
1576   qw(title legend text label dropshadow outline callout);
1577 }
1578
1579 sub _filter_region {
1580   my ($self, $img, $left, $top, $right, $bottom, $filter) = @_;
1581
1582   unless (ref $filter) {
1583     my $name = $filter;
1584     $filter = $self->_get_thing($name)
1585       or return;
1586     $filter->{type}
1587       or return $self->_error("no type for filter $name");
1588   }
1589
1590   $left > 0 or $left = 0;
1591   $top > 0 or $top = 0;
1592
1593   # newer versions of Imager let you work on just part of an image
1594   if ($img->can('masked') && !$self->{_style}{features}{_debugblur}) {
1595     my $masked = $img->masked(left=>$left, top=>$top,
1596                               right=>$right, bottom=>$bottom);
1597     $masked->filter(%$filter);
1598   }
1599   else {
1600     # for older versions of Imager
1601     my $subset = $img->crop(left=>$left, top=>$top,
1602                             right=>$right, bottom=>$bottom);
1603     $subset->filter(%$filter);
1604     $img->paste(left=>$left, top=>$top, img=>$subset);
1605   }
1606 }
1607
1608 1;
1609 __END__
1610
1611 =back
1612
1613 =head1 SEE ALSO
1614
1615 Imager::Graph::Pie(3), Imager(3), perl(1).
1616
1617 =head1 AUTHOR
1618
1619 Tony Cook <tony@develop-help.com>
1620
1621 =head1 LICENSE
1622
1623 Imager::Graph is licensed under the same terms as perl itself.
1624
1625 =head1 BLAME
1626
1627 Addi for producing a cool imaging module. :)
1628
1629 =cut