loci.formats
Class ImageTools

java.lang.Object
  extended by loci.formats.ImageTools

public final class ImageTools
extends Object

A utility class with convenience methods for manipulating images. Much code was stolen and adapted from DrLaszloJamf's posts at: http://forum.java.sun.com/thread.jspa?threadID=522483

Source code:
Trac, SVN

Author:
Curtis Rueden ctrueden at wisc.edu

Field Summary
protected static Component OBS
          ImageObserver for working with AWT images.
 
Method Summary
static BufferedImage autoscale(BufferedImage img, int min, int max)
          Perform autoscaling on the given BufferedImage; map min to 0 and max to 255.
static byte[] autoscale(byte[] b, int min, int max, int bpp, boolean little)
          Perform autoscaling on the given byte array; map min to 0 and max to 255.
static BufferedImage blankImage(int w, int h, int c, int type)
          Creates a blank image with the given dimensions and transfer type.
static BufferedImage copyScaled(BufferedImage source, BufferedImage target, Object hint)
          Copies the source image into the target, applying scaling.
static short[][] demosaic(short[][] input, int w, int h)
          Perform demosaicing on a byte array, assuming a {B, G, G, R} mosaic.
static byte[][] getBytes(BufferedImage image)
          Extracts pixel data as arrays of unsigned bytes, one per channel.
static byte[] getBytes(BufferedImage img, boolean separated, int c)
          Get the bytes from an image, merging the channels as necessary.
static GraphicsConfiguration getDefaultConfiguration()
          Gets the default graphics configuration for the environment.
static double[][] getDoubles(BufferedImage image)
          Extracts pixel data as arrays of doubles, one per channel.
static float[][] getFloats(BufferedImage image)
          Extracts pixel data as arrays of floats, one per channel.
static int[][] getInts(BufferedImage image)
          Extracts pixel data as arrays of signed integers, one per channel.
static byte[][] getPixelBytes(BufferedImage img, boolean little)
          Return a 2D array of bytes representing the image.
static Object getPixels(BufferedImage image)
          Gets the image's pixel data as arrays of primitives, one per channel.
static int getPixelType(BufferedImage image)
          Gets the pixel type of the given image.
static short[][] getShorts(BufferedImage image)
          Extracts pixel data as arrays of unsigned shorts, one per channel.
static Dimension getSize(Image image)
          Gets the width and height of the given AWT image, waiting for it to finish loading if necessary.
static BufferedImage indexedToRGB(BufferedImage img, boolean le)
          Converts an indexed color BufferedImage to an RGB BufferedImage.
static byte[][] indexedToRGB(byte[][] lut, byte[] b)
          Converts a LUT and an array of indices into an array of RGB tuples.
static short[][] indexedToRGB(short[][] lut, byte[] b, boolean le)
          Converts a LUT and an array of indices into an array of RGB tuples.
static boolean loadImage(Image image)
          Ensures the given AWT image is fully loaded.
static int[] make24Bits(Object pixels, int w, int h, boolean interleaved)
          Convert an arbitrary primitive type array with 3 samples per pixel to an int array, i.e.
static byte[][] make24Bits(Object pixels, int w, int h, boolean interleaved, boolean reverse)
          Convert an arbitrary primitive type array with 3 samples per pixel to a 3 x (width * height) byte array.
static BufferedImage makeBuffered(Image image)
          Creates a buffered image from the given AWT image object.
static BufferedImage makeBuffered(Image image, ColorModel cm)
          Creates a buffered image possessing the given color model, from the specified AWT image object.
static ColorModel makeColorModel(int c, int dataType)
          Gets a color space for the given number of color components.
static BufferedImage makeCompatible(BufferedImage image, GraphicsConfiguration gc)
          Creates a buffered image compatible with the given graphics configuration, using the given buffered image as a source.
static BufferedImage makeImage(byte[][] data, int w, int h)
          Creates an image from the given unsigned byte data.
static BufferedImage makeImage(byte[][] data, int w, int h, int bpp, boolean little)
          Creates an image from the given data, performing type conversions as necessary.
