dicom 0.9.2 → 0.9.3

data/lib/dicom/audit_trail.rb

@@ -0,0 +1,117 @@
+module DICOM
+
+  # The AuditTrail class handles key/value storage for the Anonymizer.
+  # When using the advanced Anonymization options such as enumeration
+  # and UID replacement, the AuditTrail class keeps track of key/value
+  # pairs and dumps this information to a text file using the json format.
+  # This enables us to ensure a unique relationship between the anonymized
+  # values and the original values, as well as preserving this relationship
+  # for later restoration of original values.
+  #
+  class AuditTrail
+
+    # The hash used for storing the key/value pairs of this instace.
+    attr_reader :dictionary
+
+    # Creates a new AuditTrail instance by loading the information stored
+    # in the specified file.
+    #
+    # === Parameters
+    #
+    # * <tt>file_name</tt> -- The path to a file containing a previously stored audit trail.
+    #
+    def self.read(file_name)
+      audit_trail = AuditTrail.new
+      audit_trail.load(file_name)
+      return audit_trail
+    end
+
+    # 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
+
+    # Adds a tag record to the log.
+    #
+    # === Parameters
+    #
+    # * <tt>tag</tt> -- The tag string (e.q. "0010,0010").
+    # * <tt>original</tt> -- The original value (e.q. "John Doe").
+    # * <tt>replacement</tt> -- The replacement value (e.q. "Patient1").
+    #
+    def add_record(tag, original, replacement)
+      @dictionary[tag] = Hash.new unless @dictionary.key?(tag)
+      @dictionary[tag][original] = replacement
+    end
+
+    # Loads the key/value dictionary hash from a specified file.
+    #
+    # === Parameters
+    #
+    # * <tt>file_name</tt> -- The path to a file containing a previously stored audit trail.
+    #
+    def load(file_name)
+      @dictionary = JSON.load(File.new(file_name, "r"))
+    end
+
+    # Retrieves the replacement value used for the given tag and its original value.
+    #
+    # === Parameters
+    #
+    # * <tt>tag</tt> -- The tag string (e.q. "0010,0010").
+    # * <tt>replacement</tt> -- The replacement value (e.q. "Patient1").
+    #
+    def original(tag, replacement)
+      original = nil
+      if @dictionary.key?(tag)
+        original = @dictionary[tag].key(replacement)
+      end
+      return original
+    end
+
+    # Returns the key/value pairs for a specific tag.
+    #
+    # === Parameters
+    #
+    # * <tt>tag</tt> -- The tag string (e.q. "0010,0010").
+    #
+    def records(tag)
+      if @dictionary.key?(tag)
+        return @dictionary[tag]
+      else
+        return Hash.new
+      end
+    end
+
+    # Retrieves the replacement value used for the given tag and its original value.
+    #
+    # === Parameters
+    #
+    # * <tt>tag</tt> -- The tag string (e.q. "0010,0010").
+    # * <tt>original</tt> -- The original value (e.q. "John Doe").
+    #
+    def replacement(tag, original)
+      replacement = nil
+      replacement = @dictionary[tag][original] if @dictionary.key?(tag)
+      return replacement
+    end
+
+    # Dumps the key/value pairs to a json string which is written to
+    # file as specified by the @file_name attribute of this instance.
+    #
+    #
+    # === Parameters
+    #
+    # * <tt>file_name</tt> -- The file name string to be used for storing & retrieving key/value pairs on disk.
+    #
+    def write(file_name)
+      str = JSON.pretty_generate(@dictionary)
+      File.open(file_name, 'w') {|f| f.write(str) }
+    end
+
+  end
+end

data/lib/dicom/constants.rb

@@ -1,7 +1,6 @@
-
 module DICOM
 
-  # Ruby DICOM's Implementation UID.
+  # Ruby DICOM's registered DICOM UID root (Implementation Class UID).
   UID = "1.2.826.0.1.3680043.8.641"
   # Ruby DICOM name & version (max 16 characters).
   NAME = "RUBY_DCM_" + DICOM::VERSION

data/lib/dicom/d_client.rb

@@ -517,12 +517,12 @@ module DICOM
           # Temporarily increase the log threshold to suppress messages from the DObject class:
           client_level = logger.level
           logger.level = Logger::FATAL
