dicom 0.8 → 0.9

data/lib/dicom/d_read.rb

@@ -1,16 +1,15 @@
-#    Copyright 2008-2010 Christoffer Lervag
-#
-# === Notes
-#
-# In addition to reading files that are compliant to DICOM 3 Part 10, the philosophy of the Ruby DICOM library is to feature maximum
-# compatibility, and as such it will also successfully read many types of 'DICOM' files that deviate in some way from the standard.
-
 module DICOM
 
   # The DRead class parses the DICOM data from a binary string.
   #
   # The source of this binary string is typically either a DICOM file or a DICOM network transmission.
   #
+  # === Notes
+  #
+  # In addition to reading files that are compliant to DICOM 3 Part 10, the philosophy of the
+  # Ruby DICOM library is to feature maximum compatibility, and as such it will also
+  # successfully read many types of 'DICOM' files that deviate in some way from the standard.
+  #
   class DRead
 
     # A boolean which reports the explicitness of the DICOM string, true if explicit and false if implicit.
@@ -18,7 +17,7 @@ module DICOM
     # A boolean which reports the endianness of the post-meta group part of the DICOM string (true for big endian, false for little endian).
     attr_reader :file_endian
     # An array which records any status messages that are generated while parsing the DICOM string.
-    attr_reader :msg    
+    attr_reader :msg
     # A DObject instance which the parsed data elements will be connected to.
     attr_reader :obj
     # A boolean which records whether the DICOM string contained the proper DICOM header signature of 128 bytes + 'DICM'.
@@ -38,13 +37,16 @@ module DICOM
     # === Options
     #
     # * <tt>:syntax</tt> -- String. If specified, the decoding of the DICOM string will be forced to use this transfer syntax.
-    # * <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>:bin</tt> -- Boolean. If true, the string parameter will be interpreted as a binary DICOM string instead of a path string.
+    #
     def initialize(obj, string=nil, options={})
       # Set the DICOM object as an instance variable:
       @obj = obj
-      # Some of the options need to be transferred to instance variables:
-      @transfer_syntax = options[:syntax]
+      # If a transfer syntax has been specified as an option for a DICOM object, make sure that it makes it into the object:
+      if options[:syntax]
+        @transfer_syntax = options[:syntax]
+        obj.add(Element.new("0002,0010", options[:syntax])) if obj.is_a?(DObject)
+      end
       # Initiate the variables that are used during file reading:
       init_variables
       # Are we going to read from a file, or read from a binary string?
@@ -72,7 +74,7 @@ module DICOM
         # Read and verify the DICOM header:
         header = check_header
         # If the file didnt have the expected header, we will attempt to read
-        # data elements from the very start file:
+        # data elements from the very start of the file:
         if header == false
           @stream.skip(-132)
         elsif header == nil
@@ -88,9 +90,10 @@ module DICOM
         begin
           # Extracting Data element information (nil is returned if end of file is encountered in a normal way).
           data_element = process_data_element
-        rescue
+        rescue Exception => msg
           # The parse algorithm crashed. Set data_element to false to break the loop and toggle the success boolean to indicate failure.
-          @msg << "Error! Failed to process a Data Element. This is probably the result of invalid or corrupt DICOM data."
+          @msg << msg
+          @msg << "Error: Failed to parse Data Elements. This was probably an invalid/corrupt DICOM file."
           @success = false
           data_element = false
         end
@@ -218,12 +221,9 @@ module DICOM
         @current_parent = @current_parent.parent
       else
         # Create an ordinary Data Element:
-        @current_element = DataElement.new(tag, value, :bin => bin, :name => name, :parent => @current_parent, :vr => vr)
+        @current_element = Element.new(tag, value, :bin => bin, :name => name, :parent => @current_parent, :vr => vr)
         # Check that the data stream didnt end abruptly:
-        if length != @current_element.bin.length
-          set_abrupt_error
-          return false # (Failed)
-        end
+        raise "Error: The actual length of the binary (#{@current_element.bin.length}) does not match the specified length (#{length}) for Data Element #{@current_element.tag}." if length != @current_element.bin.length
       end
       # Return true to indicate success:
       return true
@@ -290,11 +290,8 @@ module DICOM
       else
         length = @stream.decode(bytes, "SL") # (4)
       end