static BufferedImage makeImage(byte[][] data, int w, int h, int bpp, boolean fp, boolean little)
          Creates an image from the given data, performing type conversions as necessary.
static BufferedImage makeImage(byte[] data, int w, int h)
          Creates an image from the given single-channel unsigned byte data.
static BufferedImage makeImage(byte[] data, int w, int h, int c, boolean interleaved)
          Creates an image from the given unsigned byte data.
static BufferedImage makeImage(byte[] data, int w, int h, int c, boolean interleaved, int bpp, boolean little)
          Creates an image from the given data, performing type conversions as necessary.
static BufferedImage makeImage(byte[] data, int w, int h, int c, boolean interleaved, int bpp, boolean fp, boolean little)
          Creates an image from the given data, performing type conversions as necessary.
static BufferedImage makeImage(double[][] data, int w, int h)
          Creates an image from the given double-precision floating point data.
static BufferedImage makeImage(double[] data, int w, int h)
          Creates an image from the given single-channel double data.
static BufferedImage makeImage(double[] data, int w, int h, int c, boolean interleaved)
          Creates an image from the given double data.
static BufferedImage makeImage(float[][] data, int w, int h)
          Creates an image from the given single-precision floating point data.
static BufferedImage makeImage(float[] data, int w, int h)
          Creates an image from the given single-channel float data.
static BufferedImage makeImage(float[] data, int w, int h, int c, boolean interleaved)
          Creates an image from the given float data.
static BufferedImage makeImage(int[][] data, int w, int h)
          Creates an image from the given signed int data.
static BufferedImage makeImage(int[] data, int w, int h)
          Creates an image from the given single-channel signed int data.
static BufferedImage makeImage(int[] data, int w, int h, int c, boolean interleaved)
          Creates an image from the given signed int data.
static BufferedImage makeImage(short[][] data, int w, int h)
          Creates an image from the given unsigned short data.
static BufferedImage makeImage(short[] data, int w, int h)
          Creates an image from the given single-channel unsigned short data.
static BufferedImage makeImage(short[] data, int w, int h, int c, boolean interleaved)
          Creates an image from the given unsigned short data.
static BufferedImage mergeChannels(BufferedImage[] images)
          Merges the given images into a single multi-channel image.
static BufferedImage padImage(BufferedImage img, int width, int height)
          Pads (or crops) the image to the given width and height.
static byte[] padImage(byte[] b, boolean interleaved, int c, int oldWidth, int width, int height)
          Pads (or crops) the byte array to the given width and height.
static double[] padImage(double[] b, boolean interleaved, int c, int oldWidth, int width, int height)
          Pads (or crops) the double array to the given width and height.
static float[] padImage(float[] b, boolean interleaved, int c, int oldWidth, int width, int height)
          Pads (or crops) the float array to the given width and height.
static int[] padImage(int[] b, boolean interleaved, int c, int oldWidth, int width, int height)
          Pads (or crops) the int array to the given width and height.
static short[] padImage(short[] b, boolean interleaved, int c, int oldWidth, int width, int height)
          Pads (or crops) the short array to the given width and height.
static BufferedImage scale(BufferedImage source, int width, int height, boolean pad)
          Scales the image using the most appropriate API, with the resultant image having the same color model as the original image.
static BufferedImage scale2D(BufferedImage image, int width, int height, Object hint, ColorModel cm)
          Scales the image using the Java2D API, with the resultant image having the given color model.
static BufferedImage scale2D(BufferedImage image, int width, int height, Object hint, GraphicsConfiguration gc)
          Scales the image using the Java2D API, with the resultant image optimized for the given graphics configuration.
static Image scaleAWT(BufferedImage source, int width, int height, int hint)
          Scales the image using the AWT Image API.
static Double[] scanData(byte[] plane, int bits, boolean littleEndian)
          Scan a plane for the channel min and max values.
static BufferedImage[] splitChannels(BufferedImage image)
          Splits the given multi-channel image into single-channel images.
static byte[][] splitChannels(byte[] array, int c, int bytes, boolean reverse, boolean interleaved)
          Splits the given multi-channel array into a 2D array.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

OBS