-          obj = DObject.read(file_or_object)
+          dcm = DObject.read(file_or_object)
           # Reset the logg threshold:
           logger.level = client_level
-          if obj.read_success
+          if dcm.read_success
             # Load the DICOM object:
-            objects << obj
+            objects << dcm
           else
             status = false
             message = "Failed to read a DObject from this file: #{file_or_object}"
@@ -538,10 +538,10 @@ module DICOM
       end
       # Extract available transfer syntaxes for the various sop classes found amongst these objects
       syntaxes = Hash.new
-      objects.each do |obj|
-        sop_class = obj.value("0008,0016")
+      objects.each do |dcm|
+        sop_class = dcm.value("0008,0016")
         if sop_class
-          transfer_syntaxes = available_transfer_syntaxes(obj.transfer_syntax)
+          transfer_syntaxes = available_transfer_syntaxes(dcm.transfer_syntax)
           if syntaxes[sop_class]
             syntaxes[sop_class] << transfer_syntaxes
           else
@@ -670,10 +670,10 @@ module DICOM
     # conveys the information from the selected DICOM file.
     #
     def perform_send(objects)
-      objects.each_with_index do |obj, index|
+      objects.each_with_index do |dcm, index|
         # Gather necessary information from the object (SOP Class & Instance UID):
-        sop_class = obj.value("0008,0016")
-        sop_instance = obj.value("0008,0018")
+        sop_class = dcm.value("0008,0016")
+        sop_instance = dcm.value("0008,0018")
         if sop_class and sop_instance
           # Only send the image if its sop_class has been accepted by the receiver:
           if @approved_syntaxes[sop_class]
@@ -685,11 +685,11 @@ module DICOM
             selected_transfer_syntax = @approved_syntaxes[sop_class][1]
             # Encode our DICOM object to a binary string which is split up in pieces, sufficiently small to fit within the specified maximum pdu length:
             # Set the transfer syntax of the DICOM object equal to the one accepted by the SCP:
-            obj.transfer_syntax = selected_transfer_syntax
+            dcm.transfer_syntax = selected_transfer_syntax
             # Remove the Meta group, since it doesn't belong in a DICOM file transfer:
-            obj.remove_group(META_GROUP)
+            dcm.delete_group(META_GROUP)
             max_header_length = 14
-            data_packages = obj.encode_segments(@max_pdu_length - max_header_length, selected_transfer_syntax)
+            data_packages = dcm.encode_segments(@max_pdu_length - max_header_length, selected_transfer_syntax)
             @link.build_command_fragment(PDU_DATA, presentation_context_id, COMMAND_LAST_FRAGMENT, @command_elements)
             @link.transmit
             # Transmit all but the last data strings:
@@ -728,7 +728,7 @@ module DICOM
       presentation_contexts.each do |pc|
         # Determine what abstract syntax this particular presentation context's id corresponds to:
         id = pc[:presentation_context_id]
-        raise "Error! Even presentation context ID received in the association response. This is not allowed according to the DICOM standard!" if id[0] == 0 # If even number.
+        raise "Error! Even presentation context ID received in the association response. This is not allowed according to the DICOM standard!" if id.even?
         abstract_syntax = find_abstract_syntax(id)
         if pc[:result] == 0
           accepted_pc += 1

data/lib/dicom/d_object.rb

@@ -1,18 +1,18 @@
 # === TODO:
 #
-# * The retrieve file network functionality (get_image() in DClient class) has not been tested.
+# * The retrieve file network functionality (#get_image in DClient class) has not been tested.
 # * Make the networking code more intelligent in its handling of unexpected network communication.
 # * Full support for compressed image data.
 # * Read/Write 12 bit image data.
-# * Full color support (RGB and PALETTE COLOR with get_object_magick() already implemented).
-# * Support for extraction of multiple encapsulated pixel data frames in get_image() and get_image_narray().
+# * Full color support (RGB and PALETTE COLOR with #image already implemented).
+# * Support for extraction of multiple encapsulated pixel data frames in #pixels and #narray.
 # * Image handling currently ignores DICOM tags like Pixel Aspect Ratio, Image Orientation and (to some degree) Photometric Interpretation.
 # * More robust and flexible options for reorienting extracted pixel arrays?
 # * A curious observation: Creating a DLibrary instance is exceptionally slow on Ruby 1.9.1: 0.4 seconds versus ~0.01 seconds on Ruby 1.8.7!
 # * Add these as github issues and remove this list!
 
 
