Interface WritableImage

All Superinterfaces:
AutoCloseable, ReadableImage
All Known Implementing Classes:
Analyze75Image, ANZImage, MultiSliceImage, NIFTI2Image, NIFTIImage, UNCImage
public interface WritableImage extends ReadableImage
Interface implemented by classes that ensure an image of that class can be written.

  • Method Details

    • getImageTypeName

      String getImageTypeName()
      Returns the normal human readable name for this type of image.
      Returns:
      a String with a one-word description of this type of image.

    • appendAuditInfo

      void appendAuditInfo(String name, 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.

    • setNativeColourMapping

      void setNativeColourMapping(ColourMapping colourMapping)
      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.
      Parameters:
      colourMapping - the new ColourMapping to be assigned to this image.

    • setTitle

      void setTitle(String title)
      Sets the title for this WritableImage, if the image format can handle titles.
      Parameters:
      title - the new title.

    • appendToTitle

      default void appendToTitle(String toAppend)
      Append some text to the title of this WritableImage, if the image format can handle titles.
      Parameters:
      toAppend - the text to append to the title.

    • setModality

      void setModality(Modality modality)
      Sets the modality with which this image was acquired. No exception occurs if the image format does not support modality recording.
      Parameters:
      modality - the new imaging modality to be assigned to this image.

    • setBodyPart

      void setBodyPart(com.xinapse.dicom.BodyPart bodyPart)
      Sets the body part imaged. No exception occurs if the image format does not support body part recording.
      Parameters:
      bodyPart - the new imaged body part.

    • setLaterality

      void setLaterality(com.xinapse.dicom.Laterality laterality)
      Sets the anatomical laterality of the image. No exception occurs if the image format does not support laterality recording.
      Parameters:
      laterality - the new image laterality.

    • setPulseSequence

      void setPulseSequence(String seqName)
      Sets the pulse sequence name for this image.
      Parameters:
      seqName - the new name of the pulse sequence to be assigned to this image.

    • setScanningSequence

      void setScanningSequence(PulseSequenceType sequenceType)
      Sets the DICOM scanning sequence for this image.
      Parameters:
      sequenceType - the new scanning sequence to be assigned to this image.

    • setSequenceVariant

      void setSequenceVariant(PulseSequenceVariant seqVariant)
      Sets the DICOM scanning sequence variant for this image.
      Parameters:
      seqVariant - the new scanning sequence variant to be assigned to this image.

    • setFlipAngle

      void setFlipAngle(Float flipAngle)
      Sets the excitation pulse flip angle for this image. No exception occurs if the image format does not support flip angle recording.
      Parameters:
      flipAngle - the new scan flip angle to be assigned to this image. If null, the flip angle should be unset.

    • setScanTR

      void setScanTR(Float tr)
      Sets the scan repetition time for this image. No exception occurs if the image format does not support scan TR recording.
      Parameters:
      tr - the new scan TR to be assigned to this image. If null, the TR should be unset.

    • setScanTI

      void setScanTI(Float ti)
      Sets the scan inversion time for this image. No exception occurs if the image format does not support scan TI recording.
      Parameters:
      ti - the new scan TI to be assigned to this image. If null, the TI should be unset.

    • setScanTE

      void setScanTE(Float te)
      Sets the scan echo time for this image. No exception occurs if the image format does not support scan TE recording.
      Parameters:
      te - the new scan TE to be assigned to this image. If null, the TE should be unset.

    • setFrameTE

      void setFrameTE(Float te, int index)
      Sets the scan echo time for one dimension index of this image. For 3-D images, the dimension index is the slice dimension. For 4-D (or higher dimensionality) images, the dimension index is the frame dimension. No exception occurs if the image format does not support a scan TE recording.
      Parameters:
      te - the new scan TE to be assigned to this image.
      index - the index to the image frame for which to set the echo time. For 3-D images, this is the slice number; for 4-D images it is the frame number.
      Throws:
      IndexOutOfBoundsException - if the index is bad for this image.

    • setDICOMImageType

      void setDICOMImageType(String[] imageTypes) throws InvalidArgumentException
      Sets the type of image, in the same way that a DICOM Element with Tag <0x0008, 0x0008> does. No exception occurs if the image format does not support setting of the image type.
      Parameters:
      imageTypes - a String[] with the important image identification characteristics. If null, the image type should be unset.
      Throws:
      InvalidArgumentException - if the length of imageTypes is less than 2 (the minimum multiplicity for <0x0008, 0x0008>).

    • setFrameDICOMImageType

      void setFrameDICOMImageType(String[] imageTypes, int index)
      Sets the type of image for one for one dimension index of this image, in the same way that a DICOM Element with Tag <0x0008, 0x0008> does. For 3-D images, the dimension index is the slice dimension. For 4-D (or higher dimensionality) images, the dimension index is the frame dimension. No exception occurs if the image format does not support setting of the image type.
      Parameters:
      imageTypes - a {link String}[] with the important image identification characteristics for the given farme. If null, the image type should be unset.
      index - the index to the image frame for which to set the image type. For 3-D images, this is the slice number; for 4-D images it is the frame number.
      Throws:
      IndexOutOfBoundsException - if the index is bad for this image.

    • setSaturationFreqOffsetPPM

      void setSaturationFreqOffsetPPM(Float freqOffset)
      Sets the saturation frequency offset in PPM for this image. No exception occurs if the image format does not support saturation frequency offset recording.
      Parameters:
      freqOffset - the new saturation frequency offset to be assigned to this image. If null, the saturation frequency offset should be unset.

    • setFrameSaturationFreqOffsetPPM

      void setFrameSaturationFreqOffsetPPM(Float freqOffset, int index)
      Sets the saturation frequency offset for one dimension index of this image. For 3-D images, the dimension index is the slice dimension. For 4-D (or higher dimensionality) images, the dimension index is the frame dimension. No exception occurs if the image format does not support saturation frequency offset recording.
      Parameters:
      freqOffset - the new saturation frequency offset to be assigned to this image.
      index - the index to the image frame for which to set the saturation frequency offset. For 3-D images, this is the slice number; for 4-D images it is the frame number.
      Throws:
      IndexOutOfBoundsException - if the index is bad for this image.

    • setEchoTrainLength

      void setEchoTrainLength(Integer etl)
      Sets the echo train length for this image. No exception occurs if the image format does not support a echo train length recording.
      Parameters:
      etl - the new scan echo train length to be assigned to this image. If null, the echo train length is unassigned.

    • setFrameDWbValue

      void setFrameDWbValue(float bValue, int index) throws IndexOutOfBoundsException
      Sets the diffusion-weighting b-value for one "frame" of this image. No exception occurs if the image format does not support recording the b-value.
      Parameters:
      bValue - the new b-value to be assigned to this image.
      index - the index to the image frame for which to set the b-value. For 3-D images, this is the slice number; for 4-D images it is the frame number.
      Throws:
      IndexOutOfBoundsException - if the index is bad for this image.

    • setFrameDWGradientVector

      void setFrameDWGradientVector(org.jogamp.vecmath.Vector3f gVector, int index) throws IndexOutOfBoundsException
      Sets the diffusion-weighting gradient vector for one "frame" of this image. No exception occurs if the image format does not support recording the gradient vector.
      Parameters:
      gVector - the new gradient vector to be assigned to this image.
      index - the index to the image frame for which to set the gradient vector. For 3-D images, this is the slice number; for 4-D images it is the frame number.
      Throws:
      IndexOutOfBoundsException - if the index is bad for this image.

    • setFrameDWBMatrix

      void setFrameDWBMatrix(float[] bMatrix, int index) throws IndexOutOfBoundsException
      Sets the diffusion-weighting B-matrix for one "frame" of this image. No exception occurs if the image format does not support recording the B-matrix.
      Parameters:
      bMatrix - the new B-matrix to be assigned to this image.
      index - the index to the image frame for which to set the B-matrix. For 3-D images, this is the slice number; for 4-D images it is the frame number.
      Throws:
      IndexOutOfBoundsException - if the index is bad for this image.

    • setFrameTriggerDelayMS

      void setFrameTriggerDelayMS(float delay, int index) throws IndexOutOfBoundsException
      Sets the trigger delay (in milliseconds) for one "frame" of this image. No exception occurs if the image format does not support recording the trigger delay.
      Parameters:
      delay - the new trigger delay to be assigned to this image.
      index - the index to the image frame for which to set the trigger delay. For 3-D images, this is the slice number; for 4-D images it is the frame number.
      Throws:
      IndexOutOfBoundsException - if the index is bad for this image.

    • setPatientName

      void setPatientName(String name)
      Attempts to set the patient name for this image. If new patient name String is longer than is allowed by the image format, then it is truncated before being applied. No exception occurs if the image format does not support patient name recording.
      Parameters:
      name - the new patient name to be assigned to this image.

    • setPatientID

      void setPatientID(String id)
      Sets the patient ID for this image. If the new patient ID String is longer than is allowed by the image format, then it is truncated before being applied. No exception occurs if the image format does not support patient ID recording.
      Parameters:
      id - the new patient ID to be assigned to this image.

    • setAccessionNumber

      void setAccessionNumber(String accessionNumber)
      Sets the accession number for this image. If the new accession number String is longer than is allowed by the image format, then it is truncated before being applied. No exception occurs if the image format does not support accession number recording.
      Parameters:
      accessionNumber - the new accession number to be assigned to this image.

    • setPatientDoB

      void setPatientDoB(Date dob)
      Sets the patient's date of birth for this image. No exception occurs if the image format does not support patient date of birth recording.
      Parameters:
      dob - the new patient date of birth to be assigned to this image.

    • setPatientSex

      void setPatientSex(com.xinapse.dicom.Sex sex)
      Sets the patient sex for this image.
      Parameters:
      sex - the patient sex to be assigned to this image.

    • setScanDate

      void setScanDate(Date scanDate)
      Sets the scan date/time for this image.
      Parameters:
      scanDate - the new scan date/time to be assigned to this image.

    • setPatientPosition

      void setPatientPosition(PatientPosition position)
      Sets the position in which the patient is lying in the scanning equipment for this WritableImage.
      Parameters:
      position - the position in which the patient is lying in the scanning equipment. e.g. PatientPosition.HFS (head-first supine).

    • setStudyID

      void setStudyID(String studyID)
      Sets the study ID for this image.
      Parameters:
      studyID - the new study ID to be assigned to this image.

    • setStudyInstanceUID

      void setStudyInstanceUID(com.xinapse.dicom.Uid uid)
      Sets the study instance UID for this image.
      Parameters:
      uid - the new study instance UID to be assigned to this image.

    • setSeriesNumber

      void setSeriesNumber(Integer seriesNumber)
      Sets the series number for this image.
      Parameters:
      seriesNumber - the new series number to be assigned to this image.

    • setSeriesInstanceUID

      void setSeriesInstanceUID(com.xinapse.dicom.Uid uid)
      Sets the series instance UID for this image.
      Parameters:
      uid - the new series instance UID to be assigned to this image.

    • setSeriesDescription

      void setSeriesDescription(String description)
      Sets a short description of the series (scan).
      Parameters:
      description - the new short description of the series, or null if none is available.

    • supportsIntensityRescaling

      boolean supportsIntensityRescaling()
      Tests whether this WritableImage format supports intensity rescaling.
      Returns:
      true if this WritableImage format supports intensity rescaling; false otherwise.

    • setIntensityRescale

      void setIntensityRescale(float rescaleSlope, float rescaleIntercept) throws InvalidImageException
      Sets the values m and b in the relationship between pixel intensity (I) values and the output units specified in setRescaleUnits(com.xinapse.dicom.RescaleUnits) in the expression:
      Output units = m*I + b.
      Parameters:
      rescaleSlope - the value of m in the expression above.
      rescaleIntercept - the value of b in the expression above.
      Throws:
      InvalidImageException - if rescaling cannot be set for this image.

    • setIntensityRescale

      void setIntensityRescale(float[] rescaleSlopeIntercept) throws InvalidImageException
      Sets the values m and b in the relationship between pixel intensity (I) values and the output units specified in setRescaleUnits(com.xinapse.dicom.RescaleUnits) in the expression:
      Output units = m*I + b.
      Parameters:
      rescaleSlopeIntercept - an array of length 2, containing the values of m and b in the expression above, in that order.
      Throws:
      InvalidImageException - if rescaling cannot be set for this image.

    • setRescaleUnits

      void setRescaleUnits(com.xinapse.dicom.RescaleUnits units)
      Sets the rescale units.
      Parameters:
      units - the rescale units.

    • setFrameOfReferenceUID

      void setFrameOfReferenceUID(com.xinapse.dicom.Uid uid)
      Sets the frame of reference UID that uniquely identifies the frame of reference for an image.
      Parameters:
      uid - the frame of reference UID. If uid is null, the frame of reference Uid is removed from the image header.

    • putSlice

      void putSlice(Object slicePix, int slice) throws InvalidImageException
      Puts the pixel values to one slice of an n-dimensional image, where n > 1.

      N.B.Whenever the radiological orientation of the image can be determined, this method sets pixel values such that when the slice is viewed on-screen, the first pixel in the array belongs at the top left of the screen, and the last pixel in the array belongs at the bottom right of the screen. This must be regardless of the sub-class of image.

      Parameters:
      slicePix - a 1-dimensional array of the correct primitive java data type for this image, with dimensions [nRows * nCols] containing the pixel values to put.
      slice - the slice number. Must be 0 for a 2-dimensional image or from 0 to dims[0]-1 for a 3-dimensional image.
      Throws:
      InvalidImageException - if the image does not have the right dimensionality, if the slice number is inappropriate for this image, if the array is not of the correct primitive data type for this image, or if there is a problem accessing the pixel values.

    • putPix

      void putPix(Object pixels, boolean radiological) throws InvalidImageException
      Put pixel values from a specified array to this image. array is an array of the correct type of element for this image from which pixel values will be copied; it must be cast to an Object and must have the correct number of elements.
      Parameters:
      pixels - a 1-dimensional array of pixel values of the correct java primitive data type to put to the image.
      radiological - true if the pixels have 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.
      If false, the pixels are put without any consideration of the orientation.
      Throws:
      InvalidImageException - if an error occurs while putting the pixel values.

    • putPix

      void putPix(Object pix, int[] pixIdx) throws InvalidImageException
      Puts a single pixel value to the image.
      Parameters:
      pix - the pixel value to put, as a suitable Object.
      pixIdx - an int[] of length at least equal to nDim for this image where each element corresponds to an index to the pixel in each dimension. The first element of pixIdx refers to the slowest-varying dimension, and the last relevant element refers to the fastest-varying dimension. For example, for a 3-D image, pixIdx[0] refers to the slice dimension, and pixIdx[2] refers to the column dimension.
      Throws:
      InvalidImageException - if the indices are inappropriate for this image, if the supplied pixel is of the wrong Class, or if the pixel value cannot be put to the image.

    • putPix

      void putPix(Object pixels, int[] lowIdx, int[] highIdx) throws InvalidImageException
      Put pixel values from a specified array to this image. array is an array of the correct type of element for this image from which pixel values will be copied; it must be cast to an Object and must have the right number of elements to copy to the pixel values requested. The lowIdx and highIdx int arrays should have at least nDim elements, and the elements specify the pixel number range for each dimension. For example, if an image has nDim = 3, and dims[] = {5, 256, 256}, then pixels for the 3 middle slices will be returned by setting lowIdx to {1, 0, 0} and highIdx to {4, 256, 256}.
      Parameters:
      pixels - a 1-dimensional array of pixel values of the correct java primitive data type to put to the image.
      lowIdx - an array of int specifying the low index of pixel values to put.
      highIdx - an array of int specifying the high index (exclusive) of pixel values to put.
      Throws:
      InvalidImageException - if the indices supplied extend beyond the image, the pixel values are of the wrong primitive data type or cannot be put for other reasons.
      IllegalStateException - if the image was opened read-only.

    • setPixelSpacing

      void setPixelSpacing(Float[] pixelSpacing) throws IndexOutOfBoundsException
      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.
      Parameters:
      pixelSpacing - 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.

    • setSliceThickness

      void setSliceThickness(Float thickness)
      Sets 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.
      Parameters:
      thickness - the slice thickness in mm, or null to remove the slice thickness information.

    • setImageOrientationPositionPatient

      void setImageOrientationPositionPatient(org.jogamp.vecmath.Vector3f[] orientation, org.jogamp.vecmath.Point3f position, boolean force)
      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.

      Parameters:
      orientation - 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:
      IndexOutOfBoundsException - if the orientation array does not have the correct length.

    • setImageOrientationPatient

      void setImageOrientationPatient(org.jogamp.vecmath.Vector3f[] orientation, int slice)
      Sets the direction cosines of the row, column and slice directions (for increasing row, column and slice) of the image, in patient (LPS) coordinates.

      If the orientation cannot be set for this image, this method does nothing.

      Parameters:
      orientation - the direction cosines of the image row, column and (optionally) slice directions respectively in Left,Posterior,Superior (LPS) coordinates.
      slice - the slice for which to set the orientation.
      Throws:
      IndexOutOfBoundsException - if the cosines array does not have the correct dimensions.
      IllegalStateException - if the image was opened read-only.

    • setImagePositionPatient

      void setImagePositionPatient(org.jogamp.vecmath.Point3f position, int slice)
      Sets the coordinates of the center of the first pixel of the image, in mm, in patient (LPS) coordinates, for one slice of this image.
      Parameters:
      position - the Left,Posterior,Superior (LPS) coordinates of the first pixel of this specified slice in the image data matrix.
      slice - the slice for which to set the position.
      Throws:
      IllegalStateException - if the image was opened read-only.

    • setMinMax

      void setMinMax(int min, int max) throws InvalidImageException
      Sets the min and max pixel values for this WritableImage. It is up to the caller to ensure that the values supplied are correct at the time they are written to the image. Any subsequent changes to the image pixel values may cause either the values returned by getMin() and getMax() to be incorrect, or cause these methods to throw a InvalidImageException.
      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.

    • setSuggestedFileName

      void setSuggestedFileName(String name)
      Sets a suggested file name for this WritableImage that might be used when saving to disk later.
      Parameters:
      name - the suggested file name.

    • write

      String write(String filename) throws InvalidImageException, IOException
      Writes this WritableImage to a file (or possibly a pair of header/image files).
      Parameters:
      filename - with which the image is to be written.
      Returns:
      the actual file name to which the image was written.
      Throws:
      InvalidImageException - if the image cannot be written.
      IOException - if an I/O error occurs.

    • getCopy

      WritableImage getCopy()
      Returns a copy of this WritableImage.
      Specified by:
      getCopy in interface ReadableImage
      Returns:
      a copy of this ReadableImage.

    • anonymise

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

    • addBasicAudit

      default void addBasicAudit(Class<? extends Object> clazz)
      Adds the bare-bones audit-trail information to this WritableImage.
      Parameters:
      clazz - the creator Class whose name is to be added as the "Creator of this image" audit information.

    • addBasicAudit

      default void addBasicAudit(String creatorClassName)
      Adds the bare-bones audit-trail information to this WritableImage.
      Parameters:
      creatorClassName - the creator Class name to be added as the "Creator of this image" audit information.