Package gov.nih.mipav.model.file

Class FileMinc

java.lang.Object
gov.nih.mipav.model.file.FileBase
gov.nih.mipav.model.file.FileMinc
public class FileMinc extends FileBase
The MINC file format is built on top of NetCDF. It has a small header that holds certain image information: position and step data for each of the dimensions, real minimum and maximum values, and history.

For more information, go to the MINC homepage or the NetCDF File Format Specification.

Version:
1.0 July 1, 2000
See Also:

  • Field Details

    • DEFAULT_NON_HEADER_START_LOCATION

      private static final int DEFAULT_NON_HEADER_START_LOCATION
      The location, in bytes, of the portion of the minc file being written directly after the header. Does not include data added to the header by the dynamically generated history attribute or dicom-exported tags.
      See Also:

    • dicomConvertedTagTable

      private Hashtable<String,Hashtable<String,String>> dicomConvertedTagTable
      Table of tags extracted from a dicom file info to be written to the minc file. Generated in writeHeader(), then used again later in writeImage() to output placeholder values outside of the header.

    • endianess

      private boolean endianess
      The endianess of the image being written or read.

      TODO: this variable either needs to be local to the read/write methods or consistently used globally. As it stands right now, it is used in both ways and confuses things greatly.

    • fileDir

      private String fileDir
      The directory containing the minc file being written out or read in.

    • fileName

      private String fileName
      The name of the minc file to be read in or written out.

    • imgBegin

      private int imgBegin
      The location, in bytes, of the image data in the minc file being written out.

    • imgSize

      private int imgSize
      The size of the image data that will be written out, in bytes.

    • location

      private int location
      TODO: THIS VARIABLE MUST BE REMOVED! It is used as if local in places and global in others. A number of methods change it, causing subtle side effects which must be carefully managed.

    • newExtents

      private int[] newExtents

    • fileInfo

      private FileInfoMinc fileInfo

  • Constructor Details

    • FileMinc

      public FileMinc(String fName, String fDir) throws IOException
      MINC reader/writer constructor.
      Parameters:
      fName - File name.
      fDir - File directory.
      Throws:
      IOException - if there is an error constructing the files

  • Method Details

    • finalize

      public void finalize()
      Prepares this class for cleanup. Calls the finalize method for existing elements, closes any open files and sets other elements to null.
      Overrides:
      finalize in class FileBase

    • isMinc

      public boolean isMinc() throws IOException
      Looks for the CDF tag at the start of the image 'C''D''F''\001' in image header ID. If present, the image is a MINC format.
      Returns:
      boolean true if the header contains CDF tag 'C''D''F''\001'
      Throws:
      IOException - Indicates error reading the file

    • getFileInfo

      public FileInfoMinc getFileInfo()

    • readHeader

      public FileInfoMinc readHeader() throws IOException
      Reads in all the tags available in the file and stores them in FileInfoMinc.

      Format:
      header := magic numrecs dim_array gatt_array var_array
      magic := 'C' 'D' 'F' '\001'
      numrecs := non negative integer
      dim_array := NC_DIMENSION nelems [dim...]
      gatt_array := att_array
      att_array := NC_ATTRIBUTE nelems [attr...]
      var_array := NC_VARIABLE nelems [var...]
      nelems is # of elements in following array.
      dim := name dim_length
      dim is the extents; the name is xspace, yspace, or zspace.
      attr := name nc_type nelems [values]
      name is the name of the attribute; nc_type is the type (integer, char, etc.); values are the values of this attribute. It seems that attributes are mostly of type char, so the entire attribute is just a string.
      var := name nelems [dimid...] vatt_array nc_type vsize begin
      name is the name of the variable; dimid is Dimension id (for dimensions variables); vatt_array is an array of attributes for this variable; nc_type is the type of the variable; vsize is the size of the variable; begin is where in the file the variable data begins.

      Image extents are orginally determined under NC_DIMENSION with the MIPAV dimension ordering being the reverse of the MINC dimension ordering. However, under NC_VARIABLE refer to dimid.length of the variable with the string name of image to determine how many of these variables to retain. The contents of the dimid array under variable image give the dimid indices of the dimensions found in NC_DIMENSION which should be retained.
      Returns:
      true confirms a successful read.
      Throws:
      IOException - if there is an error reading the file
      See Also:

    • readImage

      public ModelImage readImage(boolean one, boolean readData) throws IOException
      Reads a MINC image file and stores the data in file info.
      Parameters:
      one - Flag indicating if only one image should be read in
      readData -
      Returns:
      The image.
      Throws:
      IOException - if there is an error reading the file
      See Also:

    • writeImage

      public void writeImage(ModelImage _image, FileWriteOptions options) throws IOException
      Writes a MINC format type image. Calls the appropriate header method.
      Parameters:
      _image - Image model where the data is stored.
      options - Information about how to write this file.
      Throws:
      IOException - if there is an error writing the file
      See Also:

    • extractDicomTags

      private static Hashtable<String,Hashtable<String,String>> extractDicomTags(FileInfoBase fileInfo)
      Extracts any Dicom tags from a given FileInfoBase (if the file info is dicom) and puts them into a Hashtable.
      Parameters:
      fileInfo - the file info to extract dicom tags from
      Returns:
      Hashtable keyed on tag group, containing Hashtables keyed on tag element, containing the tag values. Returns an empty Hashtable if the file info is not dicom.

    • getDefaultMax

      public static double getDefaultMax(FileInfoBase fileInfo)
      Return the default volume maximum for different file data types. This is used to rescale the image data before storing it on disk (the reader then uses the same values to scale the data back).
      Parameters:
      fileInfo - The fileInfo containing information about the image being saved.
      Returns:
      The default volume maximum for a given fileInfo.

    • getDefaultMin

      public static double getDefaultMin(FileInfoBase fileInfo)
      Return the default volume minimum for different file data types. This is used to rescale the image data before storing it on disk (the reader then uses the same values to scale the data back).
      Parameters:
      fileInfo - The fileInfo containing information about the image being saved.
      Returns:
      The default volume minimum for a given fileInfo.

    • getDicomValueAsString

      private static String getDicomValueAsString(FileDicomTag tag)
      Returns the value of a dicom tag, represented as a string. Null tag values are ignored, as are array value types.
      Parameters:
      tag - The dicom tag (including its value).
      Returns:
      the value of the given dicom tag (null if the value is null or is an array (which we don't support at the moment))

    • getMincModality

      public static String getMincModality(int modality)
      Get the minc modality string from the mipav modality type.
      Parameters:
      modality - The mipav image modality.
      Returns:
      The appropriate minc modality string if there is one; null if there is not equivalent minc modality or if the mipav modality is unknown.

    • getNextElem

      private Object getNextElem(int type, boolean endianess) throws IOException
      Gets the next element, switching on the type.
      Parameters:
      type - Short, byte, float, etc, defined in FileInfoMinc.
      endianess - Endianess, FileBase.BIG_ENDIAN or FileBase.LITTLE_ENDIAN.
      Returns:
      The element read in.
      Throws:
      IOException - if an error is encountered reading from the file

    • getPadding

      private int getPadding(int size)
      Returns the amount of padding needed (to the nearest 4 byte boundary) after a variable of length size.
      Parameters:
      size - The length of the variable.
      Returns:
      The amount of padding needed for that variable.

    • getSizeOfExportedDicomTags

      private int getSizeOfExportedDicomTags(Hashtable<String,Hashtable<String,String>> tagTable)
      Get the size, in bytes, of the data which would be written to the header to store a set of dicom tags.
      Parameters:
      tagTable - hashtable of exported dicom tags. Hashtable inside of a Hashtable ultimately storing Strings (tagValue = table[tagGroup][tagElement]).
      Returns:
      the size of the data which will be written to the header for the exported dicom tags

    • getSizeOfWrittenName

      private int getSizeOfWrittenName(String string, int addedByte)
      Returns the number of bytes that would be written to disk by calling writeName() on a given string.
      Parameters:
      string - the string which would be passed to writeName()
      addedByte - the number of bytes of explicit padding to put after the string (see the second param of writeName())
      Returns:
      the number of bytes that would be written to disk if the given string was passed to writeName()
      See Also:

    • getVattArray

      private void getVattArray(int index, FileInfoMinc fileInfo) throws IOException
      Gets the attribute array within a variable.
      Parameters:
      index - Index into the variable array; i.e., which variable this is.
      fileInfo - The file info to fill with data from the Vatt array read in from the minc file
      Throws:
      IOException - If an error is encountered while reading from the file

    • padding

      private void padding() throws IOException
      Pads to the nearest 4 byte boundary. Everything in MINC files is padded this way.
      Throws:
      IOException - If an error is encountered while reading from the file

    • writeDicomTagsToHeader

      private void writeDicomTagsToHeader(Hashtable<String,Hashtable<String,String>> tagTable, int beginningOffset) throws IOException
      Writes the dicom-extracted tags contained in tagTable to disk.
      Parameters:
      tagTable - a tag-group keyed table, containing a tag-element keyed table of string values
      beginningOffset - the location, in bytes, directly after the data section pointed to by the previous NC_VARIABLE section (usually image-min)
      Throws:
      IOException - If an error is encountered while writing to the file
      See Also:

    • writeHeader

      private void writeHeader(FileInfoMinc fileInfo) throws IOException
      Writes a header for MINC to MINC. This is much easier than the other-format-to-MINC writeHeader; in this case, we already have all the information we need to write. Therefore, the process is just to go through the dimArray, gattArray, and varArray and write out the variables.
      Parameters:
      fileInfo - File info needed to write the header.
      Throws:
      IOException - If an error is encountered while writing to the file

    • writeHeader

      private void writeHeader(FileInfoBase fileInfo, FileWriteOptions options, int nSlices, int nVolumes) throws IOException
      Writes the header for non-MINC to MINC. MINC has a very structured format. Many of the things written out I don't understand, but they seem to be consistent across the MINC files we've seen (e.g., varid, vartype, and version attributes). The header begins with a dimension array with a specific ordering of the spaces which dictates orientation. Then there's a global attribute array, which in our case is just the history of how this file was created. Then there's a variable array. Each variable contains an attribute array, a type, a size, and a begin location. The actual value of the variable is written at its begin location, after all other header info is written. So the rootvariable's value, for example, is written after the info for image-min, which is the last variable in the array. It seems that conventionally the image-max and image-min variables are after the image variable; thus, the values of those variables are written after the "value of the image" which is the actual image data. Consequently, this function exits just before the image is to be written, even though the image-max and image-min values have yet to be written.

      This is a public method because it is called from FileIO. Previously it was called from writeImage, but this would create a file even if the dialog was cancelled. Obviously that is undesirable behavior.

      Parameters:
      fileInfo - Info to use when writing the header.
      options - The structure that returns important information about the image to be written.
      Throws:
      IOException - If an error is encountered while writing to the file

    • writeName

      private void writeName(String name, int add, boolean endianess) throws IOException
      Write a string name by writing the length of the string plus padding length, writing the string, and writing the padding.
      Parameters:
      name - Value to write.
      add - Length of padding to add.
      endianess - Endianess, FileBase.BIG_ENDIAN or FileBase.LITTLE_ENDIAN.
      Throws:
      IOException - If an error is encountered while writing to the file

    • writeNextElem

      private void writeNextElem(Object value, int type, boolean endianess) throws IOException
      Writes the next element, switching on the type.
      Parameters:
      value - The value to write out.
      type - Short, byte, float, etc, defined in FileInfoMinc.
      endianess - Endianess, FileBase.BIG_ENDIAN or FileBase.LITTLE_ENDIAN.
      Throws:
      IOException - If an error is encountered while writing to the file

    • writePadding

      private void writePadding() throws IOException
      Pads to the nearest 4 byte boundary. Everything in MINC files is padded this way.
      Throws:
      IOException - If an error is encountered while writing to the file

    • writeSpace

      private void writeSpace(double step, double start, String space, boolean endianess, boolean isNormal) throws IOException
      Writes the "space", as in xspace, yspace, zspace. The space gives information on that dimension, such as length (what we call extents), step, and start. Start tells the real talirach value of where the space starts, so -50 would be something like 50 inches away from the center of the brain to the right, depending on which space we're in. Step is the step you take per slice from the start, so the third slice in would be start + 3*step.
      Parameters:
      step - Step, see above.
      start - Start, see above.
      space - The string label used for the space ('xspace', 'yspace', 'zspace', or 'time')
      endianess - Endianess, FileBase.BIG_ENDIAN or FileBase.LITTLE_ENDIAN.
      isNormal - No longer used to determine the space direction comment. Consider removal.
      Throws:
      IOException - If an error is encountered while writing to the file

    • writeValuesArray

      private void writeValuesArray(Object[] values, int type, boolean endianess) throws IOException
      Writes the array, switching on the type.
      Parameters:
      values - Array to write.
      type - Short, byte, float, etc, defined in FileInfoMinc.
      endianess - Endianess, FileBase.BIG_ENDIAN or FileBase.LITTLE_ENDIAN.
      Throws:
      IOException - If an error is encountered while writing to the file