org.imgscalr

Class Scalr

java.lang.Object

org.imgscalr.Scalr

public class Scalr
extends Object

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 implements a few different methods for scaling an image, providing either the best-looking result, the fastest result or a balanced result between the two depending on the scaling hint provided (see Scalr.Method).

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 Scalr.Method.ULTRA_QUALITY method.

Only when scaling using the Scalr.Method.AUTOMATIC method will this class look at the size of the image before selecting an approach to scaling the image. If Scalr.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 Image.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 Image.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

All scaling operations implemented by this class maintain the proportions of the original image unless a mode of Scalr.Mode.FIT_EXACT is specified; in which case the orientation and proportion of the source image is ignored and the image is stretched (if necessary) to fit the exact dimensions given.

When not using Scalr.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 Scalr.Mode value of Scalr.Mode.FIT_TO_WIDTH or Scalr.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

Java2D provides support for a number of different image types defined as BufferedImage.TYPE_* variables, unfortunately not all image types are supported equally in the Java2D rendering pipeline.

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

depending on if the source image utilizes transparency or not. This is a recommended approach by the Java2D team for dealing with poorly (or non) supported image types. More can be read about this issue here.

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

Unfortunately in Java 6 and earlier, support for GIF's IndexColorModel is sub-par, both in accurate color-selection and in maintaining transparency when moving to an image of type BufferedImage.TYPE_INT_ARGB; because of this issue when a GIF image is processed by imgscalr and the result saved as a GIF file (instead of PNG), it is possible to lose the alpha channel of a transparent image or in the case of applying an optional BufferedImageOp, lose the entire picture all together in the result (long standing JDK bugs are filed for all of these issues).

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

The Scalr class is thread-safe (as all the methods are static); this class maintains no internal state while performing any of the provided operations and is safe to call simultaneously from multiple threads.

Logging

This class implements all its debug logging via the log(int, String, Object...) method. At this time logging is done directly to System.out via the printf method. This allows the logging to be light weight and easy to capture (every imgscalr log message is prefixed with the LOG_PREFIX string) while adding no dependencies to the library.

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.

Since:

1.1

Author:

Riyad Kalla (software@thebuzzmedia.com)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Scalr.Method Used to define the different scaling hints that the algorithm can use.
static class	Scalr.Mode Used to define the different modes of resizing that the algorithm can use.
static class	Scalr.Rotation Used to define the different types of rotations that can be applied to an image during a resize operation.

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	DEBUG Flag used to indicate if debugging output has been enabled by setting the "imgscalr.debug" system property to true.
static String	DEBUG_PROPERTY_NAME System property name used to define the debug boolean flag.
static String	LOG_PREFIX Prefix to every log message this library logs.
static String	LOG_PREFIX_PROPERTY_NAME System property name used to define a custom log prefix.
static ConvolveOp	OP_ANTIALIAS 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.
static RescaleOp	OP_BRIGHTER A RescaleOp used to make any input image 10% brighter.
static RescaleOp	OP_DARKER A RescaleOp used to make any input image 10% darker.
static ColorConvertOp	OP_GRAYSCALE A ColorConvertOp used to convert any image to a grayscale color palette.
static int	THRESHOLD_BALANCED_SPEED Threshold (in pixels) at which point the scaling operation using the Scalr.Method.AUTOMATIC method will decide if a Scalr.Method.BALANCED method will be used (if smaller than or equal to threshold) or a Scalr.Method.SPEED method will be used (if larger than threshold).
static int	THRESHOLD_QUALITY_BALANCED Threshold (in pixels) at which point the scaling operation using the Scalr.Method.AUTOMATIC method will decide if a Scalr.Method.QUALITY method will be used (if smaller than or equal to threshold) or a Scalr.Method.BALANCED method will be used (if larger than threshold).

Constructor Summary

Constructors

Constructor and Description
Scalr()

Method Summary

Methods

