org.imgscalr
Class Scalr

java.lang.Object
  extended by 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
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
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
Scalr()
           
 
Method Summary
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.
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.
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.
 
Methods inherited from class java.lang.Object
equals, 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

Copyright 2011 The Buzz Media, LLC