-#    Copyright 2008-2011 Christoffer Lervag
+#    Copyright 2008-2012 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
@@ -77,12 +77,12 @@ module DICOM
       bin = File.open(file, "rb") { |f| f.read }
       # Parse the file contents and create the DICOM object:
       if bin
-        obj = self.parse(bin)
+        dcm = self.parse(bin)
       else
-        obj = self.new
-        obj.read_success = false
+        dcm = self.new
+        dcm.read_success = false
       end
-      return obj
+      return dcm
     end
 
     # Creates a DObject instance by parsing an encoded binary DICOM string.
@@ -102,9 +102,9 @@ module DICOM
       no_header = options[:no_meta]
       raise ArgumentError, "Invalid argument 'string'. Expected String, got #{string.class}." unless string.is_a?(String)
       raise ArgumentError, "Invalid option :syntax. Expected String, got #{syntax.class}." if syntax && !syntax.is_a?(String)
-      obj = self.new
-      obj.read(string, :bin => true, :no_meta => no_header, :syntax => syntax)
-      return obj
+      dcm = self.new
+      dcm.read(string, :bin => true, :no_meta => no_header, :syntax => syntax)
+      return dcm
     end
 
     # Creates a DObject instance by reading and parsing a DICOM file.
@@ -136,12 +136,12 @@ module DICOM
       end
       # Parse the file contents and create the DICOM object:
       if bin
-        obj = self.parse(bin)
+        dcm = self.parse(bin)
       else
-        obj = self.new
-        obj.read_success = false
+        dcm = self.new
+        dcm.read_success = false
       end
-      return obj
+      return dcm
     end
 
     # A boolean set as false. This attribute is included to provide consistency with other object types for the internal methods which use it.
@@ -180,12 +180,12 @@ module DICOM
     #
     #   # Load a DICOM file (Deprecated: please use DObject.read() instead):
     #   require 'dicom'
-    #   obj = DICOM::DObject.new("test.dcm")
+    #   dcm = DICOM::DObject.new("test.dcm")
     #   # Read a DICOM file that has already been loaded into memory in a binary string (with a known transfer syntax):
     #   # (Deprecated: please use DObject.parse() instead)
-    #   obj = DICOM::DObject.new(binary_string, :bin => true, :syntax => string_transfer_syntax)
+    #   dcm = DICOM::DObject.new(binary_string, :bin => true, :syntax => string_transfer_syntax)
     #   # Create an empty DICOM object
-    #   obj = DICOM::DObject.new
+    #   dcm = DICOM::DObject.new
     #   # Increasing the log message threshold (default level is INFO):
     #   DICOM.logger.level = Logger::WARN
     #
@@ -214,6 +214,16 @@ module DICOM
       end
     end
 
+    # Returns true if the argument is an instance with attributes equal to self.
+    #
+    def ==(other)
+      if other.respond_to?(:to_dcm)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
     # Encodes the DICOM object into a series of binary string segments with a specified maximum length.
     #
     # Returns the encoded binary strings in an array.
@@ -225,7 +235,7 @@ module DICOM
     #
     # === Examples
     #
-    #  encoded_strings = obj.encode_segments(16384)
+    #  encoded_strings = dcm.encode_segments(16384)
     #
     def encode_segments(max_size, transfer_syntax=transfer_syntax)
       raise ArgumentError, "Invalid argument. Expected an Integer, got #{max_size.class}." unless max_size.is_a?(Integer)
@@ -238,6 +248,12 @@ module DICOM
       return w.segments
     end
 
+    # Generates a Fixnum hash value for this instance.
+    #
+    def hash
+      state.hash
+    end
+
     # Prints information of interest related to the DICOM object.
     # Calls the print() method of Parent as well as the information() method of DObject.
     #
@@ -396,6 +412,12 @@ module DICOM
       return info
     end
 
