Image::Math::Constrain(3pm)

1Image::Math::Constrain(U3s)er Contributed Perl DocumentatIimoange::Math::Constrain(3)
2
3
4

NAME

6       Image::Math::Constrain - Scaling math used in image size constraining
7       (such as thumbnails)
8

SYNOPSIS

10         use Image::Math::Constrain;
11
12         # Create the math object
13         my $Math = Image::Math::Constrain->new(64, 48);
14
15         # Get the scaling values for an arbitrary image
16         my $Image = My::Image->load("myimage.jpg");
17         my $scaling = $Math->constrain($Image->width, $Image->height);
18         die "Don't need to scale" if $scaling->{scale} == 1;
19
20         # Returns the three values as a list when called in array contect
21         my ($width, $height, $scale) = $Math->constrain(800, 600);
22
23         # There are lots of different ways to specify the constrain
24
25         # Constrain based on width only
26         $Math = Image::Math::Constrain->new(100, 0);
27
28         # Constrain based on height only
29         $Math = Image::Math::Constrain->new(0, 100);
30
31         # Or you can provide the two values by ARRAY ref
32         $Math = Image::Math::Constrain->new( [ 64, 48 ] );
33
34         # Constrain height and width by the same value
35         $Math = Image::Math::Constrain->new(100);
36
37         # Various string forms to do the same thing
38         $Math = Image::Math::Constrain->new('constrain(800x600)');
39         $Math = Image::Math::Constrain->new('300x200');
40         $Math = Image::Math::Constrain->new('300w200h');
41         $Math = Image::Math::Constrain->new('100w');
42         $Math = Image::Math::Constrain->new('100h');
43
44         # Serialises back to 'constrain(800x600)'.
45         # You can use this to store the object if you wish.
46         my $string = $Math->as_string;
47

DESCRIPTION

49       There are a number of different modules and systems that constrain
50       image sizes, such as thumbnailing. Every one of these independantly
51       implement the same logic. That is, given a width and/or height con‐
52       straint, they check to see if the image is bigger than the constraint,
53       and if so scale the image down proportionally so that it fits withint
54       the constraints.
55
56       Of course, they all do it slightly differnetly, and some do it better
57       than others.
58
59       "Image::Math::Constrain" has been created specifically to implement
60       this logic once, and implement it properly. Any module or script that
61       does image size constraining or thumbnailing should probably be using
62       this for its math.
63

METHODS

65       new $width, $height
66
67       -head2 new [ $width, $height ]
68

new $width_and_height

70       new $string
71
72       The "new" constructor takes the dimentions to which you wish to con‐
73       strain and creates a new math object.
74
75       You can feed a number of different height/width pairs to this object,
76       and it will returns the scaling you will need to do to shrink the image
77       down to the constraints, and the final width and height of the image
78       after scaling, at least one of which should match the constraint.
79
80       A value of zero is used to indicate that a dimension should not be con‐
81       strained. Thus, "->new(400, 0)" would indicate to constrain the width
82       to 400 pixels, but to ignore the height (only changing it to keep the
83       image proportional).
84
85       The constraint dimensions can be provided in a number of different for‐
86       mats. See the Synopsis for a quick list of these. To stay compatible
87       with automated constraint generators, you can provide constrains as
88       zero width and zero height, and the math object will not attempt to do
89       any scaling, always returning the input width/height, and a scaling
90       value of 1.
91
92       Once created, the object is fully Storable and re-usable and does not
93       store any state information from a single calculation run.
94
95       Returns a new Image::Math::Constrain object, or "undef" if the con‐
96       straints have been defined wrongly.
97
98       width
99
100       The "width" method gets the width constraint for the object.
101
102       Returns a positive integer, or zero if there is no width constraint.
103
104       height
105
106       The "height" method gets the height constrain for the object.
107
108       Returns a positive integer, or zero if there is no height constraint.
109
110       as_string
111
112       The "as_string" method returns the constrain rule as a string in the
113       format 'constrain(123x123)'. This string form is also supported by the
114       constructor and so it provides a good way to serialise the constrain
115       rule, should you ever need to do so.
116
117       As this value is not localisable, it should never really be shown to
118       the user directly, unless you are sure you will never add i18n to your
119       app.
120
121       constrain $width, $height
122
123       The "constrain" method takes the height and width of an image and
124       applies the constrain math to them to get the final width, height and
125       the scaling value needed in order to get the your image from it's cur‐
126       rent size to the final size.
127
128       The resulting size will be in proportion to the original (it will have
129       the same aspect ratio) and will never be larger than the original.
130
131       When called in array context, returns the new dimensions and scaling
132       value as a list, as in the following.
133
134         my ($width, $height, $scale) = $Math->constrain(800, 600);
135
136       When called in scalar context, it returns a reference to a hash con‐
137       taining the keys 'width', 'height', and 'scale'.
138
139         my $hash = $Math->constrain(800, 600);
140
141         print "New Width  : $hash->{width}\n";
142         print "New Height : $hash->{height}\n";
143         print "Scaling By : $hash->{scalar}\n";
144
145       Having been created correctly, the object will only return an error if
146       the width and height arguments are not correct (are not positive inte‐
147       gers).
148
149       In list context, returns a null list, so all three values will be
150       "undef".
151
152       In scalar context, just returns "undef".
153

TO DO

155       - Write more special-case unit tests
156

SUPPORT

158       Bugs should always be submitted via the CPAN bug tracker
159
160       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Image-Math-Constrain>
161
162       For other issues, contact the maintainer
163

AUTHORS

165       Adam Kennedy <cpan@ali.as>, <http://ali.as/>
166
167       Thank you to Phase N (<http://phase-n.com/>) for permitting the open
168       sourcing and release of this distribution.
169

COPYRIGHT

171       Copyright (c) 2004 - 2006 Adam Kennedy. All rights reserved.
172
173       This program is free software; you can redistribute it and/or modify it
174       under the same terms as Perl itself.
175
176       The full text of the license can be found in the LICENSE file included
177       with this module.
178
179
180
181perl v5.8.8                       2006-02-05         Image::Math::Constrain(3)