dicom 0.9.5 → 0.9.6

data/lib/dicom/audit_trail.rb

@@ -28,8 +28,6 @@ module DICOM
     # Creates a new AuditTrail instance.
     #
     def initialize
-      # The AuditTrail requires JSON for serialization:
-      require 'json'
       # Define the key/value hash used for tag records:
       @dictionary = Hash.new
     end

data/lib/dicom/d_client.rb

@@ -624,7 +624,7 @@ module DICOM
           @link.build_data_fragment(@data_elements, presentation_context_id)
           @link.transmit
           # Receive confirmation response:
-          segments = @link.receive_single_transmission
+          segments = @link.receive_multiple_transmissions
           process_returned_data(segments)
         end
         # Close the DICOM link:

data/lib/dicom/d_library.rb

@@ -24,9 +24,9 @@ module DICOM
       @methods_from_names = Hash.new
       @names_from_methods = Hash.new
       # Load the elements dictionary:
-      add_element_dictionary("#{ROOT_DIR}/dictionary/elements.txt")
+      add_element_dictionary("#{ROOT_DIR}/dictionary/elements.tsv")
       # Load the unique identifiers dictionary:
-      add_uid_dictionary("#{ROOT_DIR}/dictionary/uids.txt")
+      add_uid_dictionary("#{ROOT_DIR}/dictionary/uids.tsv")
     end
 
     # Adds a custom DictionaryElement to the ruby-dicom element dictionary.
@@ -153,22 +153,11 @@ module DICOM
           if tag.private?
             element = DictionaryElement.new(tag, 'Private', ['UN'], '1', '')
           else
-            if !(de = @elements["#{tag[0..3]},xxx#{tag[8]}"]).nil? # 1000,xxxh
-              element = DictionaryElement.new(tag, de.name, de.vrs, de.vm, de.retired)
-            elsif !(de = @elements["#{tag[0..3]},xxxx"]).nil? # 1010,xxxx
-              element = DictionaryElement.new(tag, de.name, de.vrs, de.vm, de.retired)
-            elsif !(de = @elements["#{tag[0..1]}xx,#{tag[5..8]}"]).nil? # hhxx,hhhh
-              element = DictionaryElement.new(tag, de.name, de.vrs, de.vm, de.retired)
-            elsif !(de = @elements["#{tag[0..6]}x#{tag[8]}"]).nil? # 0028,hhxh
-              element = DictionaryElement.new(tag, de.name, de.vrs, de.vm, de.retired)
-            else
-              # We are facing an unknown (but not private) tag:
-              element = DictionaryElement.new(tag, 'Unknown', ['UN'], '1', '')
-            end
+            element = unknown_or_range_element(tag)
           end
         end
       end
-      return element
+      element
     end
 
     # Extracts, and returns, all transfer syntaxes and SOP Classes from the dictionary.
@@ -230,6 +219,47 @@ module DICOM
       @uids[value]
     end
 
+
+    private
+
+
+    # Creates a list of possible 'range' tag candidates based on the given tag.
+    # Usually tags are uniquely defined in the DICOM dictionary, and the given
+    # tag can be matched directly. However, for a small set of known tags, the
+    # dictionary allows a range of tags to be associated with a specific
+    # entry. This method creates an array of candidate tags which are processed
+    # in order to match against these ranges.
+    #
+    # @param [String] tag the element tag
+    # @return [Array<String>] processed candidate tags
+    #
+    def range_candidates(tag)
+      [
+        "#{tag[0..3]},xxx#{tag[8]}", # 1000,xxxh
+        "#{tag[0..3]},xxxx", # 1010,xxxx
+        "#{tag[0..1]}xx,#{tag[5..8]}", # hhxx,hhhh
+        "#{tag[0..6]}x#{tag[8]}" # 0028,hhxh
+      ]
+    end
+
+    # Matches a tag against the possible range tag candidates, and if no match
+    # is found, returns a dictionary element representing an unknown tag.
+    #
+    # @param [String] tag the element tag
+    # @return [DictionaryElement] a matched range element or an unknown element
+    #
+    def unknown_or_range_element(tag)
+      element = nil
+      range_candidates(tag).each do |range_candidate_tag|
+        if de = @elements[range_candidate_tag]
+          element = DictionaryElement.new(tag, de.name, de.vrs, de.vm, de.retired)
+          break
+        end
+      end
+      # If nothing was matched, we are facing an unknown (but not private) tag:
+      element ||= DictionaryElement.new(tag, 'Unknown', ['UN'], '1', '')
+    end
+
   end
 
 end

data/lib/dicom/d_object.rb

