dicom 0.9.3 → 0.9.4

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://www.rubygems.org"
+
+gemspec

data/dicom.gemspec

@@ -0,0 +1,31 @@
+# encoding: UTF-8
+
+require File.expand_path('../lib/dicom/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.platform = Gem::Platform::RUBY
+  s.name = 'dicom'
+  s.version = DICOM::VERSION
+  s.date = Time.now
+  s.summary = "Library for handling DICOM files and DICOM network communication."
+  s.require_paths = ['lib']
+  s.author = "Christoffer Lervag"
+  s.email = "chris.lervag@gmail.com"
+  s.homepage = "http://dicom.rubyforge.org/"
+  s.license = "GPLv3"
+  s.description = "DICOM is a standard widely used throughout the world to store and transfer medical image data. This library enables efficient and powerful handling of DICOM in Ruby, to the benefit of any student or professional who would like to use their favorite language to process DICOM files and communicate across the network."
+  s.files = Dir["{lib}/**/*", "[A-Z]*"]
+  s.rubyforge_project = 'dicom'
+
+  s.required_ruby_version = '>= 1.9.2'
+  s.required_rubygems_version = '>= 1.8.6'
+
+  s.add_development_dependency('bundler', '>= 1.0.0')
+  s.add_development_dependency('rake', '>= 0.9.2.2')
+  s.add_development_dependency('rspec', '>= 2.9.0')
+  s.add_development_dependency('mocha', '>= 0.10.5')
+  s.add_development_dependency('narray', '>= 0.6.0.0')
+  s.add_development_dependency('rmagick', '>= 2.12.0')
+  s.add_development_dependency('mini_magick', '>= 3.2.1')
+  s.add_development_dependency('yard', '>= 0.8.2')
+end

data/lib/dicom.rb

@@ -1,51 +1,53 @@
-# Loads the files that are used by Ruby DICOM.
-#
-# 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.
-# * 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 are
-# in principle 'private' classes, which are mainly of interest to developers.
-
-# Logging:
-require_relative 'dicom/logging'
-# Core library:
-# Super classes/modules:
-require_relative 'dicom/image_processor'
-require_relative 'dicom/parent'
-require_relative 'dicom/image_item'
-require_relative 'dicom/elemental'
-# Subclasses and independent classes:
-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_relative 'dicom/ruby_extensions'
-# Module settings:
-require_relative 'dicom/version'
-require_relative 'dicom/constants'
-require_relative 'dicom/variables'
-# Image processors:
-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_relative 'dicom/anonymizer'
-require_relative 'dicom/audit_trail'
+# Loads the files that are used by ruby-dicom.
+#
+# 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.
+# * 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 YARD are
+# in principle 'private' classes, which are mainly of interest to developers.
+
+# Logging:
+require_relative 'dicom/logging'
+# Core library:
+# Super classes/modules:
+require_relative 'dicom/image_processor'
+require_relative 'dicom/parent'
+require_relative 'dicom/image_item'
+require_relative 'dicom/elemental'
+# Subclasses and independent classes:
+require_relative 'dicom/d_client'
+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'
+# Dictionary:
+require_relative 'dicom/d_library'
+require_relative 'dicom/dictionary_element'
+require_relative 'dicom/uid'
+# Extensions to the Ruby library:
+require_relative 'dicom/ruby_extensions'
+# Module settings:
+require_relative 'dicom/version'
+require_relative 'dicom/constants'
+require_relative 'dicom/variables'
+# Image processors:
+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_relative 'dicom/anonymizer'
+require_relative 'dicom/audit_trail'

data/lib/dicom/anonymizer.rb

@@ -1,12 +1,11 @@
 module DICOM
 
-  # This is a convenience class for handling anonymization of DICOM files.
+  # This is a convenience class for handling the anonymization (de-identification) of DICOM files.
   #
-  # === Notes
-  #
-  # For 'advanced' anonymization, a good resource might be:
-  # ftp://medical.nema.org/medical/dicom/supps/sup142_pc.pdf
-  # (Clinical Trials De-identification Profiles, DICOM Standards Committee, Working Group 18)
+  # @note
+  #   For 'advanced' anonymization, a good resource might be the work on "Clinical Trials
+  #   De-identification Profiles" by the DICOM Standards Committee, Working Group 18:
+  #   ftp://medical.nema.org/medical/dicom/supps/sup142_pc.pdf
   #
   class Anonymizer
     include Logging
@@ -34,26 +33,15 @@ module DICOM
 
     # Creates an Anonymizer instance.
     #
-    # === Notes
-    #
-    # * 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:
+    # @note To customize logging behaviour, refer to the Logging module documentation.
+    # @param [Hash] options the options to create an anonymizer instance with
+    # @option options [String] :audit_trail a file name path. If the file contains old audit data, these are loaded and used in the current anonymization.
+    # @option options [Boolean] :uid 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.
+    # @option options [String] :uid_root an organization (or custom) UID root to use when replacing UIDs.
+    # @example Create an Anonymizer instance and restrict the log output
     #   a = Anonymizer.new
     #   a.logger.level = Logger::ERROR
-    #   # Carry out anonymization using the audit trail feature:
+    # @example Perform anonymization using the audit trail feature
     #   a = Anonymizer.new(:audit_trail => "trail.json")
     #   a.enumeration = true
     #   a.folder = "//dicom/today/"
@@ -85,7 +73,7 @@ module DICOM
       # 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
+      @uid_root = options[:uid_root] ? options[:uid_root] : UID_ROOT
       # Setup audit trail if requested:
       if options[:audit_trail]
         @audit_trail_file = options[:audit_trail]
@@ -103,12 +91,8 @@ module DICOM
 
     # Adds an exception folder which will be avoided when anonymizing.
     #
-    # === Parameters
-    #
-    # * <tt>path</tt> -- String. A path that will be avoided.
-    #
-    # === Examples
-    #
+    # @param [String] path a path that will be avoided
+    # @example Adding a folder
     #   a.add_exception("/home/dicom/tutorials/")
     #
     def add_exception(path)
@@ -122,12 +106,8 @@ module DICOM
 
     # Adds a folder who's files will be anonymized.
     #
-    # === Parameters
-    #
-    # * <tt>path</tt> -- String. A path that will be included in the anonymization.
-    #
-    # === Examples
-    #
+    # @param [String] path a path that will be included in the anonymization
+    # @example Adding a folder
     #   a.add_folder("/home/dicom")
     #
     def add_folder(path)
@@ -135,12 +115,10 @@ module DICOM
       @folders << path
     end
 
-    # Returns the enumeration status for this tag.
-    # Returns nil if no match is found for the provided tag.
+    # Checks the enumeration status of this tag.
     #
-    # === Parameters
-    #
-    # * <tt>tag</tt> -- String. A data element tag.
+    # @param [String] tag a data element tag
+    # @return [Boolean, NilClass] the enumeration status of the tag, or nil if the tag has no match
     #
     def enum(tag)
       raise ArgumentError, "Expected String, got #{tag.class}." unless tag.is_a?(String)
@@ -158,14 +136,10 @@ module DICOM
     #
     # This method is run when all settings have been finalized for the Anonymization instance.
     #
-    # === Restrictions
-    #
-    # * Only top level data elements are anonymized!
-    #
-    #--
-    # FIXME: This method has grown a bit lengthy. Perhaps it should be looked at one day.
+    # @note Only top level data elements are anonymized!
     #
     def execute
+      # FIXME: This method has grown a bit lengthy. Perhaps it should be looked at one day.
       # Search through the folders to gather all the files to be anonymized:
       logger.info("Initiating anonymization process.")
       start_time = Time.now.to_f
@@ -286,8 +260,10 @@ module DICOM
     end
 
     # Setter method for the identity file.
-    # NB! The identity file feature is deprecated!
-    # Please use the AuditTrail feature instead.
+    #
+    # @deprecated The identity file feature is deprecated!
+    #   Please use the AuditTrail feature instead.
+    # @param [String] file_name the path of the identity file
     #
     def identity_file=(file_name)
       # Deprecation warning:
@@ -307,7 +283,7 @@ module DICOM
       type_lengths = Array.new
       value_lengths = Array.new
       @tags.each_index do |i|
-        name, vr = LIBRARY.get_name_vr(@tags[i])
+        name, vr = LIBRARY.name_and_vr(@tags[i])
         names << name
         types << vr
         tag_lengths[i] = @tags[i].length
@@ -352,12 +328,8 @@ module DICOM
 
     # Removes a tag from the list of tags that will be anonymized.
     #
-    # === Parameters
-    #
-    # * <tt>tag</tt> -- String. A data element tag.
-    #
-    # === Examples
-    #
+    # @param [String] tag a data element tag
+    # @example Do not anonymize the Patient's Name tag
     #   a.remove_tag("0010,0010")
     #
     def remove_tag(tag)
@@ -370,15 +342,11 @@ 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
-    #
+    # @param [String] tag a data element tag
+    # @example Completely delete the Patient's Name tag from the DICOM files
     #   a.delete_tag("0010,0010")
     #
     def delete_tag(tag)
@@ -390,19 +358,12 @@ module DICOM
     # 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.
     #
-    # === Parameters
-    #
-    # * <tt>tag</tt> -- String. A data element tag.
-    # * <tt>options</tt> -- A hash of parameters.
-    #
-    # === Options
-    #
-    # * <tt>:value</tt> -- The replacement value to be used when anonymizing this data element. Defaults to the pre-existing value and "" for new tags.
-    # * <tt>:enum</tt> -- Boolean. Specifies if enumeration is to be used for this tag. Defaults to the pre-existing value and false for new tags.
-    #
-    # === Examples
-    #
-    #   a.set_tag("0010,0010, :value => "MrAnonymous", :enum => true)
+    # @param [String] tag a data element tag
+    # @param [Hash] options the anonymization settings for the specified tag
+    # @option options [String, Integer, Float] :value the replacement value to be used when anonymizing this data element. Defaults to the pre-existing value and "" for new tags.
+    # @option options [String, Integer, Float] :enum specifies if enumeration is to be used for this tag. Defaults to the pre-existing value and false for new tags.
+    # @example Set the anonymization settings of the Patient's Name tag
+    #   a.set_tag("0010,0010", :value => "MrAnonymous", :enum => true)
     #
     def set_tag(tag, options={})
       raise ArgumentError, "Expected String, got #{tag.class}." unless tag.is_a?(String)
@@ -415,19 +376,18 @@ module DICOM
       else
         # Add new elements:
         @tags << tag
-        @values << (options[:value] ? options[:value] : "")
+        @values << (options[:value] ? options[:value] : default_value(tag))
         @enumerations << (options[:enum] ? options[:enum] : false)
       end
     end
 
-    # Returns the value which will be used when anonymizing this tag.
-    # If enumeration is selected for the particular tag, a number will be
-    # appended in addition to the string that is returned here.
-    # Returns nil if no match is found for the provided tag.
+    # Gives the value which will be used when anonymizing this tag.
     #
-    # === Parameters
+    # @note If enumeration is selected for a string type tag, a number will be
+    #   appended in addition to the string that is returned here.
     #
-    # * <tt>tag</tt> -- String. A data element tag.
+    # @param [String] tag a data element tag
+    # @return [String, Integer, Float, NilClass] the replacement value for the specified tag, or nil if the tag is not matched
     #
     def value(tag)
       raise ArgumentError, "Expected String, got #{tag.class}." unless tag.is_a?(String)
@@ -442,18 +402,15 @@ module DICOM
     end
 
 
-    # The following methods are private:
     private
 
 
     # Finds the common path (if any) in the instance file path array, by performing a recursive search
     # on the folders that make up the path of one such file.
-    # Returns the index of the last folder in the path of the selected file that is common for all file paths.
-    #
-    # === Parameters
     #
-    # * <tt>str_arr</tt> -- An array of folder strings from the path of a select file.
-    # * <tt>index</tt> -- Fixnum. The index of the folder in str_arr to check against all file paths.
+    # @param [Array<String>] str_arr an array of folder strings from the path of a select file
+    # @param [Fixnum] index the index of the folder in str_arr to check against all file paths
+    # @return [Fixnum] the index of the last folder in the path of the selected file that is common for all file paths
     #
     def common_path(str_arr, index=0)
       common_folders = Array.new
@@ -482,16 +439,31 @@ module DICOM
       end
     end
 
+    # Determines a default value to use for anonymizing the given tag.
+    #
+    # @param [String] tag a data element tag
+    # @return [String, Integer, Float] the default replacement value for a given tag
+    #
+    def default_value(tag)
+      name, vr = LIBRARY.name_and_vr(tag)
+      conversion = VALUE_CONVERSION[vr] || :to_s
+      case conversion
+      when :to_i then return 0
+      when :to_f then return 0.0
+      else
+        # Assume type is string and return an empty string:
+        return ""
+      end
+    end
+
     # 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>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.
+    # @param [String, Integer, Float] original the original value of the tag to be anonymized
+    # @param [Fixnum] j the index of this tag in the tag-related instance arrays
+    # @return [String, Integer, Float] the replacement value which is used for the anonymization of the tag
     #
     def enumerated_value(original, j)
       # Is enumeration requested for this tag?
@@ -503,7 +475,11 @@ module DICOM
             # 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
+            if @values[j].is_a?(String)
+              replacement = @values[j] + index.to_s
+            else
+              replacement = @values[j] + index
+            end
             # Add this tag record to the audit trail:
             @audit_trail.add_record(@tags[j], original, replacement)
           end
@@ -558,8 +534,8 @@ module DICOM
     end
 
     # Analyzes the write_path and the 'read' file path to determine if they have some common root.
-    # If there are parts of the file path that exists also in the write path, the common parts will not be added to the write_path.
-    # The processed paths are put in a write_path instance array.
+    # If there are parts of the file path that exists also in the write path, the common parts will
+    # not be added to the write_path. The processed paths are put in a write_path instance array.
     #
     def process_write_paths
       # First make sure @write_path ends with a file separator character:
@@ -594,13 +570,10 @@ module DICOM
 
     # 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.
-    #
+    # @note Empty UIDs are ignored (we don't generate new UIDs for these).
+    # @note 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.
+    # @param [DObject] dcm the dicom object to be processed
     #
     def replace_uids(dcm)
       @uids.each_pair do |tag, prefix|
@@ -641,28 +614,27 @@ module DICOM
       # 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
-      ["0008,0020", "20000101", false], # Study Date
-      ["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
-      ["0008,1070", "Operator", true], # Operator's Name
-      ["0010,0010", "Patient", true], # Patient's name
-      ["0010,0020", "ID", true], # Patient's ID
-      ["0010,0030", "20000101", false], # Patient's Birth Date
-      ["0010,0040", "N", false], # Patient's Sex
-      ["0020,4000", "", false], # Image Comments
+        ["0008,0012", "20000101", false], # Instance Creation Date
+        ["0008,0013", "000000.00", false], # Instance Creation Time
+        ["0008,0020", "20000101", false], # Study Date
+        ["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
+        ["0008,1070", "Operator", true], # Operator's Name
+        ["0010,0010", "Patient", true], # Patient's name
+        ["0010,0020", "ID", true], # Patient's ID
+        ["0010,0030", "20000101", false], # Patient's Birth Date
+        ["0010,0040", "N", false], # Patient's Sex
+        ["0020,4000", "", false], # Image Comments
       ].transpose
       @tags = data[0]
       @values = data[1]
       @enumerations = data[2]
-      
-      # Tags to be deleted completely during anonymization
+      # Tags to be deleted completely during anonymization:
       @delete_tags = [
       ]
     end
@@ -670,6 +642,9 @@ module DICOM
     # Writes an identity file, which allows reidentification of DICOM files that have been anonymized
     # using the enumeration feature. Values are saved in a text file, using semi colon delineation.
     #
+    # @deprecated The identity file feature is deprecated!
+    #   Please use the AuditTrail feature instead.
+    #
     def write_identity_file
       raise ArgumentError, "Expected String, got #{@identity_file.class}. Unable to write identity file." unless @identity_file.is_a?(String)
       # Open file and prepare to write text: