com.xinapse.multisliceimage
Class PixArray

java.lang.Object
  com.xinapse.multisliceimage.PixArray

All Implemented Interfaces:

java.lang.Cloneable

public abstract class PixArray
extends java.lang.Object
implements java.lang.Cloneable

An abstract representation of an array of pixels of varying type. This Class is only of interest to developers wishing to sub-class MultiSliceImage. Users of the MultiSliceImage package should always access pixel values via the methods of MultiSliceImage.

Field Summary

protected PixelDataType

dataType The type of pixel that this PixArray stores.

Method Summary

PixArray	clone() Returns a new PixArray object that contains pixel values and properties that are the same as the original.
abstract int[]	getHisto(int nbins) Computes a histogram of this PixArray.
static PixArray	getInstance(PixelDataType dataType, java.io.DataInputStream s, java.nio.ByteOrder byteOrder, int nDim, int[] dims) Creates one of the sub-classes of PixArray Object of the type specified by the dataType with pixel data coming from a DataInputStream.
static PixArray	getInstance(PixelDataType dataType, int nDim, int[] dims) Creates one of the sub-classes of PixArray Object of the type specified by the pixel data type.
static PixArray	getInstance(PixelDataType dataType, java.io.RandomAccessFile randomAccessFile, java.nio.ByteOrder byteOrder, int fileOffset, int nDim, int[] dims) Creates one of the sub-classes of PixArray Object of the type specified by the dataType with pixel data coming from a RandomAccessFile.
int[]	getMinMax() Finds the minimum and maximum values in this PixArray.
abstract java.lang.Object	getPutPix(java.lang.Object pix, int[] pixIdx, boolean get) Gets/puts a single pixel value from/to an an image.
abstract java.lang.Object	getPutPix(java.lang.Object array, int[] lowIdx, int[] highIdx, boolean get) Basic pixel accessor method for images of any dimensionality.
abstract java.lang.Object	getPutSlice(java.lang.Object array, int slice, boolean get) Returns a 1-Dimensional array of type appropriate of the image pixel type, cast as an Object, with array indices [0 to (nRows * nCols)-1], representing the pixel intensity values for one slice of this image.
abstract long	write(java.io.DataOutputStream s, java.nio.ByteOrder byteOrder) Writes this PixArray Object to a DataOutputStream.

Methods inherited from class java.lang.Object

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

Field Detail

dataType

protected PixelDataType dataType

The type of pixel that this PixArray stores.

Method Detail

getInstance

public static final PixArray getInstance(PixelDataType dataType,
                                         int nDim,
                                         int[] dims)
                                  throws MultiSliceImageException

Creates one of the sub-classes of PixArray Object of the type specified by the pixel data type.

Parameters:

dataType - a supported PixelDataType, one of:

• PixelDataType.BINARY,
• PixelDataType.BYTE,
• PixelDataType.UBYTE,
• PixelDataType.RGB,
• PixelDataType.COLOURPACKED
• PixelDataType.SHORT,
• PixelDataType.USHORT,
• PixelDataType.INT,
• PixelDataType.UINT,
• PixelDataType.LONG,
• PixelDataType.FLOAT,
• PixelDataType.COMPLEX, or
• PixelDataType.DOUBLE,
• PixelDataType.DOUBLECOMPLEX,

nDim - the dimensionality of the PixArray.

dims - the dimensions of the PixArray.

Throws:

MultiSliceImageException - if the dataType is not supported.

getInstance

public static final PixArray getInstance(PixelDataType dataType,
                                         java.io.RandomAccessFile randomAccessFile,
                                         java.nio.ByteOrder byteOrder,
                                         int fileOffset,
                                         int nDim,
                                         int[] dims)
                                  throws MultiSliceImageException

Creates one of the sub-classes of PixArray Object of the type specified by the dataType with pixel data coming from a RandomAccessFile.

Parameters:

dataType - a supported PixelDataType, one of:

• PixelDataType.BINARY,
• PixelDataType.BYTE,
• PixelDataType.UBYTE,
• PixelDataType.RGB,
• PixelDataType.COLOURPACKED
• PixelDataType.SHORT,
• PixelDataType.USHORT,
• PixelDataType.INT,
• PixelDataType.UINT,
• PixelDataType.LONG,
• PixelDataType.FLOAT,
• PixelDataType.COMPLEX, or
• PixelDataType.DOUBLE,
• PixelDataType.DOUBLECOMPLEX,

randomAccessFile - the RandomAccessFile from which the pixel data values will be derived.

byteOrder - the ByteOrder of the data in the file.

fileOffset - an offset (in bytes) from the start of the file, to the start of the pixel data.

nDim - the dimensionality of the PixArray.

dims - the dimensions of the PixArray.

Throws:

MultiSliceImageException - if the dataType is not supported, or the pixel values cannot be derived from randomAccessFile.

getInstance

public static final PixArray getInstance(PixelDataType dataType,
                                         java.io.DataInputStream s,
                                         java.nio.ByteOrder byteOrder,
                                         int nDim,
                                         int[] dims)
                                  throws MultiSliceImageException

Creates one of the sub-classes of PixArray Object of the type specified by the dataType with pixel data coming from a DataInputStream.

Parameters:

dataType - a supported PixelDataType, one of

• PixelDataType.BINARY,
• PixelDataType.BYTE,
• PixelDataType.UBYTE,
• PixelDataType.RGB,
• PixelDataType.COLOURPACKED
• PixelDataType.SHORT,
• PixelDataType.USHORT,
• PixelDataType.INT,
• PixelDataType.UINT,
• PixelDataType.LONG,
• PixelDataType.FLOAT,
• PixelDataType.COMPLEX, or
• PixelDataType.DOUBLE,
• PixelDataType.DOUBLECOMPLEX,

s - the DataInputStream from which the pixel data values will be derived.

byteOrder - the ByteOrder of the data in the input stream.

nDim - the dimensionality of the PixArray.

dims - the dimensions of the PixArray.

Throws:

MultiSliceImageException - if the dataType not supported, or the pixel values cannot be derived from s.

getPutPix

public abstract java.lang.Object getPutPix(java.lang.Object array,
                                           int[] lowIdx,
                                           int[] highIdx,
                                           boolean get)
                                    throws MultiSliceImageException

Basic pixel accessor method for images of any dimensionality. The int[] lowIdx contains indexes to the lowest index of the image pixel array that is required to be accessed, and highIdx indexes to the highest index of the image pixel array that is required to be accessed. Only image dimensions from lowIdx to highIdx are accessed. For example, if you have a 10-slice 256x256 3-dimensional image and want the pixel values for just slices 2 to 5, then lowIdx would have values {2, 0, 0} and highIdx would have values {5, 255, 255}.

Parameters:

array - for get operations is an array to put pixels values in; for put operations contains the pixel values to put.

lowIdx - contains indexes to the lowest index of the image pixel array that is required to be accessed

highIdx - contains indexes to the highest index of the image pixel array that is required to be accessed

get - true for get operations, false for put operations.

Returns:

a 1-dimensional array of the appropriate type cast to an Object.

Throws:

MultiSliceImageException - if the requested pixel values cannot be put or got, or if the class of the array is incorrect for this type of image.

getPutPix

public abstract java.lang.Object getPutPix(java.lang.Object pix,
                                           int[] pixIdx,
                                           boolean get)
                                    throws MultiSliceImageException

Gets/puts a single pixel value from/to an an image. Returns a java Object of the appropriate class for the primitive pixel type, cast to an Object. This represents the pixel intensity value for the pixel indexed by each element of pixIdx.

The class of pixel that nust be supplied (for put operations), or that is returned (for get operations) is:
PixelDataType.BINARY images - java.lang.Boolean.
PixelDataType.UBYTE images - java.lang.Short.
PixelDataType.BYTE images - java.lang.Byte.
PixelDataType.RGB_INTERLACED images - java.awt.Color.
PixelDataType.RGB_BY_PLANE images - java.awt.Color.
PixelDataType.COLOURPACKED images - java.awt.Color.
PixelDataType.SHORT images - java.lang.Short.
PixelDataType.INT images - java.lang.Integer.
PixelDataType.FLOAT images - java.lang.Float.
PixelDataType.COMPLEX images - com.xinapse.multisliceimage.Complex.
PixelDataType.DOUBLE images - java.lang.Double.

