Class ImageUtils

java.lang.Object
com.xinapse.image.ImageUtils
public abstract class ImageUtils extends Object
Contains various image utility static methods.

  • Field Details

    • DEFAULT_IMAGE_CLASS

      public static final Class<? extends WritableImage> DEFAULT_IMAGE_CLASS
      The default image class to work with, if the user has no Preference.

  • Method Details

    • getOutputImageClass

      public static Class<? extends WritableImage> getOutputImageClass()
      Returns the Class for the creation of output images, if the Class is not specified implicitly.

      The Class returned depend on the setting of the System Property given by Props.OUTPUT_TYPE_PROPERTY if set. If not set, it depends on the value set in the user Preferences, or the default DEFAULT_IMAGE_CLASS.

      Returns:
      the Class of WritableImage for writing images.

    • getPreferredImageClass

      public static Class<? extends WritableImage> getPreferredImageClass()
      Returns the WritableImage class set in the user's Preferences.
      Returns:
      the WritableImage class that has been set in the user's Preferences as the one that the user most often works with.

    • savePreferredImageClass

      public static void savePreferredImageClass(Class<? extends WritableImage> imageClass)
      Saves the supplied class to the user's Preferences.
      Parameters:
      imageClass - the {Class<? extends WritableImage> that the user most often works with, and which will be set as the default to use when this Class loads.

    • getWritableImageClasses

      public static List<Class<? extends WritableImage>> getWritableImageClasses()
      Returns a List of classes that are known to implement WritableImage.
      Returns:
      a List of classes that implement WritableImage.

    • getWritableImageCommonName

      public static String getWritableImageCommonName(Class<? extends WritableImage> imageClass)
      Returns the "common name" (for example, "NIFTI-1") for a Class of WritableImage.
      Parameters:
      imageClass - the WritableImage Class.
      Returns:
      the common name for the image class.

    • getWritableImageClass

      public static Class<? extends WritableImage> getWritableImageClass(Object image)
      Returns the WritableImage Class that can be deduced from the supplied image, or the WritableImage Class set in the user's Preferences.
      Parameters:
      image - the Object from which to deduce the WritableImage Class.
      Returns:
      the WritableImage Class deduced from the supplied Object, set in the System Properties, or the user's preferred WritableImage Class.

    • getWritableImageClass

      public static Class<? extends WritableImage> getWritableImageClass(String className) throws ClassNotFoundException, ClassCastException
      Returns the WritableImage Class that is assignable from the supplied class name.
      Parameters:
      className - the fully-qualified name of the Class to be assigned, or its "common name" (the name returned by the WritableImage.getImageTypeName() method).
      Returns:
      the WritableImage Class that is assignable from the supplied class name.
      Throws:
      ClassCastException - if the Class name supplied cannot be assigned to WritableImage class.
      ClassNotFoundException - if a Class with the supplied name cannot be found.

    • getWritableImageClass

      public static Class<? extends WritableImage> getWritableImageClass(Class<? extends Object> clazz) throws ClassCastException
      Returns the WritableImage Class that is assignable from the supplied class, or if not assignable, the WritableImage Class set in the system properties or in the user's Preferences.
      Parameters:
      clazz - the Class to be assigned.
      Returns:
      the WritableImage Class that is assignable from the supplied class, the system properties or the user's preferred WritableImage Class.
      Throws:
      ClassCastException

    • getReadableImage

      public static ReadableImage getReadableImage(String fileName, Logger logger) throws InvalidImageException
      Returns a ReadableImage, reading the image data from a file.
      Parameters:
      fileName - the name (path) of the image file.
      logger - the Logger for verbose reporting and error messages.
      Returns:
      a ReadableImage obtained from the file.
      Throws:
      InvalidImageException - if the file does not yield a valid WritableImage.

    • getWritableImage

      public static WritableImage getWritableImage(String fileName, Logger logger) throws InvalidImageException
      Returns a WritableImage (opened read-write), reading the image data from a file.
      Parameters:
      fileName - the name (path) of the image file.
      logger - the Logger for verbose reporting and error messages.
      Returns:
      a WritableImage obtained from the file.
      Throws:
      InvalidImageException - if the file does not yield a valid WritableImage.

    • getReadableImage

      public static ReadableImage getReadableImage(File f, Logger logger) throws InvalidImageException
      Returns a ReadableImage, reading the image data from a file.
      Parameters:
      f - the image file.
      logger - the Logger for verbose reporting and error messages.
      Returns:
      a ReadableImage obtained from the file.
      Throws:
      InvalidImageException - if the file does not yield a valid WritableImage.

    • getWritableImage

      public static WritableImage getWritableImage(File f, Logger logger) throws InvalidImageException
      Returns a WritableImage (opened read-write), reading the image data from a file.
      Parameters:
      f - the image file.
      logger - the Logger for verbose reporting and error messages.
      Returns:
      a WritableImage obtained from the file.
      Throws:
      InvalidImageException - if the file does not yield a valid WritableImage.

    • getWritableImage

      public static WritableImage getWritableImage(ReadableImage templateImage) throws InvalidImageException
      Returns a WritableImage that is a copy of the image supplied.
      Parameters:
      templateImage - the ReadableImage on which to base the copy.
      Returns:
      the new WritableImage that is created.
      Throws:
      InvalidImageException - if the supplied ReadableImage is invalid.

    • getWritableImage

      public static WritableImage getWritableImage(ReadableImage templateImage, PixelDataType pixelDataType) throws InvalidImageException
      Returns a WritableImage that is a copy of the image supplied except that the stored and presentation PixelDataType may be changed. If necessary, the pixel values from the templateImage will be coerced and clipped to fit within the intensity range of the returned image.
      Parameters:
      templateImage - the ReadableImage on which to base the copy.
      pixelDataType - the requested presentation PixelDataType for the returned WritableImage.
      Returns:
      the new WritableImage that is created.
      Throws:
      InvalidImageException - if the supplied ReadableImage is invalid or the data type requirements cannot be met.

    • getWritableImage

      public static WritableImage getWritableImage(ReadableImage templateImage, PixelDataType storedDataType, PixelDataType presentationDataType) throws InvalidImageException
      Returns a WritableImage that is a copy of the image supplied except that the stored and presentation PixelDataType may be changed. If necessary, the pixel values from the templateImage will be coerced and clipped to fit within the intensity range of the returned image.
      Parameters:
      templateImage - the ReadableImage on which to base the copy.
      storedDataType - the requested stored PixelDataType for the returned WritableImage.
      presentationDataType - the requested presentation PixelDataType for the returned WritableImage.
      Returns:
      the new WritableImage that is created.
      Throws:
      InvalidImageException - if the supplied ReadableImage is invalid or the data type requirements cannot be met.

    • getWritableImage

      public static WritableImage getWritableImage(ReadableImage templateImage, int nSlices) throws InvalidImageException
      Returns a WritableImage that is a copy of the image supplied except that the number of image slices may be changed.
      Parameters:
      templateImage - the ReadableImage on which to base the copy.
      nSlices - the number of slices for the new image.
      Returns:
      the new WritableImage that is created.
      Throws:
      InvalidImageException - if the supplied ReadableImage is invalid.

    • getWritableImage

      public static WritableImage getWritableImage(ReadableImage templateImage, int nDim, int[] dims) throws InvalidImageException
      Returns a WritableImage that is a copy of the image supplied except that the image dimensionality and dimensions may be changed.
      Parameters:
      templateImage - the ReadableImage on which to base the copy.
      nDim - the dimensionality for the new image.
      dims - the dimensions of the new image.
      Returns:
      the new WritableImage that is created.
      Throws:
      InvalidImageException - if the supplied ReadableImage is invalid.

    • getWritableImage

      public static WritableImage getWritableImage(ReadableImage templateImage, Class<? extends WritableImage> toImageClass) throws InvalidImageException
      Returns a WritableImage that is a copy of the image supplied except that the class of the image may be changed.
      Parameters:
      templateImage - the image on which to base the copy.
      toImageClass - the class of the new image.
      Returns:
      the new WritableImage that is created.
      Throws:
      InvalidImageException - if the supplied image is invalid.

    • getWritableImage

      public static WritableImage getWritableImage(ReadableImage templateImage, Class<? extends WritableImage> toImageClass, int nSlices, PixelDataType storedDataType, PixelDataType presentationDataType) throws InvalidImageException
      Creates a new WritableImage with the class of WritableImage class given by the argument, possibly changing the number of slices in the image and the PixelDataType.

      If the number of slices requested for the new image is less than the original, only the first slices will be copied to the new image. If the number of slices requested for the new image is more than the original, the additional slices will be filled with zero pixel values, and the slice-specific information will be empty.

      Parameters:
      templateImage - the image on which to base the copy.
      toImageClass - the class of the new image.
      nSlices - the number of slices for the new image. as necessary to fit within the intensity range of the storedDataType.
      storedDataType - the requested stored PixelDataType for the returned WritableImage.
      presentationDataType - the requested presentation PixelDataType for the returned WritableImage.
      Returns:
      the new WritableImage that is created.
      Throws:
      InvalidImageException - if the supplied image is invalid.

    • getWritableImage

      public static WritableImage getWritableImage(ReadableImage templateImage, Class<? extends WritableImage> toImageClass, int nDim, int[] dims, PixelDataType pixelDataType) throws InvalidImageException
      Creates a new WritableImage with the class of WritableImage class given by the argument, possibly changing the number of slices in the image and the PixelDataType.

      If the number of slices requested for the new image is less than the original, only the first slices will be copied to the new image. If the number of slices requested for the new image is more than the original, the additional slices will be filled with zero pixel values, and the slice-specific information will be empty.

      Parameters:
      templateImage - the image on which to base the copy.
      toImageClass - the class of the new image.
      nDim - the dimensionality of the new image.
      dims - the image dimensions.
      pixelDataType - the requested stored and presentation PixelDataType for the returned WritableImage.
      Returns:
      the new WritableImage that is created.
      Throws:
      InvalidImageException - if the supplied image is invalid.

    • getWritableImage

      public static WritableImage getWritableImage(ReadableImage templateImage, Class<? extends WritableImage> toImageClass, int nDim, int[] dims, PixelDataType storedDataType, PixelDataType presentationDataType) throws InvalidImageException
      Creates a new WritableImage with the class of WritableImage class given by the argument, possibly changing the number of slices in the image and the PixelDataType.

      If the number of slices requested for the new image is less than the original, only the first slices will be copied to the new image. If the number of slices requested for the new image is more than the original, the additional slices will be filled with zero pixel values, and the slice-specific information will be empty.

      Parameters:
      templateImage - the image on which to base the copy.
      toImageClass - the class of the new image.
      nDim - the dimensionality for the new image.
      dims - the dimensions of the new image.
      storedDataType - the requested stored PixelDataType for the returned WritableImage.
      presentationDataType - the requested presentation PixelDataType for the returned WritableImage.
      Returns:
      the new WritableImage that is created.
      Throws:
      InvalidImageException - if the supplied image is invalid.

    • checkIndices

      public static void checkIndices(ReadableImage image, int[] pixIdx) throws IllegalArgumentException
      Checks compatibility of the pixel indices that reference a particular pixel of an image. Checking ensures that the pixel addressed by the indices is within the bounds of the image.
      Parameters:
      image - the image against which the indices will be checked.
      pixIdx - an array where each element of the array is an index to one dimension of the image.
      Throws:
      IllegalArgumentException - if the supplied indices are bad for this image.

    • getNPixels

      public static int getNPixels(int nDim, int[] dims) throws IllegalStateException
      Returns the total number of picture elements for an image with the given dimensions.
      Parameters:
      nDim - the dimensionality of the image.
      dims - the size of the image in each dimension.
      Returns:
      the total number of pixels for an image with the given dimensions.
      Throws:
      IllegalStateException - if the dimensionality is illegal, or if the image is too large (has more than 231-1 pixels).

    • checkMinMax

      public static void checkMinMax(int min, int max, PixelDataType dataType) throws InvalidImageException
      Checks the integrity of the minimum and maximum pixel values taking into account the data type of the image.
      Parameters:
      min - the putative minimum pixel value.
      max - the putative maximum pixel value.
      dataType - the PixelDataType for the image.
      Throws:
      InvalidImageException - if the min/max values are unsuitable for this image.

    • isImage

      public static boolean isImage(File f) throws FileNotFoundException
      Tests whether the supplied File refers to a WritableImage file.
      Parameters:
      f - the File to be tested.
      Returns:
      true if the supplied File refers an image file; false otherwise.
      Throws:
      FileNotFoundException - if the file does not exist.

    • imageExists

      public static boolean imageExists(String filename, Class<? extends WritableImage> imageClass)
      Tests whether a WritableImage with the given name already exists on disk. Analyze/NIFTI/DICOM file extensions are handled in a smart fashion.
      Parameters:
      filename - the name of the image file to test for existence.
      imageClass - the Class of WritableImage for which to test existence.
      Returns:
      true if an image with the specified file name exists on disk; false otherwise.

    • deleteImage

      public static boolean deleteImage(String filename, Class<? extends ReadableImage> c)
      Attempts to delete an image of the given Class<? extends WritableImage> with the given name.
      Parameters:
      filename - the name of the image file that is to be deleted.
      c - the class of image to delete; used to help find which file of is correct one to delete, which may be useful if the file name is given without extension and multiple images with the same base name exist.
      Returns:
      true if the image file is successfully deleted, or if the image file did not exist in the first place.

    • getImageCentrePatient

      public static org.jogamp.vecmath.Point3f getImageCentrePatient(ReadableImage image) throws InvalidImageException
      Returns the coordinates of the center of the block of slices of an image, in mm, in patient coordinates.
      Parameters:
      image - the image for which to find the centre location.
      Returns:
      a the Point3f corresponding to the Left,Posterior,Superior (LPS) coordinates of the centre of the block of slices for the image. Returns null if the position cannot be retrieved from the image.
      Throws:
      InvalidImageException - if the image is invalid.

    • reorientRadiological

      public static void reorientRadiological(ReadableImage image, Object pix)
      Reorients a set of pixels for an image so that they will be presented in standard radiological orientation. This is:
      • For axial images, increasing left coordinate with column number, and increasing posterior coordinate with row number.
      • For coronal images, increasing left coordinate with column number, and increasing inferior coordinate with row number.
      • For sagittal images, increasing posterior coordinate with column number, and increasing inferior coordinate with row number.
      If the orientation of the image slice cannot be found, then nothing is done.
      Parameters:
      image - the ReadableImage for which the pixels are to be reoriented.
      pix - the array of pixels to reorient. The reorientation is done in-place.

    • setOrientationPositionRadiological

      public static void setOrientationPositionRadiological(org.jogamp.vecmath.Vector3f[] orientation, org.jogamp.vecmath.Point3f position, int nCols, int nRows, float pixelXSize, float pixelYSize)
      Reorientates the image orientation vectors, and repositions an image position so that the positions and orientations refer to blocks of image pixels that have been gotten in an anatomical orientation.

      This method works out the way in which an image slice with the supplied orientation and position will be presented radiologically, and sets the orientation and position "in place" correctly for the image slice as presented radiologically.

      Parameters:
      orientation - the current orientation of the image slice.
      position - the current position of the image slice.
      nCols - the number of columns in the image.
      nRows - the number of rows in the image.
      pixelXSize - the pixel size along a row.
      pixelYSize - the pixel size down a column.

    • getSlicesAreReversed

      public static boolean getSlicesAreReversed(ReadableImage image)
      Tests whether the supplied image has slices which are in reverse order compared to standard radiological presentation order.
      Parameters:
      image - the image for which to test the slice order.
      Returns:
      true if the slices are in reverse order compared to standard radiological presentation order; false otherwise.

    • set3DBlockParameters

      public static void set3DBlockParameters(WritableImage image) throws IOException, InvalidImageException
      For an image which contains multiple slices with all slices parallel and regularly-spaced, this method will modify the image position (patient coords), image orientation (patient coords) and pixel spacing (pixel sizes) according to the block.

      Images that do not consist of a single block of parallel, equally-spaced slices are unaffeted by this method.

      Parameters:
      image - the image for which the parameters are to be set.
      Throws:
      InvalidImageException - if the image information cannot be modified.
      IOException - if an I/O error occurs.

    • reSample

      public static WritableImage reSample(ReadableImage image, int[] newDims, InterpolationType interpolationType, SubSampleType subSampleType, MonitorWorker worker, Logger logger) throws InvalidArgumentException, InvalidImageException, CancelledException
      Resamples an existing image to have different numbers of pixels. The newDims array specifies the new number of pixels in each dimension of the image.
      Parameters:
      image - the image to be resampled.
      newDims - the number of samples in each of the dimensions of the image. newDims must have the same number of elements as there are dimensions in this image. The integer in each element of the array specifies the number of samples in each dimension for the resampled image. The column dimension is the last array element; the row dimension is the next-to-last; the slice dimension is the second-from-last, and the time dimension is the third-from-last. Any dimensions that are below the time dimension are ignored, and no resampling will occur in these dimensions.
      interpolationType - the type of interpolation to used if the number of samples increases in any dimension.
      subSampleType - the type of sub-sampling to be used if the pixel size is increased in any dimension.
      worker - if non-null, a ProgressMonitor may be created, showing the progress of the resampling.
      logger - the Logger for logging verbose, warning and error messages.
      Returns:
      a new WritableImage based on the supplied image, but resampled to the specified number of samples.
      Throws:
      InvalidArgumentException - if the new dimensions are unsuitable for resampling the supplied image.
      InvalidImageException - if any of the new number of samples is less than or equal to zero, or if the length of the newDims array is incorrect for this image.
      CancelledException - if resampling is cancelled via the ProgressMonitor that may pop up.

    • autoResample

      public static WritableImage autoResample(ReadableImage image, int maxNVoxels, SubSampleType subSampleType, boolean allowSliceResample, MonitorWorker worker, Logger logger) throws InvalidImageException, CancelledException
      Automatically resamples a ReadableImage so that the resulting resampled image has no more than the given maximum number of voxels.

      The numbers of samples will be calculated to give a more isotropic resolution. The algorithm will reduce the number of samples (if necessary) in any or all dimensions so that the resulting image has no more than the specified number of voxels, but the number of samples in any direction will never be increased to try to achieve isotropic resolution.

      The number of voxels may be less than the maximum because the resulting image will always have the same field of view as this image, and the number of samples in each dimension must (of course) be a whole number.

      Resampling of the fourth dimension of 4-D images does not take place, only of the three spatial dimensions. Images with dimensionality greater than 4 may not ne resampled with this method.

      Parameters:
      image - the image to be resampled.
      maxNVoxels - maximum number of voxels allowed in the resampled image.
      subSampleType - the type of sub-sampling to be used if the pixel size is increased in any dimension.
      allowSliceResample - if true, resampling of pixels in the slice direction is allowed; if false, resampling in the slice direction is disallowed.
      worker - if non-null, the MonitorWorker that is checked for cancellation.
      logger - the Logger for logging verbose, warning and error messages.
      Returns:
      a resampled image with no more than the specified maximum number of voxels, or the original image if it already has fewer voxels than the specified maximum.
      Throws:
      InvalidImageException - if the image dimensionality is greater than 4. or equal to zero, or if the length of the newDims array is incorrect for this image.
      CancelledException - if resampling is cancelled via the ProgressMonitor that may pop up.

    • reSample

      public static WritableImage reSample(ReadableImage image, float[] newPixelSizes, InterpolationType interpolationType, SubSampleType subSampleType, MonitorWorker worker, Logger logger) throws InvalidArgumentException, InvalidImageException, CancelledException
      Resamples an existing ReadableImage to have different pixel sizes. The newPixelSizes array specifies the physical size of pixels in each dimension of the image that has a physical "size". If, for any dimension of this image, the pixel size cannot be found, or if the pixel size is invalid, that dimension is not resampled. reSample does not know how to resample in any dimension greater than 4; in any image with dimensions higher than 4, higher dimensions are are not resampled, since reSample cannot find the pixel size in these dimensions. Any new pixel sizes you set for these higher dimensions will be ignored.
      Parameters:
      image - the image to be resampled.
      newPixelSizes - the physical pixel size in each of the dimensions of the image. newPixelSizes must have the same number of elements as there are dimensions in this image. The floating point number in each element of the array specifies the pixel size in each dimension for the resampled image. The column dimension is the last array element; the row dimension is the next-to-last; the slice dimension is the second-from-last, and the time dimension is the third-from-last. Any other dimensions are ignored.
      interpolationType - the type of interpolation to be used if the pixel size is reduced in any dimension.
      subSampleType - the type of sub-sampling to be used if the pixel size is increased in any dimension.
      worker - if non-null, a ProgressMonitor may be created, showing the progress of the resampling.
      logger - the Logger for logging verbose, warning and error messages.
      Returns:
      a new WritableImage like the supplied image, but resampled to the specified pixel sizes.
      Throws:
      InvalidArgumentException - if the array of pixel sizes is unsuitable for resampling the supplied image.
      InvalidImageException - if any of the new pixel sizes is not positive, or if the length of the newPixelSizes array is insufficient for this image.
      CancelledException - if resampling is cancelled via the ProgressMonitor that may pop up.

    • rotate

      public static WritableImage rotate(ReadableImage image, RotationAngle rotationAngle, MonitorWorker worker, Logger logger) throws InvalidArgumentException, InvalidImageException, IOException, CancelledException
      Rotates a ReadableImage in multiples of 90 degrees.
      Parameters:
      image - the image to be rotated.
      rotationAngle - the RotationAngle.
      worker - if non-null, a ProgressMonitor may be created, showing the progress of the rotation.
      logger - the Logger for logging verbose, warning and error messages.
      Returns:
      a new WritableImage of the same class as the input image (if the input image is also a WritableImage), but rotated.
      Throws:
      InvalidArgumentException - if the image is unsuitable for rotating.
      InvalidImageException - if the supplied image is invalid.
      IOException - if an I/O error occurs.
      CancelledException - if rotation is cancelled via the ProgressMonitor that may pop up.

    • flip

      public static WritableImage flip(ReadableImage image, boolean flipHorizontally, boolean flipVertically, boolean flipSlices, MonitorWorker worker, Logger logger) throws InvalidImageException, CancelledException
      Flips the image data in a ReadableImage. Only the image data are affected by the flip operation. Any orientation information stored in the image header is copied to the output image unchanged. Thus, this method is suitable for correcting the orientation of images where it is known that the orientation stored in the image header does not match that displayed on screen, and the error can be corrected by simple flips
      Parameters:
      image - the image to be flipped.
      flipHorizontally - if the image is to be flipped about a vertical axis.
      flipVertically - if the image is to be flipped about a horizontal axis.
      flipSlices - if the slice order is to be reversed.
      worker - if non-null, a ProgressMonitor may be created, showing the progress of the flipping.
      logger - the Logger for logging verbose, warning and error messages.
      Returns:
      a new WritableImage of the same class as the input image (if the input image is also a WritableImage), but with the image data flipped as specified.
      Throws:
      InvalidImageException - if the supplied image is invalid, or unsuitable for flipping as requested.
      CancelledException - if flipping is cancelled via the ProgressMonitor that may pop up.

    • reorient

      public static WritableImage reorient(ReadableImage image, MostLikePlane newOrientation, MostLikePlane currentOrientation, Boolean slicesAreReversed, MonitorWorker worker, Logger logger) throws InvalidImageException, CancelledException
      Reorients a ReadableImage. The newOrientation sets the orientation of the reoriented image. If non-null, currentOrientation specifies the orientation of this image. If currentOrientation is null, this method will try to determine the orientation of this image.
      Parameters:
      image - the image to be reoriented.
      newOrientation - the MostLikePlane of the required new orientation.
      currentOrientation - the MostLikePlane of the current orientation, or null to force an attempt to determine the orientation automatically.
      slicesAreReversed - if non-null, specifies whether the slices are in reverse order compared to standard radiological order (which is:
      • axial: increasing superior coordinate with slice number
      • coronal: increasing posterior coordinate with slice number
      • sagittal: increasing left coordinate with slice number
      If null, the slice order is determined from the image header.
      worker - if non-null, a ProgressMonitor may be created, showing the progress of the reorientation.
      logger - the Logger for logging verbose, warning and error messages.
      Returns:
      a new WritableImage of the same class as the input image (if the input image is also a WritableImage), but reoriented to the specified new orientation.
      Throws:
      InvalidImageException - if currentOrientation is null, and the orientation of this image cannot be determined.
      CancelledException - if reorienting is cancelled via the ProgressMonitor that may pop up.

    • reverseSlices

      public static void reverseSlices(WritableImage image, MonitorWorker worker, Logger logger) throws InvalidImageException, CancelledException
      Reverses the slice order of a WritableImage in place. The only operation performed is to replace the pixel data for the first slice with that for the last slice; the image data for the second slice with that for the next-to-last slice, etc.
      Parameters:
      image - the image to have its slice order reversed.
      worker - if non-null, a ProgressMonitor may be created, showing the progress of the slice reversal..
      logger - the Logger for logging verbose, warning and error messages.
      Throws:
      InvalidImageException - if the supplied image is invalid.
      CancelledException - if reorienting is cancelled via the ProgressMonitor that may pop up.

    • crop

      public static WritableImage crop(ReadableImage image, int[][] cropDims, MonitorWorker worker, Logger logger) throws InvalidArgumentException, InvalidImageException, CancelledException
      Crops a WritableImage to produce a new image. The cropDims array specifies the range of pixel indices in each dimension of the image from which to select a block of pixels.
      Parameters:
      image - the image to crop.
      cropDims - the low and high indices (referenced from zero; high index is exclusive) of samples in each of the dimensions of the image. cropDims must have the same number of elements as there are dimensions in this image, and each element must be an array of length 2. The first element of each array specifies the low pixel index for that dimension, and the second element of the array specifies the high pixel index (exclusive) to select for the cropped image. The column dimension is the last array element; the row dimension is the next-to-last; the slice dimension is the second-from-last etc.
      worker - if non-null, a ProgressMonitor may be created, showing the progress of the cropping.
      logger - the Logger for logging verbose, warning and error messages.
      Returns:
      a new WritableImage of the same class as the input image (if the input image is also a WritableImage), but cropped to the specified range of pixels.
      Throws:
      InvalidArgumentException - if any of the indices is less than zero, or greater than the number of samples, or if the size of the cropDims array is incorrect for this image.
      InvalidImageException - if the cropped image cannot be created.
      CancelledException - if cropping is cancelled via the ProgressMonitor that may pop up.

    • autoCrop

      public static WritableImage autoCrop(ReadableImage image, Logger logger) throws InvalidImageException
      Automatically crop an image to remove regions of background. The threshold for separating the foreground from the background is selected using the Otsu method.
      Parameters:
      image - the image to crop.
      logger - the Logger for error/warning messages, or null.
      Returns:
      a new WritableImage of the same class as the input image (if the input image is also a WritableImage), but cropped to remove the background.
      Throws:
      InvalidImageException - if the cropped image cannot be created.

    • autoCrop

      public static WritableImage autoCrop(ReadableImage image, Double threshold, Logger logger) throws InvalidImageException
      Automatically crop an image to remove regions of background.
      Parameters:
      image - the image to crop.
      threshold - if non-null, the intensity threshold that separates the foreground from the background. If null, the threshold is selected using the Otsu method.
      logger - the Logger for error/warning messages, or null.
      Returns:
      a new WritableImage of the same class as the input image (if the input image is also a WritableImage), but cropped to remove the background.
      Throws:
      InvalidImageException - if the cropped image cannot be created.

    • autoCrop

      public static WritableImage autoCrop(ReadableImage image, MonitorWorker worker, Logger logger) throws InvalidImageException, CancelledException
      Automatically crop an image to remove regions of background. The threshold for separating the foreground from the background is selected using the Otsu method.
      Parameters:
      image - the image to crop.
      worker - if non-null, the MonitorWorker that can be used to cancel the operation.
      logger - the Logger for logging verbose, warning and error messages.
      Returns:
      a new WritableImage of the same class as the input image (if the input image is also a WritableImage), but cropped to remove the background.
      Throws:
      InvalidImageException - if the cropped image cannot be created.
      CancelledException - if cropping is cancelled via the ProgressMonitor that may pop up.

    • autoCrop

      public static WritableImage autoCrop(ReadableImage image, Double threshold, MonitorWorker worker, Logger logger) throws InvalidImageException, CancelledException
      Automatically crop an image to remove regions of background.
      Parameters:
      image - the image to crop.
      threshold - if non-null, the intensity threshold that separates the foreground from the background. If null, the threshold is selected using the Otsu method.
      worker - if non-null, the MonitorWorker that can be used to cancel the operation.
      logger - the Logger for logging verbose, warning and error messages.
      Returns:
      a new WritableImage of the same class as the input image (if the input image is also a WritableImage), but cropped to remove the background.
      Throws:
      InvalidImageException - if the cropped image cannot be created.
      CancelledException - if cropping is cancelled via the ProgressMonitor that may pop up.

    • getAutoCropDims

      public static int[][] getAutoCropDims(ReadableImage image, Double threshold, MonitorWorker worker, boolean slicesOnly) throws InvalidImageException, CancelledException
      Returns the crop dimensions that will to remove regions of background in an image. This method allows the crop dimensions to be found from one image, and then applied to a series of images of the same original dimensions.
      Parameters:
      image - the image from which to find the to crop dimensions.
      threshold - if non-null, the intensity threshold that separates the foreground from the background. If null, the threshold is selected using the Otsu method.
      worker - if non-null, the MonitorWorker that can be used to cancel the operation.
      slicesOnly - if cropping is to be done only in the slice direction.
      Returns:
      the crop dimensions that can be used to subsequently crop images.
      Throws:
      InvalidImageException - if the image is invalid.
      CancelledException - if cropping is cancelled via the ProgressMonitor that may pop up.

    • autoCropSlices

      public static WritableImage autoCropSlices(ReadableImage image, Logger logger) throws InvalidImageException
      Automatically crop an image to remove slices that only contain background. The threshold for separating the foreground from the background is selected using the Otsu method.
      Parameters:
      image - the image from which to crop slices with only background.
      logger - the Logger for verbose reporting and error messages.
      Returns:
      a new WritableImage of the same class as the input image (if the input image is also a WritableImage), but cropped to remove the background slices.
      Throws:
      InvalidImageException - if the cropped image cannot be created.

    • autoCropSlices

      public static WritableImage autoCropSlices(ReadableImage image, Double threshold, Logger logger) throws InvalidImageException
      Automatically crop an image to remove slices that only contain background.
      Parameters:
      image - the image from which to crop slices with only background.
      threshold - if non-null, the intensity threshold that separates the foreground from the background. If null, the threshold is selected using the Otsu method.
      logger - the Logger for verbose reporting and error messages.
      Returns:
      a new WritableImage of the same class as the input image (if the input image is also a WritableImage), but cropped to remove the background slices.
      Throws:
      InvalidImageException - if the cropped image cannot be created.

    • autoCropSlices

      public static WritableImage autoCropSlices(ReadableImage image, MonitorWorker worker, Logger logger) throws InvalidImageException, CancelledException
      Automatically crop an image to remove slices that only contain background. The threshold for separating the foreground from the background is selected using the Otsu method.
      Parameters:
      image - the image from which to crop slices with only background.
      worker - if non-null, the MonitorWorker that can be used to cancel the operation.
      logger - the Logger for verbose reporting and error messages.
      Returns:
      a new WritableImage of the same class as the input image (if the input image is also a WritableImage), but cropped to remove the background slices.
      Throws:
      InvalidImageException - if the cropped image cannot be created.
      CancelledException - if cropping is cancelled via the ProgressMonitor that may pop up.

    • autoCropSlices

      public static WritableImage autoCropSlices(ReadableImage image, Double threshold, MonitorWorker worker, Logger logger) throws InvalidImageException, CancelledException
      Automatically crop an image to remove slices that only contain background.
      Parameters:
      image - the image from which to crop slices with only background.
      threshold - if non-null, the intensity threshold that separates the foreground from the background. If null, the threshold is selected using the Otsu method.
      worker - if non-null, the MonitorWorker that can be used to cancel the operation.
      logger - the Logger for logging verbose, warning and error messages.
      Returns:
      a new WritableImage of the same class as the input image (if the input image is also a WritableImage), but cropped to remove the background slices.
      Throws:
      InvalidImageException - if the cropped image cannot be created.
      CancelledException - if cropping is cancelled via the ProgressMonitor that may pop up.

    • autoCrop

      public static WritableImage[] autoCrop(ReadableImage[] images, Logger logger) throws InvalidImageException
      Automatically crops an array of images to remove regions which are background in any of the images. All input images must be of the same dimensions. The threshold for separating the foreground from the background is selected using the Otsu method.
      Parameters:
      images - the images to crop.
      logger - the Logger for verbose reporting and error messages.
      Returns:
      a new WritableImage array of the same classes as the input images (if the input image is also a WritableImage), but cropped to remove the background. All returned images will have the same dimensions, and regions which are background in any of the imnput images will be cropped.
      Throws:
      InvalidImageException - if the cropped images cannot be created.

    • autoCrop

      public static WritableImage[] autoCrop(ReadableImage[] images, Double threshold, Logger logger) throws InvalidImageException
      Automatically crops an array of images to remove regions which are background in any of the images. All input images must be of the same dimensions.
      Parameters:
      images - the images to crop.
      threshold - if non-null, the intensity threshold that separates the foreground from the background. If null, the threshold is selected using the Otsu method.
      logger - the Logger for verbose reporting and error messages.
      Returns:
      a new WritableImage array of the same classes as the input images (if the input image is also a WritableImage), but cropped to remove the background. All returned images will have the same dimensions, and regions which are background in any of the imnput images will be cropped.
      Throws:
      InvalidImageException - if the cropped images cannot be created.

    • autoCrop

      public static WritableImage[] autoCrop(ReadableImage[] images, MonitorWorker worker, Logger logger) throws InvalidImageException, CancelledException
      Automatically crops an array of images to remove regions which are background in any of the images. All input images must be of the same dimensions. The threshold for separating the foreground from the background is selected using the Otsu method.
      Parameters:
      images - the images to crop.
      worker - if non-null, the MonitorWorker that can be used to cancel the operation.
      logger - the Logger for logging verbose, warning and error messages.
      Returns:
      a new WritableImage array of the same classes as the input images (if the input image is also a WritableImage), but cropped to remove the background. All returned images will have the same dimensions, and regions which are background in any of the imnput images will be cropped.
      Throws:
      InvalidImageException - if the cropped images cannot be created.
      CancelledException - if cropping is cancelled via the ProgressMonitor that may pop up.

    • autoCrop

      public static WritableImage[] autoCrop(ReadableImage[] images, Double threshold, MonitorWorker worker, Logger logger) throws InvalidImageException, CancelledException
      Automatically crops an array of images to remove regions which are background in any of the images. All input images must be of the same dimensions.
      Parameters:
      images - the images to crop.
      threshold - if non-null, the intensity threshold that separates the foreground from the background. If null, the threshold is selected using the Otsu method.
      worker - if non-null, the MonitorWorker that can be used to cancel the operation.
      logger - the Logger for logging verbose, warning and error messages.
      Returns:
      a new WritableImage of the same class as the input image (if the input image is also a WritableImage), but cropped to remove the background.
      Throws:
      InvalidImageException - if the cropped images cannot be created.
      CancelledException - if cropping is cancelled via the ProgressMonitor that may pop up.

    • pad

      public static WritableImage pad(ReadableImage image, int[] padDims, MonitorWorker worker, Logger logger) throws InvalidArgumentException, InvalidImageException, CancelledException
      Pads a WritableImage with zero-intensity pixels around the edge of the image. The padDims array specifies the number of samples in each dimension of the padded image. The zero-intensity pixels are distributed as evenly as possible to either side of the current field of view (within the constrains imposed by odd/even numbers of pixel samples).
      Parameters:
      image - the image to pad.
      padDims - the number of samples in each dimension of the image for the padded image. padDims must have the same number of elements as there are dimensions in this image. The column dimension is the last array element; the row dimension is the next-to-last; the slice dimension is the second-from-last etc. If any value is less than the number of samples in the current image, then the number of samples in that dimension is unchanged in the new image.
      worker - if non-null, a ProgressMonitor may be created, showing the progress of the padding.
      logger - the Logger for logging verbose, warning and error messages.
      Returns:
      a new WritableImage of the same class as the input image (if the input image is also a WritableImage), but padded to the specified number of pixel samples.
      Throws:
      InvalidArgumentException - if the size of the padDims array is incorrect for this image.
      InvalidImageException - if the padded image cannot be created.
      CancelledException - if padding is cancelled via the ProgressMonitor that may pop up.

    • getAutoContrastMinMax

      public static double[] getAutoContrastMinMax(ReadableImage image, ComplexMode complexMode) throws InvalidImageException
      Returns suitable minimum and maximum pixel intensities for displaying an image.
      Parameters:
      image - the image which will be displayed.
      complexMode - if non-null the ComplexMode for complex image display.
      Returns:
      an array of length 2 containing the minimum and maximum display contrast settings, in that order.
      Throws:
      InvalidImageException - if the image intensity histogram is needed but can't be formed.

    • getAutoContrastMinMax

      public static double[] getAutoContrastMinMax(PixelDataType dataType, Histogram histo, ComplexMode complexMode)
      Returns suitable minimum and maximum pixel intensities for displaying an image.
      Parameters:
      dataType - the image PixelDataType.
      histo - the Histogram of pixel intensities.
      complexMode - if non-null, the ComplexMode for complex image display.
      Returns:
      an array of length 2 containing the minimum and maximum display contrast settings, in that order.

    • export

      public static void export(ReadableImage image, String suffix, String filename, ColourMapping cm, double displayMin, double displayMax, ComplexMode complexMode, int slicesPerRow, Logger logger) throws IOException, InvalidImageException, CancelledException
      Writes an image to a disk file in a picture format (such as JPEG, GIF etc.), creating the disk image from this WritableImage, by drawing all of the slices in a raster of slices.

      The first slice will be at the top left of the image, and the image is filled across the row of slices before moving down to the next row. The width of the disk image (in pixels) will either be the number of columns in the WritableImage multiplied by the number of slicesPerRow, or 1024, whichever is the smaller.

      Parameters:
      image - the image to export.
      suffix - the suffix describing the type of image to be created. Currently, must be one of:
      • "gif"
      • "jpeg" or "jpg"
      • "bmp"
      • "png"
      The case of the suffix is ignored.
      filename - the name of the disk file to which the image will be written.
      cm - the ColourMapping to use when converting the pixel values to colours in the image. The cm is ignored for PixelDataTypes that have the R,G,B components specified.
      displayMin - the image pixel value that maps to the first entry in the ColourMapping. All pixel values below displayMin will also be mapped to the first entry.
      displayMax - the image pixel value that maps to the last entry in the ColourMapping. All pixel values above displayMax will also be mapped to the last entry.
      complexMode - the display mode for complex images. May be null for non-complex images.
      slicesPerRow - the number of image slices to put into one row of the image raster.
      logger - the Logger for verbose reporting and error messages.
      Throws:
      IOException - an error occurs writing to the file, or if an image of the type requested cannot be created.
      InvalidImageException - if this WritableImage has bad dimensionality for this operation.
      CancelledException - if the operation takes too long to complete.

    • export

      public InputStream export(ReadableImage image, String suffix, ColourMapping cm, double displayMin, double displayMax, ComplexMode complexMode, int slicesPerRow, Logger logger) throws IOException, InvalidImageException, CancelledException
      Returns an InputStream from which an external format image (such as JPEG, GIF etc.) can be read, producing the external format image from this WritableImage, by drawing all of the slices in a raster of slices. The first slice will be at the top left of the image, and the image is filled across the row of slices before moving down to the next row. The width of the image will be either be the number of columns in the WritableImage multiplied by the number of slicesPerRow, or 1024, whichever is the smaller.
      Parameters:
      image - the image to export.
      suffix - the suffix describing the type of image to be created. Currently, must be one of:
      • "gif"
      • "jpeg" or "jpg"
      • "bmp"
      • "png"
      The case of the suffix is ignored.
      cm - the ColourMapping to use when converting the pixel values to colours in the image. The cm is ignored for PixelDataTypes that have the R,G,B components specified.
      displayMin - the image pixel value that maps to the first entry in the ColourMapping. All pixel values below displayMin will also be mapped to the first entry.
      displayMax - the image pixel value that maps to the last entry in the ColourMapping. All pixel values above displayMax will also be mapped to the last entry.
      complexMode - the display mode for complex images. May be null for non-complex images.
      slicesPerRow - the number of image slices to put into one row of the image raster.
      logger - the Logger for verbose reporting and error messages.
      Returns:
      an InputStream from which the resulting external format image can be read.
      Throws:
      IOException - an error occurs writing the image, or if an image of the type requested cannot be created.
      InvalidImageException - if this WritableImage has bad dimensionality for this operation.
      CancelledException - if the operation takes too long to complete.

    • export

      public static void export(ReadableImage image, String suffix, ImageOutputStream outputStream, ColourMapping cm, double displayMin, double displayMax, ComplexMode complexMode, int slicesPerRow, Logger logger) throws IOException, InvalidImageException, CancelledException
      Writes an image to an ImageOutputStream in an external format (such as JPEG, GIF etc.), creating the disk image from this ReadableImage, by drawing all of the slices in a raster of slices. The first slice will be at the top left of the image, and the image is filled across the row of slices before moving down to the next row. The width of the image will be either be the number of columns in the WritableImage multiplied by the number of slicesPerRow, or 1024, whichever is the smaller.
      Parameters:
      image - the image to export.
      suffix - the suffix describing the type of image to be created. Currently, must be one of:
      • "gif"
      • "jpeg" or "jpg"
      • "bmp"
      • "png"
      The case of the suffix is ignored.
      outputStream - the ImageOutputStream to which the image will be written.
      cm - the ColourMapping to use when converting the pixel values to colours in the image. The cm is ignored for PixelDataTypes that have the R,G,B components specified.
      displayMin - the image pixel value that maps to the first entry in the ColourMapping. All pixel values below displayMin will also be mapped to the first entry.
      displayMax - the image pixel value that maps to the last entry in the ColourMapping. All pixel values above displayMax will also be mapped to the last entry.
      complexMode - the display mode for complex images. May be null for non-complex images.
      slicesPerRow - the number of image slices to put into one row of the image raster.
      logger - the Logger for verbose reporting and error messages.
      Throws:
      IOException - an error occurs writing to the ImageOutputStream, or if an image of the type requested cannot be created.
      InvalidImageException - if this WritableImage has bad dimensionality for this operation.
      CancelledException - if the operation is cancelled by the user.

    • toBufferedImage

      public static BufferedImage toBufferedImage(ReadableImage image, ColourMapping cm, double displayMin, double displayMax, ComplexMode complexMode, int slicesPerRow) throws IllegalArgumentException, InvalidImageException, CancelledException
      Create a BufferedImage from a ReadableImage, by drawing all of the slices in a raster of slices. The first slice will be at the top left of the BufferedImage, and the BufferedImage is filled across the row of slices before moving down to the next row. The width of the BufferedImage will be either the number of columns in the ReadableImage multiplied by the number of slicesPerRow, or 1048, whichever is the smaller.
      Parameters:
      image - the image to be drawn.
      cm - the ColourMapping to use when converting the pixel values to colours in the BufferedImage. The cm is ignored for PixelDataTypes that have the R,G,B components specified.
      displayMin - the image pixel value that maps to the first entry in the ColourMapping. All pixel values below displayMin will also be mapped to the first entry.
      displayMax - the image pixel value that maps to the last entry in the ColourMapping. All pixel values above displayMax will also be mapped to the last entry.
      complexMode - the display mode for complex images. May be null for non-complex images.
      slicesPerRow - the number of image slices to put into one row of the BufferedImage raster.
      Returns:
      a BufferedImage showing all the slices of this WritableImage.
      Throws:
      IllegalArgumentException - if this image cannot be converted to a BufferedImage.
      InvalidImageException - if this WritableImage has bad dimensionality for this operation.
      CancelledException - if the operation takes too long to complete.

    • main

      public static void main(String[] args)
      Run the self-test of this class.
      Parameters:
      args - the program arguments.