NAME
Image::Shoehorn - massage the dimensions and filetype of an image
SYNOPSIS
use Image::Shoehorn;
use Data::Dumper;
my $image = Image::Shoehorn->new({
tmpdir => "/usr/tmp",
cleanup => \&my_cleanup
}) || die Image::Shoehorn->last_error();
my $imgs = $image->import({
source => "/some/large/image.jpg",
max_height => 600,
valid => [ "png" ],
convert => 1,
scale => { thumb => "x50", small => "50%" },
overwrite => 1,
}) || die Image::Shoehorn->last_error();
print &Dumper($imgs);DESCRIPTION
Image::Shoehorn will massage the dimensions and filetype of an image, optionally creating one or more "scaled" copies.
It uses Image::Magick to do the heavy lifting and provides a single "import" objet method to hide a number of tasks from the user.
RATIONALE
Just before I decided to submit this package to the CPAN, I noticed that Lee Goddard had just released Image::Magick::Thumbnail. Although there is a certain amount of overlap, creating thumbnails is only a part of the functionality of Image::Shoehorn.
Image::Shoehorn is designed for taking a single image, optionally converting its file type and resizing it, and then creating one or more "scaled" versions of the (modified) image.
One example would be a photo-gallery application where the gallery may define (n) number of scaled versions. In a mod_perl context, if the scaled image had not already been created, the application might create the requested image for the request and then register a cleanup handler to create the remaining "scaled" versions. Additionally, scaled images may be defined as "25%", "x50", "200x" or "25x75" (Apache::Image::Shoehorn is next...)
SHOEHORN ?!
This package started life as Image::Import; designed to slurp and munge images into a database. It's not a very exciting name and, further, is a bit ambiguous.
So, I started fishing around for a better name and for a while I was thinking about Image::Tailor - a module for taking in the "hem" of an image, of fussing and making an image fit properly.
When I asked the Dict servers for a definition of "tailor", it returned a WordNet entry containing the definition...
make fit for a specific purpose [syn: {shoehorn}]..and that was that.
PACKAGE METHODS
__PACKAGE__->last_error()
Returns the last error recorded by the object.
__PACKAGE__->dimensions_for_scale($x,$y,$scale)
__PACKAGE__->scaled_name([$source,$scale])
__PACKAGE__->converted_name([$source,$type])
__PACKAGE__->scaled_dimensions([$cur_x,$cur_y,$new_x,$new_y])
$pkg = __PACKAGE__->new(\%args)
Object constructor. Valid arguments are :
tmpdir
String.
The path to a directory where your program has permissions to create new files. Required
cleanup
Code reference.
By default, any new images that are created, in the tmp directory, are deleted when a different image is imported or when the Image::Shoehorn::DESTROY method is invoked.
You may optionally provide your own cleanup method which will be called in place.
Your method will be passed a hash reference where the keys are "source" and any other names you may define in the scale parameter of the import object method. Each key points to a hash reference whose keys are :
path
width
height
format
type
Note that this method will only affect new images. The original source file may be altered, if it is imported with the overwrite parameter, but will not be deleted.
Returns an object. Woot!
OBJECT METHODS
$obj->import(\%args)
Valid arguments are :
source
String.
The path to the image you are trying to import. If ImageMagick can read it, you can import it.
Required
max_width
Int.
The maximum width that the image you are importing may be. Height is scaled accordingly.
max_height
Int.
The maximum height that the image you are importing may be. Width is scaled accordingly.
scale
Hash reference.
One or more key-value pairs that define scaling dimensions for creating multiple instances of the current image.
The key is a human readable label because humans are simple that way. The key may be anything you'd like except "source" which is reserved for the image the object is munging.
The value for a given key is the dimension flag which may be represented as :
n%
nxn
xn
nx
Note that images are scaled after the original source file may have been resized according to the max_height, max_width flags and convert flags.
Scaled images are created in the tmp_dir defined in the object constructor.
valid
Array reference.
An list of valid file-types for which Image::Magick has encoding support.
convert
Boolean.
If this value is true and the source does not a valid file-type, the method will create a temporary file attempt to convert it to one of the specified valid file-types. The method will try to convert in the order the valid file-types are specified, stopping on success.
cleanup
Code reference.
Define a per instance cleanup function for an image. This functions exactly the same way that a cleanup function defined in the object constructor does, except that it is forgotten as soon as a new image is imported.
overwrite
Boolean.
Indicates whether or not to preserve the source file. By default, the package will not perform munging on the source file itself and will instead create a new file in the tmp_dir defined in the object constructor.
Returns a hash reference with information for the source image -- note that this may or may not be the input document, but the newly converted/resized image created in you tmp directory -- and any scaled images you may have defined.
The keys of the hash are human readable names. The values are hash references whose keys are :
path
height
width
extension
contenttype
format
type
Deprecated in favour or extension
If there was an error, the method will return undef.
VERSION
1.42
DATE
$Date: 2003/05/30 22:51:06 $
AUTHOR
Aaron Straup Cope
TO DO
Modify constructor to accept all the options defined in the import method as defaults.
Modify import to accept multiple files.
Modify import to accept strings and filehandles.
SEE ALSO
LICENSE
Copyright (c) 2001-2003, Aaron Straup Cope. All Rights Reserved.
This is free software, you may use it and distribute it under the same terms as Perl itself.