The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
GFL-0.14a
River stage zero No dependents
++
/ GFL::Image

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->brightness(-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)