dicom 0.8 → 0.9

data/lib/dicom/ruby_extensions.rb

@@ -1,11 +1,34 @@
-# This file contains extensions to the Ruby library which are used by Ruby-DICOM.
+# encoding: UTF-8
+
+# This file contains extensions to the Ruby library which are used by Ruby DICOM.
 
 # Extension to the String class. These extensions are focused on processing/analysing Data Element tags.
-# A tag string (as used by the Ruby-DICOM library) is 9 characters long and of the form "GGGG,EEEE"
+# A tag string (as used by the Ruby DICOM library) is 9 characters long and of the form "GGGG,EEEE"
 # (where G represents a group hexadecimal, and E represents an element hexadecimal).
 #
 class String
 
+  # Renames the original unpack method.
+  #
+  alias __original_unpack__ unpack
+
+  # Divides a string into a number of sub-strings of exactly equal length, and returns these in an array.
+  # The length of self must be a multiple of parts, or an error will be raised.
+  #
+  def divide(parts)
+    raise ArgumentError, "Expected an integer (Fixnum). Got #{parts.class}." unless parts.is_a?(Fixnum)
+    raise ArgumentError, "Argument must be in the range <1 - self.length (#{self.length})>. Got #{parts}." if parts < 1 or parts > self.length
+    raise ArgumentError, "Length of self (#{self.length}) must be a multiple of parts (#{parts})." unless (self.length/parts).to_f == self.length/parts.to_f
+    if parts > 1
+      sub_strings = Array.new
+      sub_length = self.length/parts
+      parts.times { sub_strings << self.slice!(0..(sub_length-1)) }
+      return sub_strings
+    else
+      return [self]
+    end
+  end
+
   # Returns the element part of the tag string: The last 4 characters.
   #
   def element
@@ -44,7 +67,7 @@ class String
     return ((self.upcase =~ /\A[a-fA-F\d]{3}[1,3,5,7,9,B,D,F],[a-fA-F\d]{4}\z/) == nil ? false : true)
   end
 
-  # Checks if the string is a valid tag (as defined by Ruby-DICOM: "GGGG,EEEE").
+  # Checks if the string is a valid tag (as defined by Ruby DICOM: "GGGG,EEEE").
   # Returns true if it is a valid tag, false if not.
   #
   def tag?
@@ -53,4 +76,153 @@ class String
     return ((self.upcase =~ /\A[a-fA-F\d]{4},[a-fA-F\d]{4}\z/) == nil ? false : true)
   end
 
