dicom 0.8 → 0.9

data/{CHANGELOG → CHANGELOG.rdoc}

@@ -1,56 +1,114 @@
+= 0.9
+
+=== 17th May, 2011
+
+* Fixed an issue where data elements added to a DObject didn't get their endianness updated.
+* Added the ability to encode/decode 32 bit pixel data.
+* Added the ability to encode/decode big endian signed integers.
+* Added the remove_children() method to parent elements.
+* Added the ability to decode color images.
+* Added the ability to retrieve multiple pixel frames as image objects.
+* Added a :level option to the image retrieval methods which accepts custom window center/width values.
+* Renamed the :rescale option to :remap in the image retrieval methods.
+* Added the ability to decode RLE and JPEG Baseline compressed images.
+* Added a specification test suite (using rspec and mocha).
+* Implemented proper handling of data element values with VR "AT" (tag references).
+* Changed the specification for Item indices (now starts at 0).
+* Introduced the concept of ImageProcessors to replace the previously integrated RMagick image methods:
+  * The user can select which ImageProcessor to be used at run-time.
+  * Initially supported ImageProcessors: RMagick and mini_magick.
+  * Additional ImageProcessors can easily be added using existing template.
+  * Major refactoring and simplification of all image related code.
+* Some changes of the Anonymizer class:
+  * Added a :verbose option.
+  * Added enum(), set_tag() and value() methods.
+  * Removed add_tag, change_enum() and change_value() methods.
+  * Added a log attribute.
+* Fixed an issue where using a transfer syntax option with a binary string did not result in a correct application of the supplied syntax.
+* Added a .dcm extension to DICOM files received by DServer.
+* Fixed an issue where sending DICOM files with compressed pixel data resulted in an invalid DICOM transfer.
+* Changed the specification to allow the query methods of DClient to accept any tag as a query parameter.
+* Improved the handling of parent-child relations so these are always properly updated when adding, removing or changing parent elements.
+* Renamed the following classes/modules:
+  * SuperParent -> Parent
+  * SuperItem -> ImageItem
+  * DataElement -> Element
+  * Elements -> Elemental
+* Replaced ImageItem#image_properties() with num_cols(), num_rows() and num_frames().
+* Renamed the following ImageItem methods:
+  * get_image_magick() -> image()
+  * get_images_magick() -> images()
+  * set_image_magick() -> image=()
+  * get_image() -> pixels
+  * get_image_narray -> narray
+  * set_image -> pixels=()
+  * set_image_narray -> pixels=()
+* Added the following conversion methods to DObject, Sequence, Item & Element:
+  * inspect()
+  * to_hash()
+  * to_json()
+  * to_yaml()
+* Added the ability to use DICOM element names as methods for creating, editing and deleting elements.
+* Added the ability to read a DICOM file from a http string, using open-uri (experimental).
+* Added alias_methods read? for read_success and written? for write_success in DObject.
+* Renamed DObject#information() to summary().
+* Added various ArgumentError exceptions to facility easier debugging.
+* Various bug fixes.
+
+
 = 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).
+  * 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).
+  * 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().
+  * 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).
+  * 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.
+  * 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.
+  * 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.
+  * 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.
+  * 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.
+  * 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
@@ -102,7 +160,7 @@
 
 * Complete rewrite of encoding/decoding to reduce code duplication and simplify the code.
 * General optimizations to improve speed and reduce code complexity.
-* Rewrote Dictionary to use Hash instead of Array. This has significantly improved the read spead of the library.
+* Rewrote Dictionary to use Hash instead of Array. This has significantly improved the read speed of the library.
 * Ruby DICOM now automatically strips away trailing whitespace when decoding string values.
 * Introducing basic, experimental network functionality.
 * The new DClient class enables features such as query, move and send.
@@ -188,14 +246,4 @@
 First public release.
 The library does have several known issues and lacks some features I would like it to have, but it does
 offer basic functionality and should be usable for people interested in working with DICOM files in Ruby.
