dicom 0.9.1 → 0.9.2

data/lib/dicom/d_read.rb

@@ -36,8 +36,9 @@ module DICOM
     #
     # === Options
     #
-    # * <tt>:syntax</tt> -- String. If specified, the decoding of the DICOM string will be forced to use this transfer syntax.
     # * <tt>:bin</tt> -- Boolean. If true, the string parameter will be interpreted as a binary DICOM string instead of a path string.
+    # * <tt>:no_meta</tt> -- Boolean. If true, the parsing algorithm is instructed that the binary DICOM string contains no meta header.
+    # * <tt>:syntax</tt> -- String. If specified, the decoding of the DICOM string will be forced to use this transfer syntax.
     #
     def initialize(obj, string=nil, options={})
       # Set the DICOM object as an instance variable:
@@ -69,8 +70,8 @@ module DICOM
       end
       # Create a Stream instance to handle the decoding of content from this binary string:
       @stream = Stream.new(@str, @file_endian)
-      # Do not check for header information when supplied a (network) binary string:
-      unless options[:bin]
+      # Do not check for header information if we've been told there is none (typically for (network) binary strings):
+      unless options[:no_meta]
         # Read and verify the DICOM header:
         header = check_header
         # If the file didnt have the expected header, we will attempt to read
@@ -92,8 +93,8 @@ module DICOM
           data_element = process_data_element
         rescue Exception => msg
           # The parse algorithm crashed. Set data_element to false to break the loop and toggle the success boolean to indicate failure.
-          @msg << msg
-          @msg << "Error: Failed to parse Data Elements. This was probably an invalid/corrupt DICOM file."
+          @msg << [:error, msg]
+          @msg << [:warn, "Parsing a Data Element has failed. This was probably caused by an invalidly encoded (or corrupted) DICOM file."]
           @success = false
           data_element = false
         end
@@ -123,7 +124,7 @@ module DICOM
         @header_length += 132
         if identifier != "DICM" then
           # Header signature is not valid (we will still try to read it is a DICOM file though):
-          @msg << "Warning: The specified file does not contain the official DICOM header. Will try to read the file anyway, as some sources are known to skip this header."
+          @msg << [:warn, "This file does not contain the expected DICOM header. Will try to parse the file anyway (assuming a missing header)."]
           # As the file is not conforming to the DICOM standard, it is possible that it does not contain a
           # transfer syntax element, and as such, we attempt to choose the most probable encoding values here:
           @explicit = false
@@ -209,9 +210,9 @@ module DICOM
         # If length is specified (no delimitation items), load a new DRead instance to read these child elements
         # and load them into the current sequence. The exception is when we have a pixel data item.
         if length > 0 and not @enc_image
-          child_reader = DRead.new(@current_element, bin, :bin => true, :syntax => @transfer_syntax)
+          child_reader = DRead.new(@current_element, bin, :bin => true, :no_meta => true, :syntax => @transfer_syntax)
           @current_parent = @current_parent.parent
-          @msg << child_reader.msg
+          @msg += child_reader.msg unless child_reader.msg.empty?
           @success = child_reader.success
           return false unless @success
         end
@@ -223,7 +224,7 @@ module DICOM
         # Create an ordinary Data Element:
         @current_element = Element.new(tag, value, :bin => bin, :name => name, :parent => @current_parent, :vr => vr)
         # Check that the data stream didnt end abruptly:
-        raise "Error: The actual length of the binary (#{@current_element.bin.length}) does not match the specified length (#{length}) for Data Element #{@current_element.tag}." if length != @current_element.bin.length
+        raise "The actual length of the value (#{@current_element.bin.length}) does not match its specified length (#{length}) for Data Element #{@current_element.tag}" if length != @current_element.bin.length
       end
       # Return true to indicate success:
       return true
@@ -291,7 +292,7 @@ module DICOM
         length = @stream.decode(bytes, "SL") # (4)
       end
       # Check that length is valid (according to the DICOM standard, it must be even):
