nifti 0.0.1

data/lib/nifti/stream.rb

@@ -0,0 +1,373 @@
+module NIFTI
+  # The Stream class handles string operations (encoding to and decoding from binary strings).
+  #  
+  class Stream
+    # A boolean which reports the relationship between the endianness of the system and the instance string.
+    attr_reader :equal_endian
+    # Our current position in the instance string (used only for decoding).
+    attr_accessor :index
+    # The instance string.
+    attr_accessor :string
+    # The endianness of the instance string.
+    attr_reader :str_endian
+    # An array of warning/error messages that (may) have been accumulated.
+    attr_reader :errors
+    # A hash of proper strings (based on endianess) to use for unpacking binary strings.
+    attr_reader :format
+    # A File object to write to
+    attr_accessor :file
+    
+    # Creates a Stream instance.
+    #
+    # === Parameters
+    #
+    # * <tt>binary</tt> -- A binary string.
+    # * <tt>string_endian</tt> -- Boolean. The endianness of the instance string (true for big endian, false for small endian).
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:index</tt> -- Fixnum. A position (offset) in the instance string where reading will start.
+    #
+    def initialize(binary, string_endian, options={})
+      @string = binary || ""
+      @index = options[:index] || 0
+      @errors = Array.new
+      self.endian = string_endian
+    end
+    
+
+    
+    # Decodes a section of the instance string and returns the formatted data.
+    # The instance index is offset in accordance with the length read.
+    #
+    # === Notes
+    #
+    # * If multiple numbers are decoded, these are returned in an array.
+    #
+    # === Parameters
+    #
+    # * <tt>length</tt> -- Fixnum. The string length which will be decoded.
+    # * <tt>type</tt> -- String. The type (vr) of data to decode.
+    #
+    def decode(length, type)
+      # Check if values are valid:
+      if (@index + length) > @string.length
+        # The index number is bigger then the length of the binary string.
+        # We have reached the end and will return nil.
+        value = nil
+      else
+        if type == "AT"
+          value = decode_tag
+        else
+          # Decode the binary string and return value:
+          value = @string.slice(@index, length).unpack(vr_to_str(type))
+          # If the result is an array of one element, return the element instead of the array.
+          # If result is contained in a multi-element array, the original array is returned.
+          if value.length == 1
+            value = value[0]
+            # If value is a string, strip away possible trailing whitespace:
+            # Do this using gsub instead of ruby-core #strip to keep trailing carriage
+            # returns, etc., because that is valid whitespace that we want to have included
+            # (i.e. in extended header data, AFNI writes a \n at the end of it's xml info, 
+            # and that must be kept in order to not change the file on writing back out).
+            value.gsub!(/\000*$/, "") if value.respond_to? :gsub!
+          end
+          # Update our position in the string:
+          skip(length)
+        end
+      end
+      return value
+    end    
+    
+    # Returns the length of the binary instance string.
+    #
+    def length
+      return @string.length
+    end
+
+    # Calculates and returns the remaining length of the instance string (from the index position).
+    #
+    def rest_length
+      length = @string.length - @index
+      return length
+    end
+
+    # Extracts and returns the remaining part of the instance string (from the index position to the end of the string).
+    #
+    def rest_string
+      str = @string[@index..(@string.length-1)]
+      return str
+    end
+
+    # Resets the instance string and index.
+    #
+    def reset
+      @string = ""
+      @index = 0
+    end
+
+    # Resets the instance index.
+    #
+    def reset_index
+      @index = 0
+    end
+
+    # Sets an instance file variable.
+    #
+    # === Notes
+    #
+    # For performance reasons, we enable the Stream instance to write directly to file,
+    # to avoid expensive string operations which will otherwise slow down the write performance.
+    #
+    # === Parameters
+    #
+    # * <tt>file</tt> -- A File instance.
+    #
+    def set_file(file)
+      @file = file
+    end
+
+    # Sets a new instance string, and resets the index variable.
+    #
+    # === Parameters
+    #
+    # * <tt>binary</tt> -- A binary string.
+    #
+    def set_string(binary)
+      binary = binary[0] if binary.is_a?(Array)
+      @string = binary
+      @index = 0
+    end
+
+    # Applies an offset (positive or negative) to the instance index.
+    #
+    # === Parameters
+    #
+    # * <tt>offset</tt> -- Fixnum. The length to skip (positive) or rewind (negative).
+    #
+    def skip(offset)
+      @index += offset
+    end
+    
+    # Converts a data type/vr to an encode/decode string used by the pack/unpack methods, which is returned.
+    #
+    # === Parameters
+    #
+    # * <tt>vr</tt> -- String. A data type (value representation).
+    #
+    def vr_to_str(vr)
+      unless @format[vr]
+        errors << "Warning: Element type #{vr} does not have a reading method assigned to it. Something is not implemented correctly or the DICOM data analyzed is invalid."
+        return @hex
+      else
+        return @format[vr]
+      end
+    end
+    
+    # Sets an instance file variable.
+    #
+    # === Notes
+    #
+    # For performance reasons, we enable the Stream instance to write directly to file,
+    # to avoid expensive string operations which will otherwise slow down the write performance.
+    #
+    # === Parameters
+    #
+    # * <tt>file</tt> -- A File instance.
+    #
+    def set_file(file)
+      @file = file
+    end
+    
+    # Writes a binary string to the File instance.
+    #
+    # === Parameters
+    #
+    # * <tt>binary</tt> -- A binary string.
+    #
+    def write(binary)
+      @file.write(binary)
+    end
+    
+    # Encodes a value and returns the resulting binary string.
+    #
+    # === Parameters
+    #
+    # * <tt>value</tt> -- A custom value (String, Fixnum, etc..) or an array of numbers.
+    # * <tt>type</tt> -- String. The type (vr) of data to encode.
+    #
+    def encode(value, type)
+      value = [value] unless value.is_a?(Array)
+      return value.pack(vr_to_str(type))
+    end
+    
+    # Appends a string with trailling spaces to achieve a target length, and encodes it to a binary string.
+    # Returns the binary string.  Raises an error if pad option is different than :null or :spaces
+    #
+    # === Parameters
+    #
+    # * <tt>string</tt> -- A string to be processed.
+    # * <tt>target_length</tt> -- Fixnum. The target length of the string that is created.
+    # * <tt>pad</tt> -- Type of desired padding, either :null or :spaces
+    #
+    def encode_string_to_length(string, target_length, pad = :null)
+      if pad == :spaces
+        template = "A#{target_length}"
+      elsif pad == :null
+        template = "a#{target_length}"
+      else
+        raise StandardError, "Could not identify padding type #{pad}"
+      end
+      
+      length = string.length
+      if length < target_length
+        return [string].pack(template)
+      elsif length == target_length
+        return [string].pack(@str)
+      else
+        raise "The specified string is longer than the allowed maximum length (String: #{string}, Target length: #{target_length})."
+      end
+    end
+    
+    # Following methods are private:
+    private
+
+
+    # Determines the relationship between system and string endianness, and sets the instance endian variable.
+    #
+    def configure_endian
+      if CPU_ENDIAN == @str_endian
+        @equal_endian = true
+      else
+        @equal_endian = false
+      end
+    end
+    
+    # Sets the pack/unpack format strings that is used for encoding/decoding.
+    # Some of these depends on the endianness of the system and the String.
+    #
+    #--
+    # Note: Surprisingly the Ruby pack/unpack methods lack a format for signed short
+    # and signed long in the network byte order. A hack has been implemented to to ensure
+    # correct behaviour in this case, but it is slower (~4 times slower than a normal pack/unpack).
+    #
+    def set_string_formats
+      if @equal_endian
+        # Native byte order:
+        @us = "S*" # Unsigned short (2 bytes)
+        @ss = "s*" # Signed short (2 bytes)
+        @ul = "I*" # Unsigned long (4 bytes)
+        @sl = "l*" # Signed long (4 bytes)
+        @fs = "e*" # Floating point single (4 bytes)
+        @fd = "E*" # Floating point double ( 8 bytes)
+      else
+        # Network byte order:
+        @us = "n*"
+        @ss = CUSTOM_SS # Custom string for our redefined pack/unpack.
+        @ul = "N*"
+        @sl = CUSTOM_SL # Custom string for our redefined pack/unpack.
+        @fs = "g*"
+        @fd = "G*"
+      end
+      # Format strings that are not dependent on endianness:
+      @by = "C*" # Unsigned char (1 byte)
+      @str = "a*"
+      @hex = "H*" # (this may be dependent on endianness(?))
+    end
+  
+    # Sets the hash which is used to convert data element types (VR) to
+    # encode/decode strings accepted by the pack/unpack methods.
+    #
+    def set_format_hash
+      @format = {
+        "BY" => @by, # Byte/Character (1-byte integers)
+        "US" => @us, # Unsigned short (2 bytes)
+        "SS" => @ss, # Signed short (2 bytes)
+        "UL" => @ul, # Unsigned long (4 bytes)
+        "SL" => @sl, # Signed long (4 bytes)
+        "FL" => @fs, # Floating point single (4 bytes)
+        "FD" => @fd, # Floating point double (8 bytes)
+        "OB" => @by, # Other byte string (1-byte integers)
+        "OF" => @fs, # Other float string (4-byte floating point numbers)
+        "OW" => @us, # Other word string (2-byte integers)
+        "AT" => @hex, # Tag reference (4 bytes) NB: This may need to be revisited at some point...
+        "UN" => @hex, # Unknown information (header element is not recognized from local database)
+        "HEX" => @hex, # HEX
+        # We have a number of VRs that are decoded as string:
+        "AE" => @str,
+        "AS" => @str,
+        "CS" => @str,
+        "DA" => @str,
+        "DS" => @str,
+        "DT" => @str,
+        "IS" => @str,
+        "LO" => @str,
+        "LT" => @str,
+        "PN" => @str,
+        "SH" => @str,
+        "ST" => @str,
+        "TM" => @str,
+        "UI" => @str,
+        "UT" => @str,
+        "STR" => @str
+      }
+    end
+    
+    # Sets the hash which is used to keep track of which bytes to use for padding
+    # data elements of various vr which have an odd value length.
+    #
+    def set_pad_byte
+      @pad_byte = {
+        # Space character:
+        "AE" => "\x20",
+        "AS" => "\x20",
+        "CS" => "\x20",
+        "DA" => "\x20",
+        "DS" => "\x20",
+        "DT" => "\x20",
+        "IS" => "\x20",
+        "LO" => "\x20",
+        "LT" => "\x20",
+        "PN" => "\x20",
+        "SH" => "\x20",
+        "ST" => "\x20",
+        "TM" => "\x20",
+        "UT" => "\x20",
+        # Zero byte:
+        "AT" => "\x00",
+        "FL" => "\x00",
+        "FD" => "\x00",
+        "OB" => "\x00",
+        "OF" => "\x00",
+        "OW" => "\x00",
+        "SL" => "\x00",
+        "SQ" => "\x00",
+        "SS" => "\x00",
+        "UI" => "\x00",
+        "UL" => "\x00",
+        "UN" => "\x00",
+        "US" => "\x00"
+      }
+      @pad_byte.default = "\20"
+    end
+
+
+    # Sets the endianness of the instance string. The relationship between the string endianness and
+    # the system endianness, determines which encoding/decoding flags to use.
+    #
+    # === Parameters
+    #
+    # * <tt>string_endian</tt> -- Boolean. The endianness of the instance string (true for big endian, false for small endian).
+    #
+    def endian=(string_endian)
+      @str_endian = string_endian
+      configure_endian
+      set_string_formats
+      set_format_hash
+      set_pad_byte
+    end
+
+  end
+  
+end