-The reading algorithm has been tested succesfully with some 40 different DICOM files, so it should be fairly robust.
-
-
-Known issues:
-* The retrieve file network functionality (get_image() in DClient class) has not been tested.
-* Compressed pixel data is poorly handled.
-* Read/Write 12 bit image data not available.
-* Color image data is poorly handled.
-* Incomplete support for Big endian (Everything but signed short and signed long has been implemented).
-* Incomplete support for multiple frame image data to NArray and RMagick objects (partial support already featured).
-* Image handling does not take into consideration DICOM tags which specify orientation, samples per pixel and photometric interpretation.
+The reading algorithm has been tested successfully with some 40 different DICOM files, so it should be fairly robust.

data/README.rdoc

@@ -0,0 +1,126 @@
+= RUBY DICOM
+
+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 basic support for select network
+communication modalities like querying, moving, sending and receiving files.
+
+
+== INSTALLATION
+
+  gem install dicom
+
+
+== BASIC USAGE
+
+=== Load & Include
+
+  require 'dicom'
+  include DICOM
+
+=== Read, modify and write
+
+  # Read file:
+  obj = DObject.new("some_file.dcm")
+  # Extract the Patient's Name value:
+  obj.patients_name.value
+  # Add or modify the Patient's Name element:
+  obj.patients_name = "Anonymous"
+  # Remove a data element from the DICOM object:
+  obj.pixel_data = nil
+  # Write to file:
+  obj.write("new_file.dcm")
+
+=== Modify using tag strings instead of dictionary method names
+
+  # Extract the Patient's Name value:
+  obj.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")
+
+=== Extracting information about the DICOM object
+
+  # Display a short summary of the file's properties:
+  obj.summary
+  # Print all data elements to screen:
+  obj.print
+  # Convert the data element hierarchy to a nested hash:
+  obj.to_hash
+
+=== Handle pixel data
+
+  # Retrieve the pixel data in a Ruby Array:
+  obj.pixels
+  # Load the pixel data to an numerical array (NArray):
+  obj.narray
+  # Load the pixel data to an RMagick image object and display it on the screen:
+  obj.image.display
+
+=== Transmit a DICOM file
+
+  # Send a local file to a server (PACS) over the network:
+  node = DClient.new("10.1.25.200", 104)
+  node.send("some_file.dcm")
+
+=== Start a DICOM server
+
+  # Initiate a simple storage provider which can receive DICOM files of all modalities:
+  s = DServer.new(104, :host_ae => "MY_DICOM_SERVER")
+  s.start_scp("C:/temp/")
+
+=== IRB Tip
+
+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:
+  obj = DObject.new("some_file.dcm") ;0
+
+
+== RESOURCES
+
+* {Official home page}[http://dicom.rubyforge.org/]
+* {Discussion forum}[http://groups.google.com/group/ruby-dicom]
+* {Source code repository}[https://github.com/dicom/ruby-dicom]
+
+
+== COPYRIGHT
+
+Copyright 2008-2011 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
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see http://www.gnu.org/licenses/ .
+
+
+== ABOUT THE AUTHOR
+
+* Name: Christoffer Lervåg
+* Location: Norway
+* Email: chris.lervag [@nospam.com] @gmail.com
+
+Please don't hesitate to email me if you have any feedback related to this project!
+
+
+== CONTRIBUTORS
+
+* {Christoffer Lervåg}[https://github.com/dicom]
+* {John Axel Eriksson}[https://github.com/johnae]
+* {Donnie Millar}[https://github.com/dmillar]
+* Björn Albers
+* {Lars Benner}[https://github.com/Maturin]
+* {Steven Bedrick}[https://github.com/stevenbedrick]

data/lib/dicom.rb

@@ -2,8 +2,8 @@
 #
 # 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.
+# * 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.
@@ -13,11 +13,11 @@
 
 # Core library:
 # Super classes/modules:
-require 'dicom/super_parent'
-require 'dicom/super_item'
-require 'dicom/elements'
+require 'dicom/image_processor'
+require 'dicom/parent'
+require 'dicom/image_item'
+require 'dicom/elemental'
 # Subclasses and independent classes:
-require 'dicom/data_element'
 require 'dicom/d_client'
 require 'dicom/dictionary'
 require 'dicom/d_library'
@@ -25,6 +25,7 @@ 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'
@@ -32,8 +33,13 @@ require 'dicom/sequence'
 require 'dicom/stream'
 # Extensions to the Ruby library:
 require 'dicom/ruby_extensions'
-# Module constants:
+# Module settings:
+require 'dicom/version'
 require 'dicom/constants'
+require 'dicom/variables'
+# Image processors:
+require 'dicom/image_processor_mini_magick'
+require 'dicom/image_processor_r_magick'
 
 # Extensions (non-core functionality):
 require 'dicom/anonymizer'

data/lib/dicom/anonymizer.rb

@@ -1,4 +1,3 @@
-#    Copyright 2008-2010 Christoffer Lervag
 
 module DICOM
 
@@ -16,8 +15,10 @@ module DICOM
     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.
+    # 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 path where the anonymized files will be saved. If this value is not set, the original DICOM files will be overwritten.
@@ -25,11 +26,23 @@ module DICOM
 
     # Creates an Anonymizer instance.
     #
+    # === Parameters
+    #
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:verbose</tt> -- Boolean. If set to false, the Anonymizer instance will run silently and not output status updates to the screen. Defaults to true.
+    #
     # === Examples
     #
     #   a = Anonymizer.new
+    #   # Create an instance in non-verbose mode:
+    #   a = Anonymizer.new(:verbose => false)
     #
-    def initialize
+    def initialize(options={})
+      # Default verbosity is true if verbosity hasn't been specified (nil):
+      @verbose = (options[:verbose] == false ? false : true)
       # Default value of accessors:
       @blank = false
       @enumeration = false
@@ -45,7 +58,7 @@ module DICOM
       # Default values to use on anonymized data elements:
       @values = Array.new
       # Which data elements will have enumeration applied, if requested by the user:
-      @enum = Array.new
+      @enumerations = Array.new
       # We use a Hash to store information from DICOM files if enumeration is desired:
       @enum_old_hash = Hash.new
       @enum_new_hash = Hash.new
@@ -53,6 +66,8 @@ 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
       # Set the default data elements to be anonymized:
       set_defaults
     end
@@ -68,10 +83,11 @@ module DICOM
     #   a.add_exception("/home/dicom/tutorials/")
     #
     def add_exception(path)
+      raise ArgumentError, "Expected String, got #{path.class}." unless path.is_a?(String)
       if path
         # Remove last character if the path ends with a file separator:
         path.chop! if path[-1..-1] == File::SEPARATOR
-        @exceptions << path if path
+        @exceptions << path
       end
     end
 
@@ -86,88 +102,26 @@ module DICOM
     #   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.
-    #
-    # === 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 =  options[:value]  || ""
-      enum =  options[:enum]  || false
-      if tag
-        if tag.is_a?(String)
-          if tag.length == 9
-            # Add anonymization information for this tag:
-            @tags << tag
-            @values << value
-            @enum << enum
-          else
-            puts "Warning: Invalid tag length. Please use the form 'GGGG,EEEE'."
-          end
-        else
-          puts "Warning: Tag is not a string. Can not add tag."
-        end
-      else
-        puts "Warning: No tag supplied. Nothing to add."
-      end
-    end
-
-    # 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
-        if enum
-          @enum[pos] = true
-        else
-          @enum[pos] = false
-        end
-      else
-        puts "Specified tag not found in anonymization array. No changes made."
-      end
+      raise ArgumentError, "Expected String, got #{path.class}." unless path.is_a?(String)
+      @folders << path
     end
 
-    # Changes the value to be used in the anonymization of a specific tag.
+    # Returns the enumeration status for this tag.
+    # Returns nil if no match is found for the provided 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)
+    def enum(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?
       pos = @tags.index(tag)
       if pos
-        if value
-          @values[pos] = value
-        else
-          puts "No value were specified. No changes made."
-        end
+        return @enumerations[pos]
       else
-        puts "Specified tag not found in anonymization array. No changes made."
+        add_msg("The specified tag is not found in the list of tags to be anonymized.")
+        return nil
       end
     end
 
@@ -188,30 +142,30 @@ module DICOM
     #
     def execute(verbose=false)
       # Search through the folders to gather all the files to be anonymized:
-      puts "*******************************************************"
-      puts "Initiating anonymization process."
+      add_msg("*******************************************************")
+      add_msg("Initiating anonymization process.")
       start_time = Time.now.to_f
-      puts "Searching for files..."
+      add_msg("Searching for files...")
       load_files
-      puts "Done."
+      add_msg("Done.")
       if @files.length > 0
         if @tags.length > 0
-          puts @files.length.to_s + " files have been identified in the specified folder(s)."
+          add_msg(@files.length.to_s + " files have been identified in the specified folder(s).")
           if @write_path
             # Determine the write paths, as anonymized files will be written to a separate location:
-            puts "Processing write paths..."
+            add_msg("Processing write paths...")
             process_write_paths
-            puts "Done"
+            add_msg("Done")
           else
             # Overwriting old files:
-            puts "Separate write folder not specified. Will overwrite existing DICOM files."
+            add_msg("Separate write folder not specified. Will overwrite existing DICOM files.")
             @write_paths = @files
           end
           # If the user wants enumeration, we need to prepare variables for storing
           # existing information associated with each tag:
           create_enum_hash if @enumeration
           # Start the read/update/write process:
-          puts "Initiating read/update/write process (This may take some time)..."
+          add_msg("Initiating read/update/write process (This may take some time)...")
           # Monitor whether every file read/write was successful:
           all_read = true
           all_write = true
@@ -225,25 +179,22 @@ module DICOM
               @tags.each_index do |j|
                 if obj.exists?(@tags[j])
                   element = obj[@tags[j]]
-                  if element.is_a?(DataElement)
+                  if element.is_a?(Element)
                     if @blank
                       value = ""
                     elsif @enumeration
                       old_value = element.value
-                      # Only launch enumeration logic if tag exists:
+                      # Only launch enumeration logic if there is an actual value to the data element:
                       if old_value
                         value = get_enumeration_value(old_value, j)
                       else
                         value = ""
                       end
                     else
-                      # Value is simply value in array:
+                      # Use the value that has been set for this tag:
                       value = @values[j]
                     end
                     element.value = value
-                  elsif element.is_a?(Item)
-                    # Possibly a binary data item:
-                    element.bin = ""
                   end
                 end
               end
@@ -263,32 +214,32 @@ module DICOM
           end
           # Finished anonymizing files. Print elapsed time and status of anonymization:
           end_time = Time.now.to_f
-          puts "Anonymization process completed!"
+          add_msg("Anonymization process completed!")
           if all_read
-            puts "All files in specified folder(s) were SUCCESSFULLY read to DICOM objects."
+            add_msg("All files in specified folder(s) were SUCCESSFULLY read to DICOM objects.")
           else
-            puts "Some files were NOT successfully read (#{files_failed_read} files). If folder(s) contain non-DICOM files, this is probably the reason."
+            add_msg("Some files were NOT successfully read (#{files_failed_read} files). If folder(s) contain non-DICOM files, this is probably the reason.")
           end
           if all_write
-            puts "All DICOM objects were SUCCESSFULLY written as DICOM files (#{files_written} files)."
+            add_msg("All DICOM objects were SUCCESSFULLY written as DICOM files (#{files_written} files).")
           else
-            puts "Some DICOM objects were NOT succesfully written to file. You are advised to have a closer look (#{files_written} files succesfully written)."
+            add_msg("Some DICOM objects were NOT succesfully written to file. You are advised to have a closer look (#{files_written} files succesfully written).")
           end
           # Has user requested enumeration and specified an identity file in which to store the anonymized values?
           if @enumeration and @identity_file
-            puts "Writing identity file."
+            add_msg("Writing identity file.")
             write_identity_file
-            puts "Done"
+            add_msg("Done")
           end
           elapsed = (end_time-start_time).to_s
-          puts "Elapsed time: " + elapsed[0..elapsed.index(".")+1] + " seconds"
+          add_msg("Elapsed time: " + elapsed[0..elapsed.index(".")+1] + " seconds")
         else
-          puts "No tags have been selected for anonymization. Aborting."
+          add_msg("No tags have been selected for anonymization. Aborting.")
         end
       else
-        puts "No files were found in specified folders. Aborting."
+        add_msg("No files were found in specified folders. Aborting.")
       end
-      puts "*******************************************************"
+      add_msg("*******************************************************")
     end
 
     # Prints to screen a list of which tags are currently selected for anonymization along with
@@ -328,7 +279,7 @@ module DICOM
         f4 = " " if @blank
         f4 = " "*(value_maxL-@values[i].to_s.length+1) unless @blank
         if @enumeration
-          enum = @enum[i]
+          enum = @enumerations[i]
         else
           enum = ""
         end
@@ -357,13 +308,67 @@ module DICOM
     #   a.remove_tag("0010,0010")
     #
     def remove_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?
       pos = @tags.index(tag)
       if pos
         @tags.delete_at(pos)
         @values.delete_at(pos)
-        @enum.delete_at(pos)
+        @enumerations.delete_at(pos)
+      end
+    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.
+    #
+    # === 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)
+    #
+    def set_tag(tag, options={})
+      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?
+      pos = @tags.index(tag)
+      if pos
+        # Update existing values:
+        @values[pos] = options[:value] if options[:value]
+        @enumerations[pos] = options[:enum] if options[:enum] != nil
       else
-        puts "Specified tag not found in anonymization array. No changes made."
+        # Add new elements:
+        @tags << tag
+        @values << (options[:value] ? options[:value] : "")
+        @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.
+    #
+    # === Parameters
+    #
+    # * <tt>tag</tt> -- String. A data element tag.
+    #
+    def value(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?
+      pos = @tags.index(tag)
+      if pos
+        return @values[pos]
+      else
+        add_msg("The specified tag is not found in the list of tags to be anonymized.")
+        return nil
       end
     end
 
@@ -372,6 +377,18 @@ module DICOM
     private
 
 
+    # Adds one or more status messages to the log instance array, and if the verbose
+    # instance variable is true, the status message is printed to the screen as well.
+    #
+    # === Parameters
+    #
+    # * <tt>msg</tt> -- Status message string.
+    #
+    def add_msg(msg)
+      puts msg if @verbose
+      @log << msg
+    end
+
     # 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.
@@ -402,7 +419,7 @@ module DICOM
     # 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|
+      @enumerations.each_index do |i|
         @enum_old_hash[@tags[i]] = Array.new
         @enum_new_hash[@tags[i]] = Array.new
       end
@@ -420,7 +437,7 @@ module DICOM
     #
     def get_enumeration_value(current, j)
       # Is enumeration requested for this tag?
-      if @enum[j]
+      if @enumerations[j]
         # Retrieve earlier used anonymization values:
         previous_old = @enum_old_hash[@tags[j]]
         previous_new = @enum_new_hash[@tags[j]]
@@ -527,18 +544,19 @@ module DICOM
       ].transpose
       @tags = data[0]
       @values = data[1]
-      @enum = data[2]
+      @enumerations = data[2]
     end
 
     # 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.
     #
     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:
-      File.open( @identity_file, 'w' ) do |output|
+      File.open(@identity_file, 'w') do |output|
         # Cycle through each
         @tags.each_index do |i|
-          if @enum[i]
+          if @enumerations[i]
             # This tag has had enumeration. Gather original and anonymized values:
             old_values = @enum_old_hash[@tags[i]]
             new_values = @enum_new_hash[@tags[i]]