.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.08)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Image::Math::Constrain 3pm"
.TH Image::Math::Constrain 3pm "2008-07-10" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Image::Math::Constrain \- Scaling math used in image size constraining (such
as thumbnails)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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\*(Aqt 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(\*(Aqconstrain(800x600)\*(Aq);
\&  $math = Image::Math::Constrain\->new(\*(Aq300x200\*(Aq);
\&  $math = Image::Math::Constrain\->new(\*(Aq300w200h\*(Aq);
\&  $math = Image::Math::Constrain\->new(\*(Aq100w\*(Aq);
\&  $math = Image::Math::Constrain\->new(\*(Aq100h\*(Aq);
\&  
\&  # Serialises back to \*(Aqconstrain(800x600)\*(Aq.
\&  # You can use this to store the object if you wish.
\&  my $string = $math\->as_string;
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
Of course, they all do it slightly differnetly, and some do it better
than others.
.PP
\&\f(CW\*(C`Image::Math::Constrain\*(C'\fR 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.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "new $width, $height"
.el .SS "new \f(CW$width\fP, \f(CW$height\fP"
.IX Subsection "new $width, $height"
\&\-head2 new [ \f(CW$width\fR, \f(CW$height\fR ]
.ie n .SH "new $width_and_height"
.el .SH "new \f(CW$width_and_height\fP"
.IX Header "new $width_and_height"
.ie n .SS "new $string"
.el .SS "new \f(CW$string\fP"
.IX Subsection "new $string"
The \f(CW\*(C`new\*(C'\fR constructor takes the dimentions to which you wish to
constrain and creates a new math object.
.PP
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.
.PP
A value of zero is used to indicate that a dimension should not be
constrained. Thus, \f(CW\*(C`\->new(400, 0)\*(C'\fR would indicate to constrain the
width to 400 pixels, but to ignore the height (only changing it to keep
the image proportional).
.PP
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 \fBcan\fR 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.
.PP
Once created, the object is fully Storable and re-usable and does not
store any state information from a single calculation run.
.PP
Returns a new Image::Math::Constrain object, or \f(CW\*(C`undef\*(C'\fR if the
constraints have been defined wrongly.
.SS "width"
.IX Subsection "width"
The \f(CW\*(C`width\*(C'\fR method gets the width constraint for the object.
.PP
Returns a positive integer, or zero if there is no width constraint.
.SS "height"
.IX Subsection "height"
The \f(CW\*(C`height\*(C'\fR method gets the height constrain for the object.
.PP
Returns a positive integer, or zero if there is no height constraint.
.SS "as_string"
.IX Subsection "as_string"
The \f(CW\*(C`as_string\*(C'\fR 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.
.PP
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.
.ie n .SS "constrain $width, $height"
.el .SS "constrain \f(CW$width\fP, \f(CW$height\fP"
.IX Subsection "constrain $width, $height"
The \f(CW\*(C`constrain\*(C'\fR 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.
.PP
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.
.PP
When called in array context, returns the new dimensions and scaling value
as a list, as in the following.
.PP
.Vb 1
\&  my ($width, $height, $scale) = $math\->constrain(800, 600);
.Ve
.PP
When called in scalar context, it returns a reference to a hash containing
the keys 'width', 'height', and 'scale'.
.PP
.Vb 1
\&  my $hash = $math\->constrain(800, 600);
\&  
\&  print "New Width  : $hash\->{width}\en";
\&  print "New Height : $hash\->{height}\en";
\&  print "Scaling By : $hash\->{scalar}\en";
.Ve
.PP
Having been created correctly, the object will only return an error if the
width and height arguments are not correct (are not positive integers).
.PP
In list context, returns a null list, so all three values will be \f(CW\*(C`undef\*(C'\fR.
.PP
In scalar context, just returns \f(CW\*(C`undef\*(C'\fR.
.SH "TO DO"
.IX Header "TO DO"
\&\- Write more special-case unit tests
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs should always be submitted via the \s-1CPAN\s0 bug tracker
.PP
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Image\-Math\-Constrain>
.PP
For other issues, contact the maintainer
.SH "AUTHORS"
.IX Header "AUTHORS"
Adam Kennedy <adamk@cpan.org>
.PP
Thank you to Phase N (<http://phase\-n.com/>) for permitting
the open sourcing and release of this distribution.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2004 \- 2008 Adam Kennedy.
.PP
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the
\&\s-1LICENSE\s0 file included with this module.