NAME

Imager - Perl extension for Generating 24 bit Images

SYNOPSIS

  use Imager;

  init();
  $img = Imager->new();
  $img->open(file=>'image.ppm',type=>'ppm') || print "failed: ",$img->{ERRSTR},"\n";
  $scaled=$img->scale(xpixels=>400,ypixels=>400);
  $scaled->write(file=>'sc_image.ppm',type=>'ppm') || print "failed: ",$scaled->{ERRSTR},"\n";

DESCRIPTION

    Imager is a module for creating and altering images - It 
    is not meant as a replacement or a competitor to ImageMagick or
    GD. Both are excellent packages and well supported.
    
    Why a new module? Compiling PerlMagick has been more than trivial
    for me, and it lacks drawing functions. GD.pm has those but only
    does gif.  I like studying graphics, so why not let others in
    a similar situation benefit?  The basis for this module is code
    written to preprocess remote sensing data. 

OO interface

    An Image object is created with $img = Imager->new(). Should this fail
    for some reason an explanation can be found in $Imager::ERRSTR. 
    usually error messages are stored in $img->{ERRSTR}, but since no
    object is created this is the only way to give back errors.  $Imager::ERRSTR
    is also used to report all errors not directly associated with an image object.
    
    An image object is a wrapper around the raw handle to an image.  It is stored in the IMG
    value of the object hash.  When Imager->new() is called the IMG member is set to undef.

    $img->open() has two parameters, 'file' and 'type', for type 'raw' two extra parameters
    are necessary 'xsize' and 'ysize', if the 'channel' parameter is omitted for 'raw' it is
    assumed to be 3.  Gif and png images that have a palette are converted to 24 bit when read.
    Grayscale jpegs are still 1 channel images in memory though.  For jpeg images the iptc header
    information (stored in the APP13 header) is avaliable to some degree. You can get the raw
    header with $img->{IPTCRAW}, but you can also retreive the most basic information with
    %hsh=$img->parseiptc() as always: patches welcome.
    
    $img->write has the same interface as open(), for jpeg quality can be adjusted via the
    'jpegquality' parameter (0-100).  The number of colorplanes in gifs are set with 'gifplanes' and
    should be between 1 (2 color) and 8 (256 colors).

    $img->getwidth() and $img->getheight() are used to get the dimensions of the image.
    $img->getmask() and $img->setmask() are used to get/set the channel mask of the image.
    

    To scale an image so porportions are maintained use the $img->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: 
    $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 qtype=>'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.

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=>'ppm',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 if you test this.

Functional interface

    Use only if you cannot do what you need to do with
    the OO interface. This is mostly intended for 
    people who want to develop the OO interface or
    the XS part of the module.
    
   $bool   = i_has_format($str);
             
   $colref = i_color_set($colref,$r,$g,$b,$a);

   $imref  = i_img_empty($imref,$x,$y);
   $imref  = i_img_empty_ch($imref,$x,$y,$channels);

   @iminfo = i_img_info($imref);

             i_img_setmask($imref,$channel_mask);
$chan_mask = i_img_getmask($imref);

             i_draw($imref,$x1,$y1,$x2,$y2,$colref);
             i_box($imref,$x1,$y1,$x2,$y2,$colref);
             i_box_filled($imref,$x1,$y1,$x2,$y2,$colref);
             i_arc($imref,$x,$y,$rad,$deg1,$deg2,$colref);

             i_copyto($imref,$srcref,$x1,$y1,$x2,$y2,$tx,$ty,$trans_cl_ref);
             i_rubthru($imref,$srcref,$tx,$ty);
   $imref  = i_scaleaxis($imref,$scale_factor,$axis);
 
             i_gaussian($imref,$stdev);
             i_conv($imref,$arrayref,$array_len);

             i_img_diff($imref1,$imref2);


             i_init_fonts();

             i_t1_set_aa($level);
             i_t1_cp($imref,$xb,$yb,$channel,$fontnum,$pts,$str,$strlen,$align);
             i_t1_text($imref,$xb,$yb,$colorref,$fontnum,$pts,$str,$strlen,$align);
    @bbox  = i_t1_bbox($fontnum,$pts,$str,$strlen);

    $imref = i_readjpeg($imref,$fd);
             i_writejpeg($imref,$fd,$qfactor);

    $imref = i_readpng($imref,$fd);
             i_writepng($imref,$fd);

    $imref = i_readgif($imref,$fd);
             i_writegif($imref,$fd,$planes);

    $imref = i_readppm($imref,$fd);
             i_writeppm($imref,$fd);

             i_readraw($imref,$fd,$xsize,$ysize,$datachannels,$storechannels,$interleave);
             i_writeraw($imref,$fd);



   

AUTHOR

Arnar M. Hrafnkelsson, amh@mbl.is

SEE ALSO

perl(1). http://gauss.mbl.is/~amh/Imager/