-=item random
-
-A semi-random map is used. The map is the same each time.
-
-=item dot8
-
-8x8 dot dither.
-
-=item dot4
-
-4x4 dot dither
-
-=item hline
-
-horizontal line dither.
-
-=item vline
-
-vertical line dither.
-
-=item "/line"
-
-=item slashline
-
-diagonal line dither
-
-=item '\line'
-
-=item backline
-
-diagonal line dither
-
-=item tiny
-
-dot matrix dither (currently the default). This is probably the best
-for displays (like web pages).
-
-=item custom
-
-A custom dither matrix is used - see tr_map
-
-=back
-
-=item tr_map
-
-When tr_orddith is custom this defines an 8 x 8 matrix of integers
-representing the transparency threshold for pixels corresponding to
-each position. This should be a 64 element array where the first 8
-entries correspond to the first row of the matrix. Values should be
-betweern 0 and 255.
-
-=item make_colors
-
-Defines how the quantization engine will build the palette(s).
-Currently this is ignored if 'translate' is 'giflib', but that may
-change. Possible values are:
-
-=over 4
-
-=item none
-
-Only colors supplied in 'colors' are used.
-
-=item webmap
-
-The web color map is used (need url here.)
-
-=item addi
-
-The original code for generating the color map (Addi's code) is used.
-
-=back
-
-Other methods may be added in the future.
-
-=item colors
-
-A arrayref containing Imager::Color objects, which represents the
-starting set of colors to use in translating the images. webmap will
-ignore this. The final colors used are copied back into this array
-(which is expanded if necessary.)
-
-=item max_colors
-
-The maximum number of colors to use in the image.
-
-=item translate
-
-The method used to translate the RGB values in the source image into
-the colors selected by make_colors. Note that make_colors is ignored
-whene translate is 'giflib'.
-
-Possible values are:
-
-=over 4
-
-=item giflib
-
-The giflib native quantization function is used.
-
-=item closest
-
-The closest color available is used.
-
-=item perturb
-
-The pixel color is modified by perturb, and the closest color is chosen.
-
-=item errdiff
-
-An error diffusion dither is performed.
-
-=back
-
-It's possible other transate values will be added.
-
-=item errdiff
-
-The type of error diffusion dither to perform. These values (except
-for custom) can also be used in tr_errdif.
-
-=over 4
-
-=item floyd
-
-Floyd-Steinberg dither
-
-=item jarvis
-
-Jarvis, Judice and Ninke dither
-
-=item stucki
-
-Stucki dither
-
-=item custom
-
-Custom. If you use this you must also set errdiff_width,
-errdiff_height and errdiff_map.
-
-=back
-
-=item errdiff_width
-
-=item errdiff_height
-
-=item errdiff_orig
-
-=item errdiff_map
-
-When translate is 'errdiff' and errdiff is 'custom' these define a
-custom error diffusion map. errdiff_width and errdiff_height define
-the size of the map in the arrayref in errdiff_map. errdiff_orig is
-an integer which indicates the current pixel position in the top row
-of the map.
-
-=item perturb
-
-When translate is 'perturb' this is the magnitude of the random bias
-applied to each channel of the pixel before it is looked up in the
-color table.
-
-=back
-
-=head2 Obtaining/setting attributes of images
-
-To get the size of an image in pixels the C<$img-E<gt>getwidth()> and
-C<$img-E<gt>getheight()> are used.
-
-To get the number of channels in
-an image C<$img-E<gt>getchannels()> is used. $img-E<gt>getmask() and
-$img-E<gt>setmask() are used to get/set the channel mask of the image.
-
- $mask=$img->getmask();
- $img->setmask(mask=>1+2); # modify red and green only
- $img->setmask(mask=>8); # modify alpha only
- $img->setmask(mask=>$mask); # restore previous mask
-
-The mask of an image describes which channels are updated when some
-operation is performed on an image. Naturally it is not possible to
-apply masks to operations like scaling that alter the dimensions of
-images.
-
-It is possible to have Imager find the number of colors in an image
-by using C<$img-E<gt>getcolorcount()>. It requires memory proportionally
-to the number of colors in the image so it is possible to have it
-stop sooner if you only need to know if there are more than a certain number
-of colors in the image. If there are more colors than asked for
-the function return undef. Examples:
-
- if (!defined($img->getcolorcount(maxcolors=>512)) {
- print "Less than 512 colors in image\n";
- }
-
-=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 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). The C<$srcimage> must be a 4 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
- turbnoise
- autolevels lsat(0.1) usat(0.1) skew(0)
- radnoise
- noise amount(3) subtype(0)
- contrast intensity
- hardinvert
- gradgen xo yo colors dist
-
-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.
-
-FIXME: make a seperate pod for filters?
-
-=head2 Color transformations
-
-You can use the convert method to transform the color space of an
-image using a matrix. For ease of use some presets are provided.
-
-The convert method can be used to:
-
-=over 4
-
-=item *
-
-convert an RGB or RGBA image to grayscale.
-
-=item *
-
-convert a grayscale image to RGB.
-
-=item *
-
-extract a single channel from an image.
-
-=item *
-
-set a given channel to a particular value (or from another channel)
-
-=back
-
-The currently defined presets are:
-
-=over
-
-=item gray
-
-=item grey
-
-converts an RGBA image into a grayscale image with alpha channel, or
-an RGB image into a grayscale image without an alpha channel.
-
-This weights the RGB channels at 22.2%, 70.7% and 7.1% respectively.
-
-=item noalpha
-
-removes the alpha channel from a 2 or 4 channel image. An identity
-for other images.
-
-=item red
-
-=item channel0
-
-extracts the first channel of the image into a single channel image
-
-=item green
-
-=item channel1
-
-extracts the second channel of the image into a single channel image
-
-=item blue
-
-=item channel2
-
-extracts the third channel of the image into a single channel image
-
-=item alpha
-
-extracts the alpha channel of the image into a single channel image.
-
-If the image has 1 or 3 channels (assumed to be grayscale of RGB) then
-the resulting image will be all white.
-
-=item rgb
-
-converts a grayscale image to RGB, preserving the alpha channel if any
-
-=item addalpha
-
-adds an alpha channel to a grayscale or RGB image. Preserves an
-existing alpha channel for a 2 or 4 channel image.
-
-=back
-
-For example, to convert an RGB image into a greyscale image:
-
- $new = $img->convert(preset=>'grey'); # or gray
-
-or to convert a grayscale image to an RGB image:
-
- $new = $img->convert(preset=>'rgb');
-
-The presets aren't necessary simple constants in the code, some are
-generated based on the number of channels in the input image.
-
-If you want to perform some other colour transformation, you can use
-the 'matrix' parameter.
-
-For each output pixel the following matrix multiplication is done:
-
- channel[0] [ [ $c00, $c01, ... ] inchannel[0]
- [ ... ] = ... x [ ... ]
- channel[n-1] [ $cn0, ..., $cnn ] ] inchannel[max]
- 1
-
-So if you want to swap the red and green channels on a 3 channel image:
-
- $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
- [ 1, 0, 0 ],
- [ 0, 0, 1 ] ]);
-
-or to convert a 3 channel image to greyscale using equal weightings:
-
- $new = $img->convert(matrix=>[ [ 0.333, 0.333, 0.334 ] ])
-
-=head2 Color Mappings
-
-You can use the map method to map the values of each channel of an
-image independently using a list of lookup tables. It's important to
-realize that the modification is made inplace. The function simply
-returns the input image again or undef on failure.
-
-Each channel is mapped independently through a lookup table with 256
-entries. The elements in the table should not be less than 0 and not
-greater than 255. If they are out of the 0..255 range they are
-clamped to the range. If a table does not contain 256 entries it is
-silently ignored.
-
-Single channels can mapped by specifying their name and the mapping
-table. The channel names are C<red>, C<green>, C<blue>, C<alpha>.
-
- @map = map { int( $_/2 } 0..255;
- $img->map( red=>\@map );
-
-It is also possible to specify a single map that is applied to all
-channels, alpha channel included. For example this applies a gamma
-correction with a gamma of 1.4 to the input image.
-
- $gamma = 1.4;
- @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
- $img->map(all=> \@map);
-
-The C<all> map is used as a default channel, if no other map is
-specified for a channel then the C<all> map is used instead. If we
-had not wanted to apply gamma to the alpha channel we would have used:
-
- $img->map(all=> \@map, alpha=>[]);
-
-Since C<[]> contains fewer than 256 element the gamma channel is
-unaffected.
-
-It is also possible to simply specify an array of maps that are
-applied to the images in the rgba order. For example to apply
-maps to the C<red> and C<blue> channels one would use:
-
- $img->map(maps=>[\@redmap, [], \@bluemap]);
-
-
-
-=head2 Transformations
-
-Another special image method is transform. It can be used to generate
-warps and rotations and such features. It can be given the operations
-in postfix notation or the module Affix::Infix2Postfix can be used.
-Look in the test case t/t55trans.t for an example.
-
-transform() needs expressions (or opcodes) that determine the source
-pixel for each target pixel. Source expressions are infix expressions
-using any of the +, -, *, / or ** binary operators, the - unary
-operator, ( and ) for grouping and the sin() and cos() functions. The
-target pixel is input as the variables x and y.
-
-You specify the x and y expressions as xexpr and yexpr respectively.
-You can also specify opcodes directly, but that's magic deep enough
-that you can look at the source code.
-
-You can still use the transform() function, but the transform2()
-function is just as fast and is more likely to be enhanced and
-maintained.
-
-Later versions of Imager also support a transform2() class method
-which allows you perform a more general set of operations, rather than
-just specifying a spatial transformation as with the transform()
-method, you can also perform colour transformations, image synthesis
-and image combinations.
-
-transform2() takes an reference to an options hash, and a list of
-images to operate one (this list may be empty):
-
- my %opts;
- my @imgs;
- ...
- my $img = Imager::transform2(\%opts, @imgs)
- or die "transform2 failed: $Imager::ERRSTR";
-
-The options hash may define a transformation function, and optionally:
-
-=over 4
-
-=item *
-
-width - the width of the image in pixels. If this isn't supplied the
-width of the first input image is used. If there are no input images
-an error occurs.
-
-=item *
-
-height - the height of the image in pixels. If this isn't supplied
-the height of the first input image is used. If there are no input
-images an error occurs.
-
-=item *
-
-constants - a reference to hash of constants to define for the
-expression engine. Some extra constants are defined by Imager
-
-=back
-
-The tranformation function is specified using either the expr or
-rpnexpr member of the options.
-
-=over 4
-
-=item Infix expressions
-
-You can supply infix expressions to transform 2 with the expr keyword.
-
-$opts{expr} = 'return getp1(w-x, h-y)'
-
-The 'expression' supplied follows this general grammar:
-
- ( identifier '=' expr ';' )* 'return' expr
-
-This allows you to simplify your expressions using variables.
-
-A more complex example might be:
-
-$opts{expr} = 'pix = getp1(x,y); return if(value(pix)>0.8,pix*0.8,pix)'
-
-Currently to use infix expressions you must have the Parse::RecDescent
-module installed (available from CPAN). There is also what might be a
-significant delay the first time you run the infix expression parser
-due to the compilation of the expression grammar.
-
-=item Postfix expressions
-
-You can supply postfix or reverse-polish notation expressions to
-transform2() through the rpnexpr keyword.
-
-The parser for rpnexpr emulates a stack machine, so operators will
-expect to see their parameters on top of the stack. A stack machine
-isn't actually used during the image transformation itself.
-
-You can store the value at the top of the stack in a variable called
-foo using !foo and retrieve that value again using @foo. The !foo
-notation will pop the value from the stack.
-
-An example equivalent to the infix expression above:
-
- $opts{rpnexpr} = 'x y getp1 !pix @pix value 0.8 gt @pix 0.8 * @pix ifp'
-
-=back
-
-transform2() has a fairly rich range of operators.
-
-=over 4
-
-=item +, *, -, /, %, **
-
-multiplication, addition, subtraction, division, remainder and
-exponentiation. Multiplication, addition and subtraction can be used
-on colour values too - though you need to be careful - adding 2 white
-values together and multiplying by 0.5 will give you grey, not white.
-
-Division by zero (or a small number) just results in a large number.
-Modulo zero (or a small number) results in zero.
-
-=item sin(N), cos(N), atan2(y,x)
-
-Some basic trig functions. They work in radians, so you can't just
-use the hue values.
-
-=item distance(x1, y1, x2, y2)
-
-Find the distance between two points. This is handy (along with
-atan2()) for producing circular effects.
-
-=item sqrt(n)
-
-Find the square root. I haven't had much use for this since adding
-the distance() function.
-
-=item abs(n)
-
-Find the absolute value.
-
-=item getp1(x,y), getp2(x,y), getp3(x, y)
-
-Get the pixel at position (x,y) from the first, second or third image
-respectively. I may add a getpn() function at some point, but this
-prevents static checking of the instructions against the number of
-images actually passed in.
-
-=item value(c), hue(c), sat(c), hsv(h,s,v)
-
-Separates a colour value into it's value (brightness), hue (colour)
-and saturation elements. Use hsv() to put them back together (after
-suitable manipulation).
-
-=item red(c), green(c), blue(c), rgb(r,g,b)
-
-Separates a colour value into it's red, green and blue colours. Use
-rgb(r,g,b) to put it back together.
-
-=item int(n)
-
-Convert a value to an integer. Uses a C int cast, so it may break on
-large values.
-
-=item if(cond,ntrue,nfalse), if(cond,ctrue,cfalse)
-
-A simple (and inefficient) if function.
-
-=item <=,<,==,>=,>,!=
-
-Relational operators (typically used with if()). Since we're working
-with floating point values the equalities are 'near equalities' - an
-epsilon value is used.
-
-=item &&, ||, not(n)
-
-Basic logical operators.
-
-=back
-
-A few examples:
-
-=over 4
-
-=item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat x y getp1 !pix @pix sat 0.7 gt @pat @pix ifp'
-
-tiles a smaller version of the input image over itself where the
-colour has a saturation over 0.7.
-
-=item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat y 360 / !rat x y getp1 1 @rat - pmult @pat @rat pmult padd'
-
-tiles the input image over itself so that at the top of the image the
-full-size image is at full strength and at the bottom the tiling is
-most visible.
-
-=item rpnexpr=>'x y getp1 !pix @pix value 0.96 gt @pix sat 0.1 lt and 128 128 255 rgb @pix ifp'
-
-replace pixels that are white or almost white with a palish blue
-
-=item rpnexpr=>'x 35 % 10 * y 45 % 8 * getp1 !pat x y getp1 !pix @pix sat 0.2 lt @pix value 0.9 gt and @pix @pat @pix value 2 / 0.5 + pmult ifp'
-
-Tiles the input image overitself where the image isn't white or almost
-white.
-
-=item rpnexpr=>'x y 160 180 distance !d y 180 - x 160 - atan2 !a @d 10 / @a + 3.1416 2 * % !a2 @a2 180 * 3.1416 / 1 @a2 sin 1 + 2 / hsv'
-
-Produces a spiral.
-
-=item rpnexpr=>'x y 160 180 distance !d y 180 - x 160 - atan2 !a @d 10 / @a + 3.1416 2 * % !a2 @a 180 * 3.1416 / 1 @a2 sin 1 + 2 / hsv'
-
-A spiral built on top of a colour wheel.
-
-=back
-
-For details on expression parsing see L<Imager::Expr>. For details on
-the virtual machine used to transform the images, see
-L<Imager::regmach.pod>.
-
-=head2 Plugins
-
-It is possible to add filters to the module without recompiling the
-module itself. This is done by using DSOs (Dynamic shared object)
-avaliable on most systems. This way you can maintain our own filters
-and not have to get me to add it, or worse patch every new version of
-the Module. Modules can be loaded AND UNLOADED at runtime. This
-means that you can have a server/daemon thingy that can do something
-like:
-
- load_plugin("dynfilt/dyntest.so") || die "unable to load plugin\n";
- %hsh=(a=>35,b=>200,type=>lin_stretch);
- $img->filter(%hsh);
- unload_plugin("dynfilt/dyntest.so") || die "unable to load plugin\n";
- $img->write(type=>'pnm',file=>'testout/t60.jpg')
- || die "error in write()\n";
-
-Someone decides that the filter is not working as it should -
-dyntest.c modified and recompiled.
-
- load_plugin("dynfilt/dyntest.so") || die "unable to load plugin\n";
- $img->filter(%hsh);
-
-An example plugin comes with the module - Please send feedback to
-addi@umich.edu if you test this.
-
-Note: This seems to test ok on the following systems:
-Linux, Solaris, HPUX, OpenBSD, FreeBSD, TRU64/OSF1, AIX.
-If you test this on other systems please let me know.
-
-=head1 BUGS
-
-box, arc, circle do not support antialiasing yet. arc, is only filled
-as of yet. Some routines do not return $self where they should. This
-affects code like this, C<$img-E<gt>box()-E<gt>arc()> where an object
-is expected.
-
-When saving Gif images the program does NOT try to shave of extra
-colors if it is possible. If you specify 128 colors and there are
-only 2 colors used - it will have a 128 colortable anyway.
-
-=head1 AUTHOR
-
-Arnar M. Hrafnkelsson, addi@umich.edu, and recently lots of assistance
-from Tony Cook. See the README for a complete list.
-
-=head1 SEE ALSO
-
-perl(1), Imager::Color(3), Imager::Font, Affix::Infix2Postfix(3),
-Parse::RecDescent(3) http://www.eecs.umich.edu/~addi/perl/Imager/
-
-=cut
projects / imager.git / blobdiff