dicom 0.9.5 → 0.9.6

data/lib/dicom/extensions/hash.rb

@@ -0,0 +1,31 @@
+# Extensions to the Hash class used by the dicom gem.
+#
+class Hash
+
+  # Creates a gap in the integer keys at the specified index.
+  # This is achieved by incrementing by one all existing index keys that are equal or
+  # bigger than the given index.
+  #
+  # @note It is assumed that this hash features integers as keys and items as values!
+  # @param [Integer] index the index at which to clear
+  # @return [Hash] the modified self
+  #
+  def create_key_gap_at(index)
+    # Extract existing Hash entries to an array:
+    pairs = self.sort
+    h = Hash.new
+    # Change the key of those equal or larger than index and put these key,value pairs back in a new Hash:
+    pairs.each do |pair|
+      if pair[0] < index
+        # The key keeps its old index:
+        h[pair[0]] = pair[1]
+      else
+        # The key (and the value Item) gets its index incremented by one:
+        h[pair[0]+1] = pair[1]
+        pair[1].index = pair[0]+1
+      end
+    end
+    h
+  end
+
+end

data/lib/dicom/extensions/string.rb

@@ -0,0 +1,126 @@
+# encoding: UTF-8
+
+# Extension to the String class. These mainly facilitate the processing and analysis of element tags.
+# 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
+
+  # Checks if a string value LOOKS like a DICOM name - it may still not be valid one.
+  #
+  # @return [Boolean] true if a string looks like a DICOM name, and false if not
+  #
+  def dicom_name?
+    self == self.dicom_titleize
+  end
+
+  # Checks if a string value LOOKS like a DICOM method name - it may still not be valid one.
+  #
+  # @return [Boolean] true if a string looks like a DICOM method name, and false if not
+  #
+  def dicom_method?
+    self == self.dicom_underscore
+  end
+
+  # Capitalizes all the words in the string and replaces some characters to make a nicer looking title.
+  #
+  # @return [String] a formatted, capitalized string
+  #
+  def dicom_titleize
+    self.dicom_underscore.gsub(/_/, ' ').gsub(/\b('?[a-z])/) { $1.capitalize }
+  end
+
+  # Makes an underscored, lowercased version of the string.
+  #
+  # @return [String] an underscored, lower case string
+  #
+  def dicom_underscore
+    word = self.dup
+    word.tr!('-', '_')
+    word.downcase!
+    word
+  end
+
+  # Divides a string into a number of sub-strings of exactly equal length.
+  #
+  # @note The length of self must be a multiple of parts, or an exception will be raised.
+  # @param [Integer] parts the number of sub-strings to create
+  # @return [Array<String>] the divided sub-strings
+  #
+  def divide(parts)
+    parts = parts.to_i
+    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})." if (self.length/parts.to_f % 1) != 0
+    sub_strings = Array.new
+    sub_length = self.length/parts
+    start_index = 0
+    parts.times {
+      sub_strings <<  self.slice(start_index, sub_length)
+      start_index += sub_length
+    }
+    sub_strings
+  end
+
+  # Extracts the element part of the tag string: The last 4 characters.
+  #
+  # @return [String] the element part of the tag
+  #
+  def element
+    return self[5..8]
+  end
+
+  # Returns the group part of the tag string: The first 4 characters.
+  #
+  # @return [String] the group part of the tag
+  #
+  def group
+    return self[0..3]
+  end
+
+  # Returns the "Group Length" ('GGGG,0000') tag which corresponds to the original tag/group string.
+  # The original string may either be a 4 character group string, or a 9 character custom tag.
+  #
+  # @return [String] a group length tag
+  #
+  def group_length
+    if self.length == 4
+      return self + ',0000'
+    else
+      return self.group + ',0000'
+    end
+  end
+
+  # Checks if the string is a "Group Length" tag (its element part is '0000').
+  #
+  # @return [Boolean] true if it is a group length tag, and false if not
+  #
+  def group_length?
+    return (self.element == '0000' ? true : false)
+  end
+
+  # Checks if the string is a private tag (has an odd group number).
+  #
+  # @return [Boolean] true if it is a private tag, and false if not
+  #
+  def private?
+    return ((self.upcase =~ /\A\h{3}[1,3,5,7,9,B,D,F],\h{4}\z/) == nil ? false : true)
+  end
+
+  # Checks if the string is a valid tag (as defined by ruby-dicom: 'GGGG,EEEE').
+  #
+  # @return [Boolean] true if it is a valid tag, and false if not
+  #
+  def tag?
+    # Test that the string is composed of exactly 4 HEX characters, followed by a comma, then 4 more HEX characters:
+    return ((self.upcase =~ /\A\h{4},\h{4}\z/) == nil ? false : true)
+  end
+
+  # Converts the string to a proper DICOM element method name symbol.
+  #
+  # @return [Symbol] a DICOM element method name
+  #
+  def to_element_method
+    self.gsub(/^3/,'three_').gsub(/[#*?!]/,' ').gsub(', ',' ').gsub('&','and').gsub(' - ','_').gsub(' / ','_').gsub(/[\s\-\.\,\/\\]/,'_').gsub(/[\(\)\']/,'').gsub(/\_+/, '_').downcase.to_sym
+  end
+
+end

data/lib/dicom/{constants.rb → general/constants.rb}

@@ -1,8 +1,5 @@
 module DICOM
 
-  # Defines the gem root directory in the file system.
-  ROOT_DIR = "#{File.dirname(__FILE__)}"
-
   # Ruby DICOM's registered DICOM UID root (Implementation Class UID).
   UID_ROOT = "1.2.826.0.1.3680043.8.641"
   # Ruby DICOM name & version (max 16 characters).
@@ -109,14 +106,6 @@ module DICOM
   # 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*"
-
-  # ruby-dicom's library instance (data dictionary).
-  LIBRARY =  DICOM::DLibrary.new
-
   # Transfer Syntaxes (taken from the DICOM Specification PS 3.5, Chapter 10).
 
   # General
@@ -184,36 +173,38 @@ module DICOM
     'GB18030'    => 'GB18030',
     'ISO_IR 192' => 'UTF-8'
   }
+  ENCODING_NAME.default = 'ASCII-8BIT'
 
   # The type conversion (method) used for the various value representations.
   VALUE_CONVERSION = {
-        'BY' => :to_i,
-        'US' => :to_i,
-        'SS' => :to_i,
-        'UL' => :to_i,
-        'SL' => :to_i,
-        'OB' => :to_i,
-        'OW' => :to_i,
-        'OF' => :to_f,
-        'FL' => :to_f,
-        'FD' => :to_f,
-        'AT' => :to_s,
-        'AE' => :to_s,
-        'AS' => :to_s,
-        'CS' => :to_s,
-        'DA' => :to_s,
-        'DS' => :to_s,
-        'DT' => :to_s,
-        'IS' => :to_s,
-        'LO' => :to_s,
-        'LT' => :to_s,
-        'PN' => :to_s,
-        'SH' => :to_s,
-        'ST' => :to_s,
-        'TM' => :to_s,
-        'UI' => :to_s,
-        'UT' => :to_s
-      }
+    'BY' => :to_i,
+    'US' => :to_i,
+    'SS' => :to_i,
+    'UL' => :to_i,
+    'SL' => :to_i,
+    'OB' => :to_i,
+    'OW' => :to_i,
+    'OF' => :to_f,
+    'FL' => :to_f,
+    'FD' => :to_f,
+    'AT' => :to_s,
+    'AE' => :to_s,
+    'AS' => :to_s,
+    'CS' => :to_s,
+    'DA' => :to_s,
+    'DS' => :to_s,
+    'DT' => :to_s,
+    'IS' => :to_s,
+    'LO' => :to_s,
+    'LT' => :to_s,
+    'PN' => :to_s,
+    'SH' => :to_s,
+    'ST' => :to_s,
+    'TM' => :to_s,
+    'UI' => :to_s,
+    'UT' => :to_s
+  }
+  VALUE_CONVERSION.default = :to_s
 
 end
 