Modifier and Type	Method and Description
static BufferedImage	apply(BufferedImage src, BufferedImageOp... ops) Used to apply, in the order given, 1 or more BufferedImageOps to a given BufferedImage and return the result.
protected static BufferedImage	copyToOptimalImage(BufferedImage src) Used to copy a BufferedImage from a non-optimal type into a new BufferedImage instance of an optimal type (RGB or ARGB).
protected static BufferedImage	createOptimalImage(BufferedImage src) 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.
protected static BufferedImage	createOptimalImage(BufferedImage src, int width, int height) 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.
static BufferedImage	crop(BufferedImage src, int width, int height, BufferedImageOp... ops) Used to crop the given src image from the top-left corner and applying any optional BufferedImageOps to the result before returning it.
static BufferedImage	crop(BufferedImage src, int x, int y, int width, int height, BufferedImageOp... ops) Used to crop the given src image and apply any optional BufferedImageOps to it before returning the result.
protected static Scalr.Method	determineScalingMethod(int targetWidth, int targetHeight, float ratio) Used to determine the scaling Scalr.Method that is best suited for scaling the image to the targeted dimensions.
protected static void	log(int depth, String message, Object... params) Used to write out a useful and well-formatted log message by any piece of code inside of the imgscalr library.
static BufferedImage	pad(BufferedImage src, int padding, BufferedImageOp... ops) Used to apply padding around the edges of an image using Color.BLACK to fill the extra padded space and then return the result.
static BufferedImage	pad(BufferedImage src, int padding, Color color, BufferedImageOp... ops) 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.
static BufferedImage	resize(BufferedImage src, int targetSize, BufferedImageOp... ops) 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.
static BufferedImage	resize(BufferedImage src, int targetWidth, int targetHeight, BufferedImageOp... ops) 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.
static BufferedImage	resize(BufferedImage src, Scalr.Method scalingMethod, int targetSize, BufferedImageOp... ops) 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.
static BufferedImage	resize(BufferedImage src, Scalr.Method scalingMethod, int targetWidth, int targetHeight, BufferedImageOp... ops) 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.
static BufferedImage	resize(BufferedImage src, Scalr.Method scalingMethod, Scalr.Mode resizeMode, int targetSize, BufferedImageOp... ops) 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 Scalr.Mode specified) using the given scaling method and apply the given BufferedImageOps (if any) to the result before returning it.
static BufferedImage	resize(BufferedImage src, Scalr.Method scalingMethod, Scalr.Mode resizeMode, int targetWidth, int targetHeight, BufferedImageOp... ops) 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 Scalr.Mode specified) using the given scaling method and apply the given BufferedImageOps (if any) to the result before returning it.
static BufferedImage	resize(BufferedImage src, Scalr.Mode resizeMode, int targetSize, BufferedImageOp... ops) 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 Scalr.Mode specified) and apply the given BufferedImageOps (if any) to the result before returning it.
static BufferedImage	resize(BufferedImage src, Scalr.Mode resizeMode, int targetWidth, int targetHeight, BufferedImageOp... ops) 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 Scalr.Mode specified) and apply the given BufferedImageOps (if any) to the result before returning it.
static BufferedImage	rotate(BufferedImage src, Scalr.Rotation rotation, BufferedImageOp... ops) Used to apply a Scalr.Rotation and then 0 or more BufferedImageOps to a given image and return the result.
protected static BufferedImage	scaleImage(BufferedImage src, int targetWidth, int targetHeight, Object interpolationHintValue) Used to implement a straight-forward image-scaling operation using Java 2D.
protected static BufferedImage	scaleImageIncrementally(BufferedImage src, int targetWidth, int targetHeight, Scalr.Method scalingMethod, Object interpolationHintValue) Used to implement Chris Campbell's incremental-scaling algorithm: http://today.java.net/pub/a/today/2007/04/03/perils -of-image-getscaledinstance.html.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEBUG_PROPERTY_NAME

public static final String DEBUG_PROPERTY_NAME

System property name used to define the debug boolean flag.

Value is "imgscalr.debug".

See Also:

Constant Field Values

LOG_PREFIX_PROPERTY_NAME

public static final String LOG_PREFIX_PROPERTY_NAME

System property name used to define a custom log prefix.