data/lib/nifti/version.rb

@@ -0,0 +1,4 @@
+module NIFTI
+  # Current Version of NIFTI
+  VERSION = "0.0.1"
+end

data/lib/nifti.rb

@@ -0,0 +1,23 @@
+$: << File.dirname(__FILE__)
+
+# Loads the files that are used by Ruby NIFTI.
+#
+# The following classes are meant to be used by users of Ruby DICOM:
+# * NObject - for reading, manipulating and writing DICOM files.
+
+# NIFTI is the main namespace for all Ruby NIfTI classes, constants and methods.
+module NIFTI; end
+
+# Core library:
+require 'nifti/n_object'
+require 'nifti/n_read'
+require 'nifti/n_write'
+require 'nifti/stream'
+require 'nifti/constants'
+
+begin
+  require 'narray'
+rescue LoadError => e
+  puts "NArray requried for some image visualization options."
+  puts "Run 'gem install narray' or 'bundle install' to get it."
+end

data/nifti.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "nifti/version"
+
+Gem::Specification.new do |s|
+  s.name        = "nifti"
+  s.version     = NIFTI::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Erik Kastman"]
+  s.email       = ["ekk@medicine.wisc.edu"]
+  s.homepage    = ""
+  s.summary     = %q{A pure Ruby API to the NIfTI Neuroimaging Format}
+  s.description = %q{A pure Ruby API to the NIfTI Neuroimaging Format}
+
+  s.rubyforge_project = "nifti"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "mocha"
+  s.add_development_dependency "narray"
+end