data/lib/dicom/{variables.rb → general/methods.rb}

@@ -2,17 +2,6 @@ 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:
     #++
@@ -91,15 +80,4 @@ module DICOM
 
   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/general/variables.rb

@@ -0,0 +1,29 @@
+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
+
+  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 → general/version.rb}

@@ -1,6 +1,6 @@
 module DICOM
 
   # The ruby-dicom version string.
-  VERSION = '0.9.5'
+  VERSION = '0.9.6'
 
 end

data/lib/dicom/image_item.rb

@@ -119,7 +119,6 @@ module DICOM
     # image frames, the first image frame is returned, unless the :frame option is used.
     #
     # @note Creates an image object in accordance with the selected image processor. Available processors are :rmagick and :mini_magick.
-    # @note When calling this method the corresponding image processor gem must have been loaded in advance (example: require 'RMagick').
     #
     # @param [Hash] options the options to use for extracting the image
     # @option options [Integer] :frame for DICOM objects containing multiple frames, this option can be used to extract a specific image frame (defaults to 0)
@@ -145,7 +144,6 @@ module DICOM
     # the image related elements in the DICOM object.
     #
     # @note Creates an array of image objects in accordance with the selected image processor. Available processors are :rmagick and :mini_magick.
-    # @note When calling this method the corresponding image processor gem must have been loaded in advance (example: require 'RMagick').
     #
     # @param [Hash] options the options to use for extracting the images
     # @option options [Integer] :frame makes the method return an array containing only the image object corresponding to the specified frame number