Value is "imgscalr.logPrefix".

See Also:

Constant Field Values

DEBUG

public static final boolean DEBUG

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.

LOG_PREFIX

public static final String LOG_PREFIX

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

OP_ANTIALIAS

public static final ConvolveOp OP_ANTIALIAS

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:

.0f	.08f	.0f
.08f	.68f	.08f
.0f	.08f	.0f

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

Use of this (and other) ConvolveOps are hardware accelerated when possible. 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.

Known Issues

In all versions of Java (tested up to Java 7 preview Build 131), running this op against a GIF with transparency and attempting to save the resulting image as a GIF results in a corrupted/empty file. The file must be saved out as a PNG to maintain the transparency.

Since:

3.0

OP_DARKER

public static final RescaleOp OP_DARKER

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.

Since:

4.0

OP_BRIGHTER

public static final RescaleOp OP_BRIGHTER

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.

Since:

4.0

OP_GRAYSCALE

public static final ColorConvertOp OP_GRAYSCALE

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.

Since:

4.0

THRESHOLD_BALANCED_SPEED

public static final int THRESHOLD_BALANCED_SPEED

Threshold (in pixels) at which point the scaling operation using the Scalr.Method.AUTOMATIC method will decide if a Scalr.Method.BALANCED method will be used (if smaller than or equal to threshold) or a Scalr.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 Scalr.Method.BALANCED scale method to look decent in most all cases while using the faster Scalr.Method.SPEED method for images bigger than this threshold showed no noticeable degradation over a BALANCED scale.

See Also:

Constant Field Values

THRESHOLD_QUALITY_BALANCED

public static final int THRESHOLD_QUALITY_BALANCED

Threshold (in pixels) at which point the scaling operation using the Scalr.Method.AUTOMATIC method will decide if a Scalr.Method.QUALITY method will be used (if smaller than or equal to threshold) or a Scalr.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 Scalr.Method.QUALITY scale method to look decent in most all cases while using the faster Scalr.Method.BALANCED method for images bigger than this threshold showed no noticeable degradation over a QUALITY scale.

See Also:

Constant Field Values

Constructor Detail

Scalr

public Scalr()

Method Detail

apply

public static BufferedImage apply(BufferedImage src,
                  BufferedImageOp... ops)
                           throws IllegalArgumentException,
                                  ImagingOpException

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 Image.flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Parameters:

src - The image that will have the ops applied to it.

ops - 1 or more ops to apply to the image.

Returns:

a new BufferedImage that represents the src with all the given operations applied to it.

Throws:

IllegalArgumentException - if src is null.

IllegalArgumentException - if ops is null or empty.

ImagingOpException - if one of the given BufferedImageOps fails to apply. These exceptions bubble up from the inside of most of the BufferedImageOp implementations and are explicitly defined on the imgscalr API to make it easier for callers to catch the exception (if they are passing along optional ops to be applied). imgscalr takes detailed steps to avoid the most common pitfalls that will cause BufferedImageOps to fail, even when using straight forward JDK-image operations.

crop

public static BufferedImage crop(BufferedImage src,
                 int width,
                 int height,
                 BufferedImageOp... ops)
                          throws IllegalArgumentException,
                                 ImagingOpException

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 Image.flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Parameters:

src - The image to crop.

width - The width of the bounding cropping box.

height - The height of the bounding cropping box.

ops - 0 or more ops to apply to the image. If null or empty then src is return unmodified.

Returns:

a new BufferedImage representing the cropped region of the src image with any optional operations applied to it.

Throws:

IllegalArgumentException - if src is null.

IllegalArgumentException - if any coordinates of the bounding crop box is invalid within the bounds of the src image (e.g. negative or too big).

ImagingOpException - if one of the given BufferedImageOps fails to apply. These exceptions bubble up from the inside of most of the BufferedImageOp implementations and are explicitly defined on the imgscalr API to make it easier for callers to catch the exception (if they are passing along optional ops to be applied). imgscalr takes detailed steps to avoid the most common pitfalls that will cause BufferedImageOps to fail, even when using straight forward JDK-image operations.

