lib/Imager/Draw.pod

   1 =head1 NAME
   2
   3 Imager::Draw - Draw primitives to images
   4
   5 =head1 SYNOPSIS
   6
   7   use Imager;
   8   use Imager::Fill;
   9
  10   $img = ...;
  11   $blue = Imager::Color->new( 0, 0, 255 );
  12   $fill = Imager::Fill->new(hatch=>'stipple');
  13
  14   $img->line(color=>$blue, x1=>10, x2=>100,
  15                            y1=>20, y2=>50, aa=>1, endp=>1 );
  16
  17   $img->polyline(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]],
  18                  color=>$blue);
  19   $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1);
  20
  21   $img->box(color=> $blue, xmin=> 10, ymin=>30,
  22                            xmax=>200, ymax=>300, filled=>1);
  23   $img->box(fill=>$fill);
  24
  25   $img->arc(color=>$blue, r=>20, x=>200, y=>100,
  26             d1=>10, d2=>20 );
  27
  28   $img->circle(color=>$blue, r=>50, x=>200, y=>100);
  29
  30   $img->polygon(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]],
  31                 color=>$blue);
  32
  33   $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2]);
  34
  35   $img->flood_fill(x=>50, y=>50, color=>$color);
  36
  37   $img->setpixel(x=>50, y=>70, color=>$color);
  38
  39   $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);
  40
  41   my $color = $img->getpixel(x=>50, y=>70);
  42
  43   my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
  44
  45 =head1 DESCRIPTION
  46
  47 It is possible to draw with graphics primitives onto images.  Such
  48 primitives include boxes, arcs, circles, polygons and lines.  The
  49 coordinate system in Imager has the origin C<(0,0)> in the upper left
  50 corner of an image.  For non antialiasing operation all coordinates are
  51 rounded towards the nearest integer.  For antialiased operations floating
  52 point coordinates are used.
  53
  54 Drawing is assumed to take place in a coordinate system of infinite
  55 resolution.  This is the typical convention and really only matters when
  56 it is necessary to check for off-by-one cases.  Typically it's usefull to
  57 think of C<(10, 20)> as C<(10.00, 20.00)> and consider the consiquences.
  58
  59 The C<color> parameter for any of the drawing methods can be an
  60 L<Imager::Color> object, a simple scalar that Imager::Color can
  61 understand, a hashref of parameters that Imager::Color->new
  62 understands, or an arrayref of red, green, blue values, for example:
  63
  64   $image->box(..., color=>'red');
  65   $image->line(..., color=>'#FF0000');
  66   $image->flood_fill(..., color=>[ 255, 0, 255 ]);
  67
  68 All filled primitives, i.e. C<arc()>, C<box()>, C<circle()>,
  69 C<polygon()> and the C<flood_fill()> method can take a C<fill>
  70 parameter instead of a C<color> parameter which can either be an
  71 Imager::Fill object, or a reference to a hash containing the
  72 parameters used to create the fill, for example:
  73
  74   $image->box(..., fill=>{ hatch => 'check1x1' });
  75   my $fillimage = Imager->new;
  76   $fillimage->read(file=>$somefile) or die;
  77   $image->flood_fill(..., fill=>{ image=>$fillimage });
  78
  79 Currently you can create opaque or transparent plain color fills,
  80 hatched fills, image based fills and fountain fills.  See
  81 L<Imager::Fill> for more information.
  82
  83 =head2 List of primitives
  84
  85 =over
  86
  87 =item line
  88
  89   $img->line(color=>$green, x1=>10, x2=>100,
  90                             y1=>20, y2=>50, aa=>1, endp=>1 );
  91
  92 Draws a line from (x1,y1) to (x2,y2).  The endpoint (x2,y2) is drawn
  93 by default.  If endp of 0 is specified then the endpoint will not be
  94 drawn.  If C<aa> is set then the line will be drawn antialiased.  The
  95 I<antialias> parameter is still available for backwards compatibility.
  96
  97 =item polyline
  98
  99   $img->polyline(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
 100   $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1);
 101
 102 Polyline is used to draw multilple lines between a series of points.
 103 The point set can either be specified as an arrayref to an array of
 104 array references (where each such array represents a point).  The
 105 other way is to specify two array references.
 106
 107 The I<antialias> parameter is still available for backwards compatibility.
 108
 109 =item box
 110
 111   $blue = Imager::Color->new( 0, 0, 255 );
 112   $img->box(color => $blue, xmin=>10, ymin=>30, xmax=>200, ymax=>300,
 113             filled=>1);
 114
 115 If any of the edges of the box are ommited it will snap to the outer
 116 edge of the image in that direction.  If C<filled> is ommited the box
 117 is drawn as an outline.  Instead of a color it is possible to use a C<fill>
 118 pattern:
 119
 120   $fill = Imager::Fill->new(hatch=>'stipple');
 121   $img->box(fill=>$fill);  # fill entire image with a given fill pattern
 122
 123   $img->box(xmin=>10, ymin=>30, xmax=>150, ymax=>60,
 124             fill => { hatch=>'cross2' });
 125
 126 Also if a color is omitted a color with (255,255,255,255) is used
 127 instead.  [NOTE: This may change to use C<$img-E<gt>fgcolor()> in the future].
 128
 129 Box does not support fractional coordinates yet.
 130
 131 =item arc
 132
 133   $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20 );
 134
 135 This creates a filled red arc with a 'center' at (200, 100) and spans
 136 10 degrees and the slice has a radius of 20. [NOTE: arc has a BUG in
 137 it right now for large differences in angles.]
 138 It's also possible to supply a C<fill> parameter.
 139
 140 =item circle
 141
 142   $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1);
 143
 144 This creates an antialiased green circle with its center at (200, 100)
 145 and has a radius of 50.  It's also possible to supply a C<fill> parameter
 146 instead of a color parameter.
 147
 148 The circle is always filled but that might change, so always pass a
 149 filled=>1 parameter if you want it to be filled.
 150
 151
 152 =item polygon
 153
 154   $img->polygon(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
 155   $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], fill=>$fill);
 156
 157 Polygon is used to draw a filled polygon.  Currently the polygon is
 158 always drawn antialiased, although that will change in the future.
 159 Like other antialiased drawing functions its coordinates can be
 160 specified with floating point values.  As with other filled shapes
 161 it's possible to use a C<fill> instead of a color.
 162
 163 =item flood_fill
 164
 165 You can fill a region that all has the same color using the
 166 flood_fill() method, for example:
 167
 168   $img->flood_fill(x=>50, y=>50, color=>$color);
 169
 170 will fill all regions the same color connected to the point (50, 50).
 171
 172 You can also fill with a complex fill:
 173
 174   $img->flood_fill(x=>50, y=>50, fill=>{ hatch=>'cross1x1' });
 175
 176 =item setpixel and getpixel
 177
 178   $img->setpixel(x=>50, y=>70, color=>$color);
 179   $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);
 180   my $color = $img->getpixel(x=>50, y=>70);
 181   my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
 182
 183 setpixel() is used to set one or more individual pixels, and
 184 getpixel() to retrieve the same.
 185
 186 For either method you can supply a single set of co-ordinates as
 187 scalar x and y parameters, or set each to an arrayref of ordinates.
 188
 189 When called with arrays, getpixel() will return a list of colors in
 190 list context, and an arrayref in scalar context.
 191
 192 To receive floating point colors from getpixel, set the C<type>
 193 parameter to 'float'.
 194
 195 =head1 BUGS
 196
 197 box, arc, do not support antialiasing yet.  Arc, is only filled as of
 198 yet.  Default color is not unified yet.
 199
 200 =head1 SEE ALSO
 201
 202 Imager(3), Imager::Cookbook(3)
 203
 204 =back