dicom 0.9.1 → 0.9.2

data/CHANGELOG.rdoc

@@ -1,9 +1,26 @@
+= 0.9.2
+
+=== (Not released yet)
+
+* 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:
+  * DObject#read is the new preferred method for reading a DICOM file.
+  * DObject#parse is the new preferred method for parsing an encoded DICOM string.
+  * The experimental feature of retrieving a DICOM file through http was moved to DObject#get.
+  * Calling DObject with a string argument was deprecated. 
+* Introduced proper logging capabilities which replaced the simple message printouts to STDOUT:
+  * Based on the Logger class of the Ruby Standard Library.
+  * Automatically integrates with the Rails logger in a Rails application.
+  * Supports information levels, logging to file, and more as available in the Ruby Logger.
+
+
 = 0.9.1
 
 === 27th May, 2011
 
 * Fixed a regression in 0.9 where ruby-dicom would cause a Rails application to crash.
 
+
 = 0.9
 
 === 17th May, 2011

data/README.rdoc

@@ -23,7 +23,7 @@ communication modalities like querying, moving, sending and receiving files.
 === Read, modify and write
 
   # Read file:
-  obj = DObject.new("some_file.dcm")
+  obj = DObject.read("some_file.dcm")
   # Extract the Patient's Name value:
   obj.patients_name.value
   # Add or modify the Patient's Name element:
@@ -72,6 +72,18 @@ communication modalities like querying, moving, sending and receiving files.
   s = DServer.new(104, :host_ae => "MY_DICOM_SERVER")
   s.start_scp("C:/temp/")
 
+=== Log settings
+
+  # Change the log level so that only error messages are displayed:
+  DICOM.logger.level = Logger::ERROR
+  # Setting up a simple file log:
+  l = Logger.new('my_logfile.log')
+  DICOM.logger = l
+  # Create a logger which ages logfile daily/monthly:
+  DICOM.logger = Logger.new('foo.log', 'daily')
+  DICOM.logger = Logger.new('foo.log', 'monthly')
+
+
 === IRB Tip
 
 When working with Ruby DICOM in irb, you may be annoyed with all the information
