Package mgui.io.standard.nifti

Class Nifti1Dataset

java.lang.Object
mgui.io.standard.nifti.Nifti1Dataset
Direct Known Subclasses:
NiftiMetadata, WunilDataset
public class Nifti1Dataset
extends java.lang.Object
Nifti1Dataset is an API for reading/writing nifti-1 datasets.
The definitive nifti-1 specification is the nifti1.h file on the NIfTI DFWG website

Notes:
Compression: files compressed with gzip are read using the Java gunzip utility

Endian-ness: Java uses big-endian by default. nifti files determined to be little-endian as per the nifti spec (dim[0] field) will have the header and data swapped on read. (Not sure about write yet...)

Datatypes: the nifti-1 format supports a large number of datatypes. The current read methods typecast all data to doubles. This API will be extended to include methods to return image blobs of different datatypes.

Todo List

  • This API currently uses the traditional Java java.io methods. Will explore performance gains by using the java.nio methods, including possibly memory mapping. I think some of the new java.io methods such as readFully() use nio anyway.
  • For header read and write, should change to read/write fields from/to 348 byte blob, and read/write blob from disk in 1 call.
  • Currently the writeHeader() method writes from the lower level variables, not the "shortcut" variables ie pixdim[0] not qfac, dim[1] not XDIM, etc. need to think about this, use accessor methods
  • Will need to change read/writeVol methods to call read/write slice methds b/c blob_size has to be an int but should be a long. 32 bit int only allows max volume 1625^3 which is too small.
  • Add methods to manipulate qform/sform and roatation matrices and quaternion representations
  • Add simple method to make a Java AWT image from a slice

  • Possible extensions to this API: Extend this API to be compatible with Analyze7.5 format ?

