dicom 0.7 → 0.8

data/CHANGELOG

@@ -1,3 +1,58 @@
+= 0.8
+
+=== 1st August, 2010
+
+* Overall changes:
+   * A complete rewrite of data element handling has resulted in a substantially different syntax and significantly cleaner and simpler code.
+   * Greatly increased speed in DICOM object interaction. Especially noticeable on larger DICOM files.
+   * A complete overhaul of the documentation has resulted in a consistent RDoc-style documentation across all classes/modules.
+   * Increased use of module constants for improved code readability.
+   * Major cleanup of codes and comments to make it consistent with Ruby 'best practice' guidelines.
+   * Ready for Rails 3 (compatible with Bundler).
+* Resulting from the rewrite is a number of new classes and modules for handling the various data objects:
+   * DataElement: Ordinary data elements are instances of this class.
+   * Item: Item elements are instances of this class.
+   * Sequence: Sequence elements are instances of this class.
+   * SuperItem: Methods which are shared between DObject and Item (mostly image related methods).
+   * SuperParent: Methods which are shared between all parent objects (DObject, Item & Sequence).
+   * Elements: A mix-in module used by all element objects (DataElement, Item & Sequence).
+* DObject:
+   * Completely rewritten data element handling.
+   * Rewritten print() method with improved tree structure visualization, item indices and the ability to run on any parent element.
+   * Renamed the print_properties() method to information(), and improved the amount of information outputted.
+   * Removed the following methods: get_frames(), get_image_pos(), get_pos(), get_value(), get_bin(), set_value()
+   * Renamed get_pixels() method to decode_pixels().
+   * Replaced get_value() with value(). The set_value() method is replaced by the new() methods of DataElement, Sequence and Item classes.
+   * Added the ability to add items at a specific index (shifting any existing items to appear after the inserted item).
+   * Added the transfer_syntax=() method for changing the transfer syntax of a DICOM object.
+   * Implemented a more robust padding of data element values with odd length, based on data element VR.
+   * Added methods for removing all sequences, removing selected groups and returning all data elements of a selected group.
+   * Optimized the get_image_narray() method to more efficiently return the pixel data.
+   * Refined the print_all convenience method to call both print() and information().
+* DRead:
+   * More robust against crashing when parsing invalid files by proper use of exception handling.
+   * Fixed some cases where a failed read where incorrectly marked as successful.
+   * Increased compatibility (handles DICOM files saved with explicit syntax but no transfer syntax tag).
+   * Explicit DICOM files with data elements of type "OF" are now handled correctly (both read and write).
+* DWrite:
+   * Simplified code and execution by removing group lengths (deprecated in the DICOM standard) and using undefined length for sequences/items.
+   * More flexible insertion of missing meta group elements.
+* Dictionary:
+   * Some minor text corrections.
+* Anonymizer:
+   * Anonymizations executes much faster thanks to the work done with DObject data element handling.
+   * Only top level data elements can be anonymized.
+* DClient:
+   * Can transmit multiple DICOM files at once with the send() method, which now will accept both DObjects and file strings.
+   * Added the echo() method for performing a C-ECHO-RQ against a SCP.
+* DServer:
+   * Support for role negotiation.
+   * Properly returns called AE title in association response.
+   * The lists of acceptable abstract and transfer syntax can now be easily modified by the user.
+   * Receiving multiple files (like an entire series, or study) in a single association is now supported.
+   * Properly receives and responds to a C-ECHO-RQ.
+
+
 = 0.7
 
 === 28th February, 2010

data/README

@@ -1,48 +1,70 @@
-RUBY DICOM
+RUBY-DICOM
 ======================
 
 SUMMARY
 --------
 
