GFL::Image - An OO interface to P-e Gougelet's Graphic File Library

- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS

- GFL::Image->new
- $o->set(attrib => value, ...)
- $o->get( attrib, ... )
- $o->load( filename [, ImageIndex])
- $o->loadpreview( filename, width, height [, ImageIndex])
- $o->save( filename )
- $o->resize( Width, Height [, 'quick'])
- $o->flip( 'vertical' or 'horizontal' )
- $o->negate
- $o->crop(x, y, width, height)
- $o->`contrast(-100...100)`
- $o->gamma(0.01 <-> 5.0)
- $o->rotate( Angle )
- $o->soften( percent )
- $o->blur( percent )
- $o->sharpen( percent )
- $o->filter(filter_type => filter_size, ...)
- $o->ChangeDepth( new_depth )
- $o->LastError

- FUNCTIONS

- GFL::Image->`GetFileInformations(filename[,format])` or `getfileinformations(filename[,format])`
- GFL::Image->enableLZW
- GFL::Image->DumpAllFormats or `dumpallformats()`

- ERROR HANDLING
- COPYRIGHT
- SEE ALSO

# NAME

GFL::Image - An OO interface to P-e Gougelet's Graphic File Library

# SYNOPSIS

      use GFL::Image;

      my $im = GFL::Image-> new;

      $im -> load("test.png");
      $im -> set( output => "jpeg",
                  undolevel    => 5
                );
      $im -> resize (320, 200);
      $im -> filter( maximum => 3,
                     mediancross => 7
                     );
      $im -> undo;
      $im -> save("test.jpg");

      undef ($im);

# DESCRIPTION

This module provides an Object Oriented interface to Pierre-E. Gougelet's Graphic File Library.

GFL provides a comprehensive set of image processing tools and can access more than 300 image formats.

GFL is free for non-commercial use, you can grab the latest version at http://www.xnview.org. People wanting to use it in a commercial application must ask authorization to the author.

# METHODS

- Nearly all methods croak their usage when called with improper or missing arguments.

- All methods and attributes are case insensitive. You may say either

              $a -> set( 'output' => 'bmp')

  or

              $a -> Set( Output => 'bmp')

  or even

              $a -> SeT(OUtPuT => 'bmp')

  If the idea of loosing 3 seconds per 100000 method calls makes you sick, use all lowercase for method names to avoid Autoloading overhead. (timed on a Duron 850Mhz)

## GFL::Image->new

Create a new object. Assigning attributes via `new` is deprecated.

## $o->set(attrib => value, ...)

Set single or multiple attributes. Valid attributes are :

UndoLevel
  Define the number of possible undos.

  If `undolevel` changes and happens to be lower than the current number of undos, older undos are cleared accordingly (in FIFO order).

Verbose
  Set the verbosity level on STDERR:

              False - no STDERR report
              1 - report normal operations + errors (anonymously)
              2 - normal operations + errors, with object identifier
              3 - the above plus various internal/cleaning operations

-- ATTRIBUTES CHANGING IMAGE EXPORTATION BEHAVIOR : --
Output
  The format you want the image to be saved as. Writable formats are:

              'alias'  : Alias Image File
              'arcib'  : ArcInfo Binary
              'bmp'    : Windows Bitmap
              'cin'    : Kodak Cineon
              'degas'  : Degas & Degas Elite
              'dkb'    : DKB Ray-Tracer
              'gif'    : CompuServe GIF
              'gpat'   : Gimp Pattern
              'grob'   : HP-48/49 GROB
              'hru'    : HRU
              'ico'    : Windows Icon
              'iff'    : Amiga IFF
              'jif'    : Jeff's Image Format
              'jpeg'   : JPEG / JFIF
              'miff'   : Image Magick file
              'mtv'    : MTV Ray-Tracer
              'palm'   : Palm Pilot
              'pbm'    : Portable Bitmap
              'pcl'    : Page Control Language
              'pcx'    : Zsoft Publisher's Paintbrush
              'pgm'    : Portable Greyscale
              'png'    : Portable Network Graphics
              'pnm'    : Portable Image
              'ppm'    : Portable Pixmap
              'psion3' : Psion Serie 3 Bitmap
              'psion5' : Psion Serie 5 Bitmap
              'qrt'    : Qrt Ray-Tracer
              'rad'    : Radiance
              'raw'    : Raw
              'ray'    : Rayshade
              'rla'    : Wavefront Raster file
              'sgi'    : Silicon Graphics RGB
              'soft'   : Softimage
              'tga'    : Truevision Targa
              'ti'     : TI Bitmap
              'tiff'   : TIFF Revision 6
              'uyvy'   : YUV 16Bits
              'uyvyi'  : YUV 16Bits Interleaved
              'vista'  : Vista
              'vivid'  : Vivid Ray-Tracer
              'wbmp'   : Wireless Bitmap (level 0)
              'wrl'    : VRML2
              'xbm'    : X11 Bitmap
              'xpm'    : X11 Pixmap

