Package com.xinapse.multisliceimage.Analyze

Class ANZImage

java.lang.Object
com.xinapse.multisliceimage.MultiSliceImage
com.xinapse.multisliceimage.Analyze.ANZImage
All Implemented Interfaces:
ReadableImage, WritableImage, AutoCloseable, Cloneable
Direct Known Subclasses:
Analyze75Image, NIFTIImage
public abstract class ANZImage extends MultiSliceImage implements AutoCloseable
This is an abstract class that is the superclass of a multi-dimensional image in the Analyze 7.5 format or the NIFTI format.

Image data for images loaded from disk remains on disk, and is accessed as required; image data loaded from streams or created afresh resides in memory. Image data loaded from compressed (gzipped) disk-files also resides in memory.

Both big-endian and little-endian byte ordering are implemented and supported. When reading existing images, the byte order is auto detected from the header file. When existing images are copied or modified, the original byte order is retained. For images newly-created from scratch by this package, the byte ordering is the native byte order.

N.B. The Analyze format requires that for BINARY images, individual slices must begin on a byte boundary. In this implementation, that restriction is removed. If you wish to maintain compatibility with Analyze and other programs that maintain this restriction, ensure that a multi-slice/multi-frame images have slices with a number of pixels that is a multiple of 8 (bits).

  • Field Details

    • EXTENSION

      public static final String EXTENSION
      The file extension for Analyze image files in lower case form.
      See Also:

    • UPPERCASE_EXTENSION

      public static final String UPPERCASE_EXTENSION
      The file extension for Analyze image files in upper case form.

    • COMPRESSED_EXTENSION

      public static final String COMPRESSED_EXTENSION
      The file extension for Analyze image files in lower case form.
      See Also:

    • COMPRESSED_UPPERCASE_EXTENSION

      public static final String COMPRESSED_UPPERCASE_EXTENSION
      The file extension for Analyze image files in upper case form.

  • Method Details

    • getByteOrder

      public ByteOrder getByteOrder()
      Description copied from class: MultiSliceImage
      Returns the byte order for this image.
      Specified by:
      getByteOrder in class MultiSliceImage
      Returns:
      the byte oder for this image, or null if the byte order is not defined yet (in-memory images only).

    • imageExists

      public static boolean imageExists(String filename)
      Tests whether an ANZImage with the given name already exists on disk. File extensions are handled in a smart and case-insensitive way.
      Parameters:
      filename - the name of the image file to test for existence.
      Returns:
      true if a pair of ANZImage .img and .hdr with the specified name exist on disk; false otherwise.

    • write

      public String write(String filename) throws IOException, InvalidImageException
      Writes this ANZImage to disk.
      Specified by:
      write in interface WritableImage
      Parameters:
      filename - the root of the Analyze filename. Will be appended with ".img" and ".hdr" to create the appropriate full filenames.
      Returns:
      the actual file name used to write the image, including any added extension.
      Throws:
      InvalidImageException - if the image cannot be written.
      IOException - if an I/O error occurs.

    • disposeImageData

      public void disposeImageData()
      Description copied from interface: ReadableImage
      Gives this image the option to free up resources by removing access to image data. After this method is called, image data may no longer be accessible, and method calls to access it may result in an Exception being thrown.
      Specified by:
      disposeImageData in interface ReadableImage

    • close

      public void close() throws IOException
      Closes an ANZImage and frees up resources. For in-memory ANZImages, this merely explicity frees resources so that the garbage collector can work more efficiently. However, for disk-based images it is essential to apply the close() method. Image data is written to disk during the put methods, but header information is only written to disk by the close() method. If the close() method is not applied to a disk-based ANZImage, then any changes to the header will be lost. Any further operations to a closed ANZImage are not possible, and may cause an exception to be thrown.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface ReadableImage
      Throws:
      IOException - if an I/O error occurs.

    • isOpen

      public boolean isOpen()
      Description copied from interface: ReadableImage
      Tests whether this image is still open.
      Specified by:
      isOpen in interface ReadableImage
      Returns:
      true if the image is still open for reading and (if opened read/write) writing; false otherwise.

    • isCompressed

      public boolean isCompressed()
      Tests whether this ANZImage is compressed when on disk.
      Returns:
      true if compressed; false otherwise.

    • getNativeHeader

      public String getNativeHeader()
      Description copied from interface: ReadableImage
      Returns a String showing the 'native' header for this image.
      Specified by:
      getNativeHeader in interface ReadableImage
      Returns:
      a String describing the 'native' header for this image.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getDataType

      public ANZPixFormat getDataType()
      Returns the data type (ANZPixFormat) of this image.
      Returns:
      an ANZPixFormat representing a particular pixel data type.

    • setDBName

      public void setDBName(String name) throws ANZException
      Sets the data base name for this ANZImage.
      Parameters:
      name - a String representing the name data base name.
      Throws:
      ANZException - if the data base name cannot be set for this image.

    • setDescription

      public void setDescription(String descripstr) throws ANZException
      Sets the description for this ANZImage.
      Parameters:
      descripstr - a String representing the name description.
      Throws:
      ANZException - if the description cannot be set for the image header.

    • setMinMax

      public void setMinMax(int min, int max) throws InvalidImageException
      Sets the glMin and glMax fields for this ANZImage.
      Specified by:
      setMinMax in interface WritableImage
      Specified by:
      setMinMax in class MultiSliceImage
      Parameters:
      min - the minimum pixel value in the image.
      max - the maximum pixel value in the image.
      Throws:
      InvalidImageException - if the values supplied are unsuitable, or the values cannot be set.

    • getHeader

      public ANZHeader getHeader()
      Returns the ANZHeader image header for this image. Warning! If this header is manipulated, then accessing the image pixel data may cause errors.
      Returns:
      the Analyze image header for this image.

    • getNCols

      public int getNCols()
      Description copied from interface: ReadableImage
      Returns the number of image columns in this image.
      Specified by:
      getNCols in interface ReadableImage
      Returns:
      the number of image columns.

    • getNRows

      public int getNRows()
      Description copied from interface: ReadableImage
      Returns the number of image rows in this image.
      Specified by:
      getNRows in interface ReadableImage
      Returns:
      the number of image rows.

    • getNSlices

      public int getNSlices()
      Description copied from interface: ReadableImage
      Returns the number of physical slice locations in this image. If the image dimensionality is greater than or equal to three, then this method returns the number of samples in the third dimension. If the dimensionality is less than 3 two, it returns 1.
      Specified by:
      getNSlices in interface ReadableImage
      Returns:
      the number of physical slice locations.

    • getNFrames

      public int getNFrames()
      Description copied from interface: ReadableImage
      Returns the number of frames in a multi-frame image. If the image dimensionality is greater than or equal to four, then this method returns the number of samples in the fourth dimension. If the dimensionality is less than 4, it returns 1.
      Specified by:
      getNFrames in interface ReadableImage
      Returns:
      the number of image (movie) frames.

    • getTotalNSlices

      public int getTotalNSlices()
      Description copied from interface: ReadableImage
      Returns the total number of slices in this image. If the image is less than 3-dimensional, this method returns 1; if it is 3-dimensional, it returns the number of slices; if it is 4- or more dimensional, it sums up the total number of planar slices in each dimension and returns the total. For example a 4-dimensional image with 4 slices and 10 frames, the total number of slices is 40.
      Specified by:
      getTotalNSlices in interface ReadableImage
      Returns:
      the number of planar image slices.

    • getNDim

      public int getNDim() throws IllegalStateException
      Description copied from interface: ReadableImage
      Returns the dimensionality of this image.
      Specified by:
      getNDim in interface ReadableImage
      Returns:
      the image dimensionality.
      Throws:
      IllegalStateException

    • getDims

      public int[] getDims() throws IllegalStateException
      Description copied from interface: ReadableImage
      Returns the dimensions (numbers of samples in each image dimension) of this image.
      Specified by:
      getDims in interface ReadableImage
      Returns:
      an array with length equal to the image dimensionality, containing the numbers of pixels (samples) in each dimension of the image. By convention, element (nDim-1) contains the number of columns, element (nDim-2) the number of rows, etc. For example, in a 4-dimensional image, dims[0] is the number of frames, dims[1] the number of slices, dims[2] the number of rows and dims[3] the number of columns.
      Throws:
      IllegalStateException

    • getStoredPixelDataType

      public PixelDataType getStoredPixelDataType()
      Description copied from interface: ReadableImage
      Returns a PixelDataType representing the data type of this image, as the pixel values are stored on disk.
      Specified by:
      getStoredPixelDataType in interface ReadableImage
      Returns:
      the PixelDataType representing the data type of this image as stored on disk.

    • getFileDataOffset

      public int getFileDataOffset()
      Description copied from class: MultiSliceImage
      Returns the byte offset into the disk-based file format where pixel data begins.
      Specified by:
      getFileDataOffset in class MultiSliceImage
      Returns:
      the byte offset to the start of pixel data for images that are written to disk.

    • getPixelXSize

      public float getPixelXSize() throws ParameterNotSetException
      Description copied from interface: ReadableImage
      Returns the pixel size in the x (horizontal) direction for this image.
      Specified by:
      getPixelXSize in interface ReadableImage
      Returns:
      the pixel size in the x (horizontal) direction in mm.
      Throws:
      ParameterNotSetException - if the pixel size can't be found.

    • setPixelXSize

      public void setPixelXSize(float width) throws IllegalArgumentException, IOException
      Description copied from class: MultiSliceImage
      Sets the pixel size in the x (horizontal) direction for this image.
      Specified by:
      setPixelXSize in class MultiSliceImage
      Parameters:
      width - the width of a pixel.
      Throws:
      IllegalArgumentException - if the pixel width is not positive.
      IOException - if and I/O error occurs.

    • getPixelYSize

      public float getPixelYSize() throws ParameterNotSetException
      Description copied from interface: ReadableImage
      Returns the pixel size in the y (vertical) direction for this image.
      Specified by:
      getPixelYSize in interface ReadableImage
      Returns:
      the pixel size in the y (vertical) direction in mm.
      Throws:
      ParameterNotSetException - if the pixel size can't be found.

    • setPixelYSize

      public void setPixelYSize(float height) throws IllegalArgumentException, IOException
      Description copied from class: MultiSliceImage
      Sets the pixel size in the y (vertical) direction for this image.
      Specified by:
      setPixelYSize in class MultiSliceImage
      Parameters:
      height - the height of a pixel.
      Throws:
      IllegalArgumentException - if height is not positive.
      IOException - if an I/O error occurs.

    • getPixelZSize

      public float getPixelZSize() throws ParameterNotSetException
      Description copied from interface: ReadableImage
      Returns the separation between the centres of image planes for this image.
      Specified by:
      getPixelZSize in interface ReadableImage
      Returns:
      the pixel size in the z (slice) direction in mm.
      Throws:
      ParameterNotSetException - if the pixel size can't be found.

    • setPixelZSize

      public void setPixelZSize(float thickness) throws IllegalArgumentException, IOException
      Description copied from class: MultiSliceImage
      Sets the pixel size in the z (slice) direction for this image.
      Specified by:
      setPixelZSize in class MultiSliceImage
      Parameters:
      thickness - the thickness of a pixel.
      Throws:
      IllegalArgumentException - if thickness is not positive.
      IOException - if an I/O error occurs.

    • getTimeBetweenFrames

      public float getTimeBetweenFrames() throws ParameterNotSetException
      Description copied from interface: ReadableImage
      Returns the time between frames in a 4- or higher dimensional image.
      Specified by:
      getTimeBetweenFrames in interface ReadableImage
      Returns:
      the time between frames in seconds.
      Throws:
      ParameterNotSetException - if the time between frames is not set, or if this image doesn't have a dimensionality of at least 4.

    • setTimeBetweenFrames

      public void setTimeBetweenFrames(float deltaT) throws IllegalArgumentException, IOException
      Description copied from class: MultiSliceImage
      Sets the time between frames in a 4- or higher dimensional image.
      Specified by:
      setTimeBetweenFrames in class MultiSliceImage
      Parameters:
      deltaT - the time between frames (in seconds).
      Throws:
      IllegalArgumentException - if deltaT is negative.
      IOException - if an I/O error occurs.

    • getImageOrientationPatient

      public org.jogamp.vecmath.Vector3f[] getImageOrientationPatient()
      Description copied from interface: ReadableImage
      Returns the direction cosines of the row, column and slice directions (for increasing row, column and slice) of the image, in patient (L,P,S) coordinates.
      Specified by:
      getImageOrientationPatient in interface ReadableImage
      Returns:
      a Vector3f[], corresponding to the direction cosines of the image row, column and slice directions in Left,Posterior,Superior (LPS) coordinates. Returns null if the direction cosines cannot be retrieved from this image.

    • getImageOrientationPatient

      public org.jogamp.vecmath.Vector3f[] getImageOrientationPatient(int slice) throws IndexOutOfBoundsException
      Description copied from interface: ReadableImage
      Returns the direction cosines of the row, column and slice directions (for increasing row, column and slice) of the image, in patient coordinates.
      Specified by:
      getImageOrientationPatient in interface ReadableImage
      Parameters:
      slice - the slice for which to return the image orientation.
      Returns:
      a Vector3f[], corresponding to the direction cosines of the image row, column and slice directions in Left,Posterior,Superior (LPS) coordinates. Returns null if the direction cosines cannot be retrieved from this image.
      Throws:
      IndexOutOfBoundsException - if the image does not have the right dimensionality or the slice number is inappropriate for this image.

    • getImagePositionPatient

      public org.jogamp.vecmath.Point3f getImagePositionPatient()
      Description copied from interface: ReadableImage
      Returns the coordinates of the center of the first pixel of the image, in mm, in patient coordinates. This method will only return if the image pixels form a regular array of pixels with parallel image planes; otherwise a ParameterNotSetException is thrown.
      Specified by:
      getImagePositionPatient in interface ReadableImage
      Returns:
      the Left,Posterior,Superior (LPS) coordinates of the first pixel in the image data matrix. Returns null if the position cannot be retrieved from this image.

    • getImagePositionPatient

      public org.jogamp.vecmath.Point3f getImagePositionPatient(int slice) throws IndexOutOfBoundsException
      Description copied from interface: ReadableImage
      Returns the coordinates of the center of the first pixel of the specified slice of this image, in mm, in patient coordinates.
      Specified by:
      getImagePositionPatient in interface ReadableImage
      Parameters:
      slice - the slice number (indexed from 0) for which to return the pixel coordinates.
      Returns:
      the Left,Posterior,Superior (LPS) coordinates of the first pixel in the specified slice of this image. Returns null if the position cannot be retrieved from this image.
      Throws:
      IndexOutOfBoundsException - if the slice number is bad for this image.

    • setImageOrientationPositionPatient

      public void setImageOrientationPositionPatient(org.jogamp.vecmath.Vector3f[] dirCos, org.jogamp.vecmath.Point3f position, boolean force) throws IOException
      Description copied from class: MultiSliceImage
      Sets the direction cosines of the row, column and slice directions of the image, the coordinates of the center of the first pixel of the image, in patient (LPS) coordinates.

      N.B. the actual position and orientation set by this method may not be those specified. For example, for NIFTI-1 images, the actual orientation and position may depend on the user Preferences for whether to put pixel values in an order that is compatible with SPM. After using this method, you should use the ReadableImage.getImageOrientationPatient() and ReadableImage.getImagePositionPatient() methods to obtain the real orientation and positions set.

      If the orientation or position cannot be set for this image, this method does not report an error.

      Specified by:
      setImageOrientationPositionPatient in interface WritableImage
      Specified by:
      setImageOrientationPositionPatient in class MultiSliceImage
      Parameters:
      dirCos - the direction cosines of the image row, column and (optionally) slice directions respectively in Left,Posterior,Superior (LPS) coordinates. If orientation is null, this method will attempt to clear any orientation information, if that is supported by the image format.
      position - the Left,Posterior,Superior (LPS) coordinates of the centre of the first pixel in the image data matrix. If position is null, this method will attempt to clear any positional information, if that is supported by the image format.
      force - if true, this method will force the orientation and position to be set as requested, regardless of the user Preferences. This can be useful if you read the orientation from an existing image, and you want to set the orientation exactly the same in a new image.
      Throws:
      IOException - if an I/O error occurs.

    • setPixelSpacing

      public void setPixelSpacing(Float[] spacing) throws IndexOutOfBoundsException, IOException, IllegalArgumentException
      Description copied from interface: WritableImage
      Sets the distance (in mm) between pixel centres in the row, column and slice directions of the image, and the time between movie frames (for 4-D images) in seconds. The distances and time should always be positive values.
      Specified by:
      setPixelSpacing in interface WritableImage
      Parameters:
      spacing - a Float[] of length up to 4, corresponding to the distance between pixel centres in the row, column, slice and time directions, respectively. Spacing values will only be set for image dimensions where the spacing array is long enough and the array element is non-null. The first element of the array indicates the horizontal pixel size; the second is the vertical pixel size; the third is the pixel depth; fourth is the time between frames.
      Throws:
      IndexOutOfBoundsException - if spacing does not have the correct dimensions.
      IOException - if the pixel spacing cannot be set for this image.
      IllegalArgumentException

    • getRescaleUnits

      public com.xinapse.dicom.RescaleUnits getRescaleUnits()
      Description copied from interface: ReadableImage
      Returns the output units of Intensity Rescale Slope and Intensity Rescale Intercept, retrieved by getIntensityRescale().
      Specified by:
      getRescaleUnits in interface ReadableImage
      Returns:
      the RescaleUnits describing the physical meaning of the pixel intensity units. Returns the RescaleUnits.US if the physical meaning is unknown, or arbitrary.

    • getDescription

      public String getDescription()
      Description copied from interface: ReadableImage
      Returns a String description of this image.
      Specified by:
      getDescription in interface ReadableImage
      Returns:
      a String describing this image.

    • getDescription

      public String getDescription(int slice)
      Description copied from interface: ReadableImage
      Returns a String description of this one particular slice of this image.
      Specified by:
      getDescription in interface ReadableImage
      Parameters:
      slice - the slice to describe.
      Returns:
      a String describing the given slice of this image.

    • getTitle

      public String getTitle()
      Description copied from interface: ReadableImage
      Returns the title of this image.
      Specified by:
      getTitle in interface ReadableImage
      Returns:
      the title of this image.

    • setTitle

      public void setTitle(String title) throws IOException
      Description copied from interface: WritableImage
      Sets the title for this WritableImage, if the image format can handle titles.
      Specified by:
      setTitle in interface WritableImage
      Parameters:
      title - the new title.
      Throws:
      IOException - if an error occurs writing the title.

    • anonymise

      public void anonymise(String patientName, String patientID, Date birthDate, boolean patSex, String patAddr, String patInsurancePlanID, String accessionNumber, boolean patOther, String physicianName, String physicianAddr, String institutionName, String institutionAddr, String deptName, String stationName, String telNumber, boolean removePrivateElements) throws IOException
      Description copied from interface: WritableImage
      Anonymise this WritableImage.
      Specified by:
      anonymise in interface WritableImage
      Parameters:
      patientName - if non-null, the patient name to substitute.
      patientID - if non-null, the patient ID to substitute.
      birthDate - if non-null, the birth date to substitute.
      patSex - if true, set the sex to "OTHER".
      patAddr - if non-null, the address to substitute.
      patInsurancePlanID - if non-null, the insurance plan ID to substitute.
      accessionNumber - if non-null, the accession number to substitute.
      patOther - if true, other patient-related items will be anonymised.
      physicianName - if non-null, the physician name to substitute.
      physicianAddr - if non-null, the physician's address to substitute.
      institutionName - if non-null, the institution name to substitute.
      institutionAddr - if non-null, the institution address to substitute.
      deptName - if non-null, the department name to substitute.
      stationName - if non-null, the station name to substitute.
      telNumber - if non-null, the telephone number to substitute for all telephone numbers.
      removePrivateElements - if true, all private DICOM elements will be removed.
      Throws:
      IOException - if an I/O error occurs during anonymisation.

    • getHTMLDescription

      public String getHTMLDescription()
      Description copied from interface: ReadableImage
      Returns a String description of this image in HTML format.
      Specified by:
      getHTMLDescription in interface ReadableImage
      Returns:
      a String describing this image.

    • getHTMLDescription

      public String getHTMLDescription(int slice)
      Description copied from interface: ReadableImage
      Returns a String description of a slice of this image in HTML format.
      Specified by:
      getHTMLDescription in interface ReadableImage
      Parameters:
      slice - the slice number.
      Returns:
      a String describing this image slice.

    • getNativeColourMapping

      public ColourMapping getNativeColourMapping()
      Returns a ColourMapping if this Analyze image has an associated colour mapping. Colour mappings are kept in a file with an extension ".lkup" and with the same name root as the Analyze image.
      Specified by:
      getNativeColourMapping in interface ReadableImage
      Returns:
      a ColourMapping if this image has an associated colour mapping. Returns null if it does not.

    • setNativeColourMapping

      public void setNativeColourMapping(ColourMapping colourMapping) throws IOException
      Description copied from interface: WritableImage
      Sets the ColourMapping for this image. No exception occurs if the image format does not support a colour mapping.
      N.B. For disk-based images, the changes in the ColourMapping may not be reflected on disk unless the close() method is called.
      Specified by:
      setNativeColourMapping in interface WritableImage
      Parameters:
      colourMapping - the new ColourMapping to be assigned to this image.
      Throws:
      IOException - if the ColourMapping cannot be set for this image.

    • getMin

      public Double getMin() throws InvalidImageException
      Description copied from interface: ReadableImage
      Returns the minimum pixel intensity in the image.
      Specified by:
      getMin in interface ReadableImage
      Returns:
      the maximum pixel intensity as a Double, or null if the intensity min hasn't been calculated for this image.
      Throws:
      InvalidImageException - if the intensity cannot be returned as a Double.

    • getMax

      public Double getMax() throws InvalidImageException
      Description copied from interface: ReadableImage
      Returns the maximum pixel intensity in the image.
      Specified by:
      getMax in interface ReadableImage
      Returns:
      the maximum pixel intensity as a Double, or null if the intensity max hasn't been calculated for this image.
      Throws:
      InvalidImageException - if the intensity cannot be returned as a Double.

    • getCopy

      public ANZImage getCopy()
      Creates an in-memory copy of an Analyze image.
      Specified by:
      getCopy in interface ReadableImage
      Specified by:
      getCopy in interface WritableImage
      Returns:
      a copy of the ANZImage Object.

    • stripExtension

      public static String stripExtension(String filename)
      Strips any ".img", ".hdr", ".img.gz" or ".hdr.gz" extension (in either upper or lower case) from a file name.
      Parameters:
      filename - the file name that may or may not have an extension.
      Returns:
      the stripped file name.