data/spec/custom_matchers.rb

@@ -0,0 +1,13 @@
+require 'digest/md5'
+
+# Source: Matt Wynne; https://gist.github.com/736421
+RSpec::Matchers.define(:be_same_file_as) do |exected_file_path|
+  match do |actual_file_path|
+    md5_hash(actual_file_path).should == md5_hash(exected_file_path)
+  end
+
+  # Calculate an md5 hash from a file path
+  def md5_hash(file_path)
+    Digest::MD5.hexdigest(File.read(file_path))    
+  end
+end

data/spec/interactive/compare.rb

@@ -0,0 +1,43 @@
+# Reopen File to add a diff calculator for investigating byte differences between fixtures and created files.
+class File
+  # Checks if two files contain the same contents. Prints and returns a
+  # position and values of differences, or returns nil if there were no
+  # differnces.
+  def File.same_contents(p1, p2)
+    f1 = open(p1).read
+    f2 = open(p2).read
+    
+    # Control variables
+    differences = []
+    read_length = 1
+    same = true
+    index = 0
+    
+    while ((index + read_length) < f1.length) && ((index + read_length) < f2.length)
+      same = f1.slice(index, read_length) == f2.slice(index, read_length)
+      unless same
+        puts index 
+        pp f1.slice(index, read_length).unpack("C*")
+        pp f2.slice(index, read_length).unpack("C*")
+        differences << {:index => index, 
+          :f1_value => f1.slice(index, read_length).unpack("C*"),
+          :f2_value => f2.slice(index, read_length).unpack("C*")
+        }
+      end
+      index = index + read_length
+      differences
+    end
+  end
+end
+
+# # Original comparison from Ruby Cookbook by Carlson & Richardson
+# open(p1) do |f1|
+#   open(p2) do |f2|
+#     puts blocksize = f1.lstat.blksize
+#     same = true
+#     while same && !f1.eof? && !f2.eof?
+#       same = f1.read(blocksize) == f2.read(blocksize)
+#     end
+#     return same
+#   end
+# end