@@ -120,7 +132,8 @@ 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]
 * {Donnie Millar}[https://github.com/dmillar]
-* Björn Albers
+* {Björn Albers}[https://github.com/bjoernalbers]
 * {Lars Benner}[https://github.com/Maturin]
-* {Steven Bedrick}[https://github.com/stevenbedrick]
+* {Steven Bedrick}[https://github.com/stevenbedrick]

data/lib/dicom.rb

@@ -11,6 +11,8 @@
 # The rest of the classes visible in the documentation generated by RDoc is in principle
 # 'private' classes, which are mainly of interest to developers.
 
+# Logging:
+require 'dicom/logging'
 # Core library:
 # Super classes/modules:
 require 'dicom/image_processor'
@@ -42,4 +44,4 @@ require 'dicom/image_processor_mini_magick'
 require 'dicom/image_processor_r_magick'
 
 # Extensions (non-core functionality):
-require 'dicom/anonymizer'
+require 'dicom/anonymizer'

data/lib/dicom/anonymizer.rb

@@ -1,4 +1,3 @@
-
 module DICOM
 
   # This is a convenience class for handling anonymization of DICOM files.
@@ -10,6 +9,7 @@ module DICOM
   # (Clinical Trials De-identification Profiles, DICOM Standards Committee, Working Group 18)
   #
   class Anonymizer
+    include Logging
 
     # A boolean that if set as true will cause all anonymized tags to be blank instead of get some generic value.
     attr_accessor :blank
@@ -26,23 +26,17 @@ module DICOM
 
     # Creates an Anonymizer instance.
     #
-    # === Parameters
-    #
-    # * <tt>options</tt> -- A hash of parameters.
-    #
-    # === Options
+    # === Notes
     #
-    # * <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.
+    # * To customize logging behaviour, refer to the Logging module documentation.
     #
     # === Examples
     #
+    #   # Create an Anonymizer instance and restrict the log output:
     #   a = Anonymizer.new
-    #   # Create an instance in non-verbose mode:
-    #   a = Anonymizer.new(:verbose => false)
+    #   a.logger.level = Logger::ERROR
     #
-    def initialize(options={})
-      # Default verbosity is true if verbosity hasn't been specified (nil):
-      @verbose = (options[:verbose] == false ? false : true)
+    def initialize
       # Default value of accessors:
       @blank = false
       @enumeration = false
@@ -120,7 +114,7 @@ module DICOM
       if pos
         return @enumerations[pos]
       else
-        add_msg("The specified tag is not found in the list of tags to be anonymized.")
+        logger.warn("The specified tag (#{tag}) was not found in the list of tags to be anonymized.")
         return nil
       end
     end
@@ -133,47 +127,45 @@ module DICOM
     #
     # * 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)
+    def execute
       # Search through the folders to gather all the files to be anonymized:
-      add_msg("*******************************************************")
-      add_msg("Initiating anonymization process.")
+      logger.info("Initiating anonymization process.")
       start_time = Time.now.to_f
-      add_msg("Searching for files...")
+      logger.info("Searching for files...")
       load_files
-      add_msg("Done.")
+      logger.info("Done.")
       if @files.length > 0
         if @tags.length > 0
-          add_msg(@files.length.to_s + " files have been identified in the specified folder(s).")
+          logger.info(@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:
-            add_msg("Processing write paths...")
+            logger.info("Processing write paths...")
             process_write_paths
-            add_msg("Done")
+            logger.info("Done")
           else
             # Overwriting old files:
-            add_msg("Separate write folder not specified. Will overwrite existing DICOM files.")
+            logger.warn("Separate write folder not specified. Existing DICOM files will be overwritten.")
             @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:
-          add_msg("Initiating read/update/write process (This may take some time)...")
+          logger.info("Initiating read/update/write process. This may take some time...")
           # Monitor whether every file read/write was successful:
           all_read = true
           all_write = true
           files_written = 0
           files_failed_read = 0
+          # 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|
             # Read existing file to DICOM object:
-            obj = DICOM::DObject.new(@files[i], :verbose => verbose)
+            obj = DICOM::DObject.read(@files[i])
             if obj.read_success
               # Anonymize the desired tags:
               @tags.each_index do |j|
@@ -212,34 +204,35 @@ module DICOM
               files_failed_read += 1
             end
           end
-          # Finished anonymizing files. Print elapsed time and status of anonymization:
+          # Finished anonymizing files. Reset the logg threshold:
+          logger.level = anonymizer_level
+          # Print elapsed time and status of anonymization:
           end_time = Time.now.to_f
-          add_msg("Anonymization process completed!")
+          logger.info("Anonymization process completed!")
           if all_read
-            add_msg("All files in specified folder(s) were SUCCESSFULLY read to DICOM objects.")
+            logger.info("All files in the specified folder(s) were SUCCESSFULLY read to DICOM objects.")
           else
-            add_msg("Some files were NOT successfully read (#{files_failed_read} files). If folder(s) contain non-DICOM files, this is probably the reason.")
+            logger.warn("Some files were NOT successfully read (#{files_failed_read} files). If some folder(s) contain non-DICOM files, this is expected.")
           end
           if all_write
-            add_msg("All DICOM objects were SUCCESSFULLY written as DICOM files (#{files_written} files).")
+            logger.info("All DICOM objects were SUCCESSFULLY written as DICOM files (#{files_written} files).")
           else
-            add_msg("Some DICOM objects were NOT succesfully written to file. You are advised to have a closer look (#{files_written} files succesfully written).")
+            logger.warn("Some DICOM objects were NOT succesfully written to file. You are advised to investigate the result (#{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
-            add_msg("Writing identity file.")
+            logger.info("Writing identity file.")
             write_identity_file
-            add_msg("Done")
+            logger.info("Done")
           end
           elapsed = (end_time-start_time).to_s
-          add_msg("Elapsed time: " + elapsed[0..elapsed.index(".")+1] + " seconds")
+          logger.info("Elapsed time: #{elapsed[0..elapsed.index(".")+1]} seconds")
         else
-          add_msg("No tags have been selected for anonymization. Aborting.")
+          logger.warn("No tags were selected for anonymization. Aborting.")
         end
       else
-        add_msg("No files were found in specified folders. Aborting.")
+        logger.warn("No files were found in specified folders. Aborting.")
       end
-      add_msg("*******************************************************")
     end
 
     # Prints to screen a list of which tags are currently selected for anonymization along with
@@ -367,7 +360,7 @@ module DICOM
       if pos
         return @values[pos]
       else
-        add_msg("The specified tag is not found in the list of tags to be anonymized.")
+        logger.warn("The specified tag (#{tag}) was not found in the list of tags to be anonymized.")
         return nil
       end
     end
@@ -377,18 +370,6 @@ 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.
@@ -573,4 +554,4 @@ module DICOM
     end
 
   end
-end
+end

data/lib/dicom/d_client.rb

@@ -10,6 +10,7 @@ module DICOM
   # FIXME: The code which waits for incoming network packets seems to be very CPU intensive. Perhaps there is a more elegant way to wait for incoming messages?
   #
   class DClient
+    include Logging
 
     # The name of this client (application entity).
     attr_accessor :ae
@@ -23,19 +24,17 @@ module DICOM
     attr_accessor :port
     # The maximum period the client will wait on an answer from a server before aborting the communication.
     attr_accessor :timeout
-    # A boolean which defines if notices/warnings/errors will be printed to the screen (true) or not (false).
-    attr_accessor :verbose
     # An array, where each index contains a hash with the data elements received in a command response (with tags as keys).
     attr_reader :command_results
     # An array, where each index contains a hash with the data elements received in a data response (with tags as keys).
     attr_reader :data_results
-    # An array containing any error messages recorded.
-    attr_reader :errors
-    # An array containing any status messages recorded.
-    attr_reader :notices
 
     # Creates a DClient instance.
     #
+    # === Notes
+    #
+    # * To customize logging behaviour, refer to the Logging module documentation.
+    #
     # === Parameters
     #
     # * <tt>host_ip</tt> -- String. The IP adress of the server which you are going to communicate with.
@@ -48,7 +47,6 @@ module DICOM
     # * <tt>:host_ae</tt> -- String. The name of the server (application entity).
     # * <tt>:max_package_size</tt> -- Fixnum. The maximum allowed size of network packages (in bytes).
     # * <tt>:timeout</tt> -- Fixnum. The maximum period the server will wait on an answer from a client before aborting the communication.
-    # * <tt>:verbose</tt> -- Boolean. If set to false, the DClient instance will run silently and not output warnings and error messages to the screen. Defaults to true.
     #
     # === Examples
     #
@@ -66,11 +64,6 @@ module DICOM
       @max_package_size = options[:max_package_size] || 32768 # 16384
       @timeout = options[:timeout] || 10 # seconds
       @min_length = 12 # minimum number of bytes to expect in an incoming transmission
-      @verbose = options[:verbose]
-      @verbose = true if @verbose == nil # Default verbosity is 'on'.
-      # Other instance variables:
-      @errors = Array.new # errors and warnings are put in this array
-      @notices = Array.new # information on successful transmissions are put in this array
       # Variables used for monitoring state of transmission:
       @association = nil # DICOM Association status
       @request_approved = nil # Status of our DICOM request
@@ -396,14 +389,14 @@ module DICOM
         establish_release
       else
         # Failed when loading the specified parameter as DICOM file(s). Will not transmit.
-        add_error(message)
+        logger.error(message)
       end
     end
 
     # Tests the connection to the server in a very simple way  by negotiating an association and then releasing it.
     #
     def test
-      add_notice("TESTING CONNECTION...")
+      logger.info("TESTING CONNECTION...")
       success = false
       # Verification SOP Class:
       set_default_presentation_context(VERIFICATION_SOP)
@@ -417,9 +410,9 @@ module DICOM
         establish_release
       end
       if success
-        add_notice("TEST SUCCSESFUL!")
+        logger.info("TEST SUCCSESFUL!")
       else
-        add_error("TEST FAILED!")
+        logger.warn("TEST FAILED!")
       end
       return success
     end
@@ -429,30 +422,6 @@ module DICOM
     private
 
 
-    # Adds a warning or error message to the instance array holding messages,
-    # and prints the information to the screen if verbose is set.
-    #
-    # === Parameters
-    #
-    # * <tt>error</tt> -- A single error message or an array of error messages.
-    #
-    def add_error(error)
-      puts error if @verbose
-      @errors << error
-    end
-
-    # Adds a notice (information regarding progress or successful communications) to the instance array,
-    # and prints the information to the screen if verbose is set.
-    #
-    # === Parameters
-    #
-    # * <tt>notice</tt> -- A single status message or an array of status messages.
-    #
-    def add_notice(notice)
-      puts notice if @verbose
-      @notices << notice
-    end
-
     # Returns an array of supported transfer syntaxes for the specified transfer syntax.
     # For compressed transfer syntaxes, we currently do not support reencoding these to other syntaxes.
     #
@@ -486,11 +455,11 @@ module DICOM
           # Values of importance are extracted and put into instance variables:
           @association = true
           @max_pdu_length = info[:max_pdu_length]
-          add_notice("Association successfully negotiated with host #{@host_ae} (#{@host_ip}).")
+          logger.info("Association successfully negotiated with host #{@host_ae} (#{@host_ip}).")
           # Check if all our presentation contexts was accepted by the host:
           process_presentation_context_response(info[:pc])
         else
-          add_error("Association was denied from host #{@host_ae} (#{@host_ip})!")
+          logger.error("Association was denied from host #{@host_ae} (#{@host_ip})!")
         end
       end
     end
@@ -501,7 +470,7 @@ module DICOM
       @release = false
       if @abort
         @link.stop_session
-        add_notice("Association has been closed. (#{@host_ae}, #{@host_ip})")
+        logger.info("Association has been closed. (#{@host_ae}, #{@host_ip})")
       else
         unless @link.session.closed?
           @link.build_release_request
@@ -509,12 +478,12 @@ module DICOM
           info = @link.receive_single_transmission.first
           @link.stop_session
           if info[:pdu] == PDU_RELEASE_RESPONSE
-            add_notice("Association released properly from host #{@host_ae}.")
+            logger.info("Association released properly from host #{@host_ae}.")
           else
-            add_error("Association released from host #{@host_ae}, but a release response was not registered.")
+            logger.error("Association released from host #{@host_ae}, but a release response was not registered.")
           end
         else
-          add_error("Connection was closed by the host (for some unknown reason) before the association could be released properly.")
+          logger.error("Connection was closed by the host (for some unknown reason) before the association could be released properly.")
         end
       end
       @abort = false
@@ -533,33 +502,38 @@ module DICOM
     #
     # === Parameters
     #
-    # * <tt>files</tt> -- A single file path or an array of paths, or a DObject or an array of DObject instances.
+    # * <tt>files_or_objects</tt> -- A single file path or an array of paths, or a DObject or an array of DObject instances.
     #
-    def load_files(files)
+    def load_files(files_or_objects)
+      files_or_objects = [files_or_objects] unless files_or_objects.is_a?(Array)
       status = true
       message = ""
       objects = Array.new
       abstracts = Array.new
       id = 1
       @presentation_contexts = Hash.new
-      files = [files] unless files.is_a?(Array)
-      files.each do |file|
-        if file.is_a?(String)
-          obj = DObject.new(file, :verbose => false)
+      files_or_objects.each do |file_or_object|
+        if file_or_object.is_a?(String)
+          # Temporarily increase the log threshold to suppress messages from the DObject class:
+          client_level = logger.level
+          logger.level = Logger::FATAL
+          obj = DObject.read(file_or_object)
+          # Reset the logg threshold:
+          logger.level = client_level
           if obj.read_success
             # Load the DICOM object:
             objects << obj
           else
             status = false
-            message = "Failed to successfully parse a DObject for the following string: #{file}"
+            message = "Failed to read a DObject from this file: #{file_or_object}"
           end
-        elsif file.is_a?(DObject)
+        elsif file_or_object.is_a?(DObject)
           # Load the DICOM object and its abstract syntax:
-          abstracts << file.value("0008,0016")
-          objects << file
+          abstracts << file_or_object.value("0008,0016")
+          objects << file_or_object
         else
           status = false
-          message = "Array contains invalid object #{file}."
+          message = "Array contains invalid object: #{file_or_object.class}."
         end
       end
       # Extract available transfer syntaxes for the various sop classes found amongst these objects
@@ -732,7 +706,7 @@ module DICOM
             process_returned_data(segments)
           end
         else
-          add_error("Error: Unable to extract SOP Class UID and/or SOP Instance UID for this DICOM object. File will not be sent to its destination.")
+          logger.error("Unable to extract SOP Class UID and/or SOP Instance UID for this DICOM object. File will not be sent to its destination.")
         end
       end
     end
@@ -767,16 +741,27 @@ module DICOM
       if rejected.length == 0
         @request_approved = true
         if @approved_syntaxes.length == 1 and presentation_contexts.length == 1
-          add_notice("The presentation context was accepted by host #{@host_ae}.")
+          logger.info("The presentation context was accepted by host #{@host_ae}.")
         else
-          add_notice("All #{presentation_contexts.length} presentation contexts were accepted by host #{@host_ae} (#{@host_ip}).")
+          logger.info("All #{presentation_contexts.length} presentation contexts were accepted by host #{@host_ae} (#{@host_ip}).")
         end
       else
         # We still consider the request 'approved' if at least one context were accepted:
         @request_approved = true if @approved_syntaxes.length > 0
-        add_error("One or more of your presentation contexts were denied by host #{@host_ae}!")
-        @approved_syntaxes.each_pair {|key, value| add_error("APPROVED: #{LIBRARY.get_syntax_description(key)} (#{LIBRARY.get_syntax_description(value[1])})")}
-        rejected.each_pair {|key, value| add_error("REJECTED: #{LIBRARY.get_syntax_description(key)} (#{LIBRARY.get_syntax_description(value[1])})")}
+
+        logger.error("One or more of your presentation contexts were denied by host #{@host_ae}!")
+
+        @approved_syntaxes.each_pair do |key, value|
+          sntx_k = LIBRARY.get_syntax_description(key)
+          sntx_v = LIBRARY.get_syntax_description(value[1])
+          logger.info("APPROVED: #{sntx_k} (#{sntx_v})")
+        end
+
+        rejected.each_pair do |key, value|
+          sntx_k = LIBRARY.get_syntax_description(key)
+          sntx_v = LIBRARY.get_syntax_description(value[1])
+          logger.error("REJECTED: #{sntx_k} (#{sntx_v})")
+        end
       end
     end
 
@@ -958,4 +943,4 @@ module DICOM
     end
 
   end
-end
+end