+    # Returns self.
+    #
+    def to_dcm
+      self
+    end
+
     # Returns the transfer syntax string of the DObject.
     #
     # If a transfer syntax has not been defined in the DObject, a default tansfer syntax is assumed and returned.
@@ -447,7 +469,7 @@ module DICOM
     #
     # === Examples
     #
-    #   obj.write(path + "test.dcm")
+    #   dcm.write(path + "test.dcm")
     #
     def write(file_name, options={})
       raise ArgumentError, "Invalid file_name. Expected String, got #{file_name.class}." unless file_name.is_a?(String)
@@ -483,8 +505,8 @@ module DICOM
       end
       # Source Application Entity Title:
       Element.new("0002,0016", DICOM.source_app_title, :parent => self) unless exists?("0002,0016")
-      # Group Length: Remove the old one (if it exists) before creating a new one.
-      remove("0002,0000")
+      # Group Length: Delete the old one (if it exists) before creating a new one.
+      delete("0002,0000")
       Element.new("0002,0000", meta_group_length, :parent => self)
     end
 
@@ -507,5 +529,11 @@ module DICOM
       return group_length
     end
 
+    # Returns the attributes (children) of this instance (for comparison purposes).
+    #
+    def state
+      @tags
+    end
+
   end
 end

data/lib/dicom/d_read.rb

@@ -19,7 +19,7 @@ module DICOM
     # An array which records any status messages that are generated while parsing the DICOM string.
     attr_reader :msg
     # A DObject instance which the parsed data elements will be connected to.
-    attr_reader :obj
+    attr_reader :dcm
     # A boolean which records whether the DICOM string contained the proper DICOM header signature of 128 bytes + 'DICM'.
     attr_reader :signature
     # A boolean which reports whether the DICOM string was parsed successfully (true) or not (false).
@@ -30,7 +30,7 @@ module DICOM
     #
     # === Parameters
     #
-    # * <tt>obj</tt> -- A DObject instance which the parsed data elements will be connected to.
+    # * <tt>dcm</tt> -- A DObject instance which the parsed data elements will be connected to.
     # * <tt>string</tt> -- A string which specifies either the path of a DICOM file to be loaded, or a binary DICOM string to be parsed.
     # * <tt>options</tt> -- A hash of parameters.
     #
@@ -40,13 +40,13 @@ module DICOM
     # * <tt>:no_meta</tt> -- Boolean. If true, the parsing algorithm is instructed that the binary DICOM string contains no meta header.
     # * <tt>:syntax</tt> -- String. If specified, the decoding of the DICOM string will be forced to use this transfer syntax.
     #
-    def initialize(obj, string=nil, options={})
+    def initialize(dcm, string=nil, options={})
       # Set the DICOM object as an instance variable:
-      @obj = obj
+      @dcm = dcm
       # 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)
+        dcm.add(Element.new("0002,0010", options[:syntax])) if dcm.is_a?(DObject)
       end
       # Initiate the variables that are used during file reading:
       init_variables
@@ -292,7 +292,7 @@ module DICOM
         length = @stream.decode(bytes, "SL") # (4)
       end
       # Check that length is valid (according to the DICOM standard, it must be even):
-      raise "Encountered a Data Element (#{tag}) with an invalid (odd) value length." if length%2 == 1 and length > 0
+      raise "Encountered a Data Element (#{tag}) with an invalid (odd) value length." if length.odd? and length > 0
       return vr, length
     end
 
@@ -366,7 +366,7 @@ module DICOM
     def switch_syntax
       # Get the transfer syntax string, unless it has already been provided by keyword:
       unless @transfer_syntax
-        ts_element = @obj["0002,0010"]
+        ts_element = @dcm["0002,0010"]
         if ts_element
           @transfer_syntax = ts_element.value
         else
@@ -411,9 +411,9 @@ module DICOM
       # When the file switch from group 0002 to a later group we will update encoding values, and this switch will keep track of that:
       @switched = false
       # Keeping track of the data element parent status while parsing the DICOM string:
-      @current_parent = @obj
+      @current_parent = @dcm
       # Keeping track of what is the current data element:
-      @current_element = @obj
+      @current_element = @dcm
       # Items contained under the pixel data element may contain data directly, so we need a variable to keep track of this:
       @enc_image = false
       # Assume header size is zero bytes until otherwise is determined:

data/lib/dicom/d_server.rb

@@ -33,6 +33,8 @@ module DICOM
 
     # A customized FileHandler class to use instead of the default FileHandler included with Ruby DICOM.
     attr_accessor :file_handler
+    # The hostname that the TCPServer binds to.
+    attr_accessor :host
     # The name of the server (application entity).
     attr_accessor :host_ae
     # The maximum allowed size of network packages (in bytes).
@@ -61,6 +63,7 @@ module DICOM
     # === Options
     #
     # * <tt>:file_handler</tt> -- A customized FileHandler class to use instead of the default FileHandler.
+    # * <tt>:host</tt> -- String. The hostname that the TCPServer binds to. Defaults to '127.0.0.1'.
     # * <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>:timeout</tt> -- Fixnum. The maximum period the server will wait on an answer from a client before aborting the communication.
@@ -79,6 +82,7 @@ module DICOM
       @port = port
       # Optional parameters (and default values):
       @file_handler = options[:file_handler] || FileHandler
+      @host = options[:host] || '127.0.0.1'
       @host_ae =  options[:host_ae]  || "RUBY_DICOM"
       @max_package_size = options[:max_package_size] || 32768 # 16384
       @timeout = options[:timeout] || 10 # seconds
@@ -144,14 +148,14 @@ module DICOM
       end
     end
 
-    # Removes a specific abstract syntax from the list of abstract syntaxes that the server will accept.
+    # Deletes a specific abstract syntax from the list of abstract syntaxes that the server will accept.
     #
     #
     # === Parameters
     #
     # * <tt>uid</tt> -- An abstract syntax UID string.
     #
-    def remove_abstract_syntax(uid)
+    def delete_abstract_syntax(uid)
       if uid.is_a?(String)
         @accepted_abstract_syntaxes.delete(uid)
       else
@@ -159,13 +163,13 @@ module DICOM
       end
     end
 
-    # Removes a specific transfer syntax from the list of transfer syntaxes that the server will accept.
+    # Deletes a specific transfer syntax from the list of transfer syntaxes that the server will accept.
     #
     # === Parameters
     #
     # * <tt>uid</tt> -- A transfer syntax UID string.
     #
-    def remove_transfer_syntax(uid)
+    def delete_transfer_syntax(uid)
       if uid.is_a?(String)
         @accepted_transfer_syntaxes.delete(uid)
       else
@@ -177,9 +181,9 @@ module DICOM
     #
     # === Notes
     #
-    # * Following such a removal, the user must ensure to add the specific abstract syntaxes that are to be accepted by the server.
+    # * Following such a clearance, the user must ensure to add the specific abstract syntaxes that are to be accepted by the server.
     #
-    def remove_all_abstract_syntaxes
+    def clear_abstract_syntaxes
       @accepted_abstract_syntaxes = Hash.new
     end
 
@@ -187,9 +191,9 @@ module DICOM
     #
     # === Notes
     #
-    # * Following such a removal, the user must ensure to add the specific transfer syntaxes that are to be accepted by the server.
+    # * Following such a clearance, the user must ensure to add the specific transfer syntaxes that are to be accepted by the server.
     #
-    def remove_all_transfer_syntaxes
+    def clear_transfer_syntaxes
       @accepted_transfer_syntaxes = Hash.new
     end
 
@@ -209,7 +213,7 @@ module DICOM
         logger.info("Started DICOM SCP server on port #{@port}.")
         logger.info("Waiting for incoming transmissions...\n\n")
         # Initiate server:
-        @scp = TCPServer.new(@port)
+        @scp = TCPServer.new(@host, @port)
         # Use a loop to listen for incoming messages:
         loop do
           Thread.start(@scp.accept) do |session|
@@ -279,7 +283,7 @@ module DICOM
     #
     # === Notes
     #
-    # Other things can potentionally be checked here too, if we want to make the server more strict with regards to what information is received:
+    # Other things can potentially be checked here too, if we want to make the server more strict with regards to what information is received:
     # * Application context name, calling AE title, called AE title
     # * Description of error codes are given in the DICOM Standard, PS 3.8, Chapter 9.3.4 (Table 9-21).
     #