Updated: 2006-02-05

Index Return to Main Contents

use Image::Math::Constrain;

# Create the math object my $Math = Image::Math::Constrain->new(64, 48);

# Get the scaling values for an arbitrary image my $Image = My::Image->load("myimage.jpg"); my $scaling = $Math->constrain($Image->width, $Image->height); die "Don't need to scale" if $scaling->{scale} == 1;

# Returns the three values as a list when called in array contect my ($width, $height, $scale) = $Math->constrain(800, 600);

# There are lots of different ways to specify the constrain

# Constrain based on width only $Math = Image::Math::Constrain->new(100, 0);

# Constrain based on height only $Math = Image::Math::Constrain->new(0, 100);

# Or you can provide the two values by ARRAY ref $Math = Image::Math::Constrain->new( [ 64, 48 ] );

# Constrain height and width by the same value $Math = Image::Math::Constrain->new(100);

# Various string forms to do the same thing $Math = Image::Math::Constrain->new('constrain(800x600)'); $Math = Image::Math::Constrain->new('300x200'); $Math = Image::Math::Constrain->new('300w200h'); $Math = Image::Math::Constrain->new('100w'); $Math = Image::Math::Constrain->new('100h');

# Serialises back to 'constrain(800x600)'. # You can use this to store the object if you wish. my $string = $Math->as_string;

Of course, they all do it slightly differnetly, and some do it better than others.

`"Image::Math::Constrain"` has been created specifically to implement
this logic once, and implement it properly. Any module or script that
does image size constraining or thumbnailing should probably be using
this for its math.

You can feed a number of different height/width pairs to this object, and it will returns the scaling you will need to do to shrink the image down to the constraints, and the final width and height of the image after scaling, at least one of which should match the constraint.

A value of zero is used to indicate that a dimension should not be
constrained. Thus, `"->new(400, 0)"` would indicate to constrain the
width to 400 pixels, but to ignore the height (only changing it to keep
the image proportional).

The constraint dimensions can be provided in a number of different
formats. See the Synopsis for a quick list of these. To stay
compatible with automated constraint generators, you **can** provide
constrains as zero width and zero height, and the math object will not
attempt to do any scaling, always returning the input width/height,
and a scaling value of 1.

Once created, the object is fully Storable and re-usable and does not store any state information from a single calculation run.

Returns a new Image::Math::Constrain object, or `"undef"` if the
constraints have been defined wrongly.

Returns a positive integer, or zero if there is no width constraint.

Returns a positive integer, or zero if there is no height constraint.

As this value is not localisable, it should never really be shown to the user directly, unless you are sure you will never add i18n to your app.

The resulting size will be in proportion to the original (it will have the same aspect ratio) and will never be larger than the original.

When called in array context, returns the new dimensions and scaling value as a list, as in the following.

my ($width, $height, $scale) = $Math->constrain(800, 600);

When called in scalar context, it returns a reference to a hash containing the keys 'width', 'height', and 'scale'.

my $hash = $Math->constrain(800, 600);

print "New Width : $hash->{width}\n"; print "New Height : $hash->{height}\n"; print "Scaling By : $hash->{scalar}\n";

Having been created correctly, the object will only return an error if the width and height arguments are not correct (are not positive integers).

In list context, returns a null list, so all three values will be `"undef"`.

In scalar context, just returns `"undef"`.

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Image-Math-Constrain>

For other issues, contact the maintainer

Thank you to Phase N (<http://phase-n.com/>) for permitting the open sourcing and release of this distribution.

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

The full text of the license can be found in the LICENSE file included with this module.

- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS
- new $width,
`$height` `new $width_and_height``new $string``width``height``as_string``constrain $width,``$height``TO DO``SUPPORT``AUTHORS``COPYRIGHT`