```{index} single: Imager ``` # Imager ```{pperl-module-badges} Imager ``` Perl bindings for Imager, the raster graphics library. This is the `Imager` module, version 1.037 of the CPAN API: the same packages, methods, arguments and return values that Perl code written against `Imager` already expects - for the part of it that is available so far (see below). ```perl use Imager; my $img = Imager->new(xsize => 4, ysize => 3, channels => 4) or die Imager->errstr; $img->setpixel(x => 1, y => 1, color => Imager::Color->new(255, 0, 0)); my $c = $img->getpixel(x => 1, y => 1); printf "%dx%d, %d channels, pixel %s\n", $img->getwidth, $img->getheight, $img->getchannels, join(",", $c->rgba); # 4x3, 4 channels, pixel 255,0,0,255 my @s = $img->getsamples(y => 1, x => 1, width => 1); # 255 0 0 255 my $copy = $img->copy; $img->settag(name => 'note', value => 'hello'); ``` ## What is available The image engine and the operations on it that are native so far: creating images of every kind below, `getpixel`/`setpixel`, `getsamples`/`setsamples`, `getscanline`/`setscanline`, `copy`, palettes (`addcolors`, `getcolors`, `colorcount` and the rest), tags, the channel mask, masked images, the colour classes, drawing (`box`, `line`, `arc`, `circle`, `polygon`, `polypolygon`, `flood_fill`, `polybezier`), fills, `paste`, `crop`, `rubthrough` and `compose`, `flip`, `convert`, `map` and `Imager->combine`, `to_paletted`, `Imager->make_palette`, `getcolorcount` and `getcolorusage`, `scale`, `scaleX` and `scaleY`, `rotate` and `matrix_transform`, `trim` and `trim_rect`, `transform` and `Imager::transform2`, the filters, `difference` and `rgb_difference`, the files below, and text through `Imager::Font::FT2`. Not available: `Imager->load_plugin`, the loader for filter plugins compiled from C. It returns undef and sets `$Imager::ERRSTR` to "Couldn't load plugin '...'", as it does for a file that cannot be loaded. Imager's documentation has called that interface deprecated since 0.48 (2006). ## Drawing `box`, `line`, `arc`, `circle` and `polygon` draw in a colour or, where they fill an area, through a fill (below). `aa => 1` anti-aliases lines, arcs, circles and outlines; `filled => 0` gives the outline of a circle or an arc. A polygon is always anti-aliased, and `mode => 'nonzero'` fills it by the non-zero winding rule instead of the even-odd one; `polypolygon` takes several at once, so one can be a hole in another. `flood_fill` fills the region of one colour around a point, or with `border` everything up to that colour, and `polybezier` draws a Bezier curve through control points. ```perl $img->circle(x => 50, y => 50, r => 30, color => 'red', aa => 1); $img->arc(x => 50, y => 50, r => 40, d1 => 0, d2 => 90, filled => 0, aa => 1); $img->polygon(points => [ [ 10, 10 ], [ 90, 30 ], [ 40, 80 ] ], color => 'green'); $img->flood_fill(x => 2, y => 2, color => 'blue') or die $img->errstr; ``` ## Where Imager differs from the other raster modules Imager is not a wrapper around one C library; its image engine is its own. That engine is what this module provides natively, and it is why Imager can do things the others cannot: an image may hold **8-bit, 16-bit or floating-point samples**, may be **paletted or direct**, and may have **one to four channels**, in any combination. A greyscale 16-bit image and an RGBA 8-bit image are both ordinary Imager images. Every operation works on all of them, so code written for one kind of image works on another without change. ## Four kinds of image An image is described by three independent properties, and Imager supports the whole product of them: | Property | Values | |---|---| | sample size | 8-bit, 16-bit, double | | storage | direct, or paletted (up to 256 colours) | | channels | 1 (grey), 2 (grey+alpha), 3 (RGB), 4 (RGBA) | ```perl my $rgb = Imager->new(xsize => 10, ysize => 10); # 8-bit RGB my $deep = Imager->new(xsize => 10, ysize => 10, bits => 16); my $float = Imager->new(xsize => 10, ysize => 10, bits => 'double'); my $pal = Imager->new(xsize => 10, ysize => 10, type => 'paletted'); my $grey = Imager->new(xsize => 10, ysize => 10, channels => 1); ``` Reading and writing a pixel works the same on all of them. `getpixel`/`setpixel` speak `Imager::Color` (bytes) or `Imager::Color::Float` (doubles); a 16-bit or floating-point image keeps its extra precision only if you use the float form. ## Colours A colour is four channels. `Imager::Color` holds them as bytes, 0 to 255, which is what most code wants; `Imager::Color::Float` holds them as floating-point numbers, nominally 0 to 1, which is what a 16-bit or floating-point image needs to keep its precision. `Imager::Color->new` accepts the friendly spellings - a name, an HTML hex string, a channel list: ```perl my $red = Imager::Color->new('red'); my $red2 = Imager::Color->new('#FF0000'); my $red3 = Imager::Color->new(255, 0, 0); my $trans = Imager::Color->new(255, 0, 0, 128); my ($r, $g, $b, $a) = $red->rgba; ``` Anywhere a method takes `color =>`, an array reference works too and is the least ceremony for a one-off: `$img->setpixel(x => 0, y => 0, color => [0, 128, 255])`. ## The channel mask `$img->setmask(mask => 0x5)` makes subsequent writes touch only the channels whose bit is set - channel 0 and channel 2 here. Reads ignore it. It is how you draw into one channel of an image without disturbing the others. ## Errors Imager reports failure by returning false and leaving the reason in an error stack. `Imager->errstr` on the class gives the last error; `$img->errstr` gives that image's. Nothing croaks for an ordinary failure, so the idiom is to check and report: ```perl my $img = Imager->new(xsize => 10, ysize => 10) or die Imager->errstr; ``` ## Files PNM files (PBM, PGM and PPM, ASCII and binary, 8 and 16 bit), Windows BMP files, Targa files and raw files (`type => 'raw'`, samples and nothing else) are read and written - the formats Imager has without any library. GIF, JPEG, PNG and TIFF are not available yet. BMP is read at 1, 4, 8, 16, 24 and 32 bits a pixel, run length encoded and with bit-field masks, and written uncompressed: 24 bits for a direct image, 1, 4 or 8 for a paletted one. ```perl my $img = Imager->new(file => 'in.ppm') or die Imager->errstr; $img->write(file => 'out.pgm', type => 'pnm') or die $img->errstr; my @all = Imager->read_multi(file => 'frames.ppm'); ``` Targa is read and written colour-mapped, direct and grey, run length encoded (`compress => 1`, the default) or not, with `wierdpack => 1` for 15 and 16 bits a pixel and `idstring` for the file's id. ## Masked images `$img->masked` gives a view of a rectangle of an image, optionally written through a mask: a pixel of the view is a pixel of the image, reads see all of it, and a write lands only where the mask's first channel is not zero. The view can be drawn into, copied and written to a file like any image. ```perl my $mask = Imager->new(xsize => 100, ysize => 100, channels => 1); $mask->box(filled => 1, color => 'white', xmin => 20, xmax => 79); my $view = $img->masked(mask => $mask, left => 10, top => 10, right => 110, bottom => 110); $view->box(filled => 1, color => 'red'); # a red band in $img ``` ## Fills `box` and `arc` take a `fill` instead of a colour: a hash of `Imager::Fill->new` parameters or such an object. A fill is a solid colour, one of the 32 named hatches or a custom 8x8 one (`hatch`, `fg`, `bg`, `dx`, `dy`), a tiled image (`image`, with `xoff`, `yoff` and a `matrix`), or another fill made more transparent (`type => 'opacity'`). `combine` says how it meets what is already there: `none`, `normal`, `multiply`, `dissolve`, `add`, `subtract`, `diff`, `lighten`, `darken`, `hue`, `saturation`, `value` or `color`. A fountain fill (`fountain => 'linear'`, `radial`, `conical` and the rest, with `segments` of colours as `Imager::Fountain` builds them) is a gradient between the points `xa`, `ya` and `xb`, `yb`; the `fountain` filter draws the same over a whole image. ```perl $img->box(xmin => 10, ymin => 10, xmax => 90, ymax => 50, fill => { hatch => 'check2x2', fg => 'red', bg => 'white' }); my $glass = Imager::Fill->new(solid => Imager::Color->new(0, 0, 255, 96), combine => 'normal'); $img->arc(x => 50, y => 50, r => 30, fill => $glass); ``` ## One image onto another `paste` copies a rectangle as it is. `rubthrough` lays the source over the target by the source's alpha channel. `compose` does the same with a combine mode (the names above) and an `opacity`, and with `mask` takes the coverage of each pixel from the first channel of a third image. ```perl $img->rubthrough(src => $logo, tx => 10, ty => 10) or die $img->errstr; $img->compose(src => $logo, tx => 10, ty => 10, combine => 'multiply', opacity => 0.5, mask => $mask) or die $img->errstr; ``` `setsamples` writes samples of chosen channels, as 8-bit values, floating point (`type => 'float'`) or 16-bit (`type => '16bit'`, on a 16-bit image), and `getsamples` reads them in the same three forms. An alpha channel is written over the colour of the `i_background` tag, black without one; `pnm_write_wide_data => 1` writes a 16-bit image with 16-bit samples. `Imager->set_file_limits` bounds the width, height and bytes of what `read` accepts, and `Imager->add_file_magic` teaches the format detection a new signature. ## Channels `convert` makes a new image whose channels are weighted sums of this one's, by a `matrix` or a `preset` (`grey`, `noalpha`, `rgb`, `addalpha`, `red`, `green`, `blue`, `alpha`); `Imager->combine` makes one from a channel each of several images; `map` runs the samples of chosen channels through lookup tables in place, and `flip` mirrors the image in place. ```perl my $grey = $img->convert(preset => 'grey') or die $img->errstr; my $bgr = $img->convert(matrix => [ [ 0, 0, 1 ], [ 0, 1, 0 ], [ 1, 0, 0 ] ]); my $again = Imager->combine(src => [ $r, $g, $b ]) or die Imager->errstr; $img->map(red => [ reverse 0 .. 255 ]); $img->flip(dir => 'h'); ``` ## Scaling `scale` returns a scaled copy: by `scalefactor`, or to `xpixels` and `ypixels`, where `type` says how the two combine (`max`, `min`, `nonprop`). `qtype` picks the method: `normal` (a Lanczos filter), `preview` (nearest neighbour) or `mixing` (the mean of the area each pixel covers). `normal` and `preview` give an 8-bit image whatever the source holds, as in Imager; `mixing` keeps the depth. ```perl my $thumb = $img->scale(xpixels => 160, ypixels => 120, type => 'min', qtype => 'mixing') or die $img->errstr; ``` ## Rotation and matrix transforms `rotate(right => 90)` (or 180, 270) turns the image exactly; `rotate(degrees => ...)` or `radians` rotates by any angle into an image large enough to hold the result, with `back` for the corners. `matrix_transform` maps the image through a 3 x 3 matrix, such as `Imager::Matrix2d` builds, with bilinear interpolation. A paletted image is not interpolated. ```perl my $turned = $img->rotate(degrees => 30, back => 'white') or die $img->errstr; ``` ## Expressions per pixel `Imager::transform2` builds an image from an expression evaluated for every pixel, in postfix (`rpnexpr`) or, with Parse::RecDescent installed, infix (`expr`): arithmetic, comparisons, `getp1` to `getp3` for the pixels of up to three input images, `rgb`, `hsv` and their parts. `$img->transform` is the older form: two small stack programs give the source position of each pixel. ```perl my $mirrored = Imager::transform2({ rpnexpr => 'w x - 1 - y getp1' }, $img) or die Imager->errstr; ``` ## Filters `$img->filter(type => ...)` changes the image in place, with every filter Imager has built in: `autolevels` and `autolevels_skew`, `bumpmap` and `bumpmap_complex`, `contrast`, `conv`, `fountain`, `gaussian` and `gaussian2`, `gradgen`, `hardinvert` and `hardinvertall`, `mosaic`, `nearest_color`, `noise`, `postlevels`, `radnoise`, `turbnoise`, `unsharpmask` and `watermark`. Many work through 8-bit samples, as in Imager, so a 16-bit or double image keeps 8 bits of precision afterwards. `$img->difference` and `rgb_difference` make a new image of where two images differ. ```perl $img->filter(type => 'autolevels') or die $img->errstr; $img->filter(type => 'mosaic', size => 8); ``` ## Paletted images from direct ones `to_paletted` quantises an image. `make_colors` says where the palette comes from: `mediancut` (the default), `addi`, a fixed map (`webmap`, `mono`, `gray`, `gray4`, `gray16`) or `none` for the `colors` you give; `max_colors` bounds it. `translate` says how the pixels are matched to it: `closest`, `perturb`, or `errdiff` with an `errdiff` of `floyd`, `jarvis`, `stucki` or a custom map. `Imager->make_palette` makes one palette for several images, and `getcolorcount` and `getcolorusage` count the colours of an image. ```perl my $pal = $img->to_paletted(make_colors => 'mediancut', max_colors => 16, translate => 'errdiff') or die $img->errstr; my $n = $img->getcolorcount(maxcolors => 256); # undef if more ``` The `addi` palette and the `perturb` translation use the C library's random numbers, which Imager never seeds: the same image gives the same result every run. ## Differences from upstream Beyond `load_plugin` (above), eighteen: - Where perl 5.44 with XS Imager reads freed memory: an `Imager::ImgRaw` or `Imager::IO` used after its `DESTROY` croaks "not a live Imager::ImgRaw" (or "Imager::IO") (t/64-auto-ffi/414-imager-or-better.t). - `Imager::io_slurp` of an I/O object that is not a buffer chain croaks "io_slurp: called on a source that is not from a bufchain". Imager 1.037 ends the whole program there, silently and with exit status 0. - Reading a row of a paletted image as floating point colours (`getscanline(type => 'float')`) returns its colours and leaves the image alone. Imager 1.037 writes where it should read there (image.c `i_glinf_fp` calls `i_plin` on an uninitialised buffer): the row comes back as whatever was in memory, and the image is overwritten with it and turned into a direct colour image. - A grey image with an alpha channel written as BMP has its grey applied over the background by its own alpha. Imager 1.037 reads the wrong samples there (paste.im `i_gsamp_bg` asks for 2 a pixel and reads 4): every pixel takes its neighbour's grey as alpha and half the row is whatever was in memory. - A masked image keeps its target and its mask alive, an image fill its image and an opacity fill its base fill. In Imager 1.037 that is done by `$img->masked` and `Imager::Fill->new`, which store them in the result; the objects themselves hold bare pointers, so one made with `Imager::i_img_masked_new` or `Imager::i_new_fill_image` directly reads freed memory once the other is gone. - `paste` with a source rectangle that starts left of or above the source image writes black for the part outside it. Imager 1.037 writes whatever was in the memory it had just allocated. - The `hue` combine mode leaves a grey pixel of an image without an alpha channel as it is. Imager 1.037 changes it to a colour that differs from run to run (it reads an alpha the image does not have). - A custom hatch given as a string shorter than 8 bytes has empty rows for the missing bytes; Imager 1.037 takes them from whatever follows the string in memory. - An image fill with a `matrix` drawn into a 16-bit or double image from a source without an alpha channel draws the source. In Imager 1.037 that fill comes out black. - A polygon with a coordinate beyond 134 million pixels keeps its shape. Imager 1.037 converts such a coordinate to an `int` it does not fit in; on x86-64 the vertex lands far to the left of the image instead of far to the right. - `compose` with a rectangle the target clips and a negative source or mask offset larger than what is left draws nothing and succeeds. Imager 1.037 prints "Out of memory" and aborts the program there. - The fountain filter called as `Imager::i_fountain` with a super-sampling number it does not know draws without super-sampling, with a negative sample count draws nothing, and with segments that are not an array croaks. Imager 1.037 crashes in all three. A fountain fill none of whose samples has a colour draws transparent black where Imager draws what was in memory. - `getsamples(type => '16bit')` of a negative sample in a double image gives 0. Imager 1.037 converts the negative number to an unsigned one, which on x86-64 gives a value near 4294967295. - `to_paletted` with `make_colors => 'addi'` makes opaque colours. Imager 1.037 sets only their red, green and blue, so the palette of a four channel image has an alpha that is whatever was in memory. - `transform` and `transform2` start from black and from empty registers, end a program that reaches outside its registers or its code, clamp `rgb()` of a number beyond the int range, and refuse a missing input image or a channel count outside 1 to 4. Imager 1.037 computes from memory it never set in the first cases and crashes in the last two. - The `postlevels` filter with `levels => 0`, `autolevels_skew` on a channel whose range comes out empty, and `mosaic` with a `size` of 0 or less leave the image as it is. Imager 1.037 dies of a division by zero in the first two and never returns from the third. A negative bump map channel is refused; Imager reads outside the colour. - `Imager::i_gradgen` with a distance measure other than 0, 1 or 2 croaks. Imager 1.037 ends the program with exit status 3. - `Imager->set_out_of_memory_handler($code)` stores and returns the handler, but it is never called. An image whose pixel storage cannot be allocated fails with "Out of memory allocating image surface", as upstream; running out of memory for anything smaller ends the process, as upstream does when no handler is set. ## Modules - [`Imager::Color`](Imager/Color.md) - Color handling for Imager. - [`Imager::Expr`](Imager/Expr.md) - implements expression parsing and compilation for the expression evaluation engine used by Imager::transform2() - [`Imager::ExtUtils`](Imager/ExtUtils.md) - functions handy in writing Imager extensions - [`Imager::Fill`](Imager/Fill.md) - Imager::Fill - general fill types - [`Imager::Font`](Imager/Font.md) - Font handling for Imager. - [`Imager::Fountain`](Imager/Fountain.md) - Imager::Fountain - a class for building fountain fills suitable for use by the fountain filter. - [`Imager::Matrix2d`](Imager/Matrix2d.md) - Imager::Matrix2d - simple wrapper for matrix construction - [`Imager::Regops`](Imager/Regops.md) - generated information about the register based virtual machine - [`Imager::Test`](Imager/Test.md) - common functions used in testing Imager - [`Imager::Transform`](Imager/Transform.md) - Imager::Transform - a library of register machine image transformations - [`Imager::TrimColorList`](Imager/TrimColorList.md) - represent a list of color ranges for Imager's trim() method. ## Functions ### Library information #### `i_list_formats` The image file formats this build can read and write, as a list of short names such as `"png"` and `"jpeg"`. ### Errors #### `i_clear_error` Discard any pending error. #### `i_push_error` Add a message to the error stack. #### `i_errors` The pending errors, newest first, each as an array reference `[$message, $code]`. `Imager->errstr` is built from this. ```{toctree} :hidden: :maxdepth: 1 Imager/Color Imager/Expr Imager/ExtUtils Imager/Fill Imager/Font Imager/Fountain Imager/Matrix2d Imager/Regops Imager/Test Imager/Transform Imager/TrimColorList ```