NAME
    Image::Math::Constrain - Scaling math used in image size constraining
    (such as for thumbnails)

SYNOPSIS
      # 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;

DESCRIPTION
    There are a number of different modules and systems that constrain image
    sizes, such as thumbnailing. Every one of these independantly implement
    the same logic. That is, given a width and/or height constraint, they
    check to see if the image is bigger than the constraint, and if so scale
    the image down proportionally so that it fits withint the constraints.

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

    Image::Math::Constrain has been created to 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 it's math.

METHODS
  new $width, $height
    -head2 new [ $width, $height ]

new $width_and_height
  new $string
    The "new" constructor takes the dimentions to which you wish to
    constrain and creates a new math object.

    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 about 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.

  width
    The "width" method gets the width constraint for the object.

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

  height
    The "height" method gets the height constrain for the object.

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

  as_string
    The "as_string" method returns the constrain rule as a string in the
    format 'constrain(123x123)'. This string form is also supported by the
    constructor and so it provides a good way to serialise the constrain
    rule, should you ever need to do so.

    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.

  constrain $width, $height
    The "constrain" method takes the height and width of an image and
    applies the constrain math to them to get the final width, height and
    the scaling value needed in order to get the your image from it's
    current size to the final size.

    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".

TO DO
    - Write more special-case unit tests

SUPPORT
    Bugs should always be submitted via the CPAN bug tracker

    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Image%3A%3AMath%3A%3ACon
    strain>

    For other issues, contact the maintainer

AUTHORS
    Adam Kennedy (Maintainer), <http://ali.as/>, cpan@ali.as

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

COPYRIGHT
    Copyright (c) 2004 Adam Kennedy. All rights reserved. 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.

