-=item noise
-
-adds noise of the given I<amount> to the image. If I<subtype> is
-zero, the noise is even to each channel, otherwise noise is added to
-each channel independently.
-
-=item radnoise
-
-renders radiant Perlin turbulent noise. The centre of the noise is at
-(I<xo>, I<yo>), I<ascale> controls the angular scale of the noise ,
-and I<rscale> the radial scale, higher numbers give more detail.
-
-=item postlevels
-
-alters the image to have only I<levels> distinct level in each
-channel.
-
-=item turbnoise
-
-renders Perlin turbulent noise. (I<xo>, I<yo>) controls the origin of
-the noise, and I<scale> the scale of the noise, with lower numbers
-giving more detail.
-
-=item watermark
-
-applies I<wmark> as a watermark on the image with strength I<pixdiff>,
-with an origin at (I<tx>, I<ty>)
-
-=back
-
-A demonstration of most of the filters can be found at:
-
- http://www.develop-help.com/imager/filters.html
-
-(This is a slow link.)
-
-=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 Matrix Transformations
-
-Rather than having to write code in a little language, you can use a
-matrix to perform transformations, using the matrix_transform()
-method:
-
- my $im2 = $im->matrix_transform(matrix=>[ -1, 0, $im->getwidth-1,
- 0, 1, 0,
- 0, 0, 1 ]);
-
-By default the output image will be the same size as the input image,
-but you can supply the xsize and ysize parameters to change the size.
-
-Rather than building matrices by hand you can use the Imager::Matrix2d
-module to build the matrices. This class has methods to allow you to
-scale, shear, rotate, translate and reflect, and you can combine these
-with an overloaded multiplication operator.
-
-WARNING: the matrix you provide in the matrix operator transforms the
-co-ordinates within the B<destination> image to the co-ordinates
-within the I<source> image. This can be confusing.
-
-Since Imager has 3 different fairly general ways of transforming an
-image spatially, this method also has a yatf() alias. Yet Another
-Transformation Function.
-
-=head2 Masked Images
-
-Masked images let you control which pixels are modified in an
-underlying image. Where the first channel is completely black in the
-mask image, writes to the underlying image are ignored.
-
-For example, given a base image called $img:
-
- my $mask = Imager->new(xsize=>$img->getwidth, ysize=>getheight,
- channels=>1);
- # ... draw something on the mask
- my $maskedimg = $img->masked(mask=>$mask);
-
-You can specifiy the region of the underlying image that is masked
-using the left, top, right and bottom options.
-
-If you just want a subset of the image, without masking, just specify
-the region without specifying a mask.
-
-=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.
-
-=head2 Tags
-
-Image tags contain meta-data about the image, ie. information not
-stored as pixels of the image.
-
-At the perl level each tag has a name or code and a value, which is an
-integer or an arbitrary string. An image can contain more than one
-tag with the same name or code.
-
-You can retrieve tags from an image using the tags() method, you can
-get all of the tags in an image, as a list of array references, with
-the code or name of the tag followed by the value of the tag:
-
- my @alltags = $img->tags;
-
-or you can get all tags that have a given name:
-
- my @namedtags = $img->tags(name=>$name);
-
-or a given code:
-
- my @tags = $img->tags(code=>$code);
-
-You can add tags using the addtag() method, either by name:
-
- my $index = $img->addtag(name=>$name, value=>$value);
-
-or by code:
-
- my $index = $img->addtag(code=>$code, value=>$value);
-
-You can remove tags with the deltag() method, either by index:
-
- $img->deltag(index=>$index);
-
-or by name:
-
- $img->deltag(name=>$name);
-
-or by code:
-
- $img->deltag(code=>$code);
-
-In each case deltag() returns the number of tags deleted.
-
-When you read a GIF image using read_multi(), each image can include
-the following tags:
-
-=over
-
-=item gif_left
-
-the offset of the image from the left of the "screen" ("Image Left
-Position")
-
-=item gif_top
-
-the offset of the image from the top of the "screen" ("Image Top Position")
-
-=item gif_interlace
-
-non-zero if the image was interlaced ("Interlace Flag")
-
-=item gif_screen_width
-
-=item gif_screen_height
-
-the size of the logical screen ("Logical Screen Width",
-"Logical Screen Height")
-
-=item gif_local_map
-
-Non-zero if this image had a local color map.
-
-=item gif_background
-
-The index in the global colormap of the logical screen's background
-color. This is only set if the current image uses the global
-colormap.
-
-=item gif_trans_index
-
-The index of the color in the colormap used for transparency. If the
-image has a transparency then it is returned as a 4 channel image with
-the alpha set to zero in this palette entry. ("Transparent Color Index")
-
-=item gif_delay
-
-The delay until the next frame is displayed, in 1/100 of a second.
-("Delay Time").
-
-=item gif_user_input
-
-whether or not a user input is expected before continuing (view dependent)
-("User Input Flag").
-
-=item gif_disposal
-
-how the next frame is displayed ("Disposal Method")
-
-=item gif_loop
-
-the number of loops from the Netscape Loop extension. This may be zero.
-
-=item gif_comment
-
-the first block of the first gif comment before each image.
-
-=back
-
-Where applicable, the ("name") is the name of that field from the GIF89
-standard.
-
-The following tags are set in a TIFF image when read, and can be set
-to control output:
-
-=over
-
-=item tiff_resolutionunit
-
-The value of the ResolutionUnit tag. This is ignored on writing if
-the i_aspect_only tag is non-zero.
-
-=back
-
-The following tags are set when reading a Windows BMP file is read:
-
-=over
-
-=item bmp_compression
-
-The type of compression, if any.
-
-=item bmp_important_colors
-
-The number of important colors as defined by the writer of the image.
-
-=back
-
-Some standard tags will be implemented as time goes by:
-
-=over
-
-=item i_xres
-
-=item i_yres
-
-The spatial resolution of the image in pixels per inch. If the image
-format uses a different scale, eg. pixels per meter, then this value
-is converted. A floating point number stored as a string.
-
-=item i_aspect_only
-
-If this is non-zero then the values in i_xres and i_yres are treated
-as a ratio only. If the image format does not support aspect ratios
-then this is scaled so the smaller value is 72dpi.
-
-=back
-
-=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
projects / imager.git / blobdiff