com.xinapse.loadableimage
Interface LoadableImage

All Known Implementing Classes:

Analyze75Image, ANZImage, LoadedImage, MultiSliceImage, NIFTIImage, UNCImage

public interface LoadableImage

LoadableImage defines the requests that an image class has to handle if it is to be "loadable" into a general image analysis and display program.

The methods define the dimensionality, dimensions, pixel sizes, pixel data type, basic MR scan parameters, basic patient information, scan positioning of the image. It also allows the pixel intensity information to be retrieved either as a whole, or slice-by-slice.

Method Summary

void	appendAuditInfo(java.lang.String name, java.lang.String value) Appends audit trail information to this image.
void	close() Closes an image and frees up resources.
java.lang.String	getDescription() Returns a String description of this image.
java.lang.String	getDescription(int slice) Returns a description of a slice of this image.
float	getFlipAngle() Returns the excitation pulse flip angle for this image.
java.lang.String	getHTMLDescription() Returns a String description of this image in HTML format.
java.lang.String	getHTMLDescription(int slice) Returns a String description of a slice of this image in HTML format.
float[][]	getImageOrientationPatient() Returns the direction cosines of the row, column and slice directions (for increasing row, column and slice) of the image, in patient coordinates.
float[][]	getImageOrientationPatient(int slice) Returns the direction cosines of the row, column and (possiblly) slice directions (for increasing row, column and slice) of the image, in patient coordinates.
float[]	getImagePositionPatient() Returns the coordinates of the center of the first pixel of the image, in mm, in patient coordinates.
float[]	getImagePositionPatient(int slice) Returns the coordinates of the center of the first pixel of the specified slice of this image, in mm, in patient coordinates.
float[]	getIntensityRescale() Returns the values m and b in the relationship between pixel intensity (I) values and the output units specified in getRescaleUnits() in the expression: Output units = m*I + b.
float[]	getIntensityRescale(int slice) Returns the values m and b in the relationship between pixel intensity (I) values and the output units specified in getRescaleUnits() in the expression: Output units = m*I + b for a particular slice.
java.lang.Double	getMax() Returns the maximum pixel intensity in the image.
java.lang.Double	getMin() Returns the minimum pixel intensity in the image.
com.xinapse.dicom.Modality	getModality() Returns the imaging modality with which this image was collected.
MostLikePlane	getMostLikePlane() Returns the imaging plane that this image is "most like".
ColourMapping	getNativeColourMapping() Returns a ColourMapping if this image has an associated colour mapping.
int	getNCols() Returns the number of image columns in this image.
int	getNDim() Returns the dimensionality of this image.
int	getNFrames() Returns the number of frames in a multi-frame image.
int	getNRows() Returns the number of image rows in this image.
int	getNSlices() Returns the number of physical slice locations in this image.
java.util.Date	getPatientDoB() Returns the patient date of birth for this image.
java.lang.String	getPatientID() Returns the patient ID for this image.
java.lang.String	getPatientName() Returns the patient name for this image.
com.xinapse.dicom.PatientPosition	getPatientPosition() Returns the position in which the patient is lying in the scanning equipment.
java.lang.Object	getPix() Returns all the pixel values for this image in the order in which they are stored internally.
java.lang.Object	getPix(boolean radiological) Returns all the pixel values for this image, optionally returning them in the correct order in which they will be presented, where the first pixel should be presented at the top left corner of the display device.
PixelDataType	getPixelDataType() Returns a PixelDataType representing the data type of this image.
float	getPixelXSize() Returns the pixel size in the x (horizontal) direction for this image.
float	getPixelYSize() Returns the pixel size in the y (vertical) direction for this image.
float	getPixelZSize() Returns the separation between the centres of image planes for this image.
java.lang.String	getPulseSequence() Returns the name of the pulse sequence with which this image was collected.
java.lang.String	getRescaleUnits() Specifies the output units of Intensity Rescale Slope and Intensity Rescale Intercept, retrieved by getIntensityRescale().
java.util.List<ROI>	getROIs() Returns a List of ROIs that are stored with the image.
java.util.Date	getScanDate() Returns the scan Date for this image.
com.xinapse.dicom.PulseSequenceType	getScanningSequence() Returns the DICOM Scanning Sequence with which this image was collected.
float	getScanTE() Returns the scan echo time for this image if it has a single echo-time.
float	getScanTE(int slice) Returns the scan echo time for one slice of this image.
float	getScanTI() Returns the scan inversion time for this image.
float	getScanTR() Returns the scan repetition time for this image.
com.xinapse.dicom.PulseSequenceVariant	getSequenceVariant() Returns the DICOM Scanning Sequence Variant with which this image was collected.
java.lang.Object	getSlice(int slice) Returns the pixel values for one slice of an n-dimensional image, where n > 1.
float	getSliceThickness() Returns the slice thickness (in mm).
java.lang.String	getSuggestedFileName() Returns the suggested file name for in-memory images that are to be saved to disk.
float	getTimeBetweenFrames() Returns the time between frames in a 4- or higher dimensional image.
java.lang.String	getTitle() Returns the title of this image.
int	getTotalNSlices() Returns the total number of slices in this image.
boolean	isOpen() Tests whether this image is still open.