-      if length%2 > 0 and length > 0
-        # According to the DICOM standard, all data element lengths should be an even number.
-        # If it is not, it may indicate a file that is not standards compliant or it might even not be a DICOM file.
-        @msg << "Warning: Odd number of bytes in data element's length occured. This is a violation of the DICOM standard, but program will attempt to read the rest of the file anyway."
-      end
+      # Check that length is valid (according to the DICOM standard, it must be even):
+      raise "Error: Encountered a Data Element (#{tag}) with an invalid (odd) value length." if length%2 == 1 and length > 0
       return vr, length
     end
 
@@ -341,12 +338,29 @@ module DICOM
     #
     # === Parameters
     #
-    # * <tt>file</tt> -- A path/file string.
+    # * <tt>file</tt> -- A path/file string. The string may point to a local file or a http location.
     #
     def open_file(file)
-      if File.exist?(file)
+      if file.index('http')==0
+        # Try to open the remote file using open-uri:
+        @retrials = 0
+        begin
+          @file = open(file, 'rb') # binary encoding (ASCII-8BIT)
+        rescue Exception => e
+          if @retrials>3
+            @retrials = 0
+            raise "Unable to read the file. File does not exist?"
+          else
+            puts "Warning: Exception in ruby-dicom when loading a dicom file from: #{file}"
+            puts "Retrying... #{@retrials}"
+            @retrials+=1
+            retry
+          end
+        end
+      elsif File.exist?(file)
+        # Try to read the file on the local file system:
         if File.readable?(file)
-          if not File.directory?(file)
+          if !File.directory?(file)
             if File.size(file) > 8
               @file = File.new(file, "rb")
             else
@@ -363,14 +377,6 @@ module DICOM
       end
     end
 
-    # Registers an unexpected error by toggling a success boolean and recording an error message.
-    # The DICOM string ended abruptly because the data element's value was shorter than expected.
-    #
-    def set_abrupt_error
-      @msg << "Error! The parsed data of the last data element #{@current_element.tag} does not match its specified length value. This is probably the result of invalid or corrupt DICOM data."
-      @success = false
-    end
-
     # Changes encoding variables as the file reading proceeds past the initial meta group part (0002,xxxx) of the DICOM file.
     #
     def switch_syntax

data/lib/dicom/d_server.rb

@@ -1,5 +1,3 @@
-#    Copyright 2009-2010 Christoffer Lervag
-
 module DICOM
 
   # This class contains code for setting up a Service Class Provider (SCP),
@@ -20,9 +18,9 @@ module DICOM
     #   require 'dicom'
     #   require 'my_file_handler'
     #   include DICOM
-    #   DServer.run(104, 'c:/temp/') do
-    #     timeout = 100
-    #     file_handler = MyFileHandler
+    #   DServer.run(104, 'c:/temp/') do |s|
+    #     s.timeout = 100
+    #     s.file_handler = MyFileHandler
     #   end
     #
     def self.run(port=104, path='./received/', &block)
@@ -35,7 +33,7 @@ module DICOM
     attr_accessor :file_handler
     # The name of the server (application entity).
     attr_accessor :host_ae
-    # The maximum allowed size of network packages (in bytes). 
+    # The maximum allowed size of network packages (in bytes).
     attr_accessor :max_package_size
     # The network port to be used.
     attr_accessor :port
@@ -43,7 +41,7 @@ module DICOM
     attr_accessor :timeout
     # A boolean which defines if notices/warnings/errors will be printed to the screen (true) or not (false).
     attr_accessor :verbose
-    
+
     # A hash containing the abstract syntaxes that will be accepted.
     attr_reader :accepted_abstract_syntaxes
     # A hash containing the transfer syntaxes that will be accepted.
@@ -64,7 +62,7 @@ module DICOM
     #
     # * <tt>:file_handler</tt> -- A customized FileHandler class to use instead of the default FileHandler.
     # * <tt>:host_ae</tt> -- String. The name of the server (application entity).
-    # * <tt>:max_package_size</tt> -- Fixnum. The maximum allowed size of network packages (in bytes). 
+    # * <tt>:max_package_size</tt> -- Fixnum. The maximum allowed size of network packages (in bytes).
     # * <tt>:timeout</tt> -- Fixnum. The maximum period the server will wait on an answer from a client before aborting the communication.
     # * <tt>:verbose</tt> -- Boolean. If set to false, the DServer instance will run silently and not output warnings and error messages to the screen. Defaults to true.
     #