@@ -1,4 +1,4 @@
-#    Copyright 2008-2013 Christoffer Lervag
+#    Copyright 2008-2014 Christoffer Lervag
 #
 #    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
@@ -49,7 +49,7 @@ module DICOM
     # @note Designed for the HTTP protocol only.
     # @note Whether this method should be included or removed from ruby-dicom is up for debate.
     #
-    # @param [String] link a hyperlink string which specifies remote location of the DICOM file to be loaded.
+    # @param [String] link a hyperlink string which specifies remote location of the DICOM file to be loaded
     # @return [DObject] the created DObject instance
     #
     def self.get(link)
@@ -410,25 +410,25 @@ module DICOM
     # to ensure that a valid DICOM object is encoded.
     #
     def insert_missing_meta
-      # File Meta Information Version:
-      Element.new("0002,0001", [0,1], :parent => self) unless exists?("0002,0001")
-      # Media Storage SOP Class UID:
-      Element.new("0002,0002", value("0008,0016"), :parent => self) unless exists?("0002,0002")
-      # Media Storage SOP Instance UID:
-      Element.new("0002,0003", value("0008,0018"), :parent => self) unless exists?("0002,0003")
-      # Transfer Syntax UID:
-      Element.new("0002,0010", transfer_syntax, :parent => self) unless exists?("0002,0010")
-      if !exists?("0002,0012") and !exists?("0002,0013")
+      {
+        '0002,0001' => [0,1], # File Meta Information Version
+        '0002,0002' => value('0008,0016'), # Media Storage SOP Class UID
+        '0002,0003' => value('0008,0018'), # Media Storage SOP Instance UID
+        '0002,0010' => transfer_syntax, # Transfer Syntax UID
+        '0002,0016' => DICOM.source_app_title, # Source Application Entity Title
+      }.each_pair do |tag, value|
+        add_element(tag, value) unless exists?(tag)
+      end
+      if !exists?("0002,0012") && !exists?("0002,0013")
         # Implementation Class UID:
-        Element.new("0002,0012", UID_ROOT, :parent => self)
+        add_element("0002,0012", UID_ROOT)
         # Implementation Version Name:
-        Element.new("0002,0013", NAME, :parent => self)
+        add_element("0002,0013", NAME)
       end
-      # Source Application Entity Title:
-      Element.new("0002,0016", DICOM.source_app_title, :parent => self) unless exists?("0002,0016")
-      # Group Length: Delete the old one (if it exists) before creating a new one.
+      # Delete the old group length first (if it exists) to avoid a miscount
+      # in the coming group length determination.
       delete("0002,0000")
-      Element.new("0002,0000", meta_group_length, :parent => self)
+      add_element("0002,0000", meta_group_length)
     end
 
     # Determines the length of the meta group in the DObject instance.
@@ -449,7 +449,7 @@ module DICOM
         end
         group_length += tag + vr + length + element.bin.length
       end
-      return group_length
+      group_length
     end
 
     # Collects the attributes of this instance.

data/lib/dicom/d_read.rb

@@ -2,9 +2,35 @@ module DICOM
 
   class Parent
 
+    # Loads data from an encoded DICOM string and creates
+    # items 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
+
+
     private
 
 
+    # Checks whether the given tag is a duplicate of an existing tag with this parent.
+    #
+    # @param [String] tag the tag of the candidate duplicate elemental
+    # @param [String] elemental the duplicate elemental type (e.g. Sequence, Element)
+    #
+    def check_duplicate(tag, elemental)
+      if @current_parent[tag]
+        gp = @current_parent.parent ? "#{@current_parent.parent.representation} => " : ''
+        p = @current_parent.representation
+        logger.warn("Duplicate #{elemental} (#{tag}) detected at level: #{gp}#{p}")
+      end
+    end
+
     # Checks for the official DICOM header signature.
     #
     # @return [Boolean] true if the proper signature is present, false if not, and nil if the string was shorter then the length of the DICOM signature
@@ -88,8 +114,7 @@ module DICOM
       # Create an Element from the gathered data:
       if level_vr == "SQ" or tag == ITEM_TAG
         if level_vr == "SQ"
-          # Check for duplicate and create sequence:
-          logger.warn("Duplicate Sequence (#{tag}) detected at level #{@current_parent.parent.is_a?(DObject) ? 'DObject' : @current_parent.parent.tag + ' => ' if @current_parent.parent}#{@current_parent.is_a?(DObject) ? 'DObject' : @current_parent.tag}") if @current_parent[tag]
+          check_duplicate(tag, 'Sequence')
           unless @current_parent[tag] and !@overwrite
             @current_element = Sequence.new(tag, :length => length, :name => name, :parent => @current_parent, :vr => vr)
           else
