net.coobird.thumbnailator
Class Thumbnails.Builder<T>

java.lang.Object
  net.coobird.thumbnailator.Thumbnails.Builder<T>

Enclosing class:

Thumbnails

public static class Thumbnails.Builder<T>
extends Object

A builder interface for Thumbnailator.

An instance of this class is obtained by calling one of:

• Thumbnails.of(BufferedImage...)
• Thumbnails.of(File...)
• Thumbnails.of(String...)
• Thumbnails.of(InputStream...)
• Thumbnails.of(URL...)
• Thumbnails.fromImages(Iterable)
• Thumbnails.fromFiles(Iterable)
• Thumbnails.fromFilenames(Iterable)
• Thumbnails.fromInputStreams(Iterable)
• Thumbnails.fromURLs(Iterable)

Author:

coobird

Method Summary

Thumbnails.Builder<T>	addFilter(ImageFilter filter) Adds a ImageFilter to apply to the thumbnail.
Thumbnails.Builder<T>	addFilters(List<ImageFilter> filters) Adds multiple ImageFilters to apply to the thumbnail.
Thumbnails.Builder<T>	alphaInterpolation(AlphaInterpolation config) Sets the alpha interpolation mode when performing the resizing operation to generate the thumbnail.
Thumbnails.Builder<T>	antialiasing(Antialiasing config) Sets the antialiasing mode when performing the resizing operation to generate the thumbnail.
BufferedImage	asBufferedImage() Creates a thumbnail and returns it as a BufferedImage.
List<BufferedImage>	asBufferedImages() Create the thumbnails and return as a List of BufferedImages.
List<File>	asFiles(Iterable<File> iterable) Creates the thumbnails and stores them to the files, and returns a List of Files to the thumbnails.
List<File>	asFiles(Rename rename) Creates the thumbnails and stores them to the files, using the Rename function to determine the filenames.
Thumbnails.Builder<T>	dithering(Dithering config) Sets the dithering mode when performing the resizing operation to generate the thumbnail.
Thumbnails.Builder<T>	forceSize(int width, int height) Sets the size of the thumbnail.
Thumbnails.Builder<T>	imageType(int type) Sets the image type of the thumbnail.
Iterable<BufferedImage>	iterableBufferedImages() Create the thumbnails and return as a Iterable of BufferedImages.
Thumbnails.Builder<T>	keepAspectRatio(boolean keep) Sets whether or not to keep the aspect ratio of the original image for the thumbnail.
Thumbnails.Builder<T>	outputFormat(String format) Sets the compression format to use when writing the thumbnail.
Thumbnails.Builder<T>	outputFormatType(String formatType) Sets the compression format type of the thumbnail to write.
Thumbnails.Builder<T>	outputQuality(double quality) Sets the compression output quality of the thumbnail.
Thumbnails.Builder<T>	outputQuality(float quality) Sets the compression output quality of the thumbnail.
Thumbnails.Builder<T>	rendering(Rendering config) Sets the rendering mode when performing the resizing operation to generate the thumbnail.
Thumbnails.Builder<T>	resizer(Resizer resizer) Sets the resizing operation to use when creating the thumbnail.
Thumbnails.Builder<T>	rotate(double angle) Sets the amount of rotation to apply to the thumbnail.
Thumbnails.Builder<T>	scale(double scale) Sets the scaling factor of the thumbnail.
Thumbnails.Builder<T>	scalingMode(ScalingMode config) Sets the resizing scaling mode to use when creating the thumbnail.
Thumbnails.Builder<T>	size(int width, int height) Sets the size of the thumbnail.
Thumbnails.Builder<T>	sourceRegion(int x, int y, int width, int height) Specifies the source region from which the thumbnail is to be created from.
Thumbnails.Builder<T>	sourceRegion(Position position, int width, int height) Specifies the source region from which the thumbnail is to be created from.
Thumbnails.Builder<T>	sourceRegion(Position position, Size size) Specifies the source region from which the thumbnail is to be created from.
Thumbnails.Builder<T>	sourceRegion(Rectangle region) Specifies the source region from which the thumbnail is to be created from.
Thumbnails.Builder<T>	sourceRegion(Region sourceRegion) Specifies the source region from which the thumbnail is to be created from.
void	toFile(File outFile) Create a thumbnail and writes it to a File.
void	toFile(String outFilepath) Create a thumbnail and writes it to a File.
void	toFiles(Iterable<File> iterable) Creates the thumbnails and stores them to the files.
void	toFiles(Rename rename) Creates the thumbnails and stores them to the files, using the Rename function to determine the filenames.
void	toOutputStream(OutputStream os) Create a thumbnail and writes it to a OutputStream.
void	toOutputStreams(Iterable<? extends OutputStream> iterable) Creates the thumbnails and writes them to OutputStreams provided by the Iterable.
Thumbnails.Builder<T>	watermark(BufferedImage image) Sets the image of the watermark to apply on the thumbnail.
Thumbnails.Builder<T>	watermark(BufferedImage image, float opacity) Sets the image and opacity of the watermark to apply on the thumbnail.
Thumbnails.Builder<T>	watermark(Position position, BufferedImage image, float opacity) Sets the image and opacity and position of the watermark to apply on the thumbnail.
Thumbnails.Builder<T>	watermark(Watermark w) Sets the watermark to apply on the thumbnail.

