Walhalla

Class used to implement performant, high-quality and intelligent image scaling and manipulation algorithms in native Java 2D.

This class utilizes the Java2D "best practices" for image manipulation, ensuring that all operations (even most user-provided BufferedImageOp s) are hardware accelerated if provided by the platform and host-VM.

Image Quality

This class also implements an optimized version of the incremental scaling algorithm presented by Chris Campbell in his Perils of Image.getScaledInstance() article in order to give the best-looking image resize results (e.g. generating thumbnails that aren't blurry or jagged).

The results generated by imgscalr using this method, as compared to a single RenderingHints#VALUE_INTERPOLATION_BICUBIC scale operation look much better, especially when using the Method#ULTRA_QUALITY method.

Only when scaling using the Method#AUTOMATIC method will this class look at the size of the image before selecting an approach to scaling the image. If Method#QUALITY is specified, the best-looking algorithm possible is always used.

Minor modifications are made to Campbell's original implementation in the form of:

1. Instead of accepting a user-supplied interpolation method, RenderingHints#VALUE_INTERPOLATION_BICUBIC interpolation is always used. This was done after A/B comparison testing with large images down-scaled to thumbnail sizes showed noticeable "blurring" when BILINEAR interpolation was used. Given that Campbell's algorithm is only used in QUALITY mode when down-scaling, it was determined that the user's expectation of a much less blurry picture would require that BICUBIC be the default interpolation in order to meet the QUALITY expectation.
2. After each iteration of the do-while loop that incrementally scales the source image down, an explicit effort is made to call BufferedImage#flush() on the interim temporary BufferedImage instances created by the algorithm in an attempt to ensure a more complete GC cycle by the VM when cleaning up the temporary instances (this is in addition to disposing of the temporary Graphics2D references as well).
3. Extensive comments have been added to increase readability of the code.
4. Variable names have been expanded to increase readability of the code.

NOTE: This class does not call BufferedImage#flush() on any of the source images passed in by calling code; it is up to the original caller to dispose of their source images when they are no longer needed so the VM can most efficiently GC them.

Image Proportions

When not using Mode#FIT_EXACT, in order to maintain the proportionality of the original images, this class implements the following behavior:

1. If the image is LANDSCAPE-oriented or SQUARE, treat the targetWidth as the primary dimension and re-calculate the targetHeight regardless of what is passed in.
2. If image is PORTRAIT-oriented, treat the targetHeight as the primary dimension and re-calculate the targetWidth regardless of what is passed in.
3. If a Mode value of Mode#FIT_TO_WIDTH or Mode#FIT_TO_HEIGHT is passed in to the resize method, the image's orientation is ignored and the scaled image is fit to the preferred dimension by using the value passed in by the user for that dimension and recalculating the other (regardless of image orientation). This is useful, for example, when working with PORTRAIT oriented images that you need to all be the same width or visa-versa (e.g. showing user profile pictures in a directory listing).

Optimized Image Handling

Some more obscure image types either have poor or no support, leading to severely degraded quality and processing performance when an attempt is made by imgscalr to create a scaled instance of the same type as the source image. In many cases, especially when applying BufferedImageOp s, using poorly supported image types can even lead to exceptions or total corruption of the image (e.g. solid black image).

imgscalr specifically accounts for and automatically hands ALL of these pain points for you internally by shuffling all images into one of two types:

1. BufferedImage#TYPE_INT_RGB
2. BufferedImage#TYPE_INT_ARGB

This is also the reason we recommend using #apply(BufferedImage, BufferedImageOp...) to apply your own ops to images even if you aren't using imgscalr for anything else.

GIF Transparency

imgscalr currently does nothing to work around this manually because it is a defect in the native platform code itself. Fortunately it looks like the issues are half-fixed in Java 7 and any manual workarounds we could attempt internally are relatively expensive, in the form of hand-creating and setting RGB values pixel-by-pixel with a custom ColorModel in the scaled image. This would lead to a very measurable negative impact on performance without the caller understanding why.

Workaround: A workaround to this issue with all version of Java is to simply save a GIF as a PNG; no change to your code needs to be made except when the image is saved out, e.g. using ImageIO.

When a file type of "PNG" is used, both the transparency and high color quality will be maintained as the PNG code path in Java2D is superior to the GIF implementation.

If the issue with optional BufferedImageOps destroying GIF image content is ever fixed in the platform, saving out resulting images as GIFs should suddenly start working.

More can be read about the issue here and here.

Thread Safety

Logging

Implementation of logging in this class is as efficient as possible; avoiding any calls to the logger method or passing of arguments if logging is not enabled to avoid the (hidden) cost of constructing the Object[] argument for the varargs-based method call.

System property name used to define the debug boolean flag.

Value is "imgscalr.debug".

System property name used to define a custom log prefix.

Value is "imgscalr.logPrefix".

Flag used to indicate if debugging output has been enabled by setting the "imgscalr.debug" system property to true. This value will be false if the "imgscalr.debug" system property is undefined or set to false.

This property can be set on startup with:
-Dimgscalr.debug=true or by calling System#setProperty(String, String) to set a new property value for #DEBUG_PROPERTY_NAME before this class is loaded.

Default value is false.

Prefix to every log message this library logs. Using a well-defined prefix helps make it easier both visually and programmatically to scan log files for messages produced by this library.

This property can be set on startup with:
-Dimgscalr.logPrefix=<YOUR PREFIX HERE> or by calling System#setProperty(String, String) to set a new property value for #LOG_PREFIX_PROPERTY_NAME before this class is loaded.

Default value is "[imgscalr] " (including the space).

A ConvolveOp using a very light "blur" kernel that acts like an anti-aliasing filter (softens the image a bit) when applied to an image.

A common request by users of the library was that they wished to "soften" resulting images when scaling them down drastically. After quite a bit of A/B testing, the kernel used by this Op was selected as the closest match for the target which was the softer results from the deprecated AreaAveragingScaleFilter (which is used internally by the deprecated Image#getScaledInstance(int, int, int) method in the JDK that imgscalr is meant to replace).

This ConvolveOp uses a 3x3 kernel with the values:

For those that have worked with ConvolveOps before, this Op uses the ConvolveOp#EDGE_NO_OP instruction to not process the pixels along the very edge of the image (otherwise EDGE_ZERO_FILL would create a black-border around the image). If you have not worked with a ConvolveOp before, it just means this default OP will "do the right thing" and not give you garbage results.

This ConvolveOp uses no RenderingHints values as internally the ConvolveOp class only uses hints when doing a color conversion between the source and destination BufferedImage targets. imgscalr allows the ConvolveOp to create its own destination image every time, so no color conversion is ever needed and thus no hints.

Performance

Known Issues

A RescaleOp used to make any input image 10% darker.

This operation can be applied multiple times in a row if greater than 10% changes in brightness are desired.

A RescaleOp used to make any input image 10% brighter.

This operation can be applied multiple times in a row if greater than 10% changes in brightness are desired.

A ColorConvertOp used to convert any image to a grayscale color palette.

Applying this op multiple times to the same image has no compounding effects.

Threshold (in pixels) at which point the scaling operation using the Method#AUTOMATIC method will decide if a Method#BALANCED method will be used (if smaller than or equal to threshold) or a Method#SPEED method will be used (if larger than threshold).

The bigger the image is being scaled to, the less noticeable degradations in the image becomes and the faster algorithms can be selected.

The value of this threshold (1600) was chosen after visual, by-hand, A/B testing between different types of images scaled with this library; both photographs and screenshots. It was determined that images below this size need to use a Method#BALANCED scale method to look decent in most all cases while using the faster Method#SPEED method for images bigger than this threshold showed no noticeable degradation over a BALANCED scale.

Threshold (in pixels) at which point the scaling operation using the Method#AUTOMATIC method will decide if a Method#QUALITY method will be used (if smaller than or equal to threshold) or a Method#BALANCED method will be used (if larger than threshold).

The bigger the image is being scaled to, the less noticeable degradations in the image becomes and the faster algorithms can be selected.

The value of this threshold (800) was chosen after visual, by-hand, A/B testing between different types of images scaled with this library; both photographs and screenshots. It was determined that images below this size need to use a Method#QUALITY scale method to look decent in most all cases while using the faster Method#BALANCED method for images bigger than this threshold showed no noticeable degradation over a QUALITY scale.

Used to apply, in the order given, 1 or more BufferedImageOps to a given BufferedImage and return the result.

Feature: This implementation works around a decade-old JDK bug that can cause a RasterFormatException when applying a perfectly valid BufferedImageOps to images.

Feature: This implementation also works around BufferedImageOps failing to apply and throwing ImagingOpExceptions when run against a src image type that is poorly supported. Unfortunately using ImageIO and standard Java methods to load images provides no consistency in getting images in well-supported formats. This method automatically accounts and corrects for all those problems (if necessary).

It is recommended you always use this method to apply any BufferedImageOps instead of relying on directly using the BufferedImageOp#filter(BufferedImage, BufferedImage) method.

Performance: Not all BufferedImageOps are hardware accelerated operations, but many of the most popular (like ConvolveOp) are. For more information on if your image op is hardware accelerated or not, check the source code of the underlying JDK class that actually executes the Op code, sun.awt.image.ImagingLib.

TIP: This operation leaves the original src image unmodified. If the caller is done with the src image after getting the result of this operation, remember to call BufferedImage#flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Used to crop the given src image from the top-left corner and applying any optional BufferedImageOps to the result before returning it.

TIP: This operation leaves the original src image unmodified. If the caller is done with the src image after getting the result of this operation, remember to call BufferedImage#flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Used to crop the given src image and apply any optional BufferedImageOps to it before returning the result.

TIP: This operation leaves the original src image unmodified. If the caller is done with the src image after getting the result of this operation, remember to call BufferedImage#flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Used to apply padding around the edges of an image using Color#BLACK to fill the extra padded space and then return the result.

The amount of padding specified is applied to all sides; more specifically, a padding of 2 would add 2 extra pixels of space (filled by the given color) on the top, bottom, left and right sides of the resulting image causing the result to be 4 pixels wider and 4 pixels taller than the src image.

TIP: This operation leaves the original src image unmodified. If the caller is done with the src image after getting the result of this operation, remember to call BufferedImage#flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Used to apply padding around the edges of an image using the given color to fill the extra padded space and then return the result. Colors using an alpha channel (i.e. transparency) are supported.

The amount of padding specified is applied to all sides; more specifically, a padding of 2 would add 2 extra pixels of space (filled by the given color) on the top, bottom, left and right sides of the resulting image causing the result to be 4 pixels wider and 4 pixels taller than the src image.

TIP: This operation leaves the original src image unmodified. If the caller is done with the src image after getting the result of this operation, remember to call BufferedImage#flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Resize a given image (maintaining its original proportion) to a width and height no bigger than targetSize and apply the given BufferedImageOps (if any) to the result before returning it.

A scaling method of Method#AUTOMATIC and mode of Mode#AUTOMATIC are used.

TIP: This operation leaves the original src image unmodified. If the caller is done with the src image after getting the result of this operation, remember to call BufferedImage#flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Resize a given image (maintaining its original proportion) to a width and height no bigger than targetSize using the given scaling method and apply the given BufferedImageOps (if any) to the result before returning it.

A mode of Mode#AUTOMATIC is used.

TIP: This operation leaves the original src image unmodified. If the caller is done with the src image after getting the result of this operation, remember to call BufferedImage#flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Resize a given image (maintaining its original proportion) to a width and height no bigger than targetSize (or fitting the image to the given WIDTH or HEIGHT explicitly, depending on the Mode specified) and apply the given BufferedImageOps (if any) to the result before returning it.

A scaling method of Method#AUTOMATIC is used.

TIP: This operation leaves the original src image unmodified. If the caller is done with the src image after getting the result of this operation, remember to call BufferedImage#flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Resize a given image (maintaining its original proportion) to a width and height no bigger than targetSize (or fitting the image to the given WIDTH or HEIGHT explicitly, depending on the Mode specified) using the given scaling method and apply the given BufferedImageOps (if any) to the result before returning it.

TIP: This operation leaves the original src image unmodified. If the caller is done with the src image after getting the result of this operation, remember to call BufferedImage#flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Resize a given image (maintaining its original proportion) to the target width and height and apply the given BufferedImageOps (if any) to the result before returning it.

A scaling method of Method#AUTOMATIC and mode of Mode#AUTOMATIC are used.

TIP: See the class description to understand how this class handles recalculation of the targetWidth or targetHeight depending on the image's orientation in order to maintain the original proportion.

TIP: This operation leaves the original src image unmodified. If the caller is done with the src image after getting the result of this operation, remember to call BufferedImage#flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Resize a given image (maintaining its original proportion) to the target width and height using the given scaling method and apply the given BufferedImageOps (if any) to the result before returning it.

A mode of Mode#AUTOMATIC is used.

TIP: See the class description to understand how this class handles recalculation of the targetWidth or targetHeight depending on the image's orientation in order to maintain the original proportion.

TIP: This operation leaves the original src image unmodified. If the caller is done with the src image after getting the result of this operation, remember to call BufferedImage#flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Resize a given image (maintaining its original proportion) to the target width and height (or fitting the image to the given WIDTH or HEIGHT explicitly, depending on the Mode specified) and apply the given BufferedImageOps (if any) to the result before returning it.

A scaling method of Method#AUTOMATIC is used.

TIP: See the class description to understand how this class handles recalculation of the targetWidth or targetHeight depending on the image's orientation in order to maintain the original proportion.

TIP: This operation leaves the original src image unmodified. If the caller is done with the src image after getting the result of this operation, remember to call BufferedImage#flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Resize a given image (maintaining its original proportion) to the target width and height (or fitting the image to the given WIDTH or HEIGHT explicitly, depending on the Mode specified) using the given scaling method and apply the given BufferedImageOps (if any) to the result before returning it.

TIP: See the class description to understand how this class handles recalculation of the targetWidth or targetHeight depending on the image's orientation in order to maintain the original proportion.

TIP: This operation leaves the original src image unmodified. If the caller is done with the src image after getting the result of this operation, remember to call BufferedImage#flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Used to apply a Rotation and then 0 or more BufferedImageOps to a given image and return the result.

TIP: This operation leaves the original src image unmodified. If the caller is done with the src image after getting the result of this operation, remember to call BufferedImage#flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Used to write out a useful and well-formatted log message by any piece of code inside of the imgscalr library.

If a message cannot be logged (logging is disabled) then this method returns immediately.

NOTE: Because Java will auto-box primitive arguments into Objects when building out the params array, care should be taken not to call this method with primitive values unless Scalr#DEBUG is true; otherwise the VM will be spending time performing unnecessary auto-boxing calculations.

Used to create a BufferedImage with the most optimal RGB TYPE ( BufferedImage#TYPE_INT_RGB or BufferedImage#TYPE_INT_ARGB ) capable of being rendered into from the given src. The width and height of both images will be identical.

This does not perform a copy of the image data from src into the result image; see #copyToOptimalImage(BufferedImage) for that.

We force all rendering results into one of these two types, avoiding the case where a source image is of an unsupported (or poorly supported) format by Java2D causing the rendering result to end up looking terrible (common with GIFs) or be totally corrupt (e.g. solid black image).

Originally reported by Magnus Kvalheim from Movellas when scaling certain GIF and PNG images.

Used to create a BufferedImage with the given dimensions and the most optimal RGB TYPE ( BufferedImage#TYPE_INT_RGB or BufferedImage#TYPE_INT_ARGB ) capable of being rendered into from the given src.

This does not perform a copy of the image data from src into the result image; see #copyToOptimalImage(BufferedImage) for that.

We force all rendering results into one of these two types, avoiding the case where a source image is of an unsupported (or poorly supported) format by Java2D causing the rendering result to end up looking terrible (common with GIFs) or be totally corrupt (e.g. solid black image).

Originally reported by Magnus Kvalheim from Movellas when scaling certain GIF and PNG images.

Used to copy a BufferedImage from a non-optimal type into a new BufferedImage instance of an optimal type (RGB or ARGB). If src is already of an optimal type, then it is returned unmodified.

This method is meant to be used by any calling code (imgscalr's or otherwise) to convert any inbound image from a poorly supported image type into the 2 most well-supported image types in Java2D ( BufferedImage#TYPE_INT_RGB or BufferedImage#TYPE_INT_ARGB ) in order to ensure all subsequent graphics operations are performed as efficiently and correctly as possible.

When using Java2D to work with image types that are not well supported, the results can be anything from exceptions bubbling up from the depths of Java2D to images being completely corrupted and just returned as solid black.

Used to determine the scaling Method that is best suited for scaling the image to the targeted dimensions.

This method is intended to be used to select a specific scaling Method when a Method#AUTOMATIC method is specified. This method utilizes the Scalr#THRESHOLD_QUALITY_BALANCED and Scalr#THRESHOLD_BALANCED_SPEED thresholds when selecting which method should be used by comparing the primary dimension (width or height) against the threshold and seeing where the image falls. The primary dimension is determined by looking at the orientation of the image: landscape or square images use their width and portrait-oriented images use their height.

Used to implement a straight-forward image-scaling operation using Java 2D.

This method uses the Oracle-encouraged method of Graphics2D.drawImage(...) to scale the given image with the given interpolation hint.

Used to implement Chris Campbell's incremental-scaling algorithm: http://today.java.net/pub/a/today/2007/04/03/perils -of-image-getscaledinstance.html.

Modifications to the original algorithm are variable names and comments added for clarity and the hard-coding of using BICUBIC interpolation as well as the explicit "flush()" operation on the interim BufferedImage instances to avoid resource leaking.