Package com.xinapse.image

Class PixArray

java.lang.Object
com.xinapse.image.PixArray
All Implemented Interfaces:
Cloneable
Direct Known Subclasses:
DoublePixArray
public abstract class PixArray extends Object implements Cloneable
An abstract representation of an array of pixels of varying type. This Class is only of interest to developers wishing to implement their own WritableImage class. Users of the class that implement WritableImage should always access pixel values via the methods of those classes.

  • Field Details

  • Constructor Details

    • PixArray

      protected PixArray(Object sourceArray, int nDim, int[] dims, PixelDataType dataType) throws IllegalArgumentException
      Creates a new PixArray taking the pixel values from the supplied sourceArray. The pixel values will be copied from the sourceArray.
      Parameters:
      sourceArray - the source of pixel values from which the pixel values for this PixArraywill be copied, if non-null.
      nDim - the dimensionality of the PixArray.
      dims - the dimensions of each dimension of the PixArray. The first value of dims refers to the slowest-changing index; the second value refers to the next-slowest-changing index etc. Thus, for a 3-D image, the first index would be the number of slices; the second index would be the number of rows; and the third index would be the number of columns in the image.
      dataType - the PixelDataType for the image pixels.
      Throws:
      IllegalArgumentException - if the image cannot be created due to size constraints or if the supplied sourceArray is of the wrong size for the dimension.

  • Method Details

    • getInstance

      public static final 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.
      Parameters:
      dataType - a supported PixelDataType, one of:
      nDim - the dimensionality of the PixArray.
      dims - the dimensions of the PixArray.
      Returns:
      a PixArray for holding the specified array of pixel intensity values.

    • getInstance

      public static final PixArray getInstance(PixelDataType dataType, RandomAccessFile f, ByteOrder byteOrder, int fileOffset, int nDim, int[] dims) throws IOException
      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:
      f - 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.
      Returns:
      a PixArray with pixel intensity values read from the supplied RandomAccessFile.
      Throws:
      IOException - if the pixel values cannot be derived from the RandomAccessFile.

    • getInstance

      public static final PixArray getInstance(PixelDataType dataType, DataInputStream s, ByteOrder byteOrder, int nDim, int[] dims) throws IOException
      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
      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.
      Returns:
      a PixArray with pixel intensity values read from the supplied DataInputStream.
      Throws:
      IOException - if the pixel values cannot be derived from s.

    • getPix

      public Object getPix()
      Returns a copy of the array of pixel values encapulated by this PixArray.
      Returns:
      a copy of the pixel values.

    • getPutPix

      public abstract Object getPutPix(Object array, int[] lowIdx, int[] highIdx, PixelOp op) throws IllegalArgumentException
      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
      op - the type of operation (PixelOp.GET or PixelOp.PUT).
      Returns:
      a 1-dimensional array of the appropriate type cast to an Object.
      Throws:
      IllegalArgumentException - if the class of the array is incorrect for this type of image.

    • getPutPix

      public abstract Object getPutPix(Object pix, int[] pixIdx, PixelOp op) throws IllegalArgumentException
      Gets/puts a single pixel value from/to this PixArray. 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 must be supplied (for put operations), or that is returned (for get operations) is:

      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.
      op - the type of operation (PixelOp.GET or PixelOp.PUT).
      Returns:
      a pixel value for a get operation or the supplied pixel for a put operation.
      Throws:
      IllegalArgumentException - if the pixIdx is bad, or if the class of the pixel is incorrect for this type of image.

    • getPutPix

      public static Object getPutPix(Object array, RandomAccessFile f, ByteOrder byteOrder, int offset, PixelDataType dataType, int nDim, int[] dims, int[] lowIdx, int[] highIdx, PixelOp op) throws IOException
      Basic pixel accessor method for images of any dimensionality where pixel data is held in a RandomAccessFile. 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}.

      The Class of pixel that must be supplied (for put operations), or that is returned (for get operations) is:

      Parameters:
      array - for get operations is an array to put pixels values in; for put operations contains the pixel values to put.
      f - the RandomAccessFile containing the pixel values.
      byteOrder - the ByteOrder of the data in the file.
      offset - an offset in bytes to the start of the (contiguous) pixel data.
      dataType - the PixelDataType for the primitive data type of this image.
      nDim - the image dimensionality.
      dims - the image dimensions.
      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
      op - the type of operation (PixelOp.GET or PixelOp.PUT).
      Returns:
      a 1-dimensional array of the appropriate primite type cast to an Object.
      Throws:
      IOException - if the requested pixel values cannot be put or got.
      IllegalArgumentException - if the class of the array is incorrect for this type of image.

    • getPutPix

      public static Object getPutPix(Object pix, int[] pixIdx, RandomAccessFile f, ByteOrder byteOrder, int offset, PixelDataType dataType, int nDim, int[] dims, PixelOp op) throws IOException
      Gets/puts a pixel value from/to an array of pixels. Returns a java Object of type corresponding to an array of picture elements. This represents the pixel intensity value for the pixel indexed by each element of pixIdx.
      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.
      f - a RandomAccessFile containing the pixel data.
      byteOrder - the ByteOrder of the data in the file.
      offset - a byte offset from the start of the file to the pixel data for the first pixel of the image.
      dataType - the PixelDataType for the primitive data type of this image.
      nDim - the dimensionality of this image.
      dims - the numbers of pixels for each dimension of this image.
      op - the type of operation (PixelOp.GET or PixelOp.PUT).
      Returns:
      a pixel value for a get operation or the supplied pixel for a put operation.
      Throws:
      IOException - if the pixel values cannot be got/put.
      IllegalArgumentException - if the class of the pixel is incorrect for this type of image.

    • getPutSlice

      public abstract Object getPutSlice(Object array, int slice, PixelOp op) throws IllegalArgumentException
      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.
      op - the type of operation (PixelOp.GET or PixelOp.PUT).
      Returns:
      a 1-dimensional array of the appropriate primitive type cast to an Object.
      Throws:
      IllegalArgumentException - if the requested pixel values cannot be put or got, or if the class of the array is incorrect for this type of image.

    • getPutSlice

      public static Object getPutSlice(Object array, int slice, RandomAccessFile f, ByteOrder byteOrder, int offset, PixelDataType dataType, int nDim, int[] dims, PixelOp op) throws IOException
      Returns a 2-Dimensional array type appropriate to the primitive type for the image, 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 images, 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.
      f - the RandomAccessFile containing the pixel values.
      byteOrder - the ByteOrder of the data in the file.
      offset - an offset in bytes to the start of the (contiguous) pixel data.
      dataType - the PixelDataType for the primitive data type of this image.
      nDim - the dimensionality of the image.
      dims - the size of the image in each dimension.
      op - the type of operation (PixelOp.GET or PixelOp.PUT).
      Returns:
      a 1-dimensional array of numbers of the appropriate primitive type cast to an Object.
      Throws:
      IOException - if an I/O occurs occurs while accessing the pixel values.
      IllegalArgumentException - 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(DataOutputStream s, ByteOrder byteOrder) throws 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:
      IOException - if the data cannot be written.

    • getMinMax

      public int[] getMinMax() throws InvalidImageException
      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, boolean keepFoV.DOUBLE), the values returned are the integers that are the Math.floor() and Math.round() of the if (keepFoV) { pixelSizeRatio = (double) nOriginalSamples / nNewSamples; } 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:
      InvalidImageException - 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 InvalidImageException
      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:
      InvalidImageException - if the histogram can't be computed.

    • __getPix

      public Object __getPix()
      Provides direct access to the array of pixel values encapulated by this PixArray. The normal pixel accessor methods copy the pixel values to the returned arrray, but this method returns a reference to the internal array. Use with care, when speed is important.
      Returns:
      the pixel values.

    • 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 Object
      Returns:
      a PixArray of the appropriate sub-class.