-This is a small and simple library for handling DICOM in Ruby. DICOM (Digital Imaging
+Ruby-DICOM is a small and simple library for handling DICOM in Ruby. DICOM (Digital Imaging
 and Communications in Medicine) is a standard for handling, storing, printing,
 and transmitting information in medical imaging. It includes a file format definition
-and a network communications protocol. Ruby DICOM supports reading from, editing and
-writing to this file format. It also features experimental support for network
-communication modalities like query, move, sending and receiving files.
+and a network communications protocol. Ruby-DICOM supports reading from, editing
+and writing to this file format. It also features basic support for select network
+communication modalities like querying, moving, sending and receiving files.
+
+
+INSTALLATION
+------------
+
+gem install dicom
+
 
 BASIC USAGE
 -----------
 
 require "dicom"
 # Read file:
-dcm = DICOM::DObject.new("myFile.dcm")
+obj = DICOM::DObject.new("some_file.dcm")
 # Display some key information about the file:
-dcm.print_properties()
-# Print all tags to screen:
-dcm.print(true)
+obj.information
+# Print all data elements to screen:
+obj.print
 # Retrieve a data element value:
-name = dcm.get_value("0010.0010")
-# Retrieve pixel data:
-pixels = dcm.get_value("7FE0.0010")
-# Load pixel data to a RMagick object and display it on screen:
-image = dcm.get_image_magick()
-image[0].display
-# Load pixel data to a NArray object and display it on screen:
-image = dcm.get_image_narray()
-NImage.show image[0,true,true]
+name = obj.value("0010.0010")
+# Modify the data element's value:
+obj["0010.0010"].value = "Anonymous"
+# Remove a data element from the DICOM object:
+obj.remove("7FE0,0010")
+# Retrieve the pixel data in a Ruby Array:
+pixels = obj.get_image
+# Load the pixel data to a RMagick image object and display it on the screen:
+image = obj.get_image_magick
+image.display
+# Load the pixel data to a NArray object and display it on screen (using NImage):
+pixel_data = obj.get_image_narray
+NImage.show pixel_data[0,true,true]
 # Send a local file to a server (PACS) over the network:
 node = DICOM::DClient.new("10.1.25.200", 104)
-node.send("myFile.dcm")
-
-Tip:
-When playing around with Ruby DICOM in irb, you may be annoyed
-with all the information that is printed to screen, regardless
-if you have specified verbose as false. This is because in irb
-every variable loaded in the program is automatically printed.
-A hack to avoid this effect is to append ";0" after a command.
+node.send("some_file.dcm")
+
+IRB:
+When working with Ruby DICOM in irb, you may be annoyed with all the information
+that is printed to screen, regardless if you have set verbose as false. This is because
+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:
-dcm = DICOM::DObject.new("myFile.dcm") ;0
+obj = DICOM::DObject.new("some_file.dcm") ;0
+
+
+RESOURCES
+---------
+
+Official home page:
+http://dicom.rubyforge.org/
+Discussion forum:
+http://groups.google.no/group/ruby-dicom
+Source code repository:
+http://github.com/cuthbert/ruby-dicom
+
 
 COPYRIGHT
 ---------
@@ -73,6 +95,6 @@ Location:
 Oslo, Norway
 
 Email:
-chris.lervag [@nospam] @gmail.com
-Please don't hesitate to email me if have any thoughts about this project!
+chris.lervag [@nospam.com] @gmail.com
+Please don't hesitate to email me if you have any thoughts about this project!
 

data/init.rb

@@ -0,0 +1 @@
+require 'dicom'

data/lib/dicom.rb

@@ -1,25 +1,39 @@
+# 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.
+# * DataElement, Sequence, Item, SuperParent, Elements - users who wish to interact with their DICOM objects will use these classes/modules.
+# * SuperItem - 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.
+
 # Core library:
-require 'dicom/DClient'
-require 'dicom/Dictionary'
-require 'dicom/DLibrary'
-require 'dicom/DObject'
-require 'dicom/DRead'
-require 'dicom/DServer'
-require 'dicom/DWrite'
-require 'dicom/FileHandler'
-require 'dicom/Link'
-require 'dicom/Stream'
-# Extended library:
-require 'dicom/Anonymizer'
+# Super classes/modules:
+require 'dicom/super_parent'
+require 'dicom/super_item'
+require 'dicom/elements'
+# Subclasses and independent classes:
+require 'dicom/data_element'
+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/file_handler'
+require 'dicom/item'
+require 'dicom/link'
+require 'dicom/sequence'
+require 'dicom/stream'
 # Extensions to the Ruby library:
 require 'dicom/ruby_extensions'
+# Module constants:
+require 'dicom/constants'
 
-# Ruby DICOM version string:
-DICOM::VERSION = "0.7"
-
-# Load the DICOM Library class (dictionary):
-DICOM::LIBRARY =  DICOM::DLibrary.new
-
-# Ruby DICOM implementation name and uid:
-DICOM::NAME = "RUBY_DICOM_" + DICOM::VERSION
-DICOM::UID = "1.2.826.0.1.3680043.8.641"
+# Extensions (non-core functionality):
+require 'dicom/anonymizer'

data/lib/dicom/{Anonymizer.rb → anonymizer.rb}

@@ -2,26 +2,39 @@
 
 module DICOM
 
-  # Class for anonymizing DICOM files:
-  # A good resource on this topic (report from the DICOM standards committee, work group 18):
-  # ftp://medical.nema.org/medical/dicom/Supps/sup142_03.pdf
+  # This is a convenience class for handling anonymization 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)
+  #
   class Anonymizer
 
-    attr_accessor :blank, :enumeration, :identity_file, :remove_private, :verbose, :write_path
-
-    # Initialize the Anonymizer instance:
-    def initialize(opts={})
-      # Default verbosity is true: # NB: verbosity is not used currently
-      @verbose = opts[:verbose]
-      @verbose = true if @verbose == nil
+    # 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 boolean, which if enumeration has been selected, can be set as true to make the anonymization produce an identity file that will provide a relationship between original and anonymized values.
+    attr_accessor :identity_file
+    # A boolean that if set as true, will make the anonymization remove all private tags.
+    attr_accessor :remove_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
+
+    # Creates an Anonymizer instance.
+    #
+    # === Examples
+    #
+    #   a = Anonymizer.new
+    #
+    def initialize
       # Default value of accessors:
-      # Replace all values with a blank string?
       @blank = false
-      # Enumerate selected replacement values?
       @enumeration = false
-      # All private tags may be removed if desired:
+      @identity_file = nil
       @remove_private = false
-      # A separate path may be selected for writing the anonymized files:
       @write_path = nil
       # Array of folders to be processed for anonymization:
       @folders = Array.new
@@ -33,9 +46,9 @@ module DICOM
       @values = Array.new
       # Which data elements will have enumeration applied, if requested by the user:
       @enum = Array.new
-      # We use a hash to store information from DICOM files if enumeration is desired:
-      @enum_old_hash = {}
-      @enum_new_hash = {}
+      # We use a Hash to store information from DICOM files if enumeration is desired:
+      @enum_old_hash = Hash.new
+      @enum_new_hash = Hash.new
       # All the files to be anonymized will be put in this array:
       @files = Array.new
       # Write paths will be determined later and put in this array:
@@ -44,14 +57,16 @@ module DICOM
       set_defaults
     end
 
-
-    # Adds a folder who's files will be anonymized:
-    def add_folder(path)
-      @folders << path if path
-    end
-
-
-    # Adds an exception folder that is to be avoided when anonymizing:
+    # Adds an exception folder which will be avoided when anonymizing.
+    #
+    # === Parameters
+    #
+    # * <tt>path</tt> -- String. A path that will be avoided.
+    #
+    # === Examples
+    #
+    #   a.add_exception("/home/dicom/tutorials/")
+    #
     def add_exception(path)
       if path
         # Remove last character if the path ends with a file separator:
@@ -60,12 +75,40 @@ module DICOM
       end
     end
 
+    # Adds a folder who's files will be anonymized.
+    #
+    # === Parameters
+    #
+    # * <tt>path</tt> -- String. A path that will be included in the anonymization.
+    #
+    # === Examples
+    #
+    #   a.add_folder("/home/dicom")
+    #
+    def add_folder(path)
+      @folders << path if path
+    end
 
-    # Adds a tag to the list of tags that will be anonymized:
-    def add_tag(tag, opts={})
+    # Adds a tag to the list of tags that will be anonymized.
+    #
+    # === Parameters
+    #
+    # * <tt>tag</tt> -- String. A data element tag.
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:value</tt> -- A replacement value to use for when anonymizing this data element.
+    # * <tt>:enum</tt> -- Boolean. Specifies if enumeration is to be used for this tag (true) or not (false).
+    #
+    # === Examples
+    #
+    #   a.add_tag("0010,0010, :value => "MrAnonymous", :enum => true)
+    #
+    def add_tag(tag, options={})
       # Options and defaults:
-      value =  opts[:value]  || ""
-      enum =  opts[:enum]  || false
+      value =  options[:value]  || ""
+      enum =  options[:enum]  || false
       if tag
         if tag.is_a?(String)
           if tag.length == 9
@@ -84,8 +127,13 @@ module DICOM
       end
     end
 
-
-    # Set enumeration status for a specific tag (toggle true/false)
+    # Sets the enumeration status for a specific tag.
+    #
+    # === Parameters
+    #
+    # * <tt>tag</tt> -- String. A data element tag.
+    # * <tt>enum</tt> -- Boolean. True to enable enumeration, false to disable it.
+    #
     def change_enum(tag, enum)
       pos = @tags.index(tag)
       if pos
@@ -99,8 +147,17 @@ module DICOM
       end
     end
 
-
-    # Changes the value used in anonymization for a specific tag:
+    # Changes the value to be used in the anonymization of a specific tag.
+    #
+    # === Parameters
+    #
+    # * <tt>tag</tt> -- String. A data element tag.
+    # * <tt>value</tt> -- The new anonymization replacement value for this data element.
+    #
+    # === Examples
+    #
+    #   a.change_value("0008,0090", "Dr.No")
+    #
     def change_value(tag, value)
       pos = @tags.index(tag)
       if pos
@@ -114,8 +171,21 @@ module DICOM
       end
     end
 
-
-    # Executes the anonymization process:
+    # Executes the anonymization process.
+    #
+    # This method is run when all settings have been finalized for the Anonymization instance.
+    #
+    # === Restrictions
+    #
+    # * Only top level data elements are anonymized!
+    #
+    # === Parameters
+    #
+    # * <tt>verbose</tt> -- Boolean. If set as true, verbose behaviour will be set for the DObject instances that are anonymized. Defaults to false.
+    #
+    #--
+    # FIXME: This method has grown a bit lengthy. Perhaps it should be looked at one day.
+    #
     def execute(verbose=false)
       # Search through the folders to gather all the files to be anonymized:
       puts "*******************************************************"
@@ -153,24 +223,28 @@ module DICOM
             if obj.read_success
               # Anonymize the desired tags:
               @tags.each_index do |j|
-                positions = obj.get_pos(@tags[j])
-                positions.each do |pos|
-                  if @blank
-                    value = ""
-                  elsif @enumeration
-                    old_value = obj.get_value(pos, :silent => true)
-                    # Only launch enumeration logic if tag exists:
-                    if old_value
-                      value = get_enumeration_value(old_value, j)
-                    else
+                if obj.exists?(@tags[j])
+                  element = obj[@tags[j]]
+                  if element.is_a?(DataElement)
+                    if @blank
                       value = ""
+                    elsif @enumeration
+                      old_value = element.value
+                      # Only launch enumeration logic if tag exists:
+                      if old_value
+                        value = get_enumeration_value(old_value, j)
+                      else
+                        value = ""
+                      end
+                    else
+                      # Value is simply value in array:
+                      value = @values[j]
                     end
-                  else
-                    # Value is simply value in array:
-                    value = @values[j]
+                    element.value = value
+                  elsif element.is_a?(Item)
+                    # Possibly a binary data item:
+                    element.bin = ""
                   end
-                  # Update DICOM object with new value:
-                  obj.set_value(value, pos, :create => false, :silent => true)
                 end
               end
               # Remove private tags?
@@ -215,11 +289,11 @@ module DICOM
         puts "No files were found in specified folders. Aborting."
       end
       puts "*******************************************************"
-    end # of method execute
-
+    end
 
-    # Prints a list of which tags are currently selected for anonymization along with
-    # replacement values that will be used and enumeration status.
+    # 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.
+    #
     def print
       # Extract the string lengths which are needed to make the formatting nice:
       names = Array.new
@@ -229,9 +303,9 @@ module DICOM
       type_lengths = Array.new
       value_lengths = Array.new
       @tags.each_index do |i|
-        arr = LIBRARY.get_name_vr(@tags[i])
-        names << arr[0]
-        types << arr[1]
+        name, vr = LIBRARY.get_name_vr(@tags[i])
+        names << name
+        types << vr
         tag_lengths[i] = @tags[i].length
         name_lengths[i] = names[i].length
         type_lengths[i] = types[i].length
@@ -272,8 +346,16 @@ module DICOM
       end
     end
 
-
-    # Removes a tag from the list of tags that will be anonymized:
+    # Removes a tag from the list of tags that will be anonymized.
+    #
+    # === Parameters
+    #
+    # * <tt>tag</tt> -- String. A data element tag.
+    #
+    # === Examples
+    #
+    #   a.remove_tag("0010,0010")
+    #
     def remove_tag(tag)
       pos = @tags.index(tag)
       if pos
@@ -290,9 +372,16 @@ module DICOM
     private
 
 
-    # Finds the common path in an array of files, by performing a recursive search.
-    # Returns the index of the last folder in str_arr that is common in all file paths.
-    def common_path(str_arr, index)
+    # 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.
+    #
+    def common_path(str_arr, index=0)
       common_folders = Array.new
       # Find out how much of the path is similar for all files in @files array:
       folder = str_arr[index]
@@ -310,8 +399,8 @@ module DICOM
       return result
     end
 
-
-    # Creates a hash that is used for storing information used when enumeration is desired.
+    # Creates a hash that is used for storing information that is used when enumeration is selected.
+    #
     def create_enum_hash
       @enum.each_index do |i|
         @enum_old_hash[@tags[i]] = Array.new
@@ -319,8 +408,16 @@ module DICOM
       end
     end
 
-
-    # Handles enumeration for current DICOM tag:
+    # 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.
+    #
+    # === Parameters
+    #
+    # * <tt>current</tt> -- The original value of the tag that are about to be anonymized.
+    # * <tt>j</tt> -- Fixnum. The index of this tag in the tag-related instance arrays.
+    #
     def get_enumeration_value(current, j)
       # Is enumeration requested for this tag?
       if @enum[j]
@@ -346,8 +443,9 @@ module DICOM
       return value
     end
 
-
-    # Discover all the files contained in the specified directory and all its sub-directories:
+    # Discovers all the files contained in the specified directory (all its sub-directories),
+    # and adds these files to the instance file array.
+    #
     def load_files
       # Load find library:
       require 'find'
@@ -371,16 +469,16 @@ module DICOM
       end
     end
 
-
-    # Analyses the write_path and the 'read' file path to determine if the have some common root.
-    # If there are parts of file that exist also in write path, it will not add those parts to write_path.
+    # 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.
+    #
     def process_write_paths
       # First make sure @write_path ends with a file separator character:
       last_character = @write_path[-1..-1]
       @write_path = @write_path + File::SEPARATOR unless last_character == File::SEPARATOR
       # Differing behaviour if we have one, or several files in our array:
       if @files.length == 1
-        # One file.
         # Write path is requested write path + old file name:
         str_arr = @files[0].split(File::SEPARATOR)
         @write_paths << @write_path + str_arr.last
@@ -389,7 +487,7 @@ module DICOM
         # Find out how much of the path they have in common, remove that and
         # add the remaining to the @write_path:
         str_arr = @files[0].split(File::SEPARATOR)
-        last_match_index = common_path(str_arr, 0)
+        last_match_index = common_path(str_arr)
         if last_match_index >= 0
           # Remove the matching folders from the path that will be added to @write_path:
           @files.each do |file|
@@ -406,8 +504,9 @@ module DICOM
       end
     end
 
-
-    # Default tags that will be anonymized, along with default replacement value and enumeration setting.
+    # 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.
+    #
     def set_defaults
       data = [
       ["0008,0012", "20000101", false], # Instance Creation Date
@@ -431,9 +530,9 @@ module DICOM
       @enum = data[2]
     end
 
-
     # Writes an identity file, which allows reidentification of DICOM files that have been anonymized
-    # using the enumeration feature. Values will be saved in a text file, using semi colon delineation.
+    # using the enumeration feature. Values are saved in a text file, using semi colon delineation.
+    #
     def write_identity_file
       # Open file and prepare to write text:
       File.open( @identity_file, 'w' ) do |output|
@@ -455,6 +554,5 @@ module DICOM
       end
     end
 
-
-  end # of class
-end # of module
+  end
+end