Parameters:

pix - a pixel value for a put operation or null for a get operation.

pixIdx - an array of length at least nDim with elements 0 to nDim-1 equal to the index in that image dimension.

get - true for a gett operation and false for a put operation.

Returns:

a pixel value for a get operation or the supplied pixel for a put operation.

Throws:

MultiSliceImageException - if the pixIdx is bad, or if the class of the pixel is incorrect for this type of image.

getPutSlice

public abstract java.lang.Object getPutSlice(java.lang.Object array,
                                             int slice,
                                             boolean get)
                                      throws MultiSliceImageException

Returns a 1-Dimensional array of type appropriate of the image pixel type, cast as an Object, with array indices [0 to (nRows * nCols)-1], representing the pixel intensity values for one slice of this image. Applicable only to images with dimensionality of 2 or greater. If the image has dimensionality of greater than three, then this routine pretends that the image contains a just one multi-slice image, where in fact it contains series of multi-slice images - one for each of the extra dimensions. These can be accessed by providing a slice-number argument appropriate for the dimensionality of the image. For example, if the image is 4-dimensional with dimensions 10, 20, 256, 256, then this is consists of ten 3-D images each with 20 slices of 256x256 pixels. This routine pretends that thus is a 3-D image with 10x20 (=200) slices, so any slice from 0-199 could be accessed.

Parameters:

array - for get operations is an array to put pixels values in; for put operations contains the pixel values to put.

slice - the slice number.

get - true for get operations, false for put operations.

Returns:

a 1-dimensional array of the appropriate primitive type cast to an Object.

Throws:

MultiSliceImageException - if the requested pixel values cannot be put or got, or if the class of the array is incorrect for this type of image.

write

public abstract long write(java.io.DataOutputStream s,
                           java.nio.ByteOrder byteOrder)
                    throws java.io.IOException

Writes this PixArray Object to a DataOutputStream. All pixels are written.

Parameters:

s - the DataOutputStream.

byteOrder - the ByteOrder of the data in the output stream.

Returns:

the number of bytes written.

Throws:

java.io.IOException - if the data cannot be written.

getMinMax

public int[] getMinMax()
                throws MultiSliceImageException

Finds the minimum and maximum values in this PixArray. For pixel data types that can be considered as integer, the true minium and maximum values are returned.

For PixelDataType.BINARY, the values returned are always 0 and 1.

For RGB images (PixelDataType.RGB_INTERLACED, PixelDataType.RGB_BY_PLANE, PixelDataType.COLOURPACKED), the values returned are the miniumum and maximum luminance values, where the luminance is (0.299 * Red) + (0.587 * Green) + (0.114 * Blue).

For floating types (PixelDataType.FLOAT and PixelDataType.DOUBLE), the values returned are the integers that are the Math.floor() and Math.ceil() of the real min and max respectively.

For PixelDataType.COMPLEX, the values returned are the min and max magnitudes of the complex values.

Returns:

an int[] of length 2, where the first element is the miniumum pixel value and the second is the maximum pixel value.

Throws:

MultiSliceImageException - if the min/max can't be computed for the pixel data type, or if the intensity range in the pixels overflows that which can be stored as an int.

getHisto

public abstract int[] getHisto(int nbins)
                        throws MultiSliceImageException

Computes a histogram of this PixArray. This method may only return a meaningful histogram for data types that can be considered as integer.

Parameters:

nbins - the number of bins in the histogram.

Returns:

an int[] of length specified by nbins, where each element of the array is the number of pixels of intensity min + i where i is the index into the array.

Throws:

MultiSliceImageException - if the histogram can't be computed.

clone

public PixArray clone()

Returns a new PixArray object that contains pixel values and properties that are the same as the original.

Overrides:

clone in class java.lang.Object

Returns:

a PixArray of the appropriate sub-class.