@@ -127,8 +152,7 @@ module DICOM
         # The occurance of such a tag indicates that a sequence or item has ended, and the parent must be changed:
         @current_parent = @current_parent.parent
       else
-        # Check for duplicate and create an ordinary data element:
-        logger.warn("Duplicate Element (#{tag}) detected at level #{@current_parent.parent.is_a?(DObject) ? 'DObject' : @current_parent.parent.tag + ' => ' if @current_parent.parent}#{@current_parent.is_a?(DObject) ? 'DObject' : @current_parent.tag}") if @current_parent[tag]
+        check_duplicate(tag, 'Element')
         unless @current_parent[tag] and !@overwrite
           @current_element = Element.new(tag, value, :bin => bin, :name => name, :parent => @current_parent, :vr => vr)
           # Check that the data stream didn't end abruptly:

data/lib/dicom/d_write.rb

@@ -17,36 +17,31 @@ module DICOM
         unless @segments
           @stream.add_last(string)
         else
-          # As the encoded DICOM string will be cut in multiple, smaller pieces, we need to monitor the length of our encoded strings:
-          if (string.length + @stream.length) > @max_size
-            # Duplicate the string as not to ruin the binary of the data element with our slicing:
-            segment = string.dup
-            append = segment.slice!(0, @max_size-@stream.length)
-            # Join these strings together and add them to the segments:
-            @segments << @stream.export + append
-            if (30 + segment.length) > @max_size
-              # The remaining part of the string is bigger than the max limit, fill up more segments:
-              # How many full segments will this string fill?
-              number = (segment.length/@max_size.to_f).floor
-              number.times {@segments << segment.slice!(0, @max_size)}
-              # The remaining part is added to the stream:
-              @stream.add_last(segment)
-            else
-              # The rest of the string is small enough that it can be added to the stream:
-              @stream.add_last(segment)
-            end
-          elsif (30 + @stream.length) > @max_size
-            # End the current segment, and start on a new segment for this string.
-            @segments << @stream.export
-            @stream.add_last(string)
-          else
-            # We are nowhere near the limit, simply add the string:
-            @stream.add_last(string)
-          end
+          add_with_segmentation(string)
         end
       end
     end
 
+    # Adds an encoded string to the output stream, while keeping track of the
+    # accumulated size of the output stream, splitting it up as necessary, and
+    # transferring the encoded string fragments to an array.
+    #
+    # @param [String] string a pre-encoded string
+    #
+    def add_with_segmentation(string)
+      # As the encoded DICOM string will be cut in multiple, smaller pieces, we need to monitor the length of our encoded strings:
+      if (string.length + @stream.length) > @max_size
+        split_and_add(string)
+      elsif (30 + @stream.length) > @max_size
+        # End the current segment, and start on a new segment for this string.
+        @segments << @stream.export
+        @stream.add_last(string)
+      else
+        # We are nowhere near the limit, simply add the string:
+        @stream.add_last(string)
+      end
+    end
+
     # Toggles the status for enclosed pixel data.
     #
     # @param [Element, Item, Sequence] element a data element
@@ -124,6 +119,34 @@ module DICOM
       end
     end
 
+    # Splits a pre-encoded string in parts and adds it to the segments instance
+    # array.
+    #
+    # @param [String] string a pre-encoded string
+    #
+    def split_and_add(string)
+      # Duplicate the string as not to ruin the binary of the data element with our slicing:
+      segment = string.dup
+      append = segment.slice!(0, @max_size-@stream.length)
+      # Clear out the stream along with a small part of the string:
+      @segments << @stream.export + append
+      if (30 + segment.length) > @max_size
+        # The remaining part of the string is bigger than the max limit, fill up more segments:
+        # How many full segments will this string fill?
+        number = (segment.length/@max_size.to_f).floor
+        start_index = 0
+        number.times {
+          @segments << segment.slice(start_index, @max_size)
+          start_index += @max_size
+        }
+        # The remaining part is added to the stream:
+        @stream.add_last(segment.slice(start_index, segment.length - start_index))
+      else
+        # The rest of the string is small enough that it can be added to the stream:
+        @stream.add_last(segment)
+      end
+    end
+
     # Encodes and writes a single data element.
     #
     # @param [Element, Item, Sequence] element a data element

data/lib/dicom/element.rb

@@ -35,7 +35,7 @@ module DICOM
       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 instance variables:
       @tag = tag.upcase
-      # We may beed to retrieve name and vr from the library:
+      # We may need to retrieve name and vr from the library:
       if options[:name] and options[:vr]
         @name = options[:name]
         @vr = options[:vr].upcase
