Image:...strain(3pm)

💖 NAME 💖

okay so bestie, meet Image::Math::Constrain — the scaling math that does all the image size constraining (you know, thumbnails and that whole vibe) ✨

You're reading the page filed under the User Contributed Perl Documentation, and honestly? It's giving "small module, big main character energy". 🎀

---

🌸 SYNOPSIS 🌸

  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;

---

🦋 DESCRIPTION 🦋

So like… there are a LOT of modules and systems out there that constrain image sizes — thumbnailing girlies, you know the ones. And every single one of them independantly implements the same logic. Like, the exact same bit: given a width and/or height constraint, they check whether the image is bigger than the constraint, and if it is, they scale it down proportionally so it fits withint the constraints. 💅

And ofc, they all do it slightly differnetly, and some do it better than others. 🙈 (we're not naming names)

So Image::Math::Constrain was 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. Periodt. 👑

---

🧚 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. So like, ->new(400, 0) means "constrain the width to 400 pixels but ignore the height" (only changing it to keep the image proportional). 💖

The constraint dimensions can be provided in a number of different formats — check the SYNOPSIS for a quick list of these. And 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. So you can pass it around like a lil friendship bracelet. 🎀

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

heads up bestie: 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. no cap. 😬

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

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

🙈 that last one is verbatim what the docs say, i'm literally just the messenger here bestie, i don't make the rules

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-Math-Constrain>

For other issues, contact the maintainer. 🫶

---

👑 AUTHORS 👑

Adam Kennedy <adamk@cpan.org>

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

---

⭐ COPYRIGHT ⭐

Copyright 2004 - 2008 Adam Kennedy.

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.

---

and that's the whole page bestie, mwah 💅 this was perl v5.34.0, dated 2022-06-14, and yes we're closing out on Image:...strain(3pm) like we opened — iconic, honestly 🌸🦋✨