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
52       constraint, they check to see if the image is bigger than the
53       constraint, and if so scale the image down proportionally so that it
54       fits withint 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       -head2 new [ $width, $height ]
67

new $width_and_height

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

TO DO

149       - Write more special-case unit tests
150

SUPPORT

152       Bugs should always be submitted via the CPAN bug tracker
153
154       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Image-Math-Constrain>
155
156       For other issues, contact the maintainer
157

AUTHORS

159       Adam Kennedy <adamk@cpan.org>
160
161       Thank you to Phase N (<http://phase-n.com/>) for permitting the open
162       sourcing and release of this distribution.
163

165       Copyright 2004 - 2008 Adam Kennedy.
166
167       This program is free software; you can redistribute it and/or modify it
168       under the same terms as Perl itself.
169
170       The full text of the license can be found in the LICENSE file included
171       with this module.
172
173
174
175perl v5.28.0                      2008-07-10         Image::Math::Constrain(3)
Impressum