crop

public static BufferedImage crop(BufferedImage src,
                 int x,
                 int y,
                 int width,
                 int height,
                 BufferedImageOp... ops)
                          throws IllegalArgumentException,
                                 ImagingOpException

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 Image.flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Parameters:

src - The image to crop.

x - The x-coordinate of the top-left corner of the bounding box used for cropping.

y - The y-coordinate of the top-left corner of the bounding box used for cropping.

width - The width of the bounding cropping box.

height - The height of the bounding cropping box.

ops - 0 or more ops to apply to the image. If null or empty then src is return unmodified.

Returns:

a new BufferedImage representing the cropped region of the src image with any optional operations applied to it.

Throws:

IllegalArgumentException - if src is null.

IllegalArgumentException - if any coordinates of the bounding crop box is invalid within the bounds of the src image (e.g. negative or too big).

ImagingOpException - if one of the given BufferedImageOps fails to apply. These exceptions bubble up from the inside of most of the BufferedImageOp implementations and are explicitly defined on the imgscalr API to make it easier for callers to catch the exception (if they are passing along optional ops to be applied). imgscalr takes detailed steps to avoid the most common pitfalls that will cause BufferedImageOps to fail, even when using straight forward JDK-image operations.

pad

public static BufferedImage pad(BufferedImage src,
                int padding,
                BufferedImageOp... ops)
                         throws IllegalArgumentException,
                                ImagingOpException

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 Image.flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Parameters:

src - The image the padding will be added to.

padding - The number of pixels of padding to add to each side in the resulting image. If this value is 0 then src is returned unmodified.

ops - 0 or more ops to apply to the image. If null or empty then src is return unmodified.

Returns:

a new BufferedImage representing src with the given padding applied to it.

Throws:

IllegalArgumentException - if src is null.

IllegalArgumentException - if padding is < 1.

ImagingOpException - if one of the given BufferedImageOps fails to apply. These exceptions bubble up from the inside of most of the BufferedImageOp implementations and are explicitly defined on the imgscalr API to make it easier for callers to catch the exception (if they are passing along optional ops to be applied). imgscalr takes detailed steps to avoid the most common pitfalls that will cause BufferedImageOps to fail, even when using straight forward JDK-image operations.

pad

public static BufferedImage pad(BufferedImage src,
                int padding,
                Color color,
                BufferedImageOp... ops)
                         throws IllegalArgumentException,
                                ImagingOpException

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 Image.flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Parameters:

src - The image the padding will be added to.

padding - The number of pixels of padding to add to each side in the resulting image. If this value is 0 then src is returned unmodified.

color - The color to fill the padded space with. Colors using an alpha channel (i.e. transparency) are supported.

ops - 0 or more ops to apply to the image. If null or empty then src is return unmodified.

Returns:

a new BufferedImage representing src with the given padding applied to it.

Throws:

IllegalArgumentException - if src is null.

IllegalArgumentException - if padding is < 1.

IllegalArgumentException - if color is null.

ImagingOpException - if one of the given BufferedImageOps fails to apply. These exceptions bubble up from the inside of most of the BufferedImageOp implementations and are explicitly defined on the imgscalr API to make it easier for callers to catch the exception (if they are passing along optional ops to be applied). imgscalr takes detailed steps to avoid the most common pitfalls that will cause BufferedImageOps to fail, even when using straight forward JDK-image operations.

resize

public static BufferedImage resize(BufferedImage src,
                   int targetSize,
                   BufferedImageOp... ops)
                            throws IllegalArgumentException,
                                   ImagingOpException

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 Scalr.Method.AUTOMATIC and mode of Scalr.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 Image.flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Parameters:

src - The image that will be scaled.

targetSize - The target width and height (square) that you wish the image to fit within.

ops - 0 or more optional image operations (e.g. sharpen, blur, etc.) that can be applied to the final result before returning the image.

Returns:

a new BufferedImage representing the scaled src image.

Throws:

IllegalArgumentException - if src is null.

