Class ANZImage

java.lang.Object
com.xinapse.multisliceimage.MultiSliceImage
com.xinapse.multisliceimage.analyze.ANZImage
All Implemented Interfaces:
ReadableImage, WritableImage, AutoCloseable
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 NIFTI-1/NIFTI-2 format.

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).

N.B. For colour (R,G,B) Analyze/NIFTI images, the data are ordered by colour plane, (i.e., all red values are followed by all green values followed by all blue values). However, the specification is unclear, and two formats are implemented here:

  1. All red values for all slices are followed by all green values for all slices, followed by all blue values for all slices. This is the default format.
  2. All red values for the first slice are followed by all green values for the first slice, followed by all blue values for the first slice. Subsequent slices follow in the same fashion. This format seems to be implemented by other programs that create colour Analyze/NIFTI images.
The format used for reading and writing colour Analyze/NIFTI images is controlled by a user preference, which is settable from within Jim's Preferences dialog, and also by the System Property analyze.strictrgb. The System Property overrides the preferences setting, and when set to true, will use the second data format above.

  • 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()

    • 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.

    • close

      public void close() throws InvalidImageException, IOException
      Closes an ANZImage and frees up resources. If the close() method is not applied to an image opened read/write from disk, then any changes 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
      Overrides:
      close in class MultiSliceImage
      Throws:
      InvalidImageException - if the image cannot be written because it is invalid.
      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
      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()

    • getPixelXSize

      public Float getPixelXSize()
      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, or null if the pixel size can't be found.

    • setPixelXSize

      public void setPixelXSize(float width) throws IllegalArgumentException
      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.

    • getPixelYSize

      public Float getPixelYSize()
      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, or null if the pixel size can't be found.

    • setPixelYSize

      public void setPixelYSize(float height) throws IllegalArgumentException
      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.

    • getPixelZSize

      public Float getPixelZSize()
      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, or null if the pixel size can't be found.

    • setPixelZSize

      public void setPixelZSize(float thickness) throws IllegalArgumentException
      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.

    • getTimeBetweenFrames

      public Float getTimeBetweenFrames()
      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, or null if the the between frames can't be found.

    • setTimeBetweenFrames

      public void setTimeBetweenFrames(float deltaT) throws IllegalArgumentException
      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.

    • 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 a value if the image pixels form a regular array of pixels with parallel image planes; otherwise null is returned.
      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)
      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.

    • setPixelSpacing

      public void setPixelSpacing(Float[] spacing) throws IndexOutOfBoundsException, 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.
      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.

    • setTitle

      public void setTitle(String title)
      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.

    • 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)
      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.

    • 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.

    • getDescription

      public String getDescription(boolean html)
      Description copied from interface: ReadableImage
      Returns a String description of this image in HTML format.
      Specified by:
      getDescription in interface ReadableImage
      Parameters:
      html - whether in HTML format.
      Returns:
      a String describing this image.

    • getFlatSliceDescription

      public String getFlatSliceDescription(int index, boolean html)
      Description copied from interface: ReadableImage
      Returns a String description of a slice of this image in HTML format.
      Specified by:
      getFlatSliceDescription in interface ReadableImage
      Parameters:
      index - the flat slice number to describe. The flat slice number is (frame * nSlices) + slice.For single-frame images, the flat slice number is just the slice number.
      html - whether in HTML format.
      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)
      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. 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.

    • 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.

    • 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.