Method Detail

getPixelDataType

PixelDataType getPixelDataType()
                               throws InvalidImageException

Returns a PixelDataType representing the data type of this image.

Returns:

the PixelDataType representing the data type of this image.

Throws:

InvalidImageException - if the PixelDataType cannot be determined.

getNDim

int getNDim()
            throws InvalidImageException

Returns the dimensionality of this image.

Returns:

the image dimensionality.

Throws:

InvalidImageException - if not a valid image.

getNRows

int getNRows()
             throws InvalidImageException

Returns the number of image rows in this image.

Returns:

the number of image rows.

Throws:

InvalidImageException - if not a valid image.

getNCols

int getNCols()
             throws InvalidImageException

Returns the number of image columns in this image.

Returns:

the number of image columns.

Throws:

InvalidImageException - if not a valid image.

getNSlices

int getNSlices()
               throws InvalidImageException

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 two, it returns 1. If the dimensionality is less than two, it throws an InvalidImageException.

Returns:

the number of physical slice locations.

Throws:

InvalidImageException - if not a valid planar image.

getNFrames

int getNFrames()
               throws InvalidImageException

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.

Returns:

the number of image (movie) frames.

Throws:

InvalidImageException - if not a valid multi-frame image.

getTotalNSlices

int getTotalNSlices()
                    throws InvalidImageException

Returns the total number of slices in this image. If the image is 2-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.

Returns:

the number of planar image slices.

Throws:

InvalidImageException - if not a valid image with at least 2 dimensions.

getPix

java.lang.Object getPix()
                        throws InvalidImageException

Returns all the pixel values for this image in the order in which they are stored internally.

Throws:

InvalidImageException - if there is a problem accessing the pixel values.

getPix

java.lang.Object getPix(boolean radiological)
                        throws InvalidImageException

Returns all the pixel values for this image, optionally returning them in the correct order in which they will be presented, where the first pixel should be presented at the top left corner of the display device.

Parameters:

radiological - trueif the pixels are to be returned in the correct order for presentation, where the first returned pixel is to be presented at the top left, and the last at the bottom right of the display device; false if the are to be return in the order in which they are stored internally.

Throws:

InvalidImageException - if there is a problem accessing the pixel values.

getSlice

java.lang.Object getSlice(int slice)
                          throws InvalidImageException,
                                 java.lang.IndexOutOfBoundsException

Returns the pixel values for one slice of an n-dimensional image, where n > 1.

N.B.The pixel values are always returned in a standard radiological orientation. Standard radiological orientation 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.