IllegalArgumentException - if targetSize is < 0.

ImagingOpException - if one of the given BufferedImageOps fails to apply. These exceptions bubble up from the inside of most of the BufferedImageOp implementations and are explicitly defined on the imgscalr API to make it easier for callers to catch the exception (if they are passing along optional ops to be applied). imgscalr takes detailed steps to avoid the most common pitfalls that will cause BufferedImageOps to fail, even when using straight forward JDK-image operations.

resize

public static BufferedImage resize(BufferedImage src,
                   Scalr.Method scalingMethod,
                   int targetSize,
                   BufferedImageOp... ops)
                            throws IllegalArgumentException,
                                   ImagingOpException

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 Scalr.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 Image.flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Parameters:

src - The image that will be scaled.

scalingMethod - The method used for scaling the image; preferring speed to quality or a balance of both.

targetSize - The target width and height (square) that you wish the image to fit within.

ops - 0 or more optional image operations (e.g. sharpen, blur, etc.) that can be applied to the final result before returning the image.

Returns:

a new BufferedImage representing the scaled src image.

Throws:

IllegalArgumentException - if src is null.

IllegalArgumentException - if scalingMethod is null.

IllegalArgumentException - if targetSize is < 0.

ImagingOpException - if one of the given BufferedImageOps fails to apply. These exceptions bubble up from the inside of most of the BufferedImageOp implementations and are explicitly defined on the imgscalr API to make it easier for callers to catch the exception (if they are passing along optional ops to be applied). imgscalr takes detailed steps to avoid the most common pitfalls that will cause BufferedImageOps to fail, even when using straight forward JDK-image operations.

See Also:

Scalr.Method

resize

public static BufferedImage resize(BufferedImage src,
                   Scalr.Mode resizeMode,
                   int targetSize,
                   BufferedImageOp... ops)
                            throws IllegalArgumentException,
                                   ImagingOpException

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 Scalr.Mode specified) and apply the given BufferedImageOps (if any) to the result before returning it.

A scaling method of Scalr.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 Image.flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Parameters:

src - The image that will be scaled.

resizeMode - Used to indicate how imgscalr should calculate the final target size for the image, either fitting the image to the given width (Scalr.Mode.FIT_TO_WIDTH) or fitting the image to the given height (Scalr.Mode.FIT_TO_HEIGHT). If Scalr.Mode.AUTOMATIC is passed in, imgscalr will calculate proportional dimensions for the scaled image based on its orientation (landscape, square or portrait). Unless you have very specific size requirements, most of the time you just want to use Scalr.Mode.AUTOMATIC to "do the right thing".

targetSize - The target width and height (square) that you wish the image to fit within.

ops - 0 or more optional image operations (e.g. sharpen, blur, etc.) that can be applied to the final result before returning the image.

Returns:

a new BufferedImage representing the scaled src image.

Throws:

IllegalArgumentException - if src is null.

IllegalArgumentException - if resizeMode is null.

IllegalArgumentException - if targetSize is < 0.

ImagingOpException - if one of the given BufferedImageOps fails to apply. These exceptions bubble up from the inside of most of the BufferedImageOp implementations and are explicitly defined on the imgscalr API to make it easier for callers to catch the exception (if they are passing along optional ops to be applied). imgscalr takes detailed steps to avoid the most common pitfalls that will cause BufferedImageOps to fail, even when using straight forward JDK-image operations.

See Also:

Scalr.Mode

resize

public static BufferedImage resize(BufferedImage src,
                   Scalr.Method scalingMethod,
                   Scalr.Mode resizeMode,
                   int targetSize,
                   BufferedImageOp... ops)
                            throws IllegalArgumentException,
                                   ImagingOpException

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 Scalr.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 Image.flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Parameters:

src - The image that will be scaled.

scalingMethod - The method used for scaling the image; preferring speed to quality or a balance of both.