-      raise "Error: Encountered a Data Element (#{tag}) with an invalid (odd) value length." if length%2 == 1 and length > 0
+      raise "Encountered a Data Element (#{tag}) with an invalid (odd) value length." if length%2 == 1 and length > 0
       return vr, length
     end
 
@@ -338,42 +339,25 @@ module DICOM
     #
     # === Parameters
     #
-    # * <tt>file</tt> -- A path/file string. The string may point to a local file or a http location.
+    # * <tt>file</tt> -- A path/file string.
     #
     def open_file(file)
-      if file.index('http')==0
-        # Try to open the remote file using open-uri:
-        @retrials = 0
-        begin
-          @file = open(file, 'rb') # binary encoding (ASCII-8BIT)
-        rescue Exception => e
-          if @retrials>3
-            @retrials = 0
-            raise "Unable to read the file. File does not exist?"
-          else
-            puts "Warning: Exception in ruby-dicom when loading a dicom file from: #{file}"
-            puts "Retrying... #{@retrials}"
-            @retrials+=1
-            retry
-          end
-        end
-      elsif File.exist?(file)
-        # Try to read the file on the local file system:
+      if File.exist?(file)
         if File.readable?(file)
           if !File.directory?(file)
             if File.size(file) > 8
               @file = File.new(file, "rb")
             else
-              @msg << "Error! File is too small to contain DICOM information (#{file})."
+              @msg << [:error, "This file is too small to contain valid DICOM information: #{file}."]
             end
           else
-            @msg << "Error! File is a directory (#{file})."
+            @msg << [:error, "Expected a file, got a directory: #{file}"]
           end
         else
-          @msg << "Error! File exists but I don't have permission to read it (#{file})."
+          @msg << [:error, "File exists but I don't have permission to read it: #{file}"]
         end
       else
-        @msg << "Error! The file you have supplied does not exist (#{file})."
+        @msg << [:error, "Invalid (non-existing) file: #{file}"]
       end
     end
 
@@ -407,7 +391,10 @@ module DICOM
     # Creates various instance variables that are used when parsing the DICOM string.
     #
     def init_variables
-      # Array that will holde any messages generated while reading the DICOM file:
+      # Array for storing any messages that is generated while reading the DICOM file.
+      # The messages shall be of the format: [:type, "message"]
+      # (Because of the possibility of multi-pass file reading, the DRead instance does not access
+      # the Logging module directly; it lets the DObject instance pass along the messages instead)
       @msg = Array.new
       # Presence of the official DICOM signature:
       @signature = false

data/lib/dicom/d_server.rb

@@ -3,7 +3,9 @@ module DICOM
   # This class contains code for setting up a Service Class Provider (SCP),
   # which will act as a simple storage node (a DICOM server that receives images).
   #
+
   class DServer
+    include Logging
 
     # Runs the server and takes a block for initializing.
     #
@@ -39,20 +41,18 @@ module DICOM
     attr_accessor :port
     # The maximum period the server will wait on an answer from a client 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
 
     # A hash containing the abstract syntaxes that will be accepted.
     attr_reader :accepted_abstract_syntaxes
     # A hash containing the transfer syntaxes that will be accepted.
     attr_reader :accepted_transfer_syntaxes
-    # An array containing any error messages recorded.
-    attr_reader :errors
-    # An array containing any status messages recorded.
-    attr_reader :notices
 
     # Creates a DServer instance.
     #
+    # === Notes
+    #
+    # * To customize logging behaviour, refer to the Logging module documentation.
+    #
     # === Parameters
     #
     # * <tt>port</tt> -- Fixnum. The network port to be used. Defaults to 104.
@@ -64,7 +64,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 DServer instance will run silently and not output warnings and error messages to the screen. Defaults to true.
     #
     # === Examples
     #