Thus, when this slice is viewed on-screen, the first pixel in the array returned belongs at the top left of the the screen, and the last pixel in the array belongs at the bottom right of the the screen. This is regardless of the sub-class of image (for example, the flipping of Analyze images is taken care of by this method).

Parameters:

slice - the slice number. Must be 0 for a 2-dimensional image or from 0 to dims[0]-1 for a 3-dimensional image. For images of higher dimensionality, each extra dimension multiplies the number of available slices by the size in that dimension, so all images of higher dimensionality that 1 look like multi-slice images.

Returns:

a 1-dimensional array of the primitive java type appropriate for this image, and of size [nRows * nCols]. This array is cast to an Object before return.

Throws:

InvalidImageException - if there is a problem accessing the pixel values.

java.lang.IndexOutOfBoundsException - if the image does not have the right dimensionality or the slice number is inappropriate for this image.

getMostLikePlane

MostLikePlane getMostLikePlane()

Returns the imaging plane that this image is "most like".

Returns:

the plane that is "most" like the imaging plane for this image. Returns MostLikePlane.UNKNOWN if the imaging plane cannot be determined, or if the image does not contain a set of parallel slices.

appendAuditInfo

void appendAuditInfo(java.lang.String name,
                     java.lang.String value)

Appends audit trail information to this image.

Parameters:

name - a String describing the name of the action that was performed on this image.

value - a String describing the value of the action that was performed on this image.

getMin

java.lang.Double getMin()
                        throws InvalidImageException

Returns the minimum pixel intensity in the image.

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

java.lang.Double getMax()
                        throws InvalidImageException

Returns the maximum pixel intensity in the image.

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.

getNativeColourMapping

ColourMapping getNativeColourMapping()
                                     throws InvalidColourMappingException

Returns a ColourMapping if this image has an associated colour mapping.

Returns:

a ColourMapping if this image has an associated colour mapping. Returns null if it does not.

Throws:

InvalidColourMappingException - if this image has an associated ColourMapping, but the ColourMapping cannot be successfully retrieved.

getSuggestedFileName

java.lang.String getSuggestedFileName()

Returns the suggested file name for in-memory images that are to be saved to disk.

Returns:

the suggested file name, or null if not set.

close

void close()
           throws java.io.IOException,
                  InvalidImageException

Closes an image and frees up resources. Any further operations to a closed image are not possible, and may cause an exception to be thrown.

Throws:

InvalidImageException - if the image cannot be written or closed.

java.io.IOException - if an I/O error occurs.

isOpen

boolean isOpen()

Tests whether this image is still open.

Returns:

true if the image is still open for reading and (if opened read/write) writing; false otherwise.

getTitle

java.lang.String getTitle()

Returns the title of this image.

Returns:

the title of this image.

getPixelXSize

float getPixelXSize()
                    throws ParameterNotSetException

Returns the pixel size in the x (horizontal) direction for this image.

Returns:

the pixel size in the x (horizontal) direction in mm.

Throws:

ParameterNotSetException - if the pixel size can't be found.

getPixelYSize

float getPixelYSize()
                    throws ParameterNotSetException

Returns the pixel size in the y (vertical) direction for this image.

Returns:

the pixel size in the y (vertical) direction in mm.

Throws:

ParameterNotSetException - if the pixel size can't be found.

getPixelZSize

float getPixelZSize()
                    throws ParameterNotSetException

Returns the separation between the centres of image planes for this image.

Returns:

the pixel size in the z (slice) direction in mm.

Throws:

ParameterNotSetException - if the pixel size can't be found.

getTimeBetweenFrames

float getTimeBetweenFrames()
                           throws ParameterNotSetException

Returns the time between frames in a 4- or higher dimensional image.

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.

getSliceThickness

float getSliceThickness()
                        throws ParameterNotSetException

Returns the slice thickness (in mm). This method is necessary because the slice thickness may not be the same as the inter-slice pixel spacing, if there is a gap between slices.