resizeMode - Used to indicate how imgscalr should calculate the final target size for the image, either fitting the image to the given width (Scalr.Mode.FIT_TO_WIDTH) or fitting the image to the given height (Scalr.Mode.FIT_TO_HEIGHT). If Scalr.Mode.AUTOMATIC is passed in, imgscalr will calculate proportional dimensions for the scaled image based on its orientation (landscape, square or portrait). Unless you have very specific size requirements, most of the time you just want to use Scalr.Mode.AUTOMATIC to "do the right thing".

targetSize - The target width and height (square) that you wish the image to fit within.

ops - 0 or more optional image operations (e.g. sharpen, blur, etc.) that can be applied to the final result before returning the image.

Returns:

a new BufferedImage representing the scaled src image.

Throws:

IllegalArgumentException - if src is null.

IllegalArgumentException - if scalingMethod is null.

IllegalArgumentException - if resizeMode is null.

IllegalArgumentException - if targetSize is < 0.

ImagingOpException - if one of the given BufferedImageOps fails to apply. These exceptions bubble up from the inside of most of the BufferedImageOp implementations and are explicitly defined on the imgscalr API to make it easier for callers to catch the exception (if they are passing along optional ops to be applied). imgscalr takes detailed steps to avoid the most common pitfalls that will cause BufferedImageOps to fail, even when using straight forward JDK-image operations.

See Also:

Scalr.Method, Scalr.Mode

resize

public static BufferedImage resize(BufferedImage src,
                   int targetWidth,
                   int targetHeight,
                   BufferedImageOp... ops)
                            throws IllegalArgumentException,
                                   ImagingOpException

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 Scalr.Method.AUTOMATIC and mode of Scalr.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 Image.flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Parameters:

src - The image that will be scaled.

targetWidth - The target width that you wish the image to have.

targetHeight - The target height that you wish the image to have.

ops - 0 or more optional image operations (e.g. sharpen, blur, etc.) that can be applied to the final result before returning the image.

Returns:

a new BufferedImage representing the scaled src image.

Throws:

IllegalArgumentException - if src is null.

IllegalArgumentException - if targetWidth is < 0 or if targetHeight is < 0.

ImagingOpException - if one of the given BufferedImageOps fails to apply. These exceptions bubble up from the inside of most of the BufferedImageOp implementations and are explicitly defined on the imgscalr API to make it easier for callers to catch the exception (if they are passing along optional ops to be applied). imgscalr takes detailed steps to avoid the most common pitfalls that will cause BufferedImageOps to fail, even when using straight forward JDK-image operations.

resize

public static BufferedImage resize(BufferedImage src,
                   Scalr.Method scalingMethod,
                   int targetWidth,
                   int targetHeight,
                   BufferedImageOp... ops)

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 Scalr.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 Image.flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Parameters:

src - The image that will be scaled.

scalingMethod - The method used for scaling the image; preferring speed to quality or a balance of both.

targetWidth - The target width that you wish the image to have.

targetHeight - The target height that you wish the image to have.

ops - 0 or more optional image operations (e.g. sharpen, blur, etc.) that can be applied to the final result before returning the image.

Returns:

a new BufferedImage representing the scaled src image.

Throws:

IllegalArgumentException - if src is null.

IllegalArgumentException - if scalingMethod is null.

IllegalArgumentException - if targetWidth is < 0 or if targetHeight is < 0.

ImagingOpException - if one of the given BufferedImageOps fails to apply. These exceptions bubble up from the inside of most of the BufferedImageOp implementations and are explicitly defined on the imgscalr API to make it easier for callers to catch the exception (if they are passing along optional ops to be applied). imgscalr takes detailed steps to avoid the most common pitfalls that will cause BufferedImageOps to fail, even when using straight forward JDK-image operations.

See Also:

Scalr.Method

resize

public static BufferedImage resize(BufferedImage src,
                   Scalr.Mode resizeMode,
                   int targetWidth,
                   int targetHeight,
                   BufferedImageOp... ops)
                            throws IllegalArgumentException,
                                   ImagingOpException

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 Scalr.Mode specified) and apply the given BufferedImageOps (if any) to the result before returning it.

A scaling method of Scalr.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 Image.flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Parameters:

src - The image that will be scaled.

