-The bits() method retrieves the number of bits used to represent each
-channel in a pixel, typically 8. The type() method returns either
-'direct' for truecolor images or 'paletted' for paletted images. The
-virtual() method returns non-zero if the image contains no actual
-pixels, for example masked images.
-
-=head2 Paletted Images
-
-In general you can work with paletted images in the same way as RGB
-images, except that if you attempt to draw to a paletted image with a
-color that is not in the image's palette, the image will be converted
-to an RGB image. This means that drawing on a paletted image with
-anti-aliasing enabled will almost certainly convert the image to RGB.
-
-You can add colors to a paletted image with the addcolors() method:
-
- my @colors = ( Imager::Color->new(255, 0, 0),
- Imager::Color->new(0, 255, 0) );
- my $index = $img->addcolors(colors=>\@colors);
-
-The return value is the index of the first color added, or undef if
-adding the colors would overflow the palette.
-
-Once you have colors in the palette you can overwrite them with the
-setcolors() method:
-
- $img->setcolors(start=>$start, colors=>\@colors);
-
-Returns true on success.
-
-To retrieve existing colors from the palette use the getcolors() method:
-
- # get the whole palette
- my @colors = $img->getcolors();
- # get a single color
- my $color = $img->getcolors(start=>$index);
- # get a range of colors
- my @colors = $img->getcolors(start=>$index, count=>$count);
-
-To quickly find a color in the palette use findcolor():
-
- my $index = $img->findcolor(color=>$color);
-
-which returns undef on failure, or the index of the color.
-
-You can get the current palette size with $img->colorcount, and the
-maximum size of the palette with $img->maxcolors.
-
-=head2 Drawing Methods
-
-IMPLEMENTATION MORE OR LESS DONE CHECK THE TESTS
-DOCUMENTATION OF THIS SECTION OUT OF SYNC
-
-It is possible to draw with graphics primitives onto images. Such
-primitives include boxes, arcs, circles and lines. A reference
-oriented list follows.
-
-Box:
- $img->box(color=>$blue,xmin=>10,ymin=>30,xmax=>200,ymax=>300,filled=>1);
-
-The above example calls the C<box> method for the image and the box
-covers the pixels with in the rectangle specified. If C<filled> is
-ommited it is drawn as an outline. If any of the edges of the box are
-ommited it will snap to the outer edge of the image in that direction.
-Also if a color is omitted a color with (255,255,255,255) is used
-instead.
-
-Arc:
- $img->arc(color=>$red, r=20, x=>200, y=>100, d1=>10, d2=>20 );
-
-This creates a filled red arc with a 'center' at (200, 100) and spans
-10 degrees and the slice has a radius of 20. SEE section on BUGS.
-
-Circle:
- $img->circle(color=>$green, r=50, x=>200, y=>100);
-
-This creates a green circle with its center at (200, 100) and has a
-radius of 20.
-
-Line:
- $img->line(color=>$green, x1=10, x2=>100,
- y1=>20, y2=>50, antialias=>1 );
-
-That draws an antialiased line from (10,100) to (20,50).
-
-Polyline:
- $img->polyline(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
- $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], antialias=>1);
-
-Polyline is used to draw multilple lines between a series of points.
-The point set can either be specified as an arrayref to an array of
-array references (where each such array represents a point). The
-other way is to specify two array references.
-
-=head2 Text rendering
-
-Text rendering is described in the Imager::Font manpage.
-
-=head2 Image resizing
-
-To scale an image so porportions are maintained use the
-C<$img-E<gt>scale()> method. if you give either a xpixels or ypixels
-parameter they will determine the width or height respectively. If
-both are given the one resulting in a larger image is used. example:
-C<$img> is 700 pixels wide and 500 pixels tall.
-
- $img->scale(xpixels=>400); # 400x285
- $img->scale(ypixels=>400); # 560x400
-
- $img->scale(xpixels=>400,ypixels=>400); # 560x400
- $img->scale(xpixels=>400,ypixels=>400,type=>min); # 400x285
-
- $img->scale(scalefactor=>0.25); 175x125 $img->scale(); # 350x250
-
-if you want to create low quality previews of images you can pass
-C<qtype=E<gt>'preview'> to scale and it will use nearest neighbor
-sampling instead of filtering. It is much faster but also generates
-worse looking images - especially if the original has a lot of sharp
-variations and the scaled image is by more than 3-5 times smaller than
-the original.
-
-If you need to scale images per axis it is best to do it simply by
-calling scaleX and scaleY. You can pass either 'scalefactor' or
-'pixels' to both functions.
-
-Another way to resize an image size is to crop it. The parameters
-to crop are the edges of the area that you want in the returned image.
-If a parameter is omited a default is used instead.
-
- $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100);
- $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);
- $newimg = $img->crop(left=>50, right=>100); # top
-
-You can also specify width and height parameters which will produce a
-new image cropped from the center of the input image, with the given
-width and height.
-
- $newimg = $img->crop(width=>50, height=>50);
-
-The width and height parameters take precedence over the left/right
-and top/bottom parameters respectively.
-
-=head2 Copying images
-
-To create a copy of an image use the C<copy()> method. This is usefull
-if you want to keep an original after doing something that changes the image
-inplace like writing text.
-
- $img=$orig->copy();
-
-To copy an image to onto another image use the C<paste()> method.
-
- $dest->paste(left=>40,top=>20,img=>$logo);
-
-That copies the entire C<$logo> image onto the C<$dest> image so that the
-upper left corner of the C<$logo> image is at (40,20).
-
-
-=head2 Flipping images
-
-An inplace horizontal or vertical flip is possible by calling the
-C<flip()> method. If the original is to be preserved it's possible to
-make a copy first. The only parameter it takes is the C<dir>
-parameter which can take the values C<h>, C<v>, C<vh> and C<hv>.
-
- $img->flip(dir=>"h"); # horizontal flip
- $img->flip(dir=>"vh"); # vertical and horizontal flip
- $nimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically
-
-=head2 Rotating images
-
-Use the rotate() method to rotate an image.
-
-To rotate by an exact amount in degrees or radians, use the 'degrees'
-or 'radians' parameter:
-
- my $rot20 = $img->rotate(degrees=>20);
- my $rotpi4 = $img->rotate(radians=>3.14159265/4);
-
-To rotate in steps of 90 degrees, use the 'right' parameter:
-
- my $rotated = $img->rotate(right=>270);
-
-Rotations are clockwise for positive values.
-
-=head2 Blending Images
-
-To put an image or a part of an image directly
-into another it is best to call the C<paste()> method on the image you
-want to add to.
-
- $img->paste(img=>$srcimage,left=>30,top=>50);
-
-That will take paste C<$srcimage> into C<$img> with the upper
-left corner at (30,50). If no values are given for C<left>
-or C<top> they will default to 0.
-
-A more complicated way of blending images is where one image is
-put 'over' the other with a certain amount of opaqueness. The
-method that does this is rubthrough.
-
- $img->rubthrough(src=>$srcimage,tx=>30,ty=>50);
-
-That will take the image C<$srcimage> and overlay it with the upper
-left corner at (30,50). You can rub 2 or 4 channel images onto a 3
-channel image, or a 2 channel image onto a 1 channel image. The last
-channel is used as an alpha channel.
-
-
-=head2 Filters
-
-A special image method is the filter method. An example is:
-
- $img->filter(type=>'autolevels');
-
-This will call the autolevels filter. Here is a list of the filters
-that are always avaliable in Imager. This list can be obtained by
-running the C<filterlist.perl> script that comes with the module
-source.
-
- Filter Arguments
- autolevels lsat(0.1) usat(0.1) skew(0)
- bumpmap bump elevation(0) lightx lighty st(2)
- contrast intensity
- conv coef
- fountain xa ya xb yb ftype(linear) repeat(none) combine(0)
- super_sample(none) ssample_param(4) segments(see below)
- gaussian stddev
- gradgen xo yo colors dist
- hardinvert
- mosaic size(20)
- noise amount(3) subtype(0)
- postlevels levels(10)
- radnoise xo(100) yo(100) ascale(17.0) rscale(0.02)
- turbnoise xo(0.0) yo(0.0) scale(10.0)
- watermark wmark pixdiff(10) tx(0) ty(0)
-
-The default values are in parenthesis. All parameters must have some
-value but if a parameter has a default value it may be omitted when
-calling the filter function.
-
-The filters are:
-
-=over
-
-=item autolevels
-
-scales the value of each channel so that the values in the image will
-cover the whole possible range for the channel. I<lsat> and I<usat>
-truncate the range by the specified fraction at the top and bottom of
-the range respectivly..
-
-=item bumpmap
-
-uses the channel I<elevation> image I<bump> as a bumpmap on your
-image, with the light at (I<lightx>, I<lightty>), with a shadow length
-of I<st>.
-
-=item contrast
-
-scales each channel by I<intensity>. Values of I<intensity> < 1.0
-will reduce the contrast.
-
-=item conv
-
-performs 2 1-dimensional convolutions on the image using the values
-from I<coef>. I<coef> should be have an odd length.
-
-=item fountain
-
-renders a fountain fill, similar to the gradient tool in most paint
-software. The default fill is a linear fill from opaque black to
-opaque white. The points A(xa, ya) and B(xb, yb) control the way the
-fill is performed, depending on the ftype parameter:
-
-=over
-
-=item linear
-
-the fill ramps from A through to B.
-
-=item bilinear
-
-the fill ramps in both directions from A, where AB defines the length
-of the gradient.
-
-=item radial
-
-A is the center of a circle, and B is a point on it's circumference.
-The fill ramps from the center out to the circumference.
-
-=item radial_square
-
-A is the center of a square and B is the center of one of it's sides.
-This can be used to rotate the square. The fill ramps out to the
-edges of the square.
-
-=item revolution
-
-A is the centre of a circle and B is a point on it's circumference. B
-marks the 0 and 360 point on the circle, with the fill ramping
-clockwise.
-
-=item conical
-
-A is the center of a circle and B is a point on it's circumference. B
-marks the 0 and point on the circle, with the fill ramping in both
-directions to meet opposite.
-
-=back
-
-The I<repeat> option controls how the fill is repeated for some
-I<ftype>s after it leaves the AB range:
-
-=over
-
-=item none
-
-no repeats, points outside of each range are treated as if they were
-on the extreme end of that range.
-
-=item sawtooth
-
-the fill simply repeats in the positive direction
-
-=item triangle
-
-the fill repeats in reverse and then forward and so on, in the
-positive direction
-
-=item saw_both
-
-the fill repeats in both the positive and negative directions (only
-meaningful for a linear fill).
-
-=item tri_both
-
-as for triangle, but in the negative direction too (only meaningful
-for a linear fill).
-
-=back
-
-By default the fill simply overwrites the whole image (unless you have
-parts of the range 0 through 1 that aren't covered by a segment), if
-any segments of your fill have any transparency, you can set the
-I<combine> option to 1 to have the fill combined with the existing pixels.
-
-If your fill has sharp edges, for example between steps if you use
-repeat set to 'triangle', you may see some aliased or ragged edges.
-You can enable super-sampling which will take extra samples within the
-pixel in an attempt anti-alias the fill.
-
-The possible values for the super_sample option are:
-
-=over
-
-=item none
-
-no super-sampling is done
-
-=item grid
-
-a square grid of points are sampled. The number of points sampled is
-the square of ceil(0.5 + sqrt(ssample_param)).
-
-=item random
-
-a random set of points within the pixel are sampled. This looks
-pretty bad for low ssample_param values.
-
-=item circle
-
-the points on the radius of a circle within the pixel are sampled.
-This seems to produce the best results, but is fairly slow (for now).
-
-=back
projects / imager.git / blobdiff