+  # Redefines the old unpack method, adding the ability to decode signed integers in big endian.
+  #
+  # === Parameters
+  #
+  # * <tt>string</tt> -- A template string which decides the decoding scheme to use.
+  #
+  def unpack(string)
+    # Check for some custom unpack strings that we've invented:
+    case string
+      when "k*" # SS
+        # Unpack BE US, repack LE US, then finally unpack LE SS:
+        wrongly_unpacked = self.__original_unpack__("n*")
+        repacked = wrongly_unpacked.__original_pack__("S*")
+        correct = repacked.__original_unpack__("s*")
+      when "r*" # SL
+        # Unpack BE UL, repack LE UL, then finally unpack LE SL:
+        wrongly_unpacked = self.__original_unpack__("N*")
+        repacked = wrongly_unpacked.__original_pack__("I*")
+        correct = repacked.__original_unpack__("l*")
+      else
+        # Call the original method for all other (normal) cases:
+        self.__original_unpack__(string)
+    end
+  end
+
+  # Returns true for all values that LOOK like a DICOM name - they may not be valid.
+  #
+  def dicom_name?
+    self==self.titleize
+  end
+
+  # Returns true for all strings that LOOK like a DICOM method name - they may not be valid.
+  #
+  def dicom_method?
+    self == self.underscore
+  end
+
+  # Returns a proper DICOM method name string.
+  #
+  def dicom_methodize
+    self.gsub(/^3/,'three_').gsub(/[#*?!]/,' ').gsub(', ',' ').gsub('&','and').gsub(' - ','_').gsub(' / ','_').gsub(/[\s\-\.\,\/\\]/,'_').gsub(/[\(\)\']/,'').gsub(/\_+/, '_').downcase
+  end
+
+  # Capitalizes all the words and replaces some characters in the string to make a nicer looking title.
+  #
+  def titleize
+    self.underscore.gsub(/_/, " ").gsub(/\b('?[a-z])/) { $1.capitalize }
+  end
+
+  # Makes an underscored, lowercase form from the string expression.
+  #
+  def underscore
+    word = self.dup
+    word.tr!("-", "_")
+    word.downcase!
+    word
+  end
+
+end
+
+
+# Extensions to the Array class.
+# These methods deal with encoding Integer arrays as well as conversion between signed and unsigned integers.
+#
+class Array
+
+  # Renames the original pack method.
+  #
+  alias __original_pack__ pack
+
+  # Redefines the old pack method, adding the ability to encode signed integers in big endian
+  # (which surprisingly has not been supported out of the box in Ruby).
+  #
+  # === Parameters
+  #
+  # * <tt>string</tt> -- A template string which decides the encoding scheme to use.
+  #
+  def pack(string)
+    # Check for some custom pack strings that we've invented:
+    case string
+      when "k*" # SS
+        # Pack LE SS, re-unpack as LE US, then finally pack BE US:
+        wrongly_packed = self.__original_pack__("s*")
+        reunpacked = wrongly_packed.__original_unpack__("S*")
+        correct = reunpacked.__original_pack__("n*")
+      when "r*" # SL
+        # Pack LE SL, re-unpack as LE UL, then finally pack BE UL:
+        wrongly_packed = self.__original_pack__("l*")
+        reunpacked = wrongly_packed.__original_unpack__("I*")
+        correct = reunpacked.__original_pack__("N*")
+      else
+        # Call the original method for all other (normal) cases:
+        self.__original_pack__(string)
+    end
+  end
+
+  # Packs an array of (unsigned) integers to a binary string (blob).
+  #
+  # === Parameters
+  #
+  # * <tt>depth</tt> -- The bith depth to be used when encoding the unsigned integers.
+  #
+  def to_blob(depth)
+    raise ArgumentError, "Expected Integer, got #{depth.class}" unless depth.is_a?(Integer)
+    raise ArgumentError, "Unsupported bit depth #{depth}." unless [8,16].include?(depth)
+    case depth
+    when 8
+      return self.pack("C*") # Unsigned char
+    when 16
+      return self.pack("S*") # Unsigned short, native byte order
+    end
+  end
+
+  # Shifts the integer values of the array to make a signed data set.
+  # The size of the shift is determined by the bit depth.
+  #
+  # === Parameters
+  #
+  # * <tt>depth</tt> -- The bith depth of the integers.
+  #
+  def to_signed(depth)
+    raise ArgumentError, "Expected Integer, got #{depth.class}" unless depth.is_a?(Integer)
+    raise ArgumentError, "Unsupported bit depth #{depth}." unless [8,16].include?(depth)
+    case depth
+    when 8
+      return self.collect {|i| i - 128}
+    when 16
+      return self.collect {|i| i - 32768}
+    end
+  end
+
+  # Shifts the integer values of the array to make an unsigned data set.
+  # The size of the shift is determined by the bit depth.
+  #
+  # === Parameters
+  #
+  # * <tt>depth</tt> -- The bith depth of the integers.
+  #
+  def to_unsigned(depth)
+    raise ArgumentError, "Expected Integer, got #{depth.class}" unless depth.is_a?(Integer)
+    raise ArgumentError, "Unsupported bit depth #{depth}." unless [8,16].include?(depth)
+    case depth
+    when 8
+      return self.collect {|i| i + 128}
+    when 16
+      return self.collect {|i| i + 32768}
+    end
+  end
+
 end

data/lib/dicom/sequence.rb

@@ -1,13 +1,11 @@
-#    Copyright 2010 Christoffer Lervag
-
 module DICOM
 
   # The Sequence class handles information related to Sequence elements.
   #
-  class Sequence < SuperParent
+  class Sequence < Parent
 
-    # Include the Elements mix-in module:
-    include Elements
+    # Include the Elemental mix-in module:
+    include Elemental
 
     # Creates a Sequence instance.
     #
@@ -36,6 +34,7 @@ module DICOM
     #   encapsulated_pixel_data = Sequence.new("7FE0,0010", :name => "Encapsulated Pixel Data", :parent => obj, :vr => "OW")
     #
     def initialize(tag, options={})
+      raise ArgumentError, "The supplied tag (#{tag}) is not valid. The tag must be a string of the form 'GGGG,EEEE'." unless tag.is_a?(String) && tag.tag?
       # Set common parent variables:
       initialize_parent
       # Set instance variables:
@@ -54,7 +53,7 @@ module DICOM
       @length = options[:length] || -1
       if options[:parent]
         @parent = options[:parent]
-        @parent.add(self)
+        @parent.add(self, :no_follow => true)
       end
     end
 

data/lib/dicom/stream.rb

@@ -1,5 +1,3 @@
-#    Copyright 2009-2010 Christoffer Lervag
-
 module DICOM
 
   # The Stream class handles string operations (encoding to and decoding from binary strings).
@@ -14,6 +12,8 @@ module DICOM
     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 with vr as key and its corresponding pad byte as value.
@@ -71,23 +71,29 @@ module DICOM
     # * <tt>type</tt> -- String. The type (vr) of data to decode.
     #
     def decode(length, type)
+      raise ArgumentError, "Invalid argument length. Expected Fixnum, got #{length.class}" unless length.is_a?(Fixnum)
+      raise ArgumentError, "Invalid argument type. Expected string, got #{type.class}" unless type.is_a?(String)
       # 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
-        # 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:
-          value = value.rstrip if value.is_a?(String)
+        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:
+            value = value.rstrip if value.is_a?(String)
+          end
+          # Update our position in the string:
+          skip(length)
         end
-        # Update our position in the string:
-        skip(length)
       end
       return value
     end
@@ -143,6 +149,7 @@ module DICOM
     # * <tt>type</tt> -- String. The type (vr) of data to encode.
     #
     def encode(value, type)
+      raise ArgumentError, "Invalid argument type. Expected string, got #{type.class}" unless type.is_a?(String)
       value = [value] unless value.is_a?(Array)
       return value.pack(vr_to_str(type))
     end
@@ -216,14 +223,18 @@ module DICOM
     # * <tt>vr</tt> -- String. The type of data to encode.
     #
     def encode_value(value, vr)
-      # Make sure the value is in an array:
-      value = [value] unless value.is_a?(Array)
-      # Get the proper pack string:
-      type = vr_to_str(vr)
-      # Encode:
-      bin = value.pack(type)
-      # Add an empty byte if the resulting binary has an odd length:
-      bin = bin + @pad_byte[vr] if bin.length[0] == 1
+      if vr == "AT"
+        bin = encode_tag(value)
+      else
+        # Make sure the value is in an array:
+        value = [value] unless value.is_a?(Array)
+        # Get the proper pack string:
+        type = vr_to_str(vr)
+        # Encode:
+        bin = value.pack(type)
+        # Add an empty byte if the resulting binary has an odd length:
+        bin = bin + @pad_byte[vr] if bin.length[0] == 1
+      end
       return bin
     end
 
@@ -398,7 +409,7 @@ module DICOM
         "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...
+        "AT" => @hex, # Tag reference (4 bytes) NB: For tags the spesialized encode_tag/decode_tag methods are used instead of this lookup table.
         "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:
@@ -462,8 +473,9 @@ module DICOM
     # Some of these depends on the endianness of the system and the String.
     #
     #--
-    # FIXME: Apparently the Ruby pack/unpack methods lacks a format for signed short
-    # and signed long in the network byte order. A solution needs to be found for this.
+    # 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
@@ -477,9 +489,9 @@ module DICOM
       else
         # Network byte order:
         @us = "n*"
-        @ss = "n*" # Not correct (gives US)
+        @ss = CUSTOM_SS # Custom string for our redefined pack/unpack.
         @ul = "N*"
-        @sl = "N*" # Not correct (gives UL)
+        @sl = CUSTOM_SL # Custom string for our redefined pack/unpack.
         @fs = "g*"
         @fd = "G*"
       end

data/lib/dicom/variables.rb

@@ -0,0 +1,51 @@
+module DICOM
+
+  class << self
+
+    #--
+    # Module attributes:
+    #++
+
+    # The ruby-dicom image processor to be used.
+    attr_accessor :image_processor
+    # The key representation for hashes, json, yaml.
+    attr_accessor :key_representation
+    # Source Application Entity Title (gets written to the DICOM header in files where it is undefined).
+    attr_accessor :source_app_title
+
+    #--
+    # Module methods:
+    #++
+
+    # Use tags as key. Example: "0010,0010"
+    #
+    def key_use_tags
+      @key_representation = :tag
+    end
+
+    # Use names as key. Example: "Patient's Name"
+    #
+    def key_use_names
+      @key_representation = :name
+    end
+
+    # Use method names as key. Example: :patients_name
+    #
+    def key_use_method_names
+      @key_representation = :name_as_method
+    end
+
+  end
+
+  #--
+  # Default variable settings:
+  #++
+
+  # The default image processor.
+  self.image_processor = :rmagick
+  # The default key representation.
+  self.key_representation = :name
+  # The default source application entity title.
+  self.source_app_title = "RUBY_DICOM"
+
+end

data/lib/dicom/version.rb

@@ -0,0 +1,6 @@
+module DICOM
+
+  # The ruby-dicom version string.
+  VERSION = "0.9"
+
+end

metadata

@@ -1,7 +1,8 @@
 --- !ruby/object:Gem::Specification 
 name: dicom
 version: !ruby/object:Gem::Version 
-  version: "0.8"
+  prerelease: 
+  version: "0.9"
 platform: ruby
 authors: 
 - Christoffer Lervag
@@ -9,10 +10,74 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-01 00:00:00 +02:00
-default_executable: 
-dependencies: []
-
+date: 2011-05-17 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.0.0
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.5.0
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.9.12
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: narray
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rmagick
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: mini_magick
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 3.2.1
+  type: :development
+  version_requirements: *id006
 description: DICOM is a standard widely used throughout the world to store and transfer medical image data. This library enables efficient and powerful handling of DICOM in Ruby, to the benefit of any student or professional who would like to use their favorite language to process DICOM files and communicate across the network.
 email: chris.lervag@gmail.com
 executables: []
@@ -22,31 +87,34 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
-- lib/dicom.rb
-- lib/dicom/dictionary.rb
-- lib/dicom/constants.rb
-- lib/dicom/item.rb
 - lib/dicom/anonymizer.rb
+- lib/dicom/constants.rb
+- lib/dicom/d_client.rb
+- lib/dicom/d_library.rb
 - lib/dicom/d_object.rb
-- lib/dicom/stream.rb
-- lib/dicom/sequence.rb
-- lib/dicom/super_item.rb
-- lib/dicom/link.rb
-- lib/dicom/file_handler.rb
-- lib/dicom/d_write.rb
+- lib/dicom/d_read.rb
 - lib/dicom/d_server.rb
-- lib/dicom/super_parent.rb
+- lib/dicom/d_write.rb
+- lib/dicom/dictionary.rb
+- lib/dicom/element.rb
+- lib/dicom/elemental.rb
+- lib/dicom/file_handler.rb
+- lib/dicom/image_item.rb
+- lib/dicom/image_processor.rb
+- lib/dicom/image_processor_mini_magick.rb
+- lib/dicom/image_processor_r_magick.rb
+- lib/dicom/item.rb
+- lib/dicom/link.rb
+- lib/dicom/parent.rb
 - lib/dicom/ruby_extensions.rb
-- lib/dicom/d_read.rb
-- lib/dicom/d_client.rb
-- lib/dicom/elements.rb
-- lib/dicom/d_library.rb
-- lib/dicom/data_element.rb
-- CHANGELOG
-- README
+- lib/dicom/sequence.rb
+- lib/dicom/stream.rb
+- lib/dicom/variables.rb
+- lib/dicom/version.rb
+- lib/dicom.rb
+- CHANGELOG.rdoc
 - COPYING
-- init.rb
-has_rdoc: true
+- README.rdoc
 homepage: http://dicom.rubyforge.org/
 licenses: []
 
@@ -56,21 +124,21 @@ rdoc_options: []
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
       version: 1.8.6
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      version: 1.3.4
-  version: 
+      version: 1.3.6
 requirements: []
 
 rubyforge_project: dicom
-rubygems_version: 1.3.5
+rubygems_version: 1.8.2
 signing_key: 
 specification_version: 3
 summary: Library for handling DICOM files and DICOM network communication.