protected static final Component OBS
ImageObserver for working with AWT images.

Method Detail

makeImage

public static BufferedImage makeImage(byte[] data,
                                      int w,
                                      int h)
Creates an image from the given single-channel unsigned byte data.

Parameters:
data - Array containing image data.
w - Width of image plane.
h - Height of image plane.

makeImage

public static BufferedImage makeImage(short[] data,
                                      int w,
                                      int h)
Creates an image from the given single-channel unsigned short data.

Parameters:
data - Array containing image data.
w - Width of image plane.
h - Height of image plane.

makeImage

public static BufferedImage makeImage(int[] data,
                                      int w,
                                      int h)
Creates an image from the given single-channel signed int data.

Parameters:
data - Array containing image data.
w - Width of image plane.
h - Height of image plane.

makeImage

public static BufferedImage makeImage(float[] data,
                                      int w,
                                      int h)
Creates an image from the given single-channel float data.

Parameters:
data - Array containing image data.
w - Width of image plane.
h - Height of image plane.

makeImage

public static BufferedImage makeImage(double[] data,
                                      int w,
                                      int h)
Creates an image from the given single-channel double data.

Parameters:
data - Array containing image data.
w - Width of image plane.
h - Height of image plane.

makeImage

public static BufferedImage makeImage(byte[] data,
                                      int w,
                                      int h,
                                      int c,
                                      boolean interleaved)
Creates an image from the given unsigned byte data.

Parameters:
data - Array containing image data.
w - Width of image plane.
h - Height of image plane.
c - Number of channels.
interleaved - If set, the channels are assumed to be interleaved; otherwise they are assumed to be sequential. For example, for RGB data, the pattern "RGBRGBRGB..." is interleaved, while "RRR...GGG...BBB..." is sequential.

makeImage

public static BufferedImage makeImage(short[] data,
                                      int w,
                                      int h,
                                      int c,
                                      boolean interleaved)
Creates an image from the given unsigned short data.

Parameters:
data - Array containing image data.
w - Width of image plane.
h - Height of image plane.
c - Number of channels.
interleaved - If set, the channels are assumed to be interleaved; otherwise they are assumed to be sequential. For example, for RGB data, the pattern "RGBRGBRGB..." is interleaved, while "RRR...GGG...BBB..." is sequential.

makeImage

public static BufferedImage makeImage(int[] data,
                                      int w,
                                      int h,
                                      int c,
                                      boolean interleaved)
Creates an image from the given signed int data.

Parameters:
data - Array containing image data.
w - Width of image plane.
h - Height of image plane.
c - Number of channels.
interleaved - If set, the channels are assumed to be interleaved; otherwise they are assumed to be sequential. For example, for RGB data, the pattern "RGBRGBRGB..." is interleaved, while "RRR...GGG...BBB..." is sequential.

makeImage

public static BufferedImage makeImage(float[] data,
                                      int w,
                                      int h,
                                      int c,
                                      boolean interleaved)
Creates an image from the given float data.

Parameters:
data - Array containing image data.
w - Width of image plane.
h - Height of image plane.
c - Number of channels.
interleaved - If set, the channels are assumed to be interleaved; otherwise they are assumed to be sequential. For example, for RGB data, the pattern "RGBRGBRGB..." is interleaved, while "RRR...GGG...BBB..." is sequential.

makeImage

public static BufferedImage makeImage(double[] data,
                                      int w,
                                      int h,
                                      int c,
                                      boolean interleaved)
Creates an image from the given double data.

Parameters:
data - Array containing image data.
w - Width of image plane.
h - Height of image plane.
c - Number of channels.
interleaved - If set, the channels are assumed to be interleaved; otherwise they are assumed to be sequential. For example, for RGB data, the pattern "RGBRGBRGB..." is interleaved, while "RRR...GGG...BBB..." is sequential.

makeImage

public static BufferedImage makeImage(byte[][] data,
                                      int w,
                                      int h)
Creates an image from the given unsigned byte data.

Parameters:
data - Array containing image data. It is assumed that each channel corresponds to one element of the array. For example, for RGB data, data[0] is R, data[1] is G, and data[2] is B.
w - Width of image plane.
h - Height of image plane.

makeImage

public static BufferedImage makeImage(short[][] data,
                                      int w,
                                      int h)
Creates an image from the given unsigned short data.

Parameters:
data - Array containing image data. It is assumed that each channel corresponds to one element of the array. For example, for RGB data, data[0] is R, data[1] is G, and data[2] is B.
w - Width of image plane.
h - Height of image plane.

makeImage

public static BufferedImage makeImage(int[][] data,
                                      int w,
                                      int h)
Creates an image from the given signed int data.

Parameters:
data - Array containing image data. It is assumed that each channel corresponds to one element of the array. For example, for RGB data, data[0] is R, data[1] is G, and data[2] is B.
w - Width of image plane.
h - Height of image plane.

makeImage

public static BufferedImage makeImage(float[][] data,
                                      int w,
                                      int h)
Creates an image from the given single-precision floating point data.

Parameters:
data - Array containing image data. It is assumed that each channel corresponds to one element of the array. For example, for RGB data, data[0] is R, data[1] is G, and data[2] is B.
w - Width of image plane.
h - Height of image plane.

makeImage

public static BufferedImage makeImage(double[][] data,
                                      int w,
                                      int h)
Creates an image from the given double-precision floating point data.

Parameters:
data - Array containing image data. It is assumed that each channel corresponds to one element of the array. For example, for RGB data, data[0] is R, data[1] is G, and data[2] is B.
w - Width of image plane.
h - Height of image plane.

makeImage

public static BufferedImage makeImage(byte[] data,
                                      int w,
                                      int h,
                                      int c,
                                      boolean interleaved,
                                      int bpp,
                                      boolean little)
Creates an image from the given data, performing type conversions as necessary.

Parameters:
data - Array containing image data.
w - Width of image plane.
h - Height of image plane.
c - Number of channels.
interleaved - If set, the channels are assumed to be interleaved; otherwise they are assumed to be sequential. For example, for RGB data, the pattern "RGBRGBRGB..." is interleaved, while "RRR...GGG...BBB..." is sequential.
bpp - Denotes the number of bytes in the returned primitive type (e.g. if bpp == 2, we should return an array of type short).
little - Whether byte array is in little-endian order.

makeImage

public static BufferedImage makeImage(byte[] data,
                                      int w,
                                      int h,
                                      int c,
                                      boolean interleaved,
                                      int bpp,
                                      boolean fp,
                                      boolean little)
Creates an image from the given data, performing type conversions as necessary.

Parameters:
data - Array containing image data.
w - Width of image plane.
h - Height of image plane.
c - Number of channels.
interleaved - If set, the channels are assumed to be interleaved; otherwise they are assumed to be sequential. For example, for RGB data, the pattern "RGBRGBRGB..." is interleaved, while "RRR...GGG...BBB..." is sequential.
bpp - Denotes the number of bytes in the returned primitive type (e.g. if bpp == 2, we should return an array of type short).
fp - If set and bpp == 4 or bpp == 8, then return floats or doubles.
little - Whether byte array is in little-endian order.

makeImage

public static BufferedImage makeImage(byte[][] data,
                                      int w,
                                      int h,
                                      int bpp,
                                      boolean little)
Creates an image from the given data, performing type conversions as necessary.

Parameters:
data - Array containing image data, one channel per element.
w - Width of image plane.
h - Height of image plane.
bpp - Denotes the number of bytes in the returned primitive type (e.g. if bpp == 2, we should return an array of type short).
little - Whether byte array is in little-endian order.

makeImage

public static BufferedImage makeImage(byte[][] data,
                                      int w,
                                      int h,
                                      int bpp,
                                      boolean fp,
                                      boolean little)
Creates an image from the given data, performing type conversions as necessary.

Parameters:
data - Array containing image data, one channel per element.
w - Width of image plane.
h - Height of image plane.
bpp - Denotes the number of bytes in the returned primitive type (e.g. if bpp == 2, we should return an array of type short).
fp - If set and bpp == 4 or bpp == 8, then return floats or doubles.
little - Whether byte array is in little-endian order.

