dicom 0.9.2 → 0.9.3

data/CHANGELOG.rdoc

@@ -1,6 +1,25 @@
+= 0.9.3
+
+=== 6th May, 2012
+
+* Deprecated all #remove* methods (replaced with #delete*) to increase consistency with Ruby.
+* Changed preferred DObject variable name from obj to dcm for all examples.
+* Added comparison methods (#==, #eql? and #hash) as well as dynamic #to_* methods to DObject, Element, Item & Sequence classes.
+* Fixed incorrect handling of 3D pixel data with NArray (regression introduced in v0.8).
+* Anonymizer can take a list of tags to be entirely deleted from the DICOM files during anonymization.
+* Added Accession Number to default list of tags that are anonymized.
+* Added a generate_uid method for creating custom (but valid) UIDs.
+* Added an Anonymizer AuditTrail feature based on JSON, which will replace the (deprecated) identity_file feature.
+* Implemented a proper UID anonymization with AuditTrail support and preservation of relations.
+* Fixed and improved logging when failing to decompress pixel data.
+* DServer defaults to bind to 127.0.0.1, with an option available for other bindings.
+* More robust handling of invalid AT Element values when parsing DICOM files.
+* Optimizations and code cleanups allowed by the introduced Ruby 1.9 requirement.
+
+
 = 0.9.2
 
-=== (Not released yet)
+=== 10th Oct, 2011
 
 * Enabled the use of lower case tag letters in methods which previously required the use of upper case letters.
 * Added new DObject class methods to offload DObject#new:

data/README.rdoc

@@ -13,6 +13,11 @@ communication modalities like querying, moving, sending and receiving files.
   gem install dicom
 
 
+== REQUIREMENTS
+
+* Ruby 1.9.2 (if you are still on Ruby 1.8, gems up to version 0.9.1 can be used)
+
+
 == BASIC USAGE
 
 === Load & Include
@@ -23,42 +28,42 @@ communication modalities like querying, moving, sending and receiving files.
 === Read, modify and write
 
   # Read file:
-  obj = DObject.read("some_file.dcm")
+  dcm = DObject.read("some_file.dcm")
   # Extract the Patient's Name value:
-  obj.patients_name.value
+  dcm.patients_name.value
   # Add or modify the Patient's Name element:
-  obj.patients_name = "Anonymous"
+  dcm.patients_name = "Anonymous"
   # Remove a data element from the DICOM object:
-  obj.pixel_data = nil
+  dcm.pixel_data = nil
   # Write to file:
-  obj.write("new_file.dcm")
+  dcm.write("new_file.dcm")
 
 === Modify using tag strings instead of dictionary method names
 
   # Extract the Patient's Name value:
-  obj.value("0010,0010")
+  dcm.value("0010,0010")
   # Modify the Patient's Name element:
-  obj["0010,0010"].value = "Anonymous"
-  # Remove a data element from the DICOM object:
-  obj.remove("7FE0,0010")
+  dcm["0010,0010"].value = "Anonymous"
+  # Delete a data element from the DICOM object:
+  dcm.delete("7FE0,0010")
 
 === Extracting information about the DICOM object
 
   # Display a short summary of the file's properties:
-  obj.summary
+  dcm.summary
   # Print all data elements to screen:
-  obj.print
+  dcm.print
   # Convert the data element hierarchy to a nested hash:
-  obj.to_hash
+  dcm.to_hash
 
 === Handle pixel data
 
   # Retrieve the pixel data in a Ruby Array:
-  obj.pixels
+  dcm.pixels
   # Load the pixel data to an numerical array (NArray):
-  obj.narray
+  dcm.narray
   # Load the pixel data to an RMagick image object and display it on the screen:
-  obj.image.display
+  dcm.image.display
 
 === Transmit a DICOM file
 
@@ -91,19 +96,21 @@ that is printed to screen, regardless if you have set verbose as false. This is
 in irb every variable loaded in the program is automatically printed to the screen.
 A useful hack to avoid this effect is to append ";0" after a command.
 Example:
-  obj = DObject.new("some_file.dcm") ;0
+  dcm = DObject.read("some_file.dcm") ;0
 
 
 == RESOURCES
 
 * {Official home page}[http://dicom.rubyforge.org/]
 * {Discussion forum}[http://groups.google.com/group/ruby-dicom]
+* {Documentation}[http://rubydoc.info/gems/dicom/frames]
+* {Tutorials}[http://dicom.rubyforge.org/tutorials.html]
 * {Source code repository}[https://github.com/dicom/ruby-dicom]
 
 
 == COPYRIGHT
 
-Copyright 2008-2011 Christoffer Lervåg
+Copyright 2008-2012 Christoffer Lervåg
 
 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
@@ -133,7 +140,9 @@ Please don't hesitate to email me if you have any feedback related to this proje
 * {Christoffer Lervåg}[https://github.com/dicom]
 * {John Axel Eriksson}[https://github.com/johnae]
 * {Kamil Bujniewicz}[https://github.com/icdark]
+* {Jeff Miller}[https://github.com/jeffmax]
 * {Donnie Millar}[https://github.com/dmillar]
 * {Björn Albers}[https://github.com/bjoernalbers]
 * {Lars Benner}[https://github.com/Maturin]
+* {Felix Petriconi}[https://github.com/FelixPetriconi]
 * {Steven Bedrick}[https://github.com/stevenbedrick]

data/lib/dicom.rb

@@ -2,46 +2,50 @@
 #
 # The following classes are meant to be used by users of Ruby DICOM:
 # * DObject - for reading, manipulating and writing DICOM files.
-# * Element, Sequence, Item, Parent, Elemental - users who wish to interact with their DICOM objects will use these classes/modules.
+# * Element, Sequence, Item, Parent, Elemental - users who wish to interact with
+#   their DICOM objects will use these classes/modules.
 # * ImageItem - Image related methods are found in this class.
 # * DClient - for client side network communication, like querying, moving & sending DICOM files.
 # * DServer - for server side network communication: Setting up your own DICOM storage node (SCP).
 # * Anonymizer - a convenience class for anonymizing your DICOM files.
 #
-# The rest of the classes visible in the documentation generated by RDoc is in principle
-# 'private' classes, which are mainly of interest to developers.
+# The rest of the classes visible in the documentation generated by RDoc are
+# in principle 'private' classes, which are mainly of interest to developers.
 
 # Logging:
-require 'dicom/logging'
+require_relative 'dicom/logging'
 # Core library:
 # Super classes/modules:
-require 'dicom/image_processor'
-require 'dicom/parent'
-require 'dicom/image_item'
-require 'dicom/elemental'
+require_relative 'dicom/image_processor'
+require_relative 'dicom/parent'
+require_relative 'dicom/image_item'
+require_relative 'dicom/elemental'
 # Subclasses and independent classes:
-require 'dicom/d_client'
-require 'dicom/dictionary'
-require 'dicom/d_library'
-require 'dicom/d_object'
-require 'dicom/d_read'
-require 'dicom/d_server'
-require 'dicom/d_write'
-require 'dicom/element'
-require 'dicom/file_handler'
-require 'dicom/item'
-require 'dicom/link'
-require 'dicom/sequence'
-require 'dicom/stream'
+require_relative 'dicom/d_client'
+require_relative 'dicom/dictionary'
+require_relative 'dicom/d_library'
+require_relative 'dicom/d_object'
+require_relative 'dicom/d_read'
+require_relative 'dicom/d_server'
+require_relative 'dicom/d_write'
+require_relative 'dicom/element'
+require_relative 'dicom/file_handler'
+require_relative 'dicom/item'
+require_relative 'dicom/link'
+require_relative 'dicom/sequence'
+require_relative 'dicom/stream'
 # Extensions to the Ruby library:
-require 'dicom/ruby_extensions'
+require_relative 'dicom/ruby_extensions'
 # Module settings:
-require 'dicom/version'
-require 'dicom/constants'
-require 'dicom/variables'
+require_relative 'dicom/version'
+require_relative 'dicom/constants'
+require_relative 'dicom/variables'
 # Image processors:
-require 'dicom/image_processor_mini_magick'
-require 'dicom/image_processor_r_magick'
+require_relative 'dicom/image_processor_mini_magick'
+require_relative 'dicom/image_processor_r_magick'
+# Deprecated methods:
+require_relative 'dicom/deprecated'
 
 # Extensions (non-core functionality):
-require 'dicom/anonymizer'
+require_relative 'dicom/anonymizer'
+require_relative 'dicom/audit_trail'

data/lib/dicom/anonymizer.rb

@@ -11,18 +11,26 @@ module DICOM
   class Anonymizer
     include Logging
 
+    # An AuditTrail instance used for this anonymization (if specified).
+    attr_reader :audit_trail
+    # The file name used for the AuditTrail serialization (if specified).
+    attr_reader :audit_trail_file
     # A boolean that if set as true will cause all anonymized tags to be blank instead of get some generic value.
     attr_accessor :blank
     # A boolean that if set as true will cause all anonymized tags to be get enumerated values, to enable post-anonymization identification by the user.
     attr_accessor :enumeration
-    # A string, which if set (and enumeration has been set as well), will make the Anonymizer produce an identity file that provides a relationship between the original and enumerated, anonymized values.
-    attr_accessor :identity_file
-    # An array containing status messages accumulated for the Anonymization instance.
-    attr_accessor :log
-    # A boolean that if set as true, will make the anonymization remove all private tags.
-    attr_accessor :remove_private
+    # The identity file attribute.
+    attr_reader :identity_file
+    # A boolean that if set as true, will make the anonymization delete all private tags.
+    attr_accessor :delete_private
     # The path where the anonymized files will be saved. If this value is not set, the original DICOM files will be overwritten.
     attr_accessor :write_path
+    # A boolean indicating whether or not UIDs shall be replaced when executing the anonymization.
+    attr_accessor :uid
+    # The DICOM UID root to use when generating new UIDs.
+    attr_accessor :uid_root
+    # An array of UID tags that will be anonymized if the uid option is used.
+    attr_accessor :uids
 
     # Creates an Anonymizer instance.
     #
@@ -30,19 +38,33 @@ module DICOM
     #
     # * To customize logging behaviour, refer to the Logging module documentation.
     #
+    # === Parameters
+    #
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:audit_trail</tt> -- String. A file name path. If the file contains old audit data, these are loaded and used in the current anonymization.
+    # * <tt>:uid</tt> -- Boolean. If true, all (top level) UIDs will be replaced with custom generated UIDs. To preserve UID relations in studies/series, the AuditTrail feature must be used.
+    # * <tt>:uid_root</tt> -- String. An organization (or custom) UID root to use when replacing UIDs.
+    #
     # === Examples
     #
     #   # Create an Anonymizer instance and restrict the log output:
     #   a = Anonymizer.new
     #   a.logger.level = Logger::ERROR
-    #
-    def initialize
+    #   # Carry out anonymization using the audit trail feature:
+    #   a = Anonymizer.new(:audit_trail => "trail.json")
+    #   a.enumeration = true
+    #   a.folder = "//dicom/today/"
+    #   a.write_path = "//anonymized/"
+    #   a.execute
+    #
+    def initialize(options={})
       # Default value of accessors:
       @blank = false
       @enumeration = false
-      @identity_file = nil
-      @remove_private = false
-      @write_path = nil
+      @delete_private = false
       # Array of folders to be processed for anonymization:
       @folders = Array.new
       # Folders that will be skipped:
@@ -60,8 +82,21 @@ module DICOM
       @files = Array.new
       # Write paths will be determined later and put in this array:
       @write_paths = Array.new
-      # Keep track of status messages:
-      @log = Array.new
+      # Register the uid anonymization option:
+      @uid = options[:uid]
+      # Set the uid_root to be used when anonymizing study_uid series_uid and sop_instance_uid
+      @uid_root = options[:uid_root] ? options[:uid_root] : UID
+      # Setup audit trail if requested:
+      if options[:audit_trail]
+        @audit_trail_file = options[:audit_trail]
+        if File.exists?(@audit_trail_file) && File.size(@audit_trail_file) > 2
+          # Load the pre-existing audit trail from file:
+          @audit_trail = AuditTrail.read(@audit_trail_file)
+        else
+          # Start from scratch with an empty audit trail:
+          @audit_trail = AuditTrail.new
+        end
+      end
       # Set the default data elements to be anonymized:
       set_defaults
     end
@@ -160,17 +195,24 @@ module DICOM
           all_write = true
           files_written = 0
           files_failed_read = 0
+          begin
+            require 'progressbar'
+            pbar = ProgressBar.new("Anonymizing", @files.length)
+          rescue LoadError
+            pbar = nil
+          end
           # Temporarily increase the log threshold to suppress messages from the DObject class:
           anonymizer_level = logger.level
           logger.level = Logger::FATAL
           @files.each_index do |i|
+            pbar.inc if pbar
             # Read existing file to DICOM object:
-            obj = DICOM::DObject.read(@files[i])
-            if obj.read_success
+            dcm = DObject.read(@files[i])
+            if dcm.read?
               # Anonymize the desired tags:
               @tags.each_index do |j|
-                if obj.exists?(@tags[j])
-                  element = obj[@tags[j]]
+                if dcm.exists?(@tags[j])
+                  element = dcm[@tags[j]]
                   if element.is_a?(Element)
                     if @blank
                       value = ""
@@ -178,7 +220,7 @@ module DICOM
                       old_value = element.value
                       # Only launch enumeration logic if there is an actual value to the data element:
                       if old_value
-                        value = get_enumeration_value(old_value, j)
+                        value = enumerated_value(old_value, j)
                       else
                         value = ""
                       end
@@ -190,11 +232,17 @@ module DICOM
                   end
                 end
               end
-              # Remove private tags?
-              obj.remove_private if @remove_private
+              # Handle UIDs if requested:
+              replace_uids(dcm) if @uid
+              # Delete private tags?
+              dcm.delete_private if @delete_private
+              # Delete Tags marked for removal:
+              @delete_tags.each_index do |j|
+                dcm.delete(@delete_tags[j]) if dcm.exists?(@delete_tags[j])
+              end
               # Write DICOM file:
-              obj.write(@write_paths[i])
-              if obj.write_success
+              dcm.write(@write_paths[i])
+              if dcm.written?
                 files_written += 1
               else
                 all_write = false
@@ -204,7 +252,8 @@ module DICOM
               files_failed_read += 1
             end
           end
-          # Finished anonymizing files. Reset the logg threshold:
+          pbar.finish if pbar
+          # Finished anonymizing files. Reset the log threshold:
           logger.level = anonymizer_level
           # Print elapsed time and status of anonymization:
           end_time = Time.now.to_f
@@ -219,8 +268,9 @@ module DICOM
           else
             logger.warn("Some DICOM objects were NOT succesfully written to file. You are advised to investigate the result (#{files_written} files succesfully written).")
           end
+          @audit_trail.write(@audit_trail_file) if @audit_trail
           # Has user requested enumeration and specified an identity file in which to store the anonymized values?
-          if @enumeration and @identity_file
+          if @enumeration and @identity_file and !@audit_trail
             logger.info("Writing identity file.")
             write_identity_file
             logger.info("Done")
@@ -235,6 +285,16 @@ module DICOM
       end
     end
 
+    # Setter method for the identity file.
+    # NB! The identity file feature is deprecated!
+    # Please use the AuditTrail feature instead.
+    #
+    def identity_file=(file_name)
+      # Deprecation warning:
+      logger.warn("The identity_file feature of the Anonymization class has been deprecated! Please use the AuditTrail feature instead.")
+      @identity_file = file_name
+    end
+
     # Prints to screen a list of which tags are currently selected for anonymization along with
     # the replacement values that will be used and enumeration status.
     #
@@ -310,6 +370,22 @@ module DICOM
         @enumerations.delete_at(pos)
       end
     end
+    
+    # Compeletely deletes a tag from the file
+    #
+    # === Parameters
+    #
+    # * <tt>tag</tt> -- String. A data element tag.
+    #
+    # === Examples
+    #
+    #   a.delete_tag("0010,0010")
+    #
+    def delete_tag(tag)
+      raise ArgumentError, "Expected String, got #{tag.class}." unless tag.is_a?(String)
+      raise ArgumentError, "Expected a valid tag of format 'GGGG,EEEE', got #{tag}." unless tag.tag?
+      @delete_tags.push(tag) if not @delete_tags.include?(tag)
+    end
 
     # Sets the anonymization settings for the specified tag. If the tag is already present in the list
     # of tags to be anonymized, its settings are updated, and if not, a new tag entry is created.
@@ -406,39 +482,53 @@ module DICOM
       end
     end
 
-    # Handles the enumeration for the current data element tag.
-    # If its value has been encountered before, its corresponding enumerated value is retrieved,
-    # and if a new value is encountered, a new enumerated value is found by increasing an index by 1.
-    # Returns the value which will be used for the anonymization of this tag.
+    # Handles the enumeration for the given data element tag.
+    # If its value has been encountered before, its corresponding enumerated
+    # replacement value is retrieved, and if a new original value is encountered,
+    # a new enumerated replacement value is found by increasing an index by 1.
+    # Returns the replacement value which is used for the anonymization of the tag.
     #
     # === Parameters
     #
-    # * <tt>current</tt> -- The original value of the tag that are about to be anonymized.
+    # * <tt>original</tt> -- The original value of the tag that to be anonymized.
     # * <tt>j</tt> -- Fixnum. The index of this tag in the tag-related instance arrays.
     #
-    def get_enumeration_value(current, j)
+    def enumerated_value(original, j)
       # Is enumeration requested for this tag?
       if @enumerations[j]
-        # Retrieve earlier used anonymization values:
-        previous_old = @enum_old_hash[@tags[j]]
-        previous_new = @enum_new_hash[@tags[j]]
-        p_index = previous_old.length
-        if previous_old.index(current) == nil
-          # Current value has not been encountered before:
-          value = @values[j]+(p_index + 1).to_s
-          # Store value in array (and hash):
-          previous_old << current
-          previous_new << value
-          @enum_old_hash[@tags[j]] = previous_old
-          @enum_new_hash[@tags[j]] = previous_new
+        if @audit_trail
+          # Check if the UID has been encountered already:
+          replacement = @audit_trail.replacement(@tags[j], original)
+          unless replacement
+            # This original value has not been encountered yet. Determine the index to use.
+            index = @audit_trail.records(@tags[j]).length + 1
+            # Create the replacement value:
+            replacement = @values[j] + index.to_s
+            # Add this tag record to the audit trail:
+            @audit_trail.add_record(@tags[j], original, replacement)
+          end
         else
-          # Current value has been observed before:
-          value = previous_new[previous_old.index(current)]
+          # Retrieve earlier used anonymization values:
+          previous_old = @enum_old_hash[@tags[j]]
+          previous_new = @enum_new_hash[@tags[j]]
+          p_index = previous_old.length
+          if previous_old.index(original) == nil
+            # Current value has not been encountered before:
+            replacement = @values[j]+(p_index + 1).to_s
+            # Store value in array (and hash):
+            previous_old << original
+            previous_new << replacement
+            @enum_old_hash[@tags[j]] = previous_old
+            @enum_new_hash[@tags[j]] = previous_new
+          else
+            # Current value has been observed before:
+            replacement = previous_new[previous_old.index(original)]
+          end
         end
       else
-        value = @values[j]
+        replacement = @values[j]
       end
-      return value
+      return replacement
     end
 
     # Discovers all the files contained in the specified directory (all its sub-directories),
@@ -502,10 +592,54 @@ module DICOM
       end
     end
 
-    # Sets up the default tags that will be anonymized, along with default replacement values and enumeration settings.
-    # The data is stored in 3 separate instance arrays for tags, values and enumeration.
+    # Replaces the UIDs of the given DICOM object.
+    #
+    # === Notes
+    #
+    # Empty UIDs are ignored (we don't generate new UIDs for these).
+    # If AuditTrail is set, the relationship between old and new UIDs
+    # are preserved, and the relations between files in a study/series
+    # should remain valid.
+    #
+    #
+    def replace_uids(dcm)
+      @uids.each_pair do |tag, prefix|
+        original = dcm.value(tag)
+        if original && original.length > 0
+          # We have a UID value, go ahead and replace it:
+          if @audit_trail
+            # Check if the UID has been encountered already:
+            replacement = @audit_trail.replacement(tag, original)
+            unless replacement
+              # The UID has not been stored previously. Generate a new one:
+              replacement = DICOM.generate_uid(@uid_root, prefix)
+              # Add this tag record to the audit trail:
+              @audit_trail.add_record(tag, original, replacement)
+            end
+            # Replace the UID in the DICOM object:
+            dcm[tag].value = replacement
+            # NB! The SOP Instance UID must also be written to the Media Storage SOP Instance UID tag:
+            dcm["0002,0003"].value = replacement if tag == "0008,0018" && dcm.exists?("0002,0003")
+          else
+            # We don't care about preserving UID relations. Just insert a custom UID:
+            dcm[tag].value = DICOM.generate_uid(@uid_root, prefix)
+          end
+        end
+      end
+    end
+
+    # Sets up some default information variables that are used by the Anonymizer.
     #
     def set_defaults
+      # A hash of UID tags to be replaced (if requested) and prefixes to use for each tag:
+      @uids = {
+        "0008,0018" => 3, # SOP Instance UID
+        "0020,000D" => 1, # Study Instance UID
+        "0020,000E" => 2, # Series Instance UID
+        "0020,0052" => 9 # Frame of Reference UID
+      }
+      # Sets up default tags that will be anonymized, along with default replacement values and enumeration settings.
+      # This data is stored in 3 separate instance arrays for tags, values and enumeration.
       data = [
       ["0008,0012", "20000101", false], # Instance Creation Date
       ["0008,0013", "000000.00", false], # Instance Creation Time
@@ -513,6 +647,7 @@ module DICOM
       ["0008,0023", "20000101", false], # Image Date
       ["0008,0030", "000000.00", false], # Study Time
       ["0008,0033", "000000.00", false], # Image Time
+      ["0008,0050", "", true], # Accession Number
       ["0008,0080", "Institution", true], # Institution name
       ["0008,0090", "Physician", true], # Referring Physician's name
       ["0008,1010", "Station", true], # Station name
@@ -526,6 +661,10 @@ module DICOM
       @tags = data[0]
       @values = data[1]
       @enumerations = data[2]
+      
+      # Tags to be deleted completely during anonymization
+      @delete_tags = [
+      ]
     end
 
     # Writes an identity file, which allows reidentification of DICOM files that have been anonymized
@@ -552,6 +691,5 @@ module DICOM
         end
       end
     end
-
   end
 end