Dither
  Boolean.

BinaryDither
  Preferred dithering method for black & white pictures.

  One of: floyd, pattern, halftone45, halftone90

  Defaults to `floyd`.

Quality
  Defines picture quality (vs. size) for `jpeg`, `wic` , `fpx` formats.

  0 < `value` > 100 (best quality)

CompressionLevel
  Defines compression level for `png` format.

  0 < `value` > 6 (best compression)

Interlaced
  Boolean. For `gif` format.

Progressive
  Boolean. For `jpeg` format.

ReplaceExtension
  Boolean. If set to `True`, a correct extension is added to the `filename` when saving, or it's extension is replaced if incorrect.

ChannelOrder
  Defines how to store channels in file.

  One of: interleaved, sequential, separate Defaults to: `interleaved`

Compression
  Defines a desired compression method.

  One of:

  none, rle, lzw, jpeg, zip, sgi_rle, ccitt_rle, ccitt_fax3, ccitt_fax3_2d, ccitt_fax4, wavelet or lzw_predictor

  # FIXME : This option does not seem to have any effect ... I'll ask more informations to the GFL library's author.

-- ATTRIBUTES CHANGING IMAGE IMPORTATION BEHAVIOR : --
Input
  The input format. Defaults to 'auto', where GFL tries to guess the format.

  Input formats are too numerous to be listed here. Just say `dumpallformats()` for a comprehensive list.

LinePadding
  An integer.

  1 (default), 2, 4, ...

## $o->get( attrib, ... )

Get single or multiple attributes.

Valid (case insensitive) attributes are all Set-able attributes plus :

FileInformations
  Brings you a hash reference containing various informations about the current loaded file (as it is on the disk, not as it is in memory ! - this does not reflect any manipulations you have applied)

  e.g:

       $infos = $a->get(FileInformations) || die $a->lasterror;
       foreach (keys %$infos)
       {
       print "$_ => $infos->{$_}\n" if $infos->{$_};
       }

  sample output:

              Origin => 16
              Description => Sgi RGB
              Width => 182
              CompressionDescription => Sgi Rle
              BitsPerPlane => 8
              FileSize => 98145
              NumberOfPlanes => 3
              FormatName => sgi
              NumberOfImages => 1
              FormatIndex => 4
              Height => 170
              BytesPerPlane => 182
              Compression => 5

  - remember this is an hash reference, so you must access every member like this:

    $infos->{'Width'}

  - FileInformations attribute change only when you open a new file.

  - To retrieve informations about a file before loading it, see function `GetFileInformations()`

  - For informations about the current state of the image in memory, see `BitmapInformations` attribute.

BitmapInformations
  Brings you a hash reference containing various informations about the current working Bitmap.

  Sample Hash:

              Xdpi => 68
              BytesPerLine => 546
              Width => 182
              BitsPerComponent => 8
              Ydpi => 68
              Data => GFL_UINT8Ptr=SCALAR(0x81834ec)
              Height => 170
              BytesPerPixel => 3
              TransparentIndex => -1
              Type => 16

  remember this is an hash reference, so you must access every member like this:

  $infos->{'Width'}

NumberOfColours / NumberOfColors
  Return the number of unique colors in the working bitmap.

Width
  Width in pixels of the current working bitmap

Height
  Height in pixels of the current working bitmap

## $o->load( filename [, ImageIndex])

Open the given file.

- - If `input` attribute is set to 'auto' (the default), GFL will attempt to guess the format.

- - `ImageIndex` indicates which image should be loaded in the case of a multi-image or animated file. It is zero-based.

## $o->loadpreview( filename, width, height [, ImageIndex])

Open a custom size preview for the given file.

The preview becomes the current working bitmap.

- - If `input` is set to 'auto' (the default), GFL will attempt to guess the format.

- - `width` and `height` will be rounded to the nearest integer value if fractionals.