blankImage

public static BufferedImage blankImage(int w,
                                       int h,
                                       int c,
                                       int type)
Creates a blank image with the given dimensions and transfer type.

Parameters:
w - Width of image plane.
h - Height of image plane.
c - Number of channels.
type - One of the following types:
  • FormatReader.INT8
  • FormatReader.UINT8
  • FormatReader.INT16
  • FormatReader.UINT16
  • FormatReader.INT32
  • FormatReader.UINT32
  • FormatReader.FLOAT
  • FormatReader.DOUBLE

getPixels

public static Object getPixels(BufferedImage image)
Gets the image's pixel data as arrays of primitives, one per channel. The returned type will be either byte[][], short[][], int[][], float[][] or double[][], depending on the image's transfer type.


getBytes

public static byte[][] getBytes(BufferedImage image)
Extracts pixel data as arrays of unsigned bytes, one per channel.


getShorts

public static short[][] getShorts(BufferedImage image)
Extracts pixel data as arrays of unsigned shorts, one per channel.


getInts

public static int[][] getInts(BufferedImage image)
Extracts pixel data as arrays of signed integers, one per channel.


getFloats

public static float[][] getFloats(BufferedImage image)
Extracts pixel data as arrays of floats, one per channel.


getDoubles

public static double[][] getDoubles(BufferedImage image)
Extracts pixel data as arrays of doubles, one per channel.


getPixelBytes

public static byte[][] getPixelBytes(BufferedImage img,
                                     boolean little)
Return a 2D array of bytes representing the image. If the transfer type is something other than DataBuffer.TYPE_BYTE, then each pixel value is converted to the appropriate number of bytes. In other words, if we are given an image with 16-bit data, each channel of the resulting array will have width * height * 2 bytes.


getPixelType

public static int getPixelType(BufferedImage image)
Gets the pixel type of the given image.

Returns:
One of the following types:
  • FormatReader.INT8
  • FormatReader.UINT8
  • FormatReader.INT16
  • FormatReader.UINT16
  • FormatReader.INT32
  • FormatReader.UINT32
  • FormatReader.FLOAT
  • FormatReader.DOUBLE
  • -1 (unknown type)

getBytes

public static byte[] getBytes(BufferedImage img,
                              boolean separated,
                              int c)
Get the bytes from an image, merging the channels as necessary.


make24Bits

public static byte[][] make24Bits(Object pixels,
                                  int w,
                                  int h,
                                  boolean interleaved,
                                  boolean reverse)
Convert an arbitrary primitive type array with 3 samples per pixel to a 3 x (width * height) byte array.


make24Bits

public static int[] make24Bits(Object pixels,
                               int w,
                               int h,
                               boolean interleaved)
Convert an arbitrary primitive type array with 3 samples per pixel to an int array, i.e. RGB color with 8 bits per pixel. Does not perform any scaling.


splitChannels

public static byte[][] splitChannels(byte[] array,
                                     int c,
                                     int bytes,
                                     boolean reverse,
                                     boolean interleaved)
Splits the given multi-channel array into a 2D array. The "reverse" parameter is false if channels are in RGB order, true if channels are in BGR order.


splitChannels

public static BufferedImage[] splitChannels(BufferedImage image)
Splits the given multi-channel image into single-channel images.


mergeChannels

public static BufferedImage mergeChannels(BufferedImage[] images)
Merges the given images into a single multi-channel image.


padImage

public static BufferedImage padImage(BufferedImage img,
                                     int width,
                                     int height)
Pads (or crops) the image to the given width and height. The image will be centered within the new bounds.


padImage

public static byte[] padImage(byte[] b,
                              boolean interleaved,
                              int c,
                              int oldWidth,
                              int width,
                              int height)
Pads (or crops) the byte array to the given width and height. The image will be centered within the new bounds.


padImage

public static short[] padImage(short[] b,
                               boolean interleaved,
                               int c,
                               int oldWidth,
                               int width,
                               int height)
Pads (or crops) the short array to the given width and height. The image will be centered within the new bounds.


padImage