data/lib/dicom/image_processor.rb

@@ -66,8 +66,10 @@ module DICOM
     def image_module
       case DICOM.image_processor
       when :mini_magick
+        require 'mini_magick'
         DcmMiniMagick
       when :rmagick
+        require 'rmagick'
         DcmRMagick
       else
         raise "Uknown image processor #{DICOM.image_processor}"

data/lib/dicom/item.rb

@@ -9,8 +9,8 @@ module DICOM
   #
   class Item < ImageItem
 
-    # Include the Elemental mix-in module:
     include Elemental
+    include ElementalParent
 
     # The index of this Item in the group of items belonging to its parent. If the Item is without parent, index is nil.
     attr_accessor :index
@@ -98,18 +98,6 @@ module DICOM
       state.hash
     end
 
-    # Loads data from an encoded DICOM string and creates
-    # sequences and elements which are linked to this instance.
-    #
-    # @param [String] bin an encoded binary string containing DICOM information
-    # @param [String] syntax the transfer syntax to use when decoding the DICOM string
-    #
-    def parse(bin, syntax)
-      raise ArgumentError, "Invalid argument 'bin'. Expected String, got #{bin.class}." unless bin.is_a?(String)
-      raise ArgumentError, "Invalid argument 'syntax'. Expected String, got #{syntax.class}." unless syntax.is_a?(String)
-      read(bin, signature=false, :syntax => syntax)
-    end
-
     # Returns self.
     #
     # @return [Item] self

data/lib/dicom/link.rb

@@ -1426,6 +1426,7 @@ module DICOM
       response = IO.select([@session], nil, nil, @timeout)
       if response.nil?
         logger.error("No answer was received within the specified timeout period. Aborting.")
+        stop_receiving
       else
         data = @session.recv(@max_receive_size)
       end
@@ -1486,7 +1487,7 @@ module DICOM
         if info[:role_negotiation]
           pos = 3
           info[:role_negotiation].each do |role|
-            msg = Stream.new(message, @net_endian)
+            msg = Stream.new('', @net_endian)
             uid = role[:sop_uid]
             # Length of UID (2 bytes):
             msg.encode_first(uid.length, "US")

data/lib/dicom/parent.rb

@@ -61,76 +61,6 @@ module DICOM
       end
     end
 
-    # Adds a child item to a Sequence (or Item in some cases where pixel data is encapsulated).
-    #
-    # If no existing Item is given, a new item will be created and added.
-    #
-    # @note Items are specified by index (starting at 0) instead of a tag string!
-    #
-    # @param [Item] item the Item instance to be added
-    # @param [Hash] options the options used for adding the item
-    # option options [Integer] :if specified, forces the item to be inserted at that specific index (Item number)
-    # option options [Boolean] :no_follow when true, the method does not update the parent attribute of the child that is added
-    # * <tt>options</tt> -- A hash of parameters.
-    # @example Add an empty Item to a specific Sequence
-    #   dcm["3006,0020"].add_item
-    # @example Add an existing Item at the 2nd item position/index in the specific Sequence
-    #   dcm["3006,0020"].add_item(my_item, :index => 1)
-    #
-    def add_item(item=nil, options={})
-      unless self.is_a?(DObject)
-        if item
-          if item.is_a?(Item)
-            if options[:index]
-              # This Item will take a specific index, and all existing Items with index higher or equal to this number will have their index increased by one.
-              # Check if index is valid (must be an existing index):
-              if options[:index] >= 0
-                # If the index value is larger than the max index present, we dont need to modify the existing items.
-                if options[:index] < @tags.length
-                  # Extract existing Hash entries to an array:
-                  pairs = @tags.sort
-                  @tags = Hash.new
-                  # Change the key of those equal or larger than index and put these key,value pairs back in a new Hash:
-                  pairs.each do |pair|
-                    if pair[0] < options[:index]
-                      @tags[pair[0]] = pair[1] # (Item keeps its old index)
-                    else
-                      @tags[pair[0]+1] = pair[1]
-                      pair[1].index = pair[0]+1 # (Item gets updated with its new index)
-                    end
-                  end
-                else
-                  # Set the index value one higher than the already existing max value:
-                  options[:index] = @tags.length
-                end
-                #,Add the new Item and set its index:
-                @tags[options[:index]] = item
-                item.index = options[:index]
-              else
-                raise ArgumentError, "The specified index (#{options[:index]}) is out of range (Must be a positive integer)."
-              end
-            else
-              # Add the existing Item to this Sequence:
-              index = @tags.length
-              @tags[index] = item
-              # Let the Item know what index key it's got in it's parent's Hash:
-              item.index = index
-            end
-            # Set ourself as this item's new parent:
-            item.set_parent(self) unless options[:no_follow]
-          else
-            raise ArgumentError, "The specified parameter is not an Item. Only Items are allowed to be added to a Sequence."
-          end
-        else
-          # Create an empty Item with self as parent.
-          index = @tags.length
-          item = Item.new(:parent => self)
-        end
-      else
-        raise "An Item #{item} was attempted added to a DObject instance #{self}, which is not allowed."
-      end
-    end
-
     # Retrieves all (immediate) child elementals in an array (sorted by element tag).
     #
     # @return [Array<Element, Item, Sequence>] the parent's child elementals (an empty array if childless)