@@ -212,9 +212,9 @@ module DICOM
         # In most cases the original encoding is IS0-8859-1 (ISO_IR 100), but if
         # it is not specified in the DICOM object, or if the specified string
         # is not recognized, ASCII-8BIT is assumed.
-        @value.encode('UTF-8', ENCODING_NAME[character_set] || 'ASCII-8BIT')
+        @value.encode('UTF-8', ENCODING_NAME[character_set])
         # If unpleasant encoding exceptions occur, the below version may be considered:
-        #@value.encode('UTF-8', ENCODING_NAME[character_set] || 'ASCII-8BIT', :invalid => :replace, :undef => :replace)
+        #@value.encode('UTF-8', ENCODING_NAME[character_set], :invalid => :replace, :undef => :replace)
       else
         @value
       end
@@ -229,8 +229,7 @@ module DICOM
     # @param [String, Integer, Float, Array] new_value a formatted value that is assigned to the element
     #
     def value=(new_value)
-      conversion = VALUE_CONVERSION[@vr] || :to_s
-      if conversion == :to_s
+      if VALUE_CONVERSION[@vr] == :to_s
         # Unless this is actually the Character Set data element,
         # get the character set (note that it may not be available):
         character_set = (@tag != '0008,0005' && top_parent.is_a?(DObject)) ? top_parent.value('0008,0005') : nil
@@ -238,7 +237,7 @@ module DICOM
         # In most cases the DObject encoding is IS0-8859-1 (ISO_IR 100), but if
         # it is not specified in the DICOM object, or if the specified string
         # is not recognized, ASCII-8BIT is assumed.
-        @value = new_value.to_s.encode(ENCODING_NAME[character_set] || 'ASCII-8BIT', new_value.to_s.encoding.name)
+        @value = new_value.to_s.encode(ENCODING_NAME[character_set], new_value.to_s.encoding.name)
         @bin = encode(@value)
       else
         # We may have an array (of numbers) which needs to be passed directly to
@@ -247,7 +246,7 @@ module DICOM
           @value = new_value
           @bin = encode(@value)
         else
-          @value = new_value.send(conversion)
+          @value = new_value.send(VALUE_CONVERSION[@vr])
           @bin = encode(@value)
         end
       end

data/lib/dicom/elemental.rb

@@ -117,4 +117,5 @@ module DICOM
     end
 
   end
+
 end

data/lib/dicom/elemental_parent.rb

@@ -0,0 +1,64 @@
+module DICOM
+
+  # The ElementalParent mix-in module contains methods that are common among
+  # the two elemental parent classes: Item & Sequence
+  #
+  module ElementalParent
+
+    # 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={})
+      if item
+        if item.is_a?(Item)
+          if index = 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 index >= 0
+              # If the index value is larger than the max index present, we dont need to modify the existing items.
+              if index < @tags.length
+                @tags = @tags.create_key_gap_at(index)
+              else
+                # Set the index value one higher than the already existing max value:
+                index = @tags.length
+              end
+              #,Add the new Item and set its index:
+              @tags[index] = item
+              item.index = index
+            else
+              raise ArgumentError, "The specified index (#{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, "Expected Item, got #{item.class}"
+        end
+      else
+        # Create an empty item with self as parent:
+        item = Item.new(:parent => self)
+      end
+    end
+
+  end
+
+end

data/lib/dicom/extensions/array.rb

@@ -0,0 +1,57 @@
+# Extensions to the Array class.
+# These mainly deal with encoding integer arrays as well as conversion between
+# signed and unsigned integers.
+#
+class Array
+
+  # Packs an array of (unsigned) integers to a binary string (blob).
+  #
+  # @param [Integer] depth the bit depth to be used when encoding the unsigned integers
+  # @return [String] an encoded binary string
+  #
+  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, little endian 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 given bit depth.
+  #
+  # @param [Integer] depth the bit depth of the integers
+  # @return [Array<Integer>] an array of signed integers
+  #
+  def to_signed(depth)
+    case depth
+    when 8
+      self.collect {|i| i - 128}
+    when 16
+      self.collect {|i| i - 32768}
+    else
+      raise ArgumentError, "Unknown or unsupported bit depth: #{depth}"
+    end
+  end
+
+  # Shifts the integer values of the array to make an unsigned data set.
+  # The size of the shift is determined by the given bit depth.
+  #
+  # @param [Integer] depth the bit depth of the integers
+  # @return [Array<Integer>] an array of unsigned integers
+  #
+  def to_unsigned(depth)
+    case depth
+    when 8
+      self.collect {|i| i + 128}
+    when 16
+      self.collect {|i| i + 32768}
+    else
+      raise ArgumentError, "Unknown or unsupported bit depth: #{depth}"
+    end
+  end
+
+end