@@ -107,7 +105,7 @@ module DICOM
     #
     def add_abstract_syntax(uid)
       if uid.is_a?(String)
-        name = LIBRARY.get_syntax_description(uid) || "Unknown UID" 
+        name = LIBRARY.get_syntax_description(uid) || "Unknown UID"
         @accepted_abstract_syntaxes[uid] = name
       else
         raise "Invalid type of UID. Expected String, got #{uid.class}!"
@@ -123,7 +121,7 @@ module DICOM
     #
     def add_transfer_syntax(uid)
       if uid.is_a?(String)
-        name = LIBRARY.get_syntax_description(uid) || "Unknown UID" 
+        name = LIBRARY.get_syntax_description(uid) || "Unknown UID"
         @accepted_transfer_syntaxes[uid] = name
       else
         raise "Invalid type of UID. Expected String, got #{uid.class}!"

data/lib/dicom/d_write.rb

@@ -1,23 +1,21 @@
-#    Copyright 2008-2010 Christoffer Lervag
-#
-# === Notes
-#
-# The philosophy of the Ruby DICOM library is to feature maximum conformance to the DICOM standard.
-# As such, the class which writes DICOM files may manipulate the meta group, remove/change group lengths and add a header signature.
-#
-# Therefore, the file that is written may not be an exact bitwise copy of the file that was read,
-# even if no DObject manipulation has been done on the part of the user.
-#
-# Remember: If this behaviour for some reason is not wanted, it is easy to modify the source code to avoid it.
-#
-# It is important to note, that while the goal is to be fully DICOM compliant, no guarantees are given
-# that this is actually achieved. You are encouraged to thouroughly test your files for compatibility after creation.
-
 module DICOM
 
   # The DWrite class handles the encoding of a DObject instance to a valid DICOM string.
   # The String is either written to file or returned in segments to be used for network transmission.
   #
+  # === Notes
+  #
+  # The philosophy of the Ruby DICOM library is to feature maximum conformance to the DICOM standard.
+  # As such, the class which writes DICOM files may manipulate the meta group, remove/change group lengths and add a header signature.
+  #
+  # Therefore, the file that is written may not be an exact bitwise copy of the file that was read,
+  # even if no DObject manipulation has been done on the part of the user.
+  #
+  # Remember: If this behaviour for some reason is not wanted, it is easy to modify the source code to avoid it.
+  #
+  # It is important to note, that while the goal is to be fully DICOM compliant, no guarantees are given
+  # that this is actually achieved. You are encouraged to thouroughly test your files for compatibility after creation.
+  #
   class DWrite
 
     # An array which records any status messages that are generated while encoding/writing the DICOM string.
@@ -103,14 +101,10 @@ module DICOM
       @max_size = max_size
       @segments = Array.new
       elements = @obj.children
-      # When sending a DICOM file across the network, no header or meta information is needed.
-      # We must therefore find the position of the first tag which is not a meta information tag.
-      first_pos = first_non_meta(elements)
-      selected_elements = elements[first_pos..-1]
       # Create a Stream instance to handle the encoding of content to
       # the binary string that will eventually be saved to file:
       @stream = Stream.new(nil, @file_endian)
-      write_data_elements(selected_elements)
+      write_data_elements(elements)
       # Extract the remaining string in our stream instance to our array of strings:
       @segments << @stream.export
       # Mark this write session as successful:
@@ -134,19 +128,21 @@ module DICOM
         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
-            append = string.slice!(0, @max_size-@stream.length)
+            # 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 + string.length) > @max_size
+            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 = (string.length/@max_size.to_f).floor
-              number.times {@segments << string.slice!(0, @max_size)}
+              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(string)
+              @stream.add_last(segment)
             else
               # The rest of the string is small enough that it can be added to the stream:
-              @stream.add_last(string)
+              @stream.add_last(segment)
             end
           elsif (30 + @stream.length) > @max_size
             # End the current segment, and start on a new segment for this string.
@@ -209,7 +205,7 @@ module DICOM
             # Among group length elements, only write the meta group element (the others have been retired in the DICOM standard):
             write_data_element(element) if element.tag == "0002,0000"
           else