@@ -196,12 +126,7 @@ module DICOM
     #   dcm["3006,0020"].delete(1)
     #
     def delete(tag_or_index, options={})
-      if tag_or_index.is_a?(String) or tag_or_index.is_a?(Integer)
-        raise ArgumentError, "Argument (#{tag_or_index}) is not a valid tag string." if tag_or_index.is_a?(String) && !tag_or_index.tag?
-        raise ArgumentError, "Negative Integer argument (#{tag_or_index}) is not allowed." if tag_or_index.is_a?(Integer) && tag_or_index < 0
-      else
-        raise ArgumentError, "Expected String or Integer, got #{tag_or_index.class}."
-      end
+      check_key(tag_or_index, :delete)
       # We need to delete the specified child element's parent reference in addition to removing it from the tag Hash.
       element = self[tag_or_index]
       if element
@@ -528,13 +453,15 @@ module DICOM
     # @param [Symbol] sym a method name
     #
     def method_missing(sym, *args, &block)
+      s = sym.to_s
+      action = s[-1]
       # Try to match the method against a tag from the dictionary:
-      tag = LIBRARY.as_tag(sym.to_s) || LIBRARY.as_tag(sym.to_s[0..-2])
+      tag = LIBRARY.as_tag(s) || LIBRARY.as_tag(s[0..-2])
       if tag
-        if sym.to_s[-1..-1] == '?'
+        if action == '?'
           # Query:
           return self.exists?(tag)
-        elsif sym.to_s[-1..-1] == '='
+        elsif action == '='
           # Assignment:
           unless args.length==0 || args[0].nil?
             # What kind of element to create?
@@ -550,7 +477,7 @@ module DICOM
           end
         else
           # Retrieval:
-          return self[tag] rescue nil
+          return self[tag]
         end
       end
       # Forward to Object#method_missing:
@@ -595,6 +522,16 @@ module DICOM
       return elements
     end
 
+    # Gives a string which represents this DICOM parent. The DOBject is
+    # is represented by its class name, whereas elemental parents (Sequence,
+    # Item) is represented by their tags.
+    #
+    # @return [String] a representation of the DICOM parent
+    #
+    def representation
+      self.is_a?(DObject) ? 'DObject' : self.tag
+    end
+
     # Resets the length of a Sequence or Item to -1, which is the number used for 'undefined' length.
     #
     def reset_length
@@ -701,12 +638,7 @@ module DICOM
     #   uid = dcm["3006,0010"][0].value("0020,0052")
     #
     def value(tag)
-      if tag.is_a?(String) or tag.is_a?(Integer)
-        raise ArgumentError, "Argument (#{tag}) is not a valid tag string." if tag.is_a?(String) && !tag.tag?
-        raise ArgumentError, "Negative Integer argument (#{tag}) is not allowed." if tag.is_a?(Integer) && tag < 0
-      else
-        raise ArgumentError, "Expected String or Integer, got #{tag.class}."
-      end
+      check_key(tag, :value)
       if exists?(tag)
         if self[tag].is_parent?
           raise ArgumentError, "Illegal parameter '#{tag}'. Parent elements, like the referenced '#{@tags[tag].class}', have no value. Only Element tags are valid."
@@ -722,6 +654,22 @@ module DICOM
     private
 
 
+    # Checks the given key argument and logs a warning if an obviously
+    # incorrect key argument is used.
+    #
+    # @param [String, Integer] tag_or_index the tag string or item index indentifying a given elemental
+    # @param [Symbol] method a representation of the method calling this method
+    #
+    def check_key(tag_or_index, method)
+      if tag_or_index.is_a?(String)
+        logger.warn("Parent##{method} called with an invalid tag argument: #{tag_or_index}") unless tag_or_index.tag?
+      elsif tag_or_index.is_a?(Integer)
+        logger.warn("Parent##{method} called with a negative Integer argument: #{tag_or_index}") if tag_or_index < 0
+      else
+        logger.warn("Parent##{method} called with an unexpected argument. Expected String or Integer, got: #{tag_or_index.class}")
+      end
+    end
+
     # Re-encodes the value of a child Element (but only if the
     # Element encoding is influenced by a shift in endianness).
     #