nifti 0.0.1

data/Gemfile.lock

@@ -0,0 +1,30 @@
+PATH
+  remote: .
+  specs:
+    nifti (0.0.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    mocha (0.9.10)
+      rake
+    narray (0.5.9.9)
+    rake (0.8.7)
+    rspec (2.4.0)
+      rspec-core (~> 2.4.0)
+      rspec-expectations (~> 2.4.0)
+      rspec-mocks (~> 2.4.0)
+    rspec-core (2.4.0)
+    rspec-expectations (2.4.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.4.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  mocha
+  narray
+  nifti!
+  rspec

data/README.markdown

@@ -0,0 +1,126 @@
+RUBY NIfTI
+==========
+
+Ruby NIfTI is a pure-ruby library for handling NIfTI data in Ruby. NIfTI
+[(Neuroimaging Informatics Technology Initiative)](http://nifti.nimh.nih.gov/)
+is an image format designed primarily for storing and analyzing MRI & PET
+imaging data.
+
+Ruby NIfTI currently only supports basic access to NIfTI files, including
+basic and extended header information, as well as image information. It
+doesn't attempt to touch the image data (rotate it, etc.), but it does provide
+access to qform and sform orientation matrices. Nonetheless it does provide a
+nice interface to get at NIfTI info from within ruby. Since Ruby isn't as
+widely seen as a quantitative scripting language yet (Python is more well
+known, and PyNifti is more mature than NumericalRuby / NArray) I don't know
+how widely this will be used, but hopefully it will be useful for somebody.
+
+INSTALLATION
+------------
+
+    gem install nifti
+
+
+BASIC USAGE
+-----------
+
+    require "nifti"
+    # Read file:
+    obj = NIFTI::NObject.new("some_file.nii")
+    # Display some key information about the file:
+	  puts obj.header['sform_code_descr']
+    => "NIFTI_XFORM_SCANNER_ANAT"
+    # Retrieve the pixel data in a Ruby Array:
+    image = obj.get_image
+    # Load the pixel data to an NArray image object and display it on the screen:
+    image = obj.get_image_narray
+
+LIMITATIONS
+-----------
+
+There are plenty of NIfTI libraries around (the canonical
+[nifticlib](http://niftilib.sourceforge.net/), which includes c, python and
+matlab interfaces, and Matlab interfaces in the Mathworks image processing
+toolbox (IPT) and [Toolbox for
+NIfTI](http://www.mathworks.com/matlabcentral/fileexchange/8797-tools-for-nifti-and-analyze-image)
+by Jimmy Shen. 
+
+This library does not intend to replace them, but rather to provide a few ruby
+convenience methods for quickly accessing imaging data from ruby without
+having to call out to external programs, as well as write custom extensions to
+the NIfTI header. At current, it doesn't do much more than byte parsing and
+providing access to the header, and its quite slow when compared to existing
+libraries. However, [narray](http://narray.rubyforge.org/) is picking up and
+its possible that people would want to have some easy way to access NIfTI info
+using custom ruby libraries.
+
+
+CREDIT
+------
+
+Ruby NIfTI is highly derivative of the very good library [Ruby
+DICOM](http://dicom.rubyforge.org/), from which all of the design and most of
+the code has been cold-heartedly stolen. Many thanks to Chris Lervag - this
+wouldn't exist without his examples.
+
+
+RESOURCES
+---------
+
+* [Official home page](http://brainmap.wisc.edu/pages/10-RUBY-NIFTI)
+* [Development / Source code repository](https://github.com/brainmap/ruby-nifti)
+* [Documentation](http://rdoc.info/github/brainmap/ruby-nifti/master/frames)
+
+
+Examples
+--------
+
+### Using Extended Headers ###
+
+Each NObject that is successfully read has an array of extended_header hashes.
+Each extended_header hash has 3 keys, :esize, :ecode, and :data corresponding
+to the available fields in the nifti header extension.
+
+Here's a silly example (since you'd probably want to read do this using
+something that's designed for it, like 3dinfo). Suppose you wanted to collect
+the history of an image from inside the AFNI extended header. Since the data
+of the AFNI extended header is just xml, you could easily parse it with an xml
+parser like nokogiri (using the AFNI ecode of 4 to select it from the list of
+extended headers, and assuming that there's only 1 AFNI header per file):
+
+    require 'nifti'; require 'nokogiri'
+    obj = NIFTI::NObject.new('./T1.nii')
+    afni_extended_header = obj.extended_header.select{|ext| ext[:ecode] == 4 }[:data]
+    afni_xml = Nokogiri::XML(xml)
+    history = afni_xml.xpath("//AFNI_atr[@atr_name='HISTORY_NOTE']").first.children.first.text
+
+### Image Summary Statistics ###
+
+Again, this is a trivial example, but shows one usage of the library. Say you
+want to take find the mean and std dev of the entire image.
+
+    obj = NIFTI::NObject.new('./T1.nii', :narray => true)
+    mean = obj.image.mean
+    stddev = obj.image.stddev
+
+If you don't have narray installed, you could still use obj.image as a ruby
+array, but you'd have to collect the summary stats yourself.
+
+
+COPYRIGHT
+---------
+
+Copyright 2011 Erik Kastman
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see http://www.gnu.org/licenses/ .

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/lib/nifti/constants.rb

@@ -0,0 +1,223 @@
+module NIFTI
+  # Variables used to determine endianness.
+  x = 0xdeadbeef
+  endian_type = {
+    Array(x).pack("V*") => false, # Little
+    Array(x).pack("N*") => true   # Big
+  }
+  # System (CPU) Endianness.
+  CPU_ENDIAN = endian_type[Array(x).pack("L*")]
+
+  # Custom string used for (un)packing big endian signed short.
+  CUSTOM_SS = "k*"
+  # Custom string used for (un)packing big endian signed long.
+  CUSTOM_SL = "r*"
+
+  # Q/S Form Transform codes defined in the nifti header
+  # Reference: http://nifti.nimh.nih.gov/nifti-1/documentation/nifti1fields/nifti1fields_pages/qsform.html
+  XFORM_CODES = {
+    0 => 'NIFTI_XFORM_UNKNOWN',       # Arbitrary coordinates (Method 1). 
+    1 => 'NIFTI_XFORM_SCANNER_ANAT',  # Scanner-based anatomical coordinates
+    2 => 'NIFTI_XFORM_ALIGNED_ANAT',  # Coordinates aligned to another file's, or to anatomical "truth".
+    3 => 'NIFTI_XFORM_TALAIRACH',     # Coordinates aligned to Talairach-Tournoux Atlas; (0,0,0)=AC, etc.
+    4 => 'NIFTI_XFORM_MNI_152'        # MNI 152 normalized coordinates
+  }
+
+    # Take a NIFTI TypeCode and return datatype and bitpix
+    # 
+    # From Jimmy Shen: 
+    # Set bitpix according to datatype
+    # /*Acceptable values for datatype are*/ 
+    # 
+    #    0 None                     (Unknown bit per voxel) % DT_NONE, DT_UNKNOWN 
+    #    1 Binary                         (ubit1, bitpix=1) % DT_BINARY 
+    #    2 Unsigned char         (uchar or uint8, bitpix=8) % DT_UINT8, NIFTI_TYPE_UINT8 
+    #    4 Signed short                  (int16, bitpix=16) % DT_INT16, NIFTI_TYPE_INT16 
+    #    8 Signed integer                (int32, bitpix=32) % DT_INT32, NIFTI_TYPE_INT32 
+    #   16 Floating point    (single or float32, bitpix=32) % DT_FLOAT32, NIFTI_TYPE_FLOAT32 
+    #   32 Complex, 2 float32      (Use float32, bitpix=64) % DT_COMPLEX64, NIFTI_TYPE_COMPLEX64
+    #   64 Double precision  (double or float64, bitpix=64) % DT_FLOAT64, NIFTI_TYPE_FLOAT64 
+    #  128 uint8 RGB                 (Use uint8, bitpix=24) % DT_RGB24, NIFTI_TYPE_RGB24 
+    #  256 Signed char            (schar or int8, bitpix=8) % DT_INT8, NIFTI_TYPE_INT8 
+    #  511 Single RGB              (Use float32, bitpix=96) % DT_RGB96, NIFTI_TYPE_RGB96
+    #  512 Unsigned short               (uint16, bitpix=16) % DT_UNINT16, NIFTI_TYPE_UNINT16 
+    #  768 Unsigned integer             (uint32, bitpix=32) % DT_UNINT32, NIFTI_TYPE_UNINT32 
+    # 1024 Signed long long              (int64, bitpix=64) % DT_INT64, NIFTI_TYPE_INT64
+    # 1280 Unsigned long long           (uint64, bitpix=64) % DT_UINT64, NIFTI_TYPE_UINT64 
+    # 1536 Long double, float128  (Unsupported, bitpix=128) % DT_FLOAT128, NIFTI_TYPE_FLOAT128 
+    # 1792 Complex128, 2 float64  (Use float64, bitpix=128) % DT_COMPLEX128, NIFTI_TYPE_COMPLEX128 
+    # 2048 Complex256, 2 float128 (Unsupported, bitpix=256) % DT_COMPLEX128, NIFTI_TYPE_COMPLEX128 
+    NIFTI_DATATYPES = {
+      0 => "Unknown",
+      # 1 => "", Can't find a single bit encoding in ruby's unpack method?
+      2 => "OB",
+      4 => "SS",
+      8 => "SL",
+     16 => "FL",
+     32 => "FD",
+     64 => "FD",
+    128 => "RGBUnknown",
+    256 => "BY",
+    511 => "RGBUnknown",
+    512 => "US",
+    768 => "UL"
+   # 1024 => "",
+   # 1280 => "",
+   # 1536 => "",
+   # 1792 => "",
+   # 2048 => ""
+  }
+
+  # The NIFTI signature is hardcoded by bytes. This consists of arrays for 
+  # each item in the signature, where item[0] is the name of the item,
+  # item[1] is the length in bytes of the item, and dim[2] is the Format
+  # string to use in packing/unpacking the item.
+  HEADER_SIGNATURE = [
+    #                           /**********************/    /**********************/     /***************/
+    # struct nifti_1_header {  /* NIFTI-1 usage      */    /*ANALYZE 7.5 field(s)*/     /* Byte offset */
+    #                         /**********************/    /**********************/     /***************/
+    #  int   sizeof_hdr;    /*!< MUST be 348           */  /* int sizeof_hdr;      */   /*   0 */
+    ['sizeof_hdr', 4, 'SL'],
+  
+    #  char  data_type[10]; /*!< ++UNUSED++            */  /* char data_type[10];  */   /*   4 */
+    ['data_type', 10, 'STR'],
+  
+    #  char  db_name[18];   /*!< ++UNUSED++            */  /* char db_name[18];    */   /*  14 */
+    ['db_name', 18, 'STR'],
+  
+    #  int   extents;       /*!< ++UNUSED++            */  /* int extents;         */   /*  32 */
+    ['extents', 4, "SL"],
+
+    #  short session_error; /*!< ++UNUSED++            */  /* short session_error; */   /*  36 */
+    ['session_error', 2, "SS"],
+
+    #  char  regular;       /*!< ++UNUSED++            */  /* char regular;        */   /*  38 */
+    ['regular', 1, "STR"],
+
+    #  char  dim_info;      /*!< MRI slice ordering.   */  /* char hkey_un0;       */   /*  39 */
+    ['dim_info', 1, "BY"],
+
+
+    #                                       /*--- was image_dimension substruct ---*/
+    #  short dim[8];        /*!< Data array dimensions.*/  /* short dim[8];        */   /*  40 */
+    ['dim', 16, "US"],
+
+    #  float intent_p1;     /*!< 1st intent parameter. */  /* short unused8;       */   /*  56 */
+    ['intent_p1', 4, "FL"],
+
+    #  float intent_p2;     /*!< 2nd intent parameter. */  /* short unused10;      */   /*  60 */
+    ['intent_p2', 4, "FL"],
+    #                                                      /* short unused11;      */
+    #  float intent_p3;     /*!< 3rd intent parameter. */  /* short unused12;      */   /*  64 */
+    ['intent_p3', 4, "FL"],
+
+    #  short intent_code;   /*!< NIFTIINTENT code.     */  /* short unused14;      */   /*  68 */
+    ['intent_code', 2, "US"],
+
+    #  short datatype;      /*!< Defines data type!    */  /* short datatype;      */   /*  70 */
+    ['datatype', 2, "US"],
+  
+    #  short bitpix;        /*!< Number bits/voxel.    */  /* short bitpix;        */   /*  72 */
+    ['bitpix', 2, "US"],
+
+    #  short slice_start;   /*!< First slice index.    */  /* short dim_un0;       */   /*  74 */
+    ['slice_start', 2, "US"],
+
+    #  float pixdim[8];     /*!< Grid spacings.        */  /* float pixdim[8];     */   /*  76 */
+    ['pixdim', 32, "FL"],
+
+    #  float vox_offset;    /*!< Offset into .nii file */  /* float vox_offset;    */   /* 108 */
+    ['vox_offset', 4, "FL"],
+
+    #  float scl_slope;     /*!< Data scaling: slope.  */  /* float funused1;      */   /* 112 */
+    ['scl_slope', 4, "FL"],
+
+    #  float scl_inter;     /*!< Data scaling: offset. */  /* float funused2;      */   /* 116 */
+    ['scl_inter', 4, "FL"],
+
+    #  short slice_end;     /*!< Last slice index.     */  /* float funused3;      */   /* 120 */
+    ['slice_end', 2, "US"],
+
+    #  char  slice_code;    /*!< Slice timing order.   */                               /* 122 */
+    ['slice_code', 1, "BY"],
+
+    #  char  xyzt_units;    /*!< Units of pixdim[1..4] */                               /* 123 */
+    ['xyzt_units', 1, "BY"],
+
+    #  float cal_max;       /*!< Max display intensity */  /* float cal_max;       */   /* 124 */
+    ['cal_max', 4, "FL"],
+
+    #  float cal_min;       /*!< Min display intensity */  /* float cal_min;       */   /* 128 */
+    ['cal_min', 4, "FL"],
+
+    #  float slice_duration;/*!< Time for 1 slice.     */  /* float compressed;    */   /* 132 */
+    ['slice_duration', 4, "FL"],
+
+    #  float toffset;       /*!< Time axis shift.      */  /* float verified;      */   /* 136 */
+    ['toffset', 4, "FL"],
+
+    #  int   glmax;         /*!< ++UNUSED++            */  /* int glmax;           */   /* 140 */
+    ['glmax', 4, "UL"],
+
+    #  int   glmin;         /*!< ++UNUSED++            */  /* int glmin;           */   /* 144 */
+    ['glmin', 4, "UL"],
+
+    #                                          /*--- was data_history substruct ---*/
+    #  char  descrip[80];   /*!< any text you like.    */  /* char descrip[80];    */   /* 148 */
+    ['descrip', 80, "STR"],
+
+    #  char  aux_file[24];  /*!< auxiliary filename.   */  /* char aux_file[24];   */   /* 228 */
+    ['aux_file', 24, "STR"],
+
+    # 
+    #  short qform_code;    /*!< NIFTIXFORM code.      */  /*-- all ANALYZE 7.5 ---*/   /* 252 */
+    ['qform_code', 2, "US"],                           #   /*   fields below here  */
+                                                      #    /*   are replaced       */
+    #  short sform_code;    /*!< NIFTIXFORM code.      */                               /* 254 */
+    ['sform_code', 2, "US"],
+    #                                                      
+    #  float quatern_b;     /*!< Quaternion b param.    */                              /* 256 */
+    ['quatern_b', 4, "FL"],
+
+    #  float quatern_c;     /*!< Quaternion c param.    */                              /* 260 */
+    ['quatern_c', 4, "FL"],
+
+    #  float quatern_d;     /*!< Quaternion d param.    */                              /* 264 */
+    ['quatern_d', 4, "FL"],
+
+
+    #  float qoffset_x;     /*!< Quaternion x shift.    */                              /* 268 */
+    ['qoffset_x', 4, "FL"],
+
+    #  float qoffset_y;     /*!< Quaternion y shift.    */                              /* 272 */
+    ['qoffset_y', 4, "FL"],
+
+    #  float qoffset_z;     /*!< Quaternion z shift.    */                              /* 276 */
+    ['qoffset_z', 4, "FL"],
+
+    #  float srow_x[4];     /*!< 1st row affine transform.   */                         /* 280 */
+    ['srow_x', 16, "FL"],
+
+    #  float srow_y[4];     /*!< 2nd row affine transform.   */                         /* 296 */
+    ['srow_y', 16, "FL"],
+
+    #  float srow_z[4];     /*!< 3rd row affine transform.   */                         /* 312 */
+    ['srow_z', 16, "FL"],
+
+    # 
+    # 
+    #  char intent_name[16];/*!< name or meaning of data.  */                         /* 328 */
+    ['intent_name', 16, "STR"],
+
+    # 
+    # 
+    #  char magic[4];       /*!< MUST be "ni1\0" or "n+1\0". */                         /* 344 */
+    ['magic', 4, "STR"]
+
+    # } ;                   /** 348 bytes total **/
+    # 
+    # 
+  
+  
+  ]
+end

data/lib/nifti/n_object.rb

@@ -0,0 +1,155 @@
+module NIFTI
+  # The NObject class is the main class for interacting with the NIFTI object.
+  # Reading from and writing to files is executed from instances of this class.
+  # 
+  class NObject
+    # An array which contain any notices/warnings/errors that have been recorded for the NObject instance.
+    attr_reader :errors
+    # A boolean which is set as true if a NIFTI file has been successfully read & parsed from a file (or binary string).
+    attr_reader :read_success
+    # The Stream instance associated with this DObject instance (this attribute is mostly used internally).
+    attr_reader :stream
+    # A boolean which is set as true if a DObject instance has been successfully written to file (or successfully encoded).
+    attr_reader :write_success
+    # A hash of header information
+    attr_accessor :header
+    # A hash of extended attributes
+    attr_accessor :extended_header
+    # An array or narray of image values
+    attr_accessor :image
+
+    # Creates an NObject instance (NObject is an abbreviation for "NIFTI object").
+    #
+    # The NObject instance holds references to the NIFTI Header and Image
+    # A NObject is typically built by reading and parsing a file or a
+    # binary string, but can also be built from an empty state by the user.
+    #
+    # === Parameters
+    #
+    # * <tt>string</tt> -- A string which specifies either the path of a DICOM file to be loaded, or a binary DICOM string to be parsed. The parameter defaults to nil, in which case an empty DObject instance is created.
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:bin</tt> -- Boolean. If set to true, string parameter will be interpreted as a binary DICOM string, and not a path string, which is the default behaviour.
+    # * <tt>:syntax</tt> -- String. If a syntax string is specified, the DRead class will be forced to use this transfer syntax when decoding the file/binary string.
+    # * <tt>:verbose</tt> -- Boolean. If set to false, the NObject instance will run silently and not output warnings and error messages to the screen. Defaults to true.
+    # * <tt>:image</tt> -- Boolean. If set to true, automatically load the image into @image, otherwise only a header is collected and you can get an image from #get_image
+    # * <tt>:narray</tt> -- Boolean. If set to true, the NObject will build a properly shaped narray from the image data.
+    #
+    # === Examples
+    #
+    #   # Load a NIFTI file's header information:
+    #   require 'nifti'
+    #   obj = NIFTI::NObject.new("test.nii")
+    #   # Read a NIFTI header and image into a numerical-ruby narray:
+    #   obj = Nfiti::NObject.new("test.nii", :image => true, :narray => true)
+    #   # Create an empty NIfTI object & choose non-verbose behaviour:
+    #   obj = NIFTI::NObject.new(nil, :verbose => false)
+    #
+    def initialize(string=nil, options={})
+      # Process option values, setting defaults for the ones that are not specified:
+      # Default verbosity is true if verbosity hasn't been specified (nil):
+      @verbose = (options[:verbose] == false ? false : true)
+      # Messages (errors, warnings or notices) will be accumulated in an array:
+      @errors = Array.new
+      # Structural information (default values):
+      @file_endian = false
+      # Control variables:
+      @read_success = nil
+
+      # Call the read method if a string has been supplied:
+      if string.is_a?(String)
+        @file = string unless options[:bin]
+        read(string, options)
+      elsif not string == nil
+        raise ArgumentError, "Invalid argument. Expected String (or nil), got #{string.class}."
+      end
+      
+    end
+    
+    # Reopen the NIFTI File and retrieve image data
+    def get_image
+      r = NRead.new(@string, :image => true)
+      if r.success
+        @image = r.image_rubyarray
+      end
+    end
+    
+    # Passes the NObject to the DWrite class, which writes out the header and image to the specified file.
+    #
+    # === Parameters
+    #
+    # * <tt>file_name</tt> -- A string which identifies the path & name of the NIfTI file which is to be written to disk.
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # === Examples
+    #
+    #   obj.write(path + "test.dcm")
+    #
+    def write(file_name, options={})
+      if file_name.is_a?(String)
+        w = NWrite.new(self, file_name, options)
+        w.write
+        # Write process succesful?
+        @write_success = w.success
+        # If any messages has been recorded, send these to the message handling method:
+        add_msg(w.msg) if w.msg.length > 0
+      else
+        raise ArgumentError, "Invalid file_name. Expected String, got #{file_name.class}."
+      end
+    end
+    
+    # Following methods are private:
+    private 
+    
+    # Returns a NIFTI object by reading and parsing the specified file.
+    # This is accomplished by initializing the NRead class, which loads NIFTI information.
+    #
+    # === Notes
+    #
+    # This method is called automatically when initializing the NObject class with a file parameter,
+    # and in practice should not be called by users.
+    # 
+    def read(string, options={})
+      if string.is_a?(String)
+        @string = string
+        r = NRead.new(string, options)
+        # Store the data to the instance variables if the readout was a success:
+        if r.success
+          @read_success = true
+          # Update instance variables based on the properties of the NRead object:
+          @header = r.hdr
+          @extended_header = r.extended_header
+          if r.image_narray
+            @image = r.image_narray 
+          elsif r.image_rubyarray
+            @image = r.image_rubyarray
+          end
+        else
+          @read_success = false
+        end
+        # If any messages have been recorded, send these to the message handling method:
+        add_msg(r.msg) if r.msg.length > 0
+      else
+        raise ArgumentError, "Invalid argument. Expected String, got #{string.class}."
+      end
+    end
+
+    # Adds one or more status messages to the instance array holding messages, and if the verbose instance variable
+    # is true, the status message(s) are printed to the screen as well.
+    #
+    # === Parameters
+    #
+    # * <tt>msg</tt> -- Status message string, or an array containing one or more status message strings.
+    #
+    def add_msg(msg)
+      puts msg if @verbose
+      @errors << msg
+      @errors.flatten
+    end
+    
+  end
+end