-            write_data_element(element) 
+            write_data_element(element)
           end
         end
       end
@@ -315,7 +311,7 @@ module DICOM
     #
     def write_value(bin)
       # This is pretty straightforward, just dump the binary data to the file/string:
-      add(bin)
+      add(bin) if bin
     end
 
 
@@ -347,7 +343,7 @@ module DICOM
           unless File.directory?(path)
             # We need to create (parts of) this path:
             require 'fileutils'
-            FileUtils.mkdir_p path
+            FileUtils.mkdir_p(path)
           end
         end
         # The path to this non-existing file is verified, and we can proceed to create the file:
@@ -384,23 +380,6 @@ module DICOM
       @stream.endian = @rest_endian
     end
 
-    # Identifies and returns the index of the first data element that does not have a meta group ("0002,xxxx") tag.
-    #
-    # === Parameters
-    #
-    # * <tt>elements</tt> -- An array of data elements.
-    #
-    def first_non_meta(elements)
-      non_meta_index = 0
-      elements.each_index do |i|
-        if elements[i].tag.group != META_GROUP
-          non_meta_index = i
-          break
-        end
-      end
-      return non_meta_index
-    end
-
     # Creates various variables used when encoding the DICOM string.
     #
     def init_variables

data/lib/dicom/dictionary.rb

@@ -1,6 +1,4 @@
-# coding: ISO-8859-1
-#
-#    Copyright 2008-2010 Christoffer Lervag
+# encoding: UTF-8
 
 module DICOM
 

data/lib/dicom/{data_element.rb → element.rb}

@@ -1,22 +1,20 @@
-#    Copyright 2010 Christoffer Lervag
-
 module DICOM
 
-  # The DataElement class handles information related to ordinary (non-parent) data elements.
+  # The Element class handles information related to ordinary (non-parent) elementals (data elements).
   #
-  class DataElement
+  class Element
 
-    # Include the Elements mix-in module:
-    include Elements
+    # Include the Elemental mix-in module:
+    include Elemental
 
     # The (decoded) value of the data element.
     attr_reader :value
 
-    # Creates a DataElement instance.
+    # Creates a Element instance.
     #
     # === Notes
     #
-    # * In the case where the DataElement is given a binary instead of value, the DataElement will not have a formatted value (value = nil).
+    # * In the case where the Element is given a binary instead of value, the Element will not have a formatted value (value = nil).
     # * Private data elements will have their names listed as "Private".
     # * Non-private data elements that are not found in the dictionary will be listed as "Unknown".
     #
@@ -30,20 +28,21 @@ module DICOM
     #
     # * <tt>:bin</tt> -- String. If you already have the value pre-encoded to a binary string, the string can be supplied with this option to avoid it being encoded a second time.
     # * <tt>:encoded</tt> -- Boolean. If the value parameter contains a pre-encoded binary, this boolean must to be set as true.
-    # * <tt>:name</tt> - String. The name of the DataElement may be specified upon creation. If it is not, the name will be retrieved from the dictionary.
-    # * <tt>:parent</tt> - Item or DObject instance which the DataElement instance shall belong to.
-    # * <tt>:vr</tt> -- String. If a private DataElement is created with a custom value, this must be specified to enable the encoding of the value. If it is not specified, the vr will be retrieved from the dictionary.
+    # * <tt>:name</tt> - String. The name of the Element may be specified upon creation. If it is not, the name will be retrieved from the dictionary.
+    # * <tt>:parent</tt> - Item or DObject instance which the Element instance shall belong to.
+    # * <tt>:vr</tt> -- String. If a private Element is created with a custom value, this must be specified to enable the encoding of the value. If it is not specified, the vr will be retrieved from the dictionary.
     #
     # === Examples
     #
     #   # Create a new data element and connect it to a DObject instance:
-    #   patient_name = DataElement.new("0010,0010", "John Doe", :parent => obj)
+    #   patient_name = Element.new("0010,0010", "John Doe", :parent => obj)
     #   # Create a "Pixel Data" element and insert image data that you have already encoded elsewhere:
-    #   pixel_data = DataElement.new("7FE0,0010", processed_pixel_data, :encoded => true, :parent => obj)
+    #   pixel_data = Element.new("7FE0,0010", processed_pixel_data, :encoded => true, :parent => obj)
     #   # Create a private data element:
-    #   private_data = DataElement.new("0011,2102", some_data, :parent => obj, :vr => "LO")
+    #   private_data = Element.new("0011,2102", some_data, :parent => obj, :vr => "LO")
     #
     def initialize(tag, value, 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 instance variables:
       @tag = tag
       # We may beed to retrieve name and vr from the library:
@@ -78,11 +77,11 @@ module DICOM
       # Manage the parent relation if specified:
       if options[:parent]
         @parent = options[:parent]
-        @parent.add(self)
+        @parent.add(self, :no_follow => true)
       end
     end
 
-    # Sets the binary string of a DataElement.
+    # Sets the binary string of a Element.
     #
     # === Notes
     #
@@ -94,46 +93,74 @@ module DICOM
     # * <tt>new_bin</tt> -- A binary string of encoded data.
     #
     def bin=(new_bin)
-      if new_bin.is_a?(String)
-        # Add a zero byte at the end if the length of the binary is odd:
-        if new_bin.length[0] == 1
-          @bin = new_bin + stream.pad_byte[@vr]
-        else
-          @bin = new_bin
-        end
-        @value = nil
-        @length = @bin.length
+      raise ArgumentError, "Expected String, got #{new_bin.class}." unless new_bin.is_a?(String)
+      # Add a zero byte at the end if the length of the binary is odd:
+      if new_bin.length[0] == 1
+        @bin = new_bin + stream.pad_byte[@vr]
       else
-        raise "Invalid parameter type. String was expected, got #{new_bin.class}."
+        @bin = new_bin
       end
+      @value = nil
+      @length = @bin.length
     end
 
-    # Checks if an element actually has any child elements.
-    # Returns false, as DataElement instances can not have children.
+    # Checks if the Element actually has any child elementals.
+    # Returns false, as Element instances by definition can not have children.
     #
     def children?
       return false
     end
 
-    # Checks if an element is a parent.
-    # Returns false, as DataElement instance can not be parents.
+    # Returns the endianness of the encoded binary value of this data element.
+    # Returns false if little endian, true if big endian.
+    #
+    def endian
+      return stream.str_endian
+    end
+
+    # Returns a string containing a human-readable hash representation of the Element.
+    #
+    def inspect
+      to_hash.inspect
+    end
+
+    # Checks if the Element is a parent.
+    # Returns false, as Element instances by definition can not be parents.
     #
     def is_parent?
       return false
     end
 
-    # Sets the value of the DataElement instance.
+    # Returns the value of the elemental (used as value in the parent's hash representation).
+    #
+    def to_hash
+      return {self.send(DICOM.key_representation) => value}
+    end
+
+    # Returns a json string containing a human-readable representation of the Element.
+    #
+    def to_json
+      to_hash.to_json
+    end
+
+    # Returns a yaml string containing a human-readable representation of the Element.
+    #
+    def to_yaml
+      to_hash.to_yaml
+    end
+
+    # Sets the value of the Element instance.
     #
     # === Notes
     #
     # In addition to updating the value attribute, the specified value is encoded and used to
-    # update both the DataElement's binary and length attributes too.
+    # update both the Element's binary and length attributes too.
     #
-    # The specified value must be of a type that is compatible with the DataElement's value representation (vr).
+    # The specified value must be of a type that is compatible with the Element's value representation (vr).
     #
     # === Parameters
     #
-    # * <tt>new_value</tt> -- A custom value (String, Fixnum, etc..) that is assigned to the DataElement.
+    # * <tt>new_value</tt> -- A custom value (String, Fixnum, etc..) that is assigned to the Element.
     #
     def value=(new_value)
       @bin = encode(new_value)
@@ -156,20 +183,5 @@ module DICOM
       return stream.encode_value(formatted_value, @vr)
     end
 
-    # Returns a Stream instance which can be used for encoding a value to binary.
-    #
-    # === Notes
-    #
-    # * Retrieves the Stream instance of the top parent DObject instance.
-    # If this fails, a new Stream instance is created (with Little Endian encoding assumed).
-    #
-    def stream
-      if top_parent.is_a?(DObject)
-        return top_parent.stream
-      else
-        return Stream.new(nil, file_endian=false)
-      end
-    end
-
   end
 end