@@ -84,11 +83,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:
       @connection = nil # TCP connection status
       @association = nil # DICOM Association status
@@ -212,19 +206,18 @@ module DICOM
     #
     def start_scp(path='./received/')
       if @accepted_abstract_syntaxes.size > 0 and @accepted_transfer_syntaxes.size > 0
-        add_notice("Starting DICOM SCP server...")
-        add_notice("*********************************")
+        logger.info("Started DICOM SCP server on port #{@port}.")
+        logger.info("Waiting for incoming transmissions...\n\n")
         # Initiate server:
         @scp = TCPServer.new(@port)
         # Use a loop to listen for incoming messages:
         loop do
           Thread.start(@scp.accept) do |session|
             # Initialize the network package handler for this session:
-            link = Link.new(:host_ae => @host_ae, :max_package_size => @max_package_size, :timeout => @timeout, :verbose => @verbose, :file_handler => @file_handler)
+            link = Link.new(:host_ae => @host_ae, :max_package_size => @max_package_size, :timeout => @timeout, :file_handler => @file_handler)
             link.set_session(session)
-            # Note the time of reception as well as who has contacted us:
-            add_notice(Time.now.strftime("%Y-%m-%d  %H:%M:%S"))
-            add_notice("Connection established with:  #{session.peeraddr[2]}  (IP: #{session.peeraddr[3]})")
+            # Note who has contacted us:
+            logger.info("Connection established with:  #{session.peeraddr[2]}  (IP: #{session.peeraddr[3]})")
             # Receive an incoming message:
             segments = link.receive_multiple_transmissions
             info = segments.first
@@ -236,28 +229,24 @@ module DICOM
                 link.handle_association_accept(info)
                 if approved > 0
                   if approved == 1
-                    add_notice("Accepted the association request with context: #{LIBRARY.get_syntax_description(info[:pc].first[:abstract_syntax])}")
+                    logger.info("Accepted the association request with context: #{LIBRARY.get_syntax_description(info[:pc].first[:abstract_syntax])}")
                   else
                     if rejected == 0
-                      add_notice("Accepted all #{approved} proposed contexts in the association request.")
+                      logger.info("Accepted all #{approved} proposed contexts in the association request.")
                     else
-                      add_notice("Accepted only #{approved} of #{approved+rejected} of the proposed contexts in the association request.")
+                      logger.warn("Accepted only #{approved} of #{approved+rejected} of the proposed contexts in the association request.")
                     end
                   end
                   # Process the incoming data. This method will also take care of releasing the association:
                   success, messages = link.handle_incoming_data(path)
-                  if success
-                    add_notice(messages) if messages.first
-                  else
-                    # Something has gone wrong:
-                    add_error(messages) if messages.first
-                  end
+                  # Pass along any messages that has been recorded:
+                  messages.each { |m| logger.public_send(m.first, m.last) } if messages.first
                 else
                   # No abstract syntaxes in the incoming request were accepted:
                   if rejected == 1
-                    add_notice("Rejected the association request with proposed context: #{LIBRARY.get_syntax_description(info[:pc].first[:abstract_syntax])}")
+                    logger.warn("Rejected the association request with proposed context: #{LIBRARY.get_syntax_description(info[:pc].first[:abstract_syntax])}")
                   else
-                    add_notice("Rejected all #{rejected} proposed contexts in the association request.")
+                    logger.warn("Rejected all #{rejected} proposed contexts in the association request.")
                   end
                   # Since the requested abstract syntax was not accepted, the association must be released.
                   link.await_release
@@ -272,7 +261,7 @@ module DICOM
             end
             # Terminate the connection:
             link.stop_session
-            add_notice("*********************************")
+            logger.info("Connection closed.\n\n")
           end
         end
       else
@@ -285,35 +274,6 @@ module DICOM
     # Following methods are private:
     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)