- - `ImageIndex` indicates which image should be loaded in the case of a multi-image or animated file. It is zero-based.

e.g:

            $i = getfileinformations('foo.png') or die;
            $a = GFL::Image->new;
            $a -> loadpreview('foo.png', $i->{'Width'}/3, $i->{'Height'}/3);

## $o->save( filename )

Save the current Bitmap using attribute `Output` as format.

Be aware that there is no checking to see if current `Output` format support the actual color depth.

If the GFL library reports `` Can't save this bitmap in this format !'', see `ChangeDepth()` method.

## $o->resize( Width, Height [, 'quick'])

Rescale the image to the given Width/Height values.

- If the keyword 'Quick' is given as third argument, resize method is set to quick ; otherwise, Bilinear method applies.

- If `Width` and `Height` are fractionals, they are rounded to the nearest integer.

## $o->flip( 'vertical' or 'horizontal' )

Flip image on the given axis.

## $o->negate

Negate current image

## $o->crop(x, y, width, height)

Crop image starting at (x,y) coordinates from current `Origin`

## $o->`contrast(-100...100)`

## $o->gamma(0.01 <-> 5.0)

## $o->rotate( Angle )

Apply a rotation of ``Angle'' degrees.

## $o->soften( percent )

## $o->blur( percent )

## $o->sharpen( percent )

## $o->filter(filter_type => filter_size, ...)

Apply the given filters.

Where filter_type is one of: `average`, `gaussianblur`, `maximum`, `minimum`, `medianbox`, `mediancross`

And filter_size is one of: `3`, `5`, `7`, `9`, `11`, `13`

Multiple filters are applied following arguments order.

## $o->ChangeDepth( new_depth )

Change the color depth of current working bitmap.

new_depth is one of:

            binary, 4g, 8g, 16g, 32g, 64g, 128g, 216g,
            256g, 8, 16, 32, 64, 128, 216, 256 ,truecolors

Values containing a ``g'' like ``32g'' mean greyscale.

If the `dither` attribute is set (boolean), then image is dithered with Adaptative algorithm.

If, additionaly, wanted colordepth is 'binary', then dither will read the `binarydither` attribute and use the corresponding algorithm.

## $o->LastError

Retrieve the last error message.

# FUNCTIONS

Those functions aren't really methods : they do not process the object when called from it. Thus, they don't have error handling as defined in ERROR HANDLING section. However, if `getfileinformations(filename)` is called as a method on an object, you may retrieve an eventual error via `$obj->lasterror`;

`getfileinformations()` and `dumpallformats()` are also exported (in lowercase) in your namespace, so you can use them from scratch.

## GFL::Image->`GetFileInformations(filename[,format])` or `getfileinformations(filename[,format])`

Returns a hash reference containing detailed informations about a given file, or false on error. If `format` is not defined, GFL tries to autodetect it.

See also `FileInformations` attribute.

## GFL::Image->enableLZW

If you've got a patent from UNISIS, you may enable LZW compression (this is class wide). This compression algorithm is used by GIF & TIFF formats.

Always the same sad story...

## GFL::Image->DumpAllFormats or `dumpallformats()`

Issue the complete list of supported formats with description and Read/Write flag.

# ERROR HANDLING

Well, TIMTOWTDI...

To begin with, all methods except get() bring back a status report which is different in LIST and SCALAR context.

- Error reporting in LIST context

  Here, you are testing for error. You get a list with two values :

  - first value is true if the function failed, false otherwise.

  - second value is either an error string or the string `'OK'`

  e.g:

              @error = $a -> rotate(100);
              if ($error[0])
              {
                      print STDERR $error[1];
              }

- Error reporting in SCALAR context

  Here, you are testing for Success. You get true if the method succeeded, false otherwise.

  e.g:

              $a-> rotate(100) && $success++;

- error reporting via LastError attribute

  In either SCALAR or LIST context, the LastError attribute is always updated with false or an error message after a method call.

  As using `get()` would also affect `lasterror`, you must retrieve it via the special accessor `->lasterror`.

  Thus, you can say:

              $b = $a -> get('dither');
              $errormsg = $a ->lasterror and print "couldn't get dither value : $errormsg\n";

- error reporting on STDERR

  See the Verbose attribute if you want reports on STDERR.

# COPYRIGHT

copyright 2001 Germain Garand (germain@ebooksfrance.com)

This wrapper is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

# SEE ALSO

GD(3), Image::Magick(3)