resizeMode - Used to indicate how imgscalr should calculate the final target size for the image, either fitting the image to the given width (Scalr.Mode.FIT_TO_WIDTH) or fitting the image to the given height (Scalr.Mode.FIT_TO_HEIGHT). If Scalr.Mode.AUTOMATIC is passed in, imgscalr will calculate proportional dimensions for the scaled image based on its orientation (landscape, square or portrait). Unless you have very specific size requirements, most of the time you just want to use Scalr.Mode.AUTOMATIC to "do the right thing".

targetWidth - The target width that you wish the image to have.

targetHeight - The target height that you wish the image to have.

ops - 0 or more optional image operations (e.g. sharpen, blur, etc.) that can be applied to the final result before returning the image.

Returns:

a new BufferedImage representing the scaled src image.

Throws:

IllegalArgumentException - if src is null.

IllegalArgumentException - if resizeMode is null.

IllegalArgumentException - if targetWidth is < 0 or if targetHeight is < 0.

ImagingOpException - if one of the given BufferedImageOps fails to apply. These exceptions bubble up from the inside of most of the BufferedImageOp implementations and are explicitly defined on the imgscalr API to make it easier for callers to catch the exception (if they are passing along optional ops to be applied). imgscalr takes detailed steps to avoid the most common pitfalls that will cause BufferedImageOps to fail, even when using straight forward JDK-image operations.

See Also:

Scalr.Mode

resize

public static BufferedImage resize(BufferedImage src,
                   Scalr.Method scalingMethod,
                   Scalr.Mode resizeMode,
                   int targetWidth,
                   int targetHeight,
                   BufferedImageOp... ops)
                            throws IllegalArgumentException,
                                   ImagingOpException

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 Scalr.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 Image.flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Parameters:

src - The image that will be scaled.

scalingMethod - The method used for scaling the image; preferring speed to quality or a balance of both.

resizeMode - Used to indicate how imgscalr should calculate the final target size for the image, either fitting the image to the given width (Scalr.Mode.FIT_TO_WIDTH) or fitting the image to the given height (Scalr.Mode.FIT_TO_HEIGHT). If Scalr.Mode.AUTOMATIC is passed in, imgscalr will calculate proportional dimensions for the scaled image based on its orientation (landscape, square or portrait). Unless you have very specific size requirements, most of the time you just want to use Scalr.Mode.AUTOMATIC to "do the right thing".

targetWidth - The target width that you wish the image to have.

targetHeight - The target height that you wish the image to have.

ops - 0 or more optional image operations (e.g. sharpen, blur, etc.) that can be applied to the final result before returning the image.

Returns:

a new BufferedImage representing the scaled src image.

Throws:

IllegalArgumentException - if src is null.

IllegalArgumentException - if scalingMethod is null.

IllegalArgumentException - if resizeMode is null.

IllegalArgumentException - if targetWidth is < 0 or if targetHeight is < 0.

ImagingOpException - if one of the given BufferedImageOps fails to apply. These exceptions bubble up from the inside of most of the BufferedImageOp implementations and are explicitly defined on the imgscalr API to make it easier for callers to catch the exception (if they are passing along optional ops to be applied). imgscalr takes detailed steps to avoid the most common pitfalls that will cause BufferedImageOps to fail, even when using straight forward JDK-image operations.

See Also:

Scalr.Method, Scalr.Mode

rotate

public static BufferedImage rotate(BufferedImage src,
                   Scalr.Rotation rotation,
                   BufferedImageOp... ops)
                            throws IllegalArgumentException,
                                   ImagingOpException

Used to apply a Scalr.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 Image.flush() on the src to free up native resources and make it easier for the GC to collect the unused image.

Parameters:

src - The image that will have the rotation applied to it.

rotation - The rotation that will be applied to the image.

ops - Zero or more optional image operations (e.g. sharpen, blur, etc.) that can be applied to the final result before returning the image.

Returns:

a new BufferedImage representing src rotated by the given amount and any optional ops applied to it.

Throws:

IllegalArgumentException - if src is null.

IllegalArgumentException - if rotation is null.