-      if @verbose
-        puts error
-      end
-      @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)
-      if @verbose
-        puts notice
-      end
-      @notices << notice
-    end
-
     # Checks if the association request is formally correct, by matching against an exact application context UID.
     # Returns nil if valid, and an error code if it is not approved.
     #
@@ -330,7 +290,7 @@ module DICOM
     def check_association_request(info)
       unless info[:application_context] == APPLICATION_CONTEXT
         error = 2 # (application context name not supported)
-        add_error("Error: The application context in the incoming association request was not recognized: (#{info[:application_context]})")
+        logger.error("The application context in the incoming association request was not recognized: (#{info[:application_context]})")
       else
         error = nil
       end
@@ -392,4 +352,4 @@ module DICOM
     end
 
   end
-end
+end

data/lib/dicom/d_write.rb

@@ -17,9 +17,8 @@ module DICOM
   # that this is actually achieved. You are encouraged to thouroughly test your files for compatibility after creation.
   #
   class DWrite
+    include Logging
 
-    # An array which records any status messages that are generated while encoding/writing the DICOM string.
-    attr_reader :msg
     # An array of partial DICOM strings.
     attr_reader :segments
     # A boolean which reports whether the DICOM string was encoded/written successfully (true) or not (false).
@@ -48,8 +47,6 @@ module DICOM
       @file_name = file_name
       # As default, signature will be written and meta header added:
       @signature = (options[:signature] == false ? false : true)
-      # Array for storing error/warning messages:
-      @msg = Array.new
     end
 
     # Handles the encoding of DICOM information to string as well as writing it to file.
@@ -329,7 +326,7 @@ module DICOM
           @file = File.new(file, "wb")
         else
           # Existing file is not writable:
-          @msg << "Error! The program does not have permission or resources to create the file you specified: (#{file})"
+          logger.error("The program does not have permission or resources to create this file: #{file}")
         end
       else
         # File does not exist.
@@ -370,7 +367,7 @@ module DICOM
       # The information from the Transfer syntax element (if present), needs to be processed:
       valid_syntax, @rest_explicit, @rest_endian = LIBRARY.process_transfer_syntax(@transfer_syntax)
       unless valid_syntax
-        @msg << "Warning: Invalid/unknown transfer syntax! Will still write the file, but you should give this a closer look."
+        logger.warn("Invalid (unknown) transfer syntax! Will complete encoding the file, but an investigation of the result is recommended.")
       end
       # We only plan to run this method once:
       @switched = true

data/lib/dicom/element.rb

@@ -44,7 +44,7 @@ module DICOM
     def initialize(tag, value, options={})
       raise ArgumentError, "The supplied tag (#{tag}) is not valid. The tag must be a string of the form 'GGGG,EEEE'." unless tag.is_a?(String) && tag.tag?
       # Set instance variables:
-      @tag = tag
+      @tag = tag.upcase
       # We may beed to retrieve name and vr from the library:
       if options[:name] and options[:vr]
         @name = options[:name]

data/lib/dicom/file_handler.rb

@@ -47,7 +47,7 @@ module DICOM
       full_path = path_prefix + local_path + extension
       # Save the DICOM object to disk:
       obj.write(full_path, :transfer_syntax => transfer_syntax)
-      message = "DICOM file saved to: #{full_path}"
+      message = [:info, "DICOM file saved to: #{full_path}"]
       return message
     end
 
@@ -74,8 +74,13 @@ module DICOM
       # Process each DICOM object:
       objects.each_index do |i|
         if objects[i].length > 8
-          # Parse the received data stream and load it as a DICOM object:
-          obj = DObject.new(objects[i], :bin => true, :syntax => transfer_syntaxes[i])
+          # Temporarily increase the log threshold to suppress messages from the DObject class:
+          server_level = DICOM.logger.level
+          DICOM.logger.level = Logger::FATAL
+          # Parse the received data string and load it to a DICOM object:
+          obj = DObject.parse(objects[i], :no_meta => true, :syntax => transfer_syntaxes[i])
+          # Reset the logg threshold:
+          DICOM.logger.level = server_level
           if obj.read_success
             begin
               message = self.save_file(path, obj, transfer_syntaxes[i])