Methods inherited from class java.lang.Object

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

Method Detail

size

public Thumbnails.Builder<T> size(int width,
                                  int height)

Sets the size of the thumbnail.

Once this method is called, calling the scale(double) method will result in an IllegalStateException.

Calling this method multiple times will result in an IllegalStateException to be thrown.

Parameters:

width - The width of the thumbnail.

height - The height of the thumbnail.

Returns:

Reference to this object.

forceSize

public Thumbnails.Builder<T> forceSize(int width,
                                       int height)

Sets the size of the thumbnail.

The thumbnails will be forced to the specified size, therefore, the aspect ratio of the original image will not be preserved in the thumbnails. Calling this method will be equivalent to calling the size(int, int) method in conjunction with the keepAspectRatio(boolean) method with the value false.

Once this method is called, calling the scale(double) method will result in an IllegalStateException.

Calling this method multiple times will result in an IllegalStateException to be thrown.

Parameters:

width - The width of the thumbnail.

height - The height of the thumbnail.

Returns:

Reference to this object.

scale

public Thumbnails.Builder<T> scale(double scale)

Sets the scaling factor of the thumbnail.

Once this method is called, caling the size(int, int) method and the keepAspectRatio(boolean) will result in an IllegalStateException.

Calling this method multiple times will result in an IllegalStateException to be thrown.

Parameters:

scale - The scaling factor to use when creating a thumbnail.

The value must be a double which is greater than 0.0.

Returns:

Reference to this object.

sourceRegion

public Thumbnails.Builder<T> sourceRegion(Region sourceRegion)

Specifies the source region from which the thumbnail is to be created from.

Calling this method multiple times will result in an IllegalStateException to be thrown.

Parameters:

sourceRegion - Source region to use when creating a thumbnail.

Returns:

Reference to this object.

Throws:

NullPointerException - If the source region object is null.

sourceRegion

public Thumbnails.Builder<T> sourceRegion(Position position,
                                          Size size)

Specifies the source region from which the thumbnail is to be created from.

Calling this method multiple times will result in an IllegalStateException to be thrown.

Parameters:

position - Position of the source region.

size - Size of the source region.

Returns:

Reference to this object.

Throws:

NullPointerException - If the position and/or size is null.

sourceRegion

public Thumbnails.Builder<T> sourceRegion(int x,
                                          int y,
                                          int width,
                                          int height)

Specifies the source region from which the thumbnail is to be created from.

Calling this method multiple times will result in an IllegalStateException to be thrown.

Parameters:

x - The horizontal-compoennt of the top left-hand corner of the source region.

y - The vertical-compoennt of the top left-hand corner of the source region.

width - Width of the source region.

height - Height of the source region.

Returns:

Reference to this object.

Throws:

IllegalArgumentException - If the width and/or height is less than or equal to 0.

sourceRegion

public Thumbnails.Builder<T> sourceRegion(Position position,
                                          int width,
                                          int height)

Specifies the source region from which the thumbnail is to be created from.

Calling this method multiple times will result in an IllegalStateException to be thrown.

Parameters:

position - Position of the source region.

width - Width of the source region.

height - Height of the source region.

Returns:

Reference to this object.

Throws:

NullPointerException - If the position and/or size is null.

IllegalArgumentException - If the width and/or height is less than or equal to 0.

sourceRegion

public Thumbnails.Builder<T> sourceRegion(Rectangle region)

Specifies the source region from which the thumbnail is to be created from.

Calling this method multiple times will result in an IllegalStateException to be thrown.

Parameters:

region - A rectangular region which specifies the source region to use when creating the thumbnail.

Throws:

NullPointerException - If the region is null.

imageType

public Thumbnails.Builder<T> imageType(int type)

Sets the image type of the thumbnail.

Calling this method to set this parameter is optional.

Calling this method multiple times will result in an IllegalStateException to be thrown.