ImagingOpException - if one of the given BufferedImageOps fails to apply. These exceptions bubble up from the inside of most of the BufferedImageOp implementations and are explicitly defined on the imgscalr API to make it easier for callers to catch the exception (if they are passing along optional ops to be applied). imgscalr takes detailed steps to avoid the most common pitfalls that will cause BufferedImageOps to fail, even when using straight forward JDK-image operations.

See Also:

Scalr.Rotation

log

protected static void log(int depth,
       String message,
       Object... params)

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 DEBUG is true; otherwise the VM will be spending time performing unnecessary auto-boxing calculations.

Parameters:

depth - The indentation level of the log message.

message - The log message in format string syntax that will be logged.

params - The parameters that will be swapped into all the place holders in the original messages before being logged.

See Also:

LOG_PREFIX, LOG_PREFIX_PROPERTY_NAME

createOptimalImage

protected static BufferedImage createOptimalImage(BufferedImage src)

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.

Parameters:

src - The source image that will be analyzed to determine the most optimal image type it can be rendered into.

Returns:

a new BufferedImage representing the most optimal target image type that src can be rendered into.

See Also:

How Java2D handles poorly supported image types, Thanks to Morten Nobel for implementation hint

createOptimalImage

protected static BufferedImage createOptimalImage(BufferedImage src,
                               int width,
                               int height)
                                           throws IllegalArgumentException

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.

Parameters:

src - The source image that will be analyzed to determine the most optimal image type it can be rendered into.

width - The width of the newly created resulting image.

height - The height of the newly created resulting image.

Returns:

a new BufferedImage representing the most optimal target image type that src can be rendered into.

Throws:

IllegalArgumentException - if width or height are < 0.

See Also:

How Java2D handles poorly supported image types, Thanks to Morten Nobel for implementation hint

copyToOptimalImage

protected static BufferedImage copyToOptimalImage(BufferedImage src)
                                           throws IllegalArgumentException

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.

Parameters:

src - The image to copy (if necessary) into an optimally typed BufferedImage.

Returns:

a representation of the src image in an optimally typed BufferedImage, otherwise src if it was already of an optimal type.

Throws:

IllegalArgumentException - if src is null.

determineScalingMethod

protected static Scalr.Method determineScalingMethod(int targetWidth,
                                  int targetHeight,
                                  float ratio)

Used to determine the scaling Scalr.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 Scalr.Method when a Scalr.Method.AUTOMATIC method is specified. This method utilizes the THRESHOLD_QUALITY_BALANCED and 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.

Parameters:

targetWidth - The target width for the scaled image.

targetHeight - The target height for the scaled image.

ratio - A height/width ratio used to determine the orientation of the image so the primary dimension (width or height) can be selected to test if it is greater than or less than a particular threshold.

Returns:

the fastest Scalr.Method suited for scaling the image to the specified dimensions while maintaining a good-looking result.

scaleImage

protected static BufferedImage scaleImage(BufferedImage src,
                       int targetWidth,
                       int targetHeight,
                       Object interpolationHintValue)

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.

Parameters:

src - The image that will be scaled.

targetWidth - The target width for the scaled image.

targetHeight - The target height for the scaled image.

interpolationHintValue - The RenderingHints interpolation value used to indicate the method that Graphics2D should use when scaling the image.

Returns:

the result of scaling the original src to the given dimensions using the given interpolation method.

scaleImageIncrementally

protected static BufferedImage scaleImageIncrementally(BufferedImage src,
                                    int targetWidth,
                                    int targetHeight,
                                    Scalr.Method scalingMethod,
                                    Object interpolationHintValue)

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.

Parameters:

src - The image that will be scaled.

targetWidth - The target width for the scaled image.

targetHeight - The target height for the scaled image.

scalingMethod - The scaling method specified by the user (or calculated by imgscalr) to use for this incremental scaling operation.

interpolationHintValue - The RenderingHints interpolation value used to indicate the method that Graphics2D should use when scaling the image.

Returns:

an image scaled to the given dimensions using the given rendering hint.