@@ -83,28 +88,28 @@ module DICOM
             rescue
               handle_fail += 1
               all_success = false
-              messages << "Error: Saving file failed!"
+              messages << [:error, "Saving file failed!"]
             end
           else
             parse_fail += 1
             all_success = false
-            messages << "Error: Invalid DICOM data encountered: The DICOM data string could not be parsed successfully."
+            messages << [:error, "Invalid DICOM data encountered: The received string was not parsed successfully."]
           end
         else
           too_short += 1
           all_success = false
-          messages << "Error: Invalid data encountered: The data was too small to be a valid DICOM file."
+          messages << [:error, "Invalid data encountered: The received string was too small to contain any DICOM data."]
         end
       end
       # Create a summary status message, when multiple files have been received:
       if total > 1
         if successful == total
-          messages << "All #{total} DICOM files received successfully."
+          messages << [:info, "All #{total} DICOM files received successfully."]
         else
           if successful == 0
-            messages << "All #{total} received DICOM files failed!"
+            messages << [:warn, "All #{total} received DICOM files failed!"]
           else
-            messages << "Only #{successful} of #{total} DICOM files received successfully!"
+            messages << [:warn, "Only #{successful} of #{total} DICOM files received successfully!"]
           end
         end
       else

data/lib/dicom/image_item.rb

@@ -11,6 +11,7 @@ module DICOM
   class ImageItem < Parent
 
     include ImageProcessor
+    include Logging
 
     # Checks if colored pixel data is present.
     # Returns true if it is, false if not.
@@ -169,7 +170,7 @@ module DICOM
             strings.each {|string| pixel_frames << decode_rle(num_cols, num_rows, string)}
           else
             images = decompress(strings) || Array.new
-            add_msg("Warning: Decompressing pixel values has failed (unsupported transfer syntax: '#{transfer_syntax}')") unless images
+            logger.warn("Decompressing pixel values has failed (unsupported transfer syntax: '#{transfer_syntax}')") unless images
           end
         else
           # Uncompressed: Decode to numbers.
@@ -184,7 +185,7 @@ module DICOM
             if pixels
               images << read_image(pixels, num_cols, num_rows, options)
             else
-              add_msg("Warning: Processing pixel values for this particular color mode failed, unable to construct image(s).")
+              logger.warn("Processing pixel values for this particular color mode failed, unable to construct image(s).")
             end
           end
         end
@@ -210,7 +211,7 @@ module DICOM
         # Write the binary data to the Pixel Data Element:
         write_pixels(bin)
       else
-        add_msg("Notice: The specified file (#{file}) is empty. Nothing to transfer.")
+        logger.info("The specified file (#{file}) is empty. Nothing to transfer.")
       end
     end
 
@@ -362,10 +363,10 @@ module DICOM
             # Remap the image from pixel values to presentation values if the user has requested this:
             pixels = process_presentation_values_narray(pixels, -65535, 65535, options[:level]) if options[:remap] or options[:level]
           else
-            add_msg("Warning: Decompressing the Pixel Data failed. Pixel values can not be extracted.")
+            logger.warn("Decompressing the Pixel Data failed. Pixel values can not be extracted.")
           end
         else
-          add_msg("The DICOM object contains colored pixel data. Retrieval of colored pixels is not supported by this method yet.")
+          logger.warn("The DICOM object contains colored pixel data. Retrieval of colored pixels is not supported by this method yet.")
           pixels = false
         end
       end
@@ -419,7 +420,7 @@ module DICOM
             end
           end
         else
-          add_msg("Warning: Decompressing the Pixel Data failed. Pixel values can not be extracted.")
+          logger.warn("Decompressing the Pixel Data failed. Pixel values can not be extracted.")
         end
       end
       return pixels