data/spec/nifti/n_object_spec.rb

@@ -0,0 +1,111 @@
+require 'spec_helper'
+
+describe NIFTI::NObject do
+  before :all do
+    @string = File.open(NIFTI_TEST_FILE1, 'rb').read
+    @fixture_image_length = 983040
+    @fixture_afni_extension_length = 5661
+    @new_fixture_file_name = '5PlLoc.nii'
+    @valid_header = {
+      "xyzt_units"=>2, "pixdim"=>[1.0, 0.9375, 0.9375, 12.5, 0.0, 0.0, 0.0,
+      0.0], "sform_code"=>1, "aux_file"=>"", "scl_slope"=>0.0,
+      "srow_x"=>[-0.9375, -0.0, -0.0, 119.53125], "glmin"=>0, "freq_dim"=>0,
+      "srow_y"=>[-0.0, -0.9375, -0.0, 159.531005859375], "qform_code"=>1,
+      "slice_duration"=>0.0, "cal_min"=>0.0, "db_name"=>"", "magic"=>"n+1",
+      "srow_z"=>[0.0, 0.0, 12.5, -25.0], "quatern_b"=>0.0, "data_type"=>"",
+      "qform_code_descr"=>"NIFTI_XFORM_SCANNER_ANAT",
+      "sform_code_descr"=>"NIFTI_XFORM_SCANNER_ANAT", "intent_name"=>"",
+      "quatern_c"=>0.0, "slice_end"=>0, "scl_inter"=>0.0, "quatern_d"=>1.0,
+      "slice_code"=>0, "sizeof_hdr"=>348, "slice_dim"=>0,
+      "qoffset_x"=>119.53125, "dim_info"=>0, "phase_dim"=>0,
+      "qoffset_y"=>159.531005859375, "descrip"=>"", "datatype"=>4,
+      "intent_p1"=>0.0, "dim"=>[3, 256, 256, 15, 1, 1, 1, 1],
+      "qoffset_z"=>-25.0, "glmax"=>0, "toffset"=>0.0, "bitpix"=>16,
+      "intent_code"=>0, "intent_p2"=>0.0, "session_error"=>0, "extents"=>0,
+      "cal_max"=>0.0, "vox_offset"=>6032.0, "slice_start"=>0,
+      "intent_p3"=>0.0, "regular"=>"r"
+    }
+  end
+  
+  # Think of these more as integration tests, since the actual reading
+  # is done and tested in the NRead spec
+  it "should read a nifti file and correctly initialize header and image" do
+    obj = NObject.new(NIFTI_TEST_FILE1)
+    
+    obj.header.should == @valid_header
+    obj.extended_header.should_not be_empty
+    obj.extended_header.first[:esize].should == 5680
+    obj.extended_header.first[:ecode].should == 4
+    obj.extended_header.first[:data].length.should == @fixture_afni_extension_length
+    obj.image.should be_nil
+    
+  end
+
+  it "should read a binary string and correctly initialize header and image" do
+    obj = NObject.new(@string, :bin => true)
+    
+    obj.header.should == @valid_header
+    obj.extended_header.should_not be_empty
+    obj.extended_header.first[:esize].should == 5680
+    obj.extended_header.first[:ecode].should == 4
+    obj.extended_header.first[:data].length.should == @fixture_afni_extension_length
+    obj.image.should be_nil
+        
+  end
+  
+  it "should read a nifti file with image" do
+    obj = NObject.new(NIFTI_TEST_FILE1, :image => true)
+    
+    obj.header.should == @valid_header
+    obj.extended_header.should_not be_empty
+    obj.extended_header.first[:esize].should == 5680
+    obj.extended_header.first[:ecode].should == 4
+    obj.extended_header.first[:data].length.should == @fixture_afni_extension_length
+    obj.image.should_not be_nil
+    obj.image.length.should == @fixture_image_length
+    
+  end
+  
+  it "should read a nifti file with image as narray" do
+    obj = NObject.new(NIFTI_TEST_FILE1, :image => true, :narray => true)
+    
+    obj.header.should == @valid_header
+    obj.extended_header.should_not be_empty
+    obj.extended_header.first[:esize].should == 5680
+    obj.extended_header.first[:ecode].should == 4
+    obj.extended_header.first[:data].length.should == @fixture_afni_extension_length
+    obj.image.should_not be_nil
+    obj.image.class.should == NArray
+    obj.image.dim.should == 3
+    
+  end
+  
+  it "should retrieve image data when requested" do
+    obj = NObject.new(NIFTI_TEST_FILE1)
+    obj.get_image.length.should == @fixture_image_length
+  end
+  
+  
+  it "should raise an error if initialized with bad argument" do
+    lambda {
+      NObject.new(12345)
+    }.should raise_error ArgumentError, /Invalid argument/
+  end
+  
+  it "should sucessfully write a NIfTI file" do
+    obj = NObject.new(NIFTI_TEST_FILE1, :image => true)
+    obj.write(@new_fixture_file_name)
+    File.exist?(@new_fixture_file_name).should be_true
+    obj.write_success.should be_true
+  end
+  
+  it "should be able to assign an image" do 
+    obj = NObject.new(@string, :bin => true, :image => true)
+    obj.image = [0] * @fixture_image_length
+  end
+  
+  after :each do
+    File.delete @new_fixture_file_name if File.exist? @new_fixture_file_name
+  end
+
+end