Returns:

the slice thickness in mm.

Throws:

ParameterNotSetException - if the slice thickness is not set, or its value is corrupt.

getModality

com.xinapse.dicom.Modality getModality()

Returns the imaging modality with which this image was collected.

Returns:

the Modality used to collect this image.

getPulseSequence

java.lang.String getPulseSequence()
                                  throws ParameterNotSetException

Returns the name of the pulse sequence with which this image was collected.

Returns:

the name of the pulse sequence used to collect this image.

Throws:

ParameterNotSetException

getScanningSequence

com.xinapse.dicom.PulseSequenceType getScanningSequence()
                                                        throws ParameterNotSetException

Returns the DICOM Scanning Sequence with which this image was collected.

Returns:

the DICOM Scanning Sequence used to collect this image.

Throws:

ParameterNotSetException

getSequenceVariant

com.xinapse.dicom.PulseSequenceVariant getSequenceVariant()
                                                          throws ParameterNotSetException

Returns the DICOM Scanning Sequence Variant with which this image was collected.

Returns:

the DICOM Scanning Sequence Variant used to collect this image.

Throws:

ParameterNotSetException

getFlipAngle

float getFlipAngle()
                   throws ParameterNotSetException

Returns the excitation pulse flip angle for this image.

Returns:

the excitation pulse flip angle for this image.

Throws:

ParameterNotSetException - if the flip angle is not set.

getScanTR

float getScanTR()
                throws ParameterNotSetException

Returns the scan repetition time for this image.

Returns:

the scan TR for this image.

Throws:

ParameterNotSetException - if the TR is not set.

getScanTI

float getScanTI()
                throws ParameterNotSetException

Returns the scan inversion time for this image.

Returns:

the scan TI for this image.

Throws:

ParameterNotSetException - if the TI is not set.

getScanTE

float getScanTE()
                throws ParameterNotSetException

Returns the scan echo time for this image if it has a single echo-time.

Returns:

the scan TE for this image.

Throws:

ParameterNotSetException - if the TE is not set.

getScanTE

float getScanTE(int slice)
                throws ParameterNotSetException,
                       java.lang.IndexOutOfBoundsException

Returns the scan echo time for one slice of this image.

Parameters:

slice - the slice number for which to return the echo time.

Returns:

the scan TE for the specified slice of this image.

Throws:

ParameterNotSetException - if the TE is not set.

java.lang.IndexOutOfBoundsException - if the slice number is bad for this image.

getPatientName

java.lang.String getPatientName()

Returns the patient name for this image.

Returns:

the patient name for this image, or null if the patient name can't be found.

getPatientID

java.lang.String getPatientID()

Returns the patient ID for this image.

Returns:

the patientID for this image, or null if the patientID can't be found.

getPatientDoB

java.util.Date getPatientDoB()

Returns the patient date of birth for this image.

Returns:

the patient's date of birth for this image, or null if the patient's dob can't be found.

getScanDate

java.util.Date getScanDate()

Returns the scan Date for this image.

Returns:

the date/time at which this scan was performed, or null if the scan date can't be found.

getPatientPosition

com.xinapse.dicom.PatientPosition getPatientPosition()

Returns the position in which the patient is lying in the scanning equipment. For example, PatientPosition.HFS (head-first supine).

Returns:

the position in which the patient is lying in the scanning equipment.

getDescription

java.lang.String getDescription()

Returns a String description of this image.

Returns:

a String describing this image.

getDescription

java.lang.String getDescription(int slice)
                                throws java.lang.IndexOutOfBoundsException

Returns a description of a slice of this image.

Parameters:

slice - the slice number. o

Returns:

a String describing this image slice.

Throws:

java.lang.IndexOutOfBoundsException - if the slice number is bad for this image.

getHTMLDescription

java.lang.String getHTMLDescription()

Returns a String description of this image in HTML format.

Returns:

a String describing this image.

