imgscalr – Java Image Scaling Library

Sections

  1. Description
  2. License
  3. What Problem Does this Solve?
  4. Benefits
  5. Usage
  6. Intended Audience
  7. Download
  8. Javadoc & Source
  9. Maven
  10. imgscalr in Production
  11. Bug Reports
  12. Feature Requests, Comments & Feedback
  13. Additional Links
See imgscalr in action here!

Description

imgscalr is an very simple and efficient (hardware accelerated) “best-practices” image-scaling library implemented in pure Java 2D; as of the 4.0 release imgscalr now includes a handful of other convenience image operations, all as easy to use as resize.

This library makes  uses of efficient Java2D scaling techniques advocated by the Java2D team which provides hardware accelerated operations on most platforms.

This library also implements the optimized incremental scaling algorithm proposed by Chris Campbell with some minor enhancements for good-looking (and quick) thumbnail generation (previously only possible with the discouraged Image.getScaledInstance method using the much slower SCALE_AREA_AVERAGE algorithm).

License

This software is licensed under the Apache 2 License.

What Problem Does this Solve?

If you have ever wanted to quickly resize an image in Java you have probably noticed the following confusing things:

imgscalr addresses all these issues.

Benefits

  • 100% Java code based on Java2D, no native libraries to install
  • Java that works in “headless” environments without special environment variable settings; it just works.
  • Because there are no native libraries, you mitigate the risk of native libraries crashing the host VM (e.g. your app server) or thread-contention issues
  • Hardware accelerated on supported platforms (uses the optimized Java2D rendering pipeline)
  • Fast; not faster than a native-C solution, but still damn fast.
  • Simple, simple, simple. A handful of static, 1-word methods you can call. No complex configurations, managers, encoders/decoders or any other nonsense. imgscalr is not a “graphics library”, it is a set of the most commonly used graphic operations, optimized and ready to do your bidding.

Usage

The simplest use-case of the library for resizing an image is a single 2-argument method call:

BufferedImage thumbnail = Scalr.resize(image, 150);

In this use-case we pass the library our image and ask it to fit the image (while maintaing its original proportions) within a width and height of 150 pixels.

Alternatively, if we wanted some finer-grained control over how our image is scaled, quality used and possibly a light anti-aliasing filter to it (to make it look smoother) our method call would look something like this:

BufferedImage thumbnail =
  Scalr.resize(image, Scalr.Method.SPEED, Scalr.Mode.FIT_TO_WIDTH,
               150, 100, Scalr.OP_ANTIALIAS);

You can see that we a slew of knobs and levers to change when using the library. A few things worth noting are the Method and Mode enums defined on the Scalr class. These enums are used in conjunction with all of the resize methods.

Usability Tip: Java’s static imports makes using imgscalr a walk in the park, consider the following snippet of code to see how easy it becomes:

import static org.imgscalr.Scalr.*;
 
public static BufferedImage createThumbnail(BufferedImage img) {
  // Create quickly, then smooth and brighten it.
  img = resize(img, Method.SPEED, 125, OP_ANTIALIAS, OP_BRIGHTER);
 
  // Let's add a little border before we return result.
  return pad(img, 4);
}

Of course we could have inlined the resize directly inside of the pad call, but for readability I split them up; either way, you see how simple it is to use imgscalr in your projects.

There are a set of other operations we can do to our image, like rotating it, padding it, cropping it and so on.

By default imgscalr always honors the image’s original proportions above all else. If invalid target dimensions are passed in, imgscalr will re-calculate proper dimensions honoring the primary dimension of the image first (selected based on the image’s orientation). The only way to force imgscalr to resize (stretching if necessary) an image into a target bounding box is to use Scalr.Mode.FIT_EXACT.

Intended Audience

This library is intended for developers needing to quickly resize or manipulate images (using the correct or most optimal methods available in native Java) and move one with their lives.

imgscalr is general purpose and will work on any platform providing the base Java2D classes it uses. imgscalr was also written with web application’s in mind, possibly needing to generate thousands of thumbnails or previews from larger uploaded images.

This library is not meant to be a full-scale Java graphics library like JAI.

Download

All download bundles include the library JAR, source code and Javadoc.

Javadoc & Source Code

Maven

imgscalr v4.0+ is available directly from the central Maven repository and can be easily used in your project by simply adding the following dependency to your pom.xml file:

<dependencies>
  ...
  <dependency>
    <groupId>org.imgscalr</groupId>
    <artifactId>imgscalr-lib</artifactId>
    <version>4.2</version>
    <type>jar</type>
    <scope>compile</scope>
  </dependency>
  ...
<dependencies>

Be sure to adjust the version value to whichever version of imgscalr you want to grab.

groupId changed in version 4.0 from com.thebuzzmedia to org.imgscalr

If you are looking for an earlier version of imgscalr (3.2 or earlier) via Maven, you can use The Buzz Media’s own Maven Repository by adding a section to your pom.xml like so:

<repositories>
  ...
  <repository>
    <id>The Buzz Media Maven Repository</id>
    <url>http://maven.thebuzzmedia.com</url>
  </repository>
  ...
</repositories>
At this time we are not providing checksums for the files on our repository, so you will see “[WARNING] Checksum validation failed” messages from Maven, but they can be safely ignored. Writing a release POM for Maven is beyond my capabilities as a human at this time.

imgscalr in Production

Below is a quick snapshot of a few products and projects using imgscalr in production.

Bug Reports

If you find a bug, please create a new issue with a description of the problem and how to reproduce it. Example files help a lot!

Feature Requests, Comments & Feedback

Please email me at software@thebuzzmedia.com, I would love to hear from you.

Additional Links