public static int[] padImage(int[] b,
                             boolean interleaved,
                             int c,
                             int oldWidth,
                             int width,
                             int height)
Pads (or crops) the int array to the given width and height. The image will be centered within the new bounds.


padImage

public static float[] padImage(float[] b,
                               boolean interleaved,
                               int c,
                               int oldWidth,
                               int width,
                               int height)
Pads (or crops) the float array to the given width and height. The image will be centered within the new bounds.


padImage

public static double[] padImage(double[] b,
                                boolean interleaved,
                                int c,
                                int oldWidth,
                                int width,
                                int height)
Pads (or crops) the double array to the given width and height. The image will be centered within the new bounds.


demosaic

public static short[][] demosaic(short[][] input,
                                 int w,
                                 int h)
Perform demosaicing on a byte array, assuming a {B, G, G, R} mosaic.


autoscale

public static BufferedImage autoscale(BufferedImage img,
                                      int min,
                                      int max)
Perform autoscaling on the given BufferedImage; map min to 0 and max to 255. If the BufferedImage has 8 bit data, then nothing happens.


autoscale

public static byte[] autoscale(byte[] b,
                               int min,
                               int max,
                               int bpp,
                               boolean little)
Perform autoscaling on the given byte array; map min to 0 and max to 255. If the number of bytes per pixel is 1, then nothing happens.


scanData

public static Double[] scanData(byte[] plane,
                                int bits,
                                boolean littleEndian)
Scan a plane for the channel min and max values.


copyScaled

public static BufferedImage copyScaled(BufferedImage source,
                                       BufferedImage target,
                                       Object hint)
Copies the source image into the target, applying scaling.


scale2D

public static BufferedImage scale2D(BufferedImage image,
                                    int width,
                                    int height,
                                    Object hint,
                                    GraphicsConfiguration gc)
Scales the image using the Java2D API, with the resultant image optimized for the given graphics configuration.


scale2D

public static BufferedImage scale2D(BufferedImage image,
                                    int width,
                                    int height,
                                    Object hint,
                                    ColorModel cm)
Scales the image using the Java2D API, with the resultant image having the given color model.


scaleAWT

public static Image scaleAWT(BufferedImage source,
                             int width,
                             int height,
                             int hint)
Scales the image using the AWT Image API.


scale

public static BufferedImage scale(BufferedImage source,
                                  int width,
                                  int height,
                                  boolean pad)
Scales the image using the most appropriate API, with the resultant image having the same color model as the original image.


makeBuffered

public static BufferedImage makeBuffered(Image image)
Creates a buffered image from the given AWT image object. If the AWT image is already a buffered image, no new object is created.


makeBuffered

public static BufferedImage makeBuffered(Image image,
                                         ColorModel cm)
Creates a buffered image possessing the given color model, from the specified AWT image object. If the AWT image is already a buffered image with the given color model, no new object is created.


loadImage

public static boolean loadImage(Image image)
Ensures the given AWT image is fully loaded.


getSize

public static Dimension getSize(Image image)
Gets the width and height of the given AWT image, waiting for it to finish loading if necessary.


makeCompatible

public static BufferedImage makeCompatible(BufferedImage image,
                                           GraphicsConfiguration gc)
Creates a buffered image compatible with the given graphics configuration, using the given buffered image as a source. If gc is null, the default graphics configuration is used.


getDefaultConfiguration

public static GraphicsConfiguration getDefaultConfiguration()
Gets the default graphics configuration for the environment.


makeColorModel

public static ColorModel makeColorModel(int c,
                                        int dataType)
Gets a color space for the given number of color components.


indexedToRGB

public static BufferedImage indexedToRGB(BufferedImage img,
                                         boolean le)
Converts an indexed color BufferedImage to an RGB BufferedImage.


indexedToRGB

public static byte[][] indexedToRGB(byte[][] lut,
                                    byte[] b)
Converts a LUT and an array of indices into an array of RGB tuples.


indexedToRGB

public static short[][] indexedToRGB(short[][] lut,
                                     byte[] b,
                                     boolean le)
Converts a LUT and an array of indices into an array of RGB tuples.