getHTMLDescription

java.lang.String getHTMLDescription(int slice)
                                    throws java.lang.IndexOutOfBoundsException

Returns a String description of a slice of this image in HTML format.

Parameters:

slice - the slice number.

Returns:

a String describing this image slice.

Throws:

java.lang.IndexOutOfBoundsException - if the slice is bad for this image.

getRescaleUnits

java.lang.String getRescaleUnits()

Specifies the output units of Intensity Rescale Slope and Intensity Rescale Intercept, retrieved by getIntensityRescale().

Returns:

a String describing the physical meaning of the pixel intensity units. Returns the String "arbitrary units" if the physical meaning is unknown, or arbitrary.

getIntensityRescale

float[] getIntensityRescale()
                            throws ParameterNotSetException

Returns the values m and b in the relationship between pixel intensity (I) values and the output units specified in getRescaleUnits() in the expression:
Output units = m*I + b.

Returns:

an array will be of length 2 where the first element is m and the second is b.

Throws:

ParameterNotSetException - if a single rescaling has not been set for the whole image.

getIntensityRescale

float[] getIntensityRescale(int slice)
                            throws ParameterNotSetException,
                                   java.lang.IndexOutOfBoundsException

Returns the values m and b in the relationship between pixel intensity (I) values and the output units specified in getRescaleUnits() in the expression:
Output units = m*I + b
for a particular slice.

Parameters:

slice - a slice number for which to retrieve the rescaling values.

Returns:

an array will be of length 2 where the first element is m and the second is b, for the specified slice.

Throws:

ParameterNotSetException - if a single rescaling has not been set for the image slice.

java.lang.IndexOutOfBoundsException - the slice number is bad for this image.

getImageOrientationPatient

float[][] getImageOrientationPatient()

Returns the direction cosines of the row, column and slice directions (for increasing row, column and slice) of the image, in patient coordinates.

Returns:

a 3x3 float[][], corresponding to the direction cosines of the image row, column and slice directions in Left,Posterior,Superior (LPS) coordinates. cosines[0][0..2] is the row direction; cosines[1][0..2] is the column direction; and cosines[2][0..2] is the slice direction. If the distance between image adjacent slices is not the same for all slices, but the slices are parallel, then this method will return a 2x3 float[][] giving the direction cosines of the row and column directions respectively. Returns null if the direction cosines cannot be retrieved from this image.

getImageOrientationPatient

float[][] getImageOrientationPatient(int slice)
                                     throws java.lang.IndexOutOfBoundsException

Returns the direction cosines of the row, column and (possiblly) slice directions (for increasing row, column and slice) of the image, in patient coordinates.

Parameters:

slice - the slice for which to return the image orientation.

Returns:

a 3x3 or 2x3 float[][], corresponding to the direction cosines of the image row, column and slice directions in Left,Posterior,Superior (LPS) coordinates. cosines[0][0..2] is the row direction; cosines[1][0..2] is the column direction; and (if present) cosines[2][0..2] is the slice direction. Returns null if the direction cosines cannot be retrieved from this image.

Throws:

java.lang.IndexOutOfBoundsException - if the image does not have the right dimensionality or the slice number is inappropriate for this image.

getImagePositionPatient

float[] getImagePositionPatient()

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.

Returns:

a float array of length 3, corresponding to 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

float[] getImagePositionPatient(int slice)
                                throws java.lang.IndexOutOfBoundsException

Returns the coordinates of the center of the first pixel of the specified slice of this image, in mm, in patient coordinates.

Returns:

a float array of length 3, corresponding to 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:

java.lang.IndexOutOfBoundsException - if the slice number is bad for this image.

getROIs

java.util.List<ROI> getROIs()
                            throws java.io.IOException

Returns a List of ROIs that are stored with the image.

Returns:

null if there are no ROIs stored with the image.

Throws:

java.io.IOException - if an I/O error occurs while reading the ROIs.