History of changes to Nifti1Dataset

  • 3/1/2005 KF Alpha version put into SourceForge CVS
  • 10/2005 KF added copyHeader() routine
  • 2/20/2006 KF Bug fix in readHeader() for endian setting, thanks to Jason Dai.
  • 3/2006 KF added a little code to readNiiExt() to check if extensions overrun image data.
  • 2/2010 AR Minor changes to allow gzip functionality

  • Field Details

    • ANZ_HDR_EXT

      public static final java.lang.String ANZ_HDR_EXT
      See Also:
      Constant Field Values

    • ANZ_DAT_EXT

      public static final java.lang.String ANZ_DAT_EXT
      See Also:
      Constant Field Values

    • NI1_EXT

      public static final java.lang.String NI1_EXT
      See Also:
      Constant Field Values

    • GZIP_EXT

      public static final java.lang.String GZIP_EXT
      See Also:
      Constant Field Values

    • ANZ_HDR_SIZE

      public static final int ANZ_HDR_SIZE
      See Also:
      Constant Field Values

    • NII_HDR_SIZE

      public static final long NII_HDR_SIZE
      See Also:
      Constant Field Values

    • EXT_KEY_SIZE

      public static final int EXT_KEY_SIZE
      See Also:
      Constant Field Values

    • NII_MAGIC_STRING

      public static final java.lang.String NII_MAGIC_STRING
      See Also:
      Constant Field Values

    • ANZ_MAGIC_STRING

      public static final java.lang.String ANZ_MAGIC_STRING
      See Also:
      Constant Field Values

    • NIFTI_INTENT_NONE

      public static final short NIFTI_INTENT_NONE
      See Also:
      Constant Field Values

    • NIFTI_INTENT_CORREL

      public static final short NIFTI_INTENT_CORREL
      See Also:
      Constant Field Values

    • NIFTI_INTENT_TTEST

      public static final short NIFTI_INTENT_TTEST
      See Also:
      Constant Field Values

    • NIFTI_INTENT_FTEST

      public static final short NIFTI_INTENT_FTEST
      See Also:
      Constant Field Values

    • NIFTI_INTENT_ZSCORE

      public static final short NIFTI_INTENT_ZSCORE
      See Also:
      Constant Field Values

    • NIFTI_INTENT_CHISQ

      public static final short NIFTI_INTENT_CHISQ
      See Also:
      Constant Field Values

    • NIFTI_INTENT_BETA

      public static final short NIFTI_INTENT_BETA
      See Also:
      Constant Field Values

    • NIFTI_INTENT_BINOM

      public static final short NIFTI_INTENT_BINOM
      See Also:
      Constant Field Values

    • NIFTI_INTENT_GAMMA

      public static final short NIFTI_INTENT_GAMMA
      See Also:
      Constant Field Values

    • NIFTI_INTENT_POISSON

      public static final short NIFTI_INTENT_POISSON
      See Also:
      Constant Field Values

    • NIFTI_INTENT_NORMAL

      public static final short NIFTI_INTENT_NORMAL
      See Also:
      Constant Field Values

    • NIFTI_INTENT_FTEST_NONC

      public static final short NIFTI_INTENT_FTEST_NONC
      See Also:
      Constant Field Values

    • NIFTI_INTENT_CHISQ_NONC

      public static final short NIFTI_INTENT_CHISQ_NONC
      See Also:
      Constant Field Values

    • NIFTI_INTENT_LOGISTIC

      public static final short NIFTI_INTENT_LOGISTIC
      See Also:
      Constant Field Values

    • NIFTI_INTENT_LAPLACE

      public static final short NIFTI_INTENT_LAPLACE
      See Also:
      Constant Field Values

    • NIFTI_INTENT_UNIFORM

      public static final short NIFTI_INTENT_UNIFORM
      See Also:
      Constant Field Values

    • NIFTI_INTENT_TTEST_NONC

      public static final short NIFTI_INTENT_TTEST_NONC
      See Also:
      Constant Field Values

    • NIFTI_INTENT_WEIBULL

      public static final short NIFTI_INTENT_WEIBULL
      See Also:
      Constant Field Values

    • NIFTI_INTENT_CHI

      public static final short NIFTI_INTENT_CHI
      See Also:
      Constant Field Values

    • NIFTI_INTENT_INVGAUSS

      public static final short NIFTI_INTENT_INVGAUSS
      See Also:
      Constant Field Values

    • NIFTI_INTENT_EXTVAL

      public static final short NIFTI_INTENT_EXTVAL
      See Also:
      Constant Field Values

    • NIFTI_INTENT_PVAL

      public static final short NIFTI_INTENT_PVAL
      See Also:
      Constant Field Values

    • NIFTI_INTENT_ESTIMATE

      public static final short NIFTI_INTENT_ESTIMATE
      See Also:
      Constant Field Values

    • NIFTI_INTENT_LABEL

      public static final short NIFTI_INTENT_LABEL
      See Also:
      Constant Field Values

    • NIFTI_INTENT_NEURONAME

      public static final short NIFTI_INTENT_NEURONAME
      See Also:
      Constant Field Values

    • NIFTI_INTENT_GENMATRIX

      public static final short NIFTI_INTENT_GENMATRIX
      See Also:
      Constant Field Values

    • NIFTI_INTENT_SYMMATRIX

      public static final short NIFTI_INTENT_SYMMATRIX
      See Also:
      Constant Field Values

    • NIFTI_INTENT_DISPVECT

      public static final short NIFTI_INTENT_DISPVECT
      See Also:
      Constant Field Values

    • NIFTI_INTENT_VECTOR

      public static final short NIFTI_INTENT_VECTOR
      See Also:
      Constant Field Values

    • NIFTI_INTENT_POINTSET

      public static final short NIFTI_INTENT_POINTSET
      See Also:
      Constant Field Values

    • NIFTI_INTENT_TRIANGLE

      public static final short NIFTI_INTENT_TRIANGLE
      See Also:
      Constant Field Values

    • NIFTI_INTENT_QUATERNION

      public static final short NIFTI_INTENT_QUATERNION
      See Also:
      Constant Field Values

    • NIFTI_FIRST_STATCODE

      public static final short NIFTI_FIRST_STATCODE
      See Also:
      Constant Field Values

    • NIFTI_LAST_STATCODE

      public static final short NIFTI_LAST_STATCODE
      See Also:
      Constant Field Values

    • DT_NONE

      public static final short DT_NONE
      See Also:
      Constant Field Values

    • DT_BINARY

      public static final short DT_BINARY
      See Also:
      Constant Field Values

    • NIFTI_TYPE_UINT8

      public static final short NIFTI_TYPE_UINT8
      See Also:
      Constant Field Values

    • NIFTI_TYPE_INT16

      public static final short NIFTI_TYPE_INT16
      See Also:
      Constant Field Values

    • NIFTI_TYPE_INT32

      public static final short NIFTI_TYPE_INT32
      See Also:
      Constant Field Values

    • NIFTI_TYPE_FLOAT32

      public static final short NIFTI_TYPE_FLOAT32
      See Also:
      Constant Field Values

    • NIFTI_TYPE_COMPLEX64

      public static final short NIFTI_TYPE_COMPLEX64
      See Also:
      Constant Field Values

    • NIFTI_TYPE_FLOAT64

      public static final short NIFTI_TYPE_FLOAT64
      See Also:
      Constant Field Values

    • NIFTI_TYPE_RGB24

      public static final short NIFTI_TYPE_RGB24
      See Also:
      Constant Field Values

    • DT_ALL

      public static final short DT_ALL
      See Also:
      Constant Field Values

    • NIFTI_TYPE_INT8

      public static final short NIFTI_TYPE_INT8
      See Also:
      Constant Field Values

    • NIFTI_TYPE_UINT16

      public static final short NIFTI_TYPE_UINT16
      See Also:
      Constant Field Values

    • NIFTI_TYPE_UINT32

      public static final short NIFTI_TYPE_UINT32
      See Also:
      Constant Field Values

    • NIFTI_TYPE_INT64

      public static final short NIFTI_TYPE_INT64
      See Also:
      Constant Field Values

    • NIFTI_TYPE_UINT64

      public static final short NIFTI_TYPE_UINT64
      See Also:
      Constant Field Values

    • NIFTI_TYPE_FLOAT128

      public static final short NIFTI_TYPE_FLOAT128
      See Also:
      Constant Field Values

    • NIFTI_TYPE_COMPLEX128

      public static final short NIFTI_TYPE_COMPLEX128
      See Also:
      Constant Field Values

    • NIFTI_TYPE_COMPLEX256

      public static final short NIFTI_TYPE_COMPLEX256
      See Also:
      Constant Field Values

    • NIFTI_UNITS_UNKNOWN

      public static final short NIFTI_UNITS_UNKNOWN
      See Also:
      Constant Field Values

    • NIFTI_UNITS_METER

      public static final short NIFTI_UNITS_METER
      See Also:
      Constant Field Values

    • NIFTI_UNITS_MM

      public static final short NIFTI_UNITS_MM
      See Also:
      Constant Field Values

    • NIFTI_UNITS_MICRON

      public static final short NIFTI_UNITS_MICRON
      See Also:
      Constant Field Values

    • NIFTI_UNITS_SEC

      public static final short NIFTI_UNITS_SEC
      See Also:
      Constant Field Values

    • NIFTI_UNITS_MSEC

      public static final short NIFTI_UNITS_MSEC
      See Also:
      Constant Field Values

    • NIFTI_UNITS_USEC

      public static final short NIFTI_UNITS_USEC
      See Also:
      Constant Field Values

    • NIFTI_UNITS_HZ

      public static final short NIFTI_UNITS_HZ
      See Also:
      Constant Field Values

    • NIFTI_UNITS_PPM

      public static final short NIFTI_UNITS_PPM
      See Also:
      Constant Field Values

    • NIFTI_SLICE_SEQ_INC

      public static final short NIFTI_SLICE_SEQ_INC
      See Also:
      Constant Field Values

    • NIFTI_SLICE_SEQ_DEC

      public static final short NIFTI_SLICE_SEQ_DEC
      See Also:
      Constant Field Values

    • NIFTI_SLICE_ALT_INC

      public static final short NIFTI_SLICE_ALT_INC
      See Also:
      Constant Field Values

    • NIFTI_SLICE_ALT_DEC

      public static final short NIFTI_SLICE_ALT_DEC
      See Also:
      Constant Field Values

    • NIFTI_XFORM_UNKNOWN

      public static final short NIFTI_XFORM_UNKNOWN
      See Also:
      Constant Field Values

    • NIFTI_XFORM_SCANNER_ANAT

      public static final short NIFTI_XFORM_SCANNER_ANAT
      See Also:
      Constant Field Values

    • NIFTI_XFORM_ALIGNED_ANAT

      public static final short NIFTI_XFORM_ALIGNED_ANAT
      See Also:
      Constant Field Values

    • NIFTI_XFORM_TALAIRACH

      public static final short NIFTI_XFORM_TALAIRACH
      See Also:
      Constant Field Values

    • NIFTI_XFORM_MNI_152

      public static final short NIFTI_XFORM_MNI_152
      See Also:
      Constant Field Values

    • ds_hdrname

      protected java.lang.String ds_hdrname

    • ds_datname

      protected java.lang.String ds_datname

    • ds_is_nii

      public boolean ds_is_nii

    • big_endian

      public boolean big_endian

    • XDIM

      public short XDIM

    • YDIM

      public short YDIM

    • ZDIM

      public short ZDIM

    • TDIM

      public short TDIM

    • DIM5

      public short DIM5

    • DIM6

      public short DIM6

    • DIM7

      public short DIM7

    • freq_dim

      public short freq_dim

    • phase_dim

      public short phase_dim

    • slice_dim

      public short slice_dim

    • xyz_unit_code

      public short xyz_unit_code

    • t_unit_code

      public short t_unit_code

    • qfac

      public short qfac

    • sizeof_hdr

      public int sizeof_hdr

    • data_type_string

      public java.lang.StringBuffer data_type_string

    • db_name

      public java.lang.StringBuffer db_name

    • extents

      public int extents

    • session_error

      public short session_error

    • regular

      public java.lang.StringBuffer regular

    • dim_info

      public java.lang.StringBuffer dim_info

    • dim

      protected short[] dim

    • intent

      public float[] intent

    • intent_code

      public short intent_code

    • datatype

      protected short datatype

    • bitpix

      protected short bitpix

    • slice_start

      public short slice_start

    • pixdim

      public float[] pixdim

    • vox_offset

      public float vox_offset

    • scl_slope

      public float scl_slope

    • scl_inter

      public float scl_inter

    • slice_end

      public short slice_end

    • slice_code

      public byte slice_code

    • xyzt_units

      public byte xyzt_units

    • cal_max

      public float cal_max

    • cal_min

      public float cal_min

    • slice_duration

      public float slice_duration

    • toffset

      public float toffset

    • glmax

      public int glmax

    • glmin

      public int glmin

    • descrip

      public java.lang.StringBuffer descrip

    • aux_file

      public java.lang.StringBuffer aux_file

    • qform_code

      public short qform_code

    • sform_code

      public short sform_code

    • quatern

      public float[] quatern

    • qoffset

      public float[] qoffset

    • srow_x

      public float[] srow_x

    • srow_y

      public float[] srow_y

    • srow_z

      public float[] srow_z

    • intent_name

      public java.lang.StringBuffer intent_name

    • magic

      public java.lang.StringBuffer magic

    • extension

      public byte[] extension

  • Constructor Details

    • Nifti1Dataset

      public Nifti1Dataset​(java.lang.String name)
      Constructor for a dataset existing on disk.
      Parameters:
      name - - name of the nifti-1 dataset. The name can have the .hdr, .img, or .nii extension, optionally followed by a .gz compression suffix. Or, the name can be specified with no extensions or suffixes, in which case the program will look in this order for files with these extensions: .hdr<.gz> .img<.gz> .nii<.gz>

    • Nifti1Dataset

      public Nifti1Dataset()
      Constructor for creation of a new dataset. Default values are set, programmer must set or reset all fields appropriate for the new dataset.

  • Method Details

    • readHeader

      public void readHeader() throws java.io.IOException, java.io.FileNotFoundException
      Read header information into memory
      Throws:
      java.io.IOException
      java.io.FileNotFoundException

    • copyHeader

      public void copyHeader​(Nifti1Dataset A)

    • getExtensionsList

      public int[][] getExtensionsList()
      Get list of extensions and return it as nx2 array
      Returns:
      nx2 array where n = # of extensions, array elem 0 is the size in bytes of that extension and array elem 1 is the extension code.

    • removeExtension

      public void removeExtension​(int index)
      Remove an extension from a header
      Parameters:
      index - number of the extension to remove (0 based)

    • addExtension

      public void addExtension​(int code, java.lang.String filename) throws java.io.IOException
      Add an extension stored in a file to a header
      Parameters:
      code - -- code identifying the extension
      filename - -- filename containing the extension. The entire file will be added as an extension
      Throws:
      java.io.IOException

    • writeHeader

      public void writeHeader() throws java.io.IOException, java.io.FileNotFoundException
      Write header information to disk file
      Throws:
      java.io.IOException
      java.io.FileNotFoundException

    • printHeader

      public void printHeader()
      Print header information to standard out.

    • printDoubleTmcrs

      public void printDoubleTmcrs​(double[] d)
      Print a voxel timecourse to standard out.
      Parameters:
      d - 1D double array of timecourse values, length TDIM

    • exists

      public boolean exists()
      Check if a valid dataset (header+data) exists. Note that some operations (e.g. header editing) do not actually require that a data file exist. Use existsHdr() existsDat() in those cases. Gzipped files with .gz extension are permitted.
      Returns:
      true if header and data file exist, else false

    • existsHdr

      public boolean existsHdr()
      Check if a valid dataset header file exists.
      Returns:
      true if header file exist, else false

    • existsDat

      public boolean existsDat()
      Check if a valid dataset data file exists.
      Returns:
      true if data file exist, else false

    • setHeaderFilename

      public void setHeaderFilename​(java.lang.String s)
      Set the filename for the dataset header file
      Parameters:
      s - filename for the dataset header file

    • getHeaderFilename

      public java.lang.String getHeaderFilename()
      Get the filename for the dataset header file
      Returns:
      String with the disk filename for the dataset header file

    • setDataFilename

      public void setDataFilename​(java.lang.String s)
      Set the filename for the dataset data file
      Parameters:
      s - filename for the dataset data file

    • getDataFilename

      public java.lang.String getDataFilename()
      Get the filename for the dataset data file
      Returns:
      filename for the dataset data file

    • setDims

      public void setDims​(short a, short x, short y, short z, short t, short d5, short d6, short d7)
      Set the dataset dimensions

    • setDatatype

      public void setDatatype​(short code)
      Set the dataset datatype. (bitpix will also be set accordingly.)
      Parameters:
      code - nifti-1 datatype code

    • getDatatype

      public short getDatatype()
      Get the dataset datatype.
      Returns:
      datatype code (note: it is not guaranteed to be a valid code, what is there is what you get...)

    • getBitpix

      public short getBitpix()
      Get the bitpix field
      Returns:
      bitpix: number of bits per pixel

    • decodeIntent

      public java.lang.String decodeIntent​(short icode)
      Decode the nifti intent codes
      Parameters:
      icode - nifti intent code
      Returns:
      a terse string describing the intent

    • decodeDatatype

      public java.lang.String decodeDatatype​(short dcode)
      Decode the nifti datatype codes
      Parameters:
      dcode - nifti datatype code
      Returns:
      a terse string describing the datatype

    • bytesPerVoxel

      public short bytesPerVoxel​(short dcode)
      Return bytes per voxel for each nifti-1 datatype
      Parameters:
      dcode - nifti datatype code
      Returns:
      a short with number of bytes per voxel, 0 for unknown, -1 for 1 bit

    • decodeSliceOrder

      public java.lang.String decodeSliceOrder​(short code)
      Decode the nifti slice order codes
      Parameters:
      code - nifti slice order code
      Returns:
      a terse string describing the slice order

    • decodeXform

      public java.lang.String decodeXform​(short code)
      Decode the nifti xform codes
      Parameters:
      code - nifti xform code
      Returns:
      a terse string describing the coord. system

    • decodeUnits

      public java.lang.String decodeUnits​(short code)
      Decode the nifti unit codes
      Parameters:
      code - nifti units code
      Returns:
      a terse string describing the unit

    • checkHeader

      public short checkHeader()
      Check the header fields for valid settings
      Returns:
      0 if all checks are passed else, error code

    • readDoubleVol

      public double[][][] readDoubleVol​(short ttt) throws java.io.IOException
      Read one 3D volume from disk and return it as 3D double array
      Parameters:
      ttt - T dimension of vol to read (0 based index)
      Returns:
      3D double array, scale and offset have been applied. Array indices are [Z][Y][X], assuming an xyzt ordering of dimensions. ie indices are data[dim[3]][dim[2]][dim[1]]
      Throws:
      java.io.IOException

    • writeVol

      public void writeVol​(double[][][] data, short ttt) throws java.io.IOException
      Write one 3D double array to disk. Data is written in datatype of this Nifti1Dataset instance. Data is "un-scaled" as per scale/offset fields of this Nifti1Dataset instance, before being written to disk.
      Parameters:
      data - 3D array of array data Array indices are [Z][Y][X], assuming an xyzt ordering of dimensions. ie indices are data[dim[3]][dim[2]][dim[1]]
      ttt - T dimension of vol to write (0 based index)
      Throws:
      java.io.IOException

    • getGzTempFile

      protected java.lang.String getGzTempFile​(java.lang.String file_name)

    • readData

      public byte[] readData() throws java.io.IOException
      Read all the data into one byte array. Note that since the data is handled as bytes, NO byte swapping has been performed. Applications converting from the byte array to int/float datatypes will need to swap bytes if necessary. return byte array with all image data
      Throws:
      java.io.IOException

    • writeData

      public void writeData​(byte[] b) throws java.io.IOException
      Write a byte array of data to disk, starting at vox_offset, beginning of image data. It is assumed that usually the entire data array will be written with this call. Note that since the data is handled as bytes, NO byte swapping will be performed. Applications needing byteswapping must swap the bytes correctly in the input array b.
      Parameters:
      b - byte array of image data
      Throws:
      java.io.IOException

    • readDoubleTmcrs

      public double[] readDoubleTmcrs​(short x, short y, short z) throws java.io.IOException
      Read one 1D timecourse from a 4D dataset, ie all T values for a given XYZ location. Scaling is applied.
      Parameters:
      x - X dimension of vol to read (0 based index)
      y - Y dimension of vol to read (0 based index)
      z - Z dimension of vol to read (0 based index)
      Returns:
      1D double array
      Throws:
      java.io.IOException

    • main

      public static void main​(java.lang.String[] args)
      main routine is used only for testing
      Parameters:
      args -