Parameters:

type - The image type of the thumbnail.

Returns:

Reference to this object.

scalingMode

public Thumbnails.Builder<T> scalingMode(ScalingMode config)

Sets the resizing scaling mode to use when creating the thumbnail.

Calling this method to set this parameter is optional.

Calling this method multiple times will result in an IllegalStateException to be thrown.

Parameters:

config - The scaling mode to use.

Returns:

Reference to this object.

resizer

public Thumbnails.Builder<T> resizer(Resizer resizer)

Sets the resizing operation to use when creating the thumbnail.

Calling this method to set this parameter is optional.

Calling this method multiple times will result in an IllegalStateException to be thrown.

Parameters:

resizer - The scaling operation to use.

Returns:

Reference to this object.

alphaInterpolation

public Thumbnails.Builder<T> alphaInterpolation(AlphaInterpolation config)

Sets the alpha interpolation mode when performing the resizing operation to generate the thumbnail.

Calling this method to set this parameter is optional.

Calling this method multiple times will result in an IllegalStateException to be thrown.

Parameters:

config - The alpha interpolation mode.

Returns:

Reference to this object.

dithering

public Thumbnails.Builder<T> dithering(Dithering config)

Sets the dithering mode when performing the resizing operation to generate the thumbnail.

Calling this method to set this parameter is optional.

Calling this method multiple times will result in an IllegalStateException to be thrown.

Parameters:

config - The dithering mode.

Returns:

Reference to this object.

antialiasing

public Thumbnails.Builder<T> antialiasing(Antialiasing config)

Sets the antialiasing mode when performing the resizing operation to generate the thumbnail.

Calling this method to set this parameter is optional.

Calling this method multiple times will result in an IllegalStateException.

Parameters:

config - The antialiasing mode.

Returns:

Reference to this object.

rendering

public Thumbnails.Builder<T> rendering(Rendering config)

Sets the rendering mode when performing the resizing operation to generate the thumbnail.

Calling this method to set this parameter is optional.

Calling this method multiple times will result in an IllegalStateException to be thrown.

Parameters:

config - The rendering mode.

Returns:

Reference to this object.

keepAspectRatio

public Thumbnails.Builder<T> keepAspectRatio(boolean keep)

Sets whether or not to keep the aspect ratio of the original image for the thumbnail.

Calling this method without first calling the size(int, int) method will result in an IllegalStateException to be thrown.

If this method is not called when, by default the aspect ratio of the original image is preserved for the thumbnail.

Calling this method after calling the scale(double) method will result in a IllegalStateException.

Parameters:

keep - true if the thumbnail is to maintain the aspect ratio of the original image, false otherwise.

Returns:

Reference to this object.

Throws:

IllegalStateException - If the size(int, int) has not yet been called to specify the size of the thumbnail, or if the scale(double) method has been called.

outputQuality

public Thumbnails.Builder<T> outputQuality(float quality)

Sets the compression output quality of the thumbnail.

The value is a float between 0.0f and 1.0f where 0.0f indicates the minimum quality and 1.0f indicates the maximum quality settings should be used for by the compression codec.

Calling this method to set this parameter is optional.

Calling this method multiple times, or the outputQuality(double) in conjunction with this method will result in an IllegalStateException to be thrown.

Parameters:

quality - The quality of the

Returns:

Reference to this object.

Throws:

IllegalArgumentException - If the argument is less than 0.0f or is greater than 1.0f.

outputQuality

public Thumbnails.Builder<T> outputQuality(double quality)

Sets the compression output quality of the thumbnail.

The value is a double between 0.0d and 1.0d where 0.0d indicates the minimum quality and 1.0d indicates the maximum quality settings should be used for by the compression codec.

This method is a convenience method for outputQuality(float) where the double argument type is accepted instead of a float.

Calling this method to set this parameter is optional.

Calling this method multiple times, or the outputQuality(float) in conjunction with this method will result in an IllegalStateException to be thrown.

Parameters:

quality - The quality of the

Returns:

Reference to this object.

Throws:

IllegalArgumentException - If the argument is less than 0.0d or is greater than 1.0d.

outputFormat

public Thumbnails.Builder<T> outputFormat(String format)

Sets the compression format to use when writing the thumbnail.

Calling this method to set this parameter is optional.

Calling this method multiple times will result in an IllegalStateException to be thrown.

Parameters:

format - The compression format.

Returns:

Reference to this object.

Throws:

IllegalArgumentException - If an unsupported format is specified.

outputFormatType

public Thumbnails.Builder<T> outputFormatType(String formatType)

Sets the compression format type of the thumbnail to write.

If the default type for the compression codec should be used, a value of ThumbnailParameter.DEFAULT_FORMAT_TYPE should be used.

Calling this method to set this parameter is optional.

Calling this method multiple times will result in an IllegalStateException to be thrown.

Furthermore, if this method is called, then calling the outputFormat method is disabled, in order to prevent cases where the output format type does not exist in the format specified for the outputFormat method.

Parameters:

formatType - The compression format type

Returns:

Reference to this object.

Throws:

IllegalArgumentException - If an unsupported format type is specified for the current output format type. Or, if the output format has not been specified before this method was called.

watermark

public Thumbnails.Builder<T> watermark(Watermark w)

Sets the watermark to apply on the thumbnail.

This method can be called multiple times to apply multiple watermarks.

If multiple watermarks are to be applied, the watermarks will be applied in the order that this method is called.

Calling this method to set this parameter is optional.

Parameters:

w - The watermark to apply to the thumbnail.

Returns:

Reference to this object.

watermark

public Thumbnails.Builder<T> watermark(BufferedImage image)

Sets the image of the watermark to apply on the thumbnail.

This method is a convenience method for the watermark(Position, BufferedImage, float) method, where the opacity is 50%, and the position is set to center of the thumbnail:

watermark(Positions.CENTER, image, 0.5f);
 

This method can be called multiple times to apply multiple watermarks.

If multiple watermarks are to be applied, the watermarks will be applied in the order that this method is called.

Calling this method to set this parameter is optional.

Parameters:

image - The image of the watermark.

Returns:

Reference to this object.

watermark

public Thumbnails.Builder<T> watermark(BufferedImage image,
                                       float opacity)

Sets the image and opacity of the watermark to apply on the thumbnail.

This method is a convenience method for the watermark(Position, BufferedImage, float) method, where the opacity is 50%:

watermark(Positions.CENTER, image, opacity);
 

This method can be called multiple times to apply multiple watermarks.

If multiple watermarks are to be applied, the watermarks will be applied in the order that this method is called.

Calling this method to set this parameter is optional.

Parameters:

image - The image of the watermark.

opacity - The opacity of the watermark.

The value should be between 0.0f and 1.0f, where 0.0f is completely transparent, and 1.0f is completely opaque.

Returns:

Reference to this object.

watermark

public Thumbnails.Builder<T> watermark(Position position,
                                       BufferedImage image,
                                       float opacity)

Sets the image and opacity and position of the watermark to apply on the thumbnail.

This method can be called multiple times to apply multiple watermarks.

If multiple watermarks are to be applied, the watermarks will be applied in the order that this method is called.

Calling this method to set this parameter is optional.

Parameters:

position - The position of the watermark.

image - The image of the watermark.

opacity - The opacity of the watermark.

The value should be between 0.0f and 1.0f, where 0.0f is completely transparent, and 1.0f is completely opaque.

Returns:

Reference to this object.

rotate

public Thumbnails.Builder<T> rotate(double angle)

Sets the amount of rotation to apply to the thumbnail.

The thumbnail will be rotated clockwise by the angle specified.

This method can be called multiple times to apply multiple rotations.

If multiple rotations are to be applied, the rotations will be applied in the order that this method is called.

Calling this method to set this parameter is optional.

Parameters:

angle - Angle in degrees.

Returns:

Reference to this object.

addFilter

public Thumbnails.Builder<T> addFilter(ImageFilter filter)

Adds a ImageFilter to apply to the thumbnail.

This method can be called multiple times to apply multiple filters.

If multiple filters are to be applied, the filters will be applied in the order that this method is called.

Calling this method to set this parameter is optional.

Parameters:

filter - An image filter to apply to the thumbnail.

Returns:

Reference to this object.

addFilters

public Thumbnails.Builder<T> addFilters(List<ImageFilter> filters)

Adds multiple ImageFilters to apply to the thumbnail.

This method can be called multiple times to apply multiple filters.

If multiple filters are to be applied, the filters will be applied in the order that this method is called.

Calling this method to set this parameter is optional.

Parameters:

filters - A list of filters to apply to the thumbnail.

Returns:

Reference to this object.

iterableBufferedImages

public Iterable<BufferedImage> iterableBufferedImages()

Create the thumbnails and return as a Iterable of BufferedImages.

For situations where multiple thumbnails are being generated, this method is preferred over the asBufferedImages() method, as (1) the processing does not have to complete before the method returns and (2) the thumbnails can be retrieved one at a time, potentially reducing the number of thumbnails which need to be retained in the heap memory, potentially reducing the chance of OutOfMemoryErrors from occurring.

If an IOException occurs during the processing of the thumbnail, the Iterable will return a null for that element.

Returns:

An Iterable which will provide an Iterator which returns thumbnails as BufferedImages.

asBufferedImages

public List<BufferedImage> asBufferedImages()
                                     throws IOException

Create the thumbnails and return as a List of BufferedImages.

Note about performance

If there are many thumbnails generated at once, it is possible that the Java virtual machine's heap space will run out and an OutOfMemoryError could result.

If many thumbnails are being processed at once, then using the iterableBufferedImages() method would be preferable.

Returns:

A list of thumbnails.

Throws:

IOException - If an problem occurred during the reading of the original images.

asBufferedImage

public BufferedImage asBufferedImage()
                              throws IOException

Creates a thumbnail and returns it as a BufferedImage.

To call this method, the thumbnail must have been created from a single source.

Returns:

A thumbnail as a BufferedImage.

Throws:

IOException - If an problem occurred during the reading of the original image.

IllegalArgumentException - If multiple original images are specified.

asFiles

public List<File> asFiles(Iterable<File> iterable)
                   throws IOException

Creates the thumbnails and stores them to the files, and returns a List of Files to the thumbnails.

The file names for the thumbnails are obtained from the given Iterable.

Parameters:

iterable - An Iterable which returns an Iterator which returns file names which should be assigned to each thumbnail.

Returns:

A list of Files of the thumbnails which were created.

Throws:

IOException - If a problem occurs while reading the original images or writing the thumbnails to files.

toFiles

public void toFiles(Iterable<File> iterable)
             throws IOException

Creates the thumbnails and stores them to the files.

The file names for the thumbnails are obtained from the given Iterable.

Parameters:

iterable - An Iterable which returns an Iterator which returns file names which should be assigned to each thumbnail.

Throws:

IOException - If a problem occurs while reading the original images or writing the thumbnails to files.

asFiles

public List<File> asFiles(Rename rename)
                   throws IOException

Creates the thumbnails and stores them to the files, using the Rename function to determine the filenames. The files are returned as List.

To call this method, the thumbnails must have been creates from files by calling the Thumbnails.of(File...) method.

Parameters:

rename - The rename function which is used to determine the filenames of the thumbnail files to write.

Returns:

A list of Files of the thumbnails which were created.

Throws:

IOException - If a problem occurs while reading the original images or writing the thumbnails to files.

IllegalStateException - If the original images are not from files.

toFiles

public void toFiles(Rename rename)
             throws IOException

Creates the thumbnails and stores them to the files, using the Rename function to determine the filenames.

To call this method, the thumbnails must have been creates from files by calling the Thumbnails.of(File...) method.

Parameters:

rename - The rename function which is used to determine the filenames of the thumbnail files to write.

Throws:

IOException - If a problem occurs while reading the original images or writing the thumbnails to files. thumbnails to files.

IllegalStateException - If the original images are not from files.

toFile

public void toFile(File outFile)
            throws IOException

Create a thumbnail and writes it to a File.

To call this method, the thumbnail must have been created from a single source.

Parameters:

outFile - The file to which the thumbnail is to be written to.

Throws:

IOException - If a problem occurs while reading the original images or writing the thumbnails to files.

IllegalArgumentException - If multiple original image files are specified.

toFile

public void toFile(String outFilepath)
            throws IOException

Create a thumbnail and writes it to a File.

To call this method, the thumbnail must have been created from a single source.

Parameters:

outFilepath - The file to which the thumbnail is to be written to.

Throws:

IOException - If a problem occurs while reading the original images or writing the thumbnails to files.

IllegalArgumentException - If multiple original image files are specified.

toOutputStream

public void toOutputStream(OutputStream os)
                    throws IOException

Create a thumbnail and writes it to a OutputStream.

To call this method, the thumbnail must have been created from a single source.

Parameters:

os - The output stream to which the thumbnail is to be written to.

Throws:

IOException - If a problem occurs while reading the original images or writing the thumbnails.

IllegalArgumentException - If multiple original image files are specified.

IllegalStateException - If the output format has not been specified through the outputFormat(String) method.

toOutputStreams

public void toOutputStreams(Iterable<? extends OutputStream> iterable)
                     throws IOException

Creates the thumbnails and writes them to OutputStreams provided by the Iterable.

Parameters:

iterable - An Iterable which returns an Iterator which returns the output stream which should be assigned to each thumbnail.

Throws:

IOException - If a problem occurs while reading the original images or writing the thumbnails.

IllegalStateException - If the output format has not been specified through the outputFormat(String) method.