dicom 0.8 → 0.9

data/lib/dicom/image_processor.rb

@@ -0,0 +1,69 @@
+module DICOM
+  module ImageProcessor
+
+    # Creates image objects from one or more compressed, binary string blobs.
+    # Returns an array of images. If decompression fails, returns false.
+    #
+    # === Parameters
+    #
+    # * <tt>blobs</tt> -- Binary string blob(s) containing compressed pixel data.
+    #
+    def decompress(blobs)
+      raise ArgumentError, "Expected Array or String, got #{blobs.class}." unless [String, Array].include?(blobs.class)
+      blobs = [blobs] unless blobs.is_a?(Array)
+      begin
+        return image_module.decompress(blobs)
+      rescue
+        return false
+      end
+    end
+
+    # Extracts an array of pixels (integers) from an image object.
+    #
+    # === Parameters
+    #
+    # * <tt>image</tt> -- An Rmagick image object.
+    #
+    def export_pixels(image, photometry)
+      raise ArgumentError, "Expected String, got #{photometry.class}." unless photometry.is_a?(String)
+      image_module.export_pixels(image, photometry)
+    end
+
+    # Creates an image object from a binary string blob.
+    #
+    # === Parameters
+    #
+    # * <tt>blob</tt> -- Binary string blob containing raw pixel data.
+    # * <tt>columns</tt> -- Number of columns.
+    # * <tt>rows</tt> -- Number of rows.
+    # * <tt>depth</tt> -- Bit depth of the encoded pixel data.
+    # * <tt>photometry</tt> -- String describing the DICOM photometry of the pixel data. Example: 'MONOCHROME1', 'RGB'.
+    #
+    def import_pixels(blob, columns, rows, depth, photometry)
+      raise ArgumentError, "Expected String, got #{blob.class}." unless blob.is_a?(String)
+      image_module.import_pixels(blob, columns, rows, depth, photometry)
+    end
+
+    # Returns an array containing the image objects that are supported by the image processor.
+    #
+    def valid_image_objects
+      return [Magick::Image, MiniMagick::Image]
+    end
+
+
+    private
+
+
+    def image_module
+      case DICOM.image_processor
+      when :mini_magick
+        DcmMiniMagick
+      when :rmagick
+        DcmRMagick
+      else
+        raise "Uknown image processor #{DICOM.image_processor}"
+      end
+    end
+
+  end
+end

data/lib/dicom/image_processor_mini_magick.rb

@@ -0,0 +1,74 @@
+module DICOM
+  module ImageProcessor
+    module DcmMiniMagick
+
+      class << self
+
+        # Creates image objects from an array of compressed, binary string blobs.
+        # Returns an array of images. If decompression fails, returns false.
+        #
+        # === Parameters
+        #
+        # * <tt>blobs</tt> -- An array of binary string blobs containing compressed pixel data.
+        #
+        def decompress(blobs)
+          images = Array.new
+          # We attempt to decompress the pixels using ImageMagick:
+          blobs.each do |string|
+            images << MiniMagick::Image.read(string)
+          end
+          return images
+        end
+
+        # Extracts an array of pixels (integers) from an image object.
+        #
+        # === Notes
+        #
+        # * This feature is not available as of yet in the mini_magick image processor. If this feature is needed, please try another image processor (RMagick).
+        #
+        # === Parameters
+        #
+        # * <tt>image</tt> -- An MiniMagick image object.
+        #
+        def export_pixels(image, photometry)
+          raise ArgumentError, "Expected MiniMagick::Image, got #{image.class}." unless image.is_a?(MiniMagick::Image)
+          raise "Exporting pixels is not yet available with the mini_magick processor. Please try another image processor (RMagick)."
+        end
+
+        # Creates an image object from a binary string blob which contains raw pixel data.
+        #
+        # === Parameters
+        #
+        # * <tt>blob</tt> -- Binary string blob containing raw pixel data.
+        # * <tt>columns</tt> -- Number of columns.
+        # * <tt>rows</tt> -- Number of rows.
+        # * <tt>depth</tt> -- Bit depth of the encoded pixel data.
+        # * <tt>photometry</tt> -- String describing the DICOM photometry of the pixel data.
+        # * <tt>format</tt> -- String describing the image format to be used when creating the image object. Defaults to 'png'.
+        #
+        def import_pixels(blob, columns, rows, depth, photometry, format="png")
+          image = MiniMagick::Image.import_pixels(blob, columns, rows, depth, im_map(photometry), format)
+        end
+
+        # Returns an ImageMagick pixel map string based on the input DICOM photometry string.
+        #
+        # === Parameters
+        #
+        # * <tt>photometry</tt> -- String describing the photometry of the pixel data. Example: 'MONOCHROME1' or 'COLOR'.
+        #
+        def im_map(photometry)
+          raise ArgumentError, "Expected String, got #{photometry.class}." unless photometry.is_a?(String)
+          if photometry.include?("COLOR") or photometry.include?("RGB")
+            return "rgb"
+          elsif photometry.include?("YBR")
+            return "ybr"
+          else
+            return "gray" # (Assuming monochromeX - greyscale)
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/dicom/image_processor_r_magick.rb

@@ -0,0 +1,102 @@
+module DICOM
+  module ImageProcessor
+    module DcmRMagick
+
+      class << self
+
+        # Creates image objects from an array of compressed, binary string blobs.
+        # Returns an array of images. If decompression fails, returns false.
+        #
+        # === Notes
+        #
+        # The method tries to use RMagick of unpacking, but it seems that ImageMagick is not able to handle most of the
+        # compressed image variants used in the DICOM standard. To get a more robust implementation which is able to handle
+        # most types of compressed DICOM files, something else is needed.
+        #
+        # Probably a good candidate to use is the PVRG-JPEG library, which seems to be able to handle everything that is jpeg.
+        # It exists in the Ubuntu repositories, where it can be installed and run through terminal. For source code, and some
+        # additional information, check this link:  http://www.panix.com/~eli/jpeg/
+        #
+        # Another idea would be to study how other open source libraries, like GDCM handle these files.
+        #
+        # === Parameters
+        #
+        # * <tt>blobs</tt> -- An array of binary string blobs containing compressed pixel data.
+        #
+        #--
+        # The following transfer syntaxes have been verified as failing with ImageMagick:
+        # TXS_JPEG_LOSSLESS_NH is not supported by (my) ImageMagick version: "Unsupported JPEG process: SOF type 0xc3"
+        # TXS_JPEG_LOSSLESS_NH_FOP is not supported by (my) ImageMagick version: "Unsupported JPEG process: SOF type 0xc3"
+        # TXS_JPEG_2000_PART1_LOSSLESS is not supported by (my) ImageMagick version: "jpc_dec_decodepkts failed"
+        #
+        def decompress(blobs)
+          images = Array.new
+          # We attempt to decompress the pixels using ImageMagick:
+            blobs.each do |string|
+              images << Magick::Image.from_blob(string).first
+            end
+          return images
+        end
+
+        # Extracts an array of pixels (integers) from an image object.
+        #
+        # === Parameters
+        #
+        # * <tt>image</tt> -- An Rmagick image object.
+        #
+        def export_pixels(image, photometry)
+          raise ArgumentError, "Expected Magick::Image, got #{image.class}." unless image.is_a?(Magick::Image)
+          pixels = image.export_pixels(0, 0, image.columns, image.rows, rm_map(photometry))
+          return pixels
+        end
+
+        # Creates an image object from a binary string blob which contains raw pixel data.
+        #
+        # === Parameters
+        #
+        # * <tt>blob</tt> -- Binary string blob containing raw pixel data.
+        # * <tt>columns</tt> -- Number of columns.
+        # * <tt>rows</tt> -- Number of rows.
+        # * <tt>depth</tt> -- Bit depth of the encoded pixel data.
+        # * <tt>photometry</tt> -- String describing the DICOM photometry of the pixel data.
+        # * <tt>format</tt> -- String describing the image format to be used when creating the image object. Defaults to 'png'.
+        #
+        def import_pixels(blob, columns, rows, depth, photometry, format="png")
+          image = Magick::Image.new(columns,rows).import_pixels(0, 0, columns, rows, rm_map(photometry), blob, rm_data_type(depth))
+        end
+
+        # Returns the RMagick StorageType pixel value corresponding to the given bit length.
+        #
+        def rm_data_type(bit_depth)
+          return case bit_depth
+          when 8
+            Magick::CharPixel
+          when 16
+            Magick::ShortPixel
+          else
+            raise ArgumentError, "Unsupported bit depth: #{bit_depth}."
+          end
+        end
+
+        # Returns an RMagick pixel map string based on the input DICOM photometry string.
+        #
+        # === Parameters
+        #
+        # * <tt>photometry</tt> -- String describing the photometry of the pixel data. Example: 'MONOCHROME1' or 'COLOR'.
+        #
+        def rm_map(photometry)
+          raise ArgumentError, "Expected String, got #{photometry.class}." unless photometry.is_a?(String)
+          if photometry.include?("COLOR") or photometry.include?("RGB")
+            return "RGB"
+          elsif photometry.include?("YBR")
+            return "YBR"
+          else
+            return "I" # (Assuming monochromeX - greyscale)
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/dicom/item.rb

@@ -1,13 +1,16 @@
-#    Copyright 2010 Christoffer Lervag
-
 module DICOM
 
   # The Item class handles information related to items - the elements contained in sequences.
   #
-  class Item < SuperItem
+  # === Inheritance
+  #
+  # As the Item class inherits from the ImageItem class, which itself inherits from the Parent class,
+  # all ImageItem and Parent methods are also available to instances of Item.
+  #
+  class Item < ImageItem
 
-    # Include the Elements mix-in module:
-    include Elements
+    # Include the Elemental mix-in module:
+    include Elemental
 
     # The index of this Item in the group of items belonging to its parent. If the Item is without parent, index is nil.
     attr_accessor :index
@@ -47,13 +50,15 @@ module DICOM
       @value = nil
       @name = options[:name] || "Item"
       @vr = options[:vr] || ITEM_VR
-      @bin = options[:bin]
-      @length = options[:length]
-      @length = -1 unless options[:length] or options[:bin]
+      if options[:bin]
+        self.bin = options[:bin]
+      else
+        @length = options[:length] || -1
+      end
       if options[:parent]
         @parent = options[:parent]
         @index = options[:index] if options[:index]
-        @parent.add_item(self, :index => options[:index])
+        @parent.add_item(self, :index => options[:index], :no_follow => true)
       end
     end
 
@@ -69,18 +74,15 @@ module DICOM
     #   obj["7FE0,0010"][1].children.first.bin = jpeg_binary_string
     #
     def bin=(new_bin)
-      if new_bin.is_a?(String)
-        # Add an empty byte at the end if the length of the binary is odd:
-        if new_bin.length[0] == 1
-          @bin = new_bin + "\x00"
-        else
-          @bin = new_bin
-        end
-        @value = nil
-        @length = @bin.length
+      raise ArgumentError, "Invalid parameter type. String was expected, got #{new_bin.class}." unless new_bin.is_a?(String)
+      # Add an empty byte at the end if the length of the binary is odd:
+      if new_bin.length[0] == 1
+        @bin = new_bin + "\x00"
       else
-        raise "Invalid parameter type. String was expected, got #{new_bin.class}."
+        @bin = new_bin
       end
+      @value = nil
+      @length = @bin.length
     end
 
   end

data/lib/dicom/link.rb

@@ -1,5 +1,3 @@
-#    Copyright 2009-2010 Christoffer Lervag
-
 module DICOM
 
   # This class handles the construction and interpretation of network packages as well as network communication.
@@ -8,7 +6,7 @@ module DICOM
 
     # A customized FileHandler class to use instead of the default FileHandler included with Ruby DICOM.
     attr_accessor :file_handler
-    # The maximum allowed size of network packages (in bytes). 
+    # The maximum allowed size of network packages (in bytes).
     attr_accessor :max_package_size
     # A hash which keeps track of the relationship between context ID and chosen transfer syntax.
     attr_accessor :presentation_contexts
@@ -32,7 +30,7 @@ module DICOM
     # * <tt>:ae</tt> -- String. The name of the client (application entity).
     # * <tt>:file_handler</tt> -- A customized FileHandler class to use instead of the default FileHandler.
     # * <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>:max_package_size</tt> -- Fixnum. The maximum allowed size of network packages (in bytes).
     # * <tt>:timeout</tt> -- Fixnum. The maximum period to wait for an answer before aborting the communication.
     # * <tt>:verbose</tt> -- Boolean. If set to false, the DLink instance will run silently and not output warnings and error messages to the screen. Defaults to true.
     #
@@ -121,17 +119,19 @@ module DICOM
       # encodes the presentation context, we pass on a one-element array containing nil).
       abstract_syntaxes = Array.new(1, nil)
       # Note: The order of which these components are built is not arbitrary.
-      append_application_context(info[:application_context])
+      append_application_context
       # Reset the presentation context instance variable:
       @presentation_contexts = Hash.new
+      # Create the presentation context hash object that will be passed to the builder method:
+      p_contexts = Hash.new
       # Build the presentation context strings, one by one:
       info[:pc].each do |pc|
-        context_id = pc[:presentation_context_id]
-        result = pc[:result]
-        transfer_syntax = pc[:selected_transfer_syntax]
-        @presentation_contexts[context_id] = transfer_syntax
-        append_presentation_contexts(abstract_syntaxes, ITEM_PRESENTATION_CONTEXT_RESPONSE, transfer_syntax, context_id, result)
+        @presentation_contexts[pc[:presentation_context_id]] = pc[:selected_transfer_syntax]
+        # Add the information from this pc item to the p_contexts hash:
+        p_contexts[pc[:abstract_syntax]] = Hash.new unless p_contexts[pc[:abstract_syntax]]
+        p_contexts[pc[:abstract_syntax]][pc[:presentation_context_id]] = {:transfer_syntaxes => [pc[:selected_transfer_syntax]], :result => pc[:result]}
       end
+      append_presentation_contexts(p_contexts, ITEM_PRESENTATION_CONTEXT_RESPONSE)
       append_user_information(@user_information)
       # Header must be built last, because we need to know the length of the other components.
       append_association_header(PDU_ASSOCIATION_ACCEPT, info[:called_ae])
@@ -170,20 +170,18 @@ module DICOM
     #
     # === Parameters
     #
-    # * <tt>ac_uid</tt> -- The application context UID string.
-    # * <tt>as</tt> -- An array of abstract syntax strings.
-    # * <tt>ts</tt> -- An array of transfer syntax strings.
+    # * <tt>presentation_contexts</tt> -- A hash containing abstract_syntaxes, presentation context ids and transfer syntaxes.
     # * <tt>user_info</tt> -- A user information items array.
     #
-    def build_association_request(ac_uid, as, ts, user_info)
+    def build_association_request(presentation_contexts, user_info)
       # Big endian encoding:
       @outgoing.endian = @net_endian
       # Clear the outgoing binary string:
       @outgoing.reset
       # Note: The order of which these components are built is not arbitrary.
       # (The first three are built 'in order of appearance', the header is built last, but is put first in the message)
-      append_application_context(ac_uid)
-      append_presentation_contexts(as, ITEM_PRESENTATION_CONTEXT_REQUEST, ts)
+      append_application_context
+      append_presentation_contexts(presentation_contexts, ITEM_PRESENTATION_CONTEXT_REQUEST, request=true)
       append_user_information(user_info)
       # Header must be built last, because we need to know the length of the other components.
       append_association_header(PDU_ASSOCIATION_REQUEST, @host_ae)
@@ -1136,19 +1134,15 @@ module DICOM
 
     # Builds the application context (which is part of the association request/response).
     #
-    # === Parameters
-    #
-    # * <tt>ac_uid</tt> -- Application context UID string.
-    #
-    def append_application_context(ac_uid)
+    def append_application_context
       # Application context item type (1 byte)
       @outgoing.encode_last(ITEM_APPLICATION_CONTEXT, "HEX")
       # Reserved (1 byte)
       @outgoing.encode_last("00", "HEX")
       # Application context item length (2 bytes)
-      @outgoing.encode_last(ac_uid.length, "US")
+      @outgoing.encode_last(APPLICATION_CONTEXT.length, "US")
       # Application context (variable length)
-      @outgoing.encode_last(ac_uid, "STR")
+      @outgoing.encode_last(APPLICATION_CONTEXT, "STR")
     end
 
     # Builds the binary string that makes up the header part the association request/response.
@@ -1202,70 +1196,58 @@ module DICOM
     #
     # === Parameters
     #
-    # * <tt>abstract_syntaxes</tt> -- An array of abstract syntax strings.
-    # * <tt>pc</tt> -- Presentation context item (request or response).
-    # * <tt>ts</tt> -- An array of transfer syntax strings.
-    # * <tt>context_id</tt> -- The ID of the current presentation context.
-    # * <tt>result</tt> -- The result (accepted/refused) for the current presentation context.
-    #
-    def append_presentation_contexts(abstract_syntaxes, pc, ts, context_id=nil, result=ACCEPTANCE)
-      # One presentation context for each abstract syntax:
-      abstract_syntaxes.each_with_index do |as, index|
-        # PRESENTATION CONTEXT:
-        # Presentation context item type (1 byte)
-        @outgoing.encode_last(pc, "HEX")
-        # Reserved (1 byte)
-        @outgoing.encode_last("00", "HEX")
-        # Presentation context item length (2 bytes)
-        if ts.is_a?(Array)
-          ts_length = 4*ts.length + ts.join.length
-        else # (String)
-          ts_length = 4 + ts.length
-        end
-        if as
-          items_length = 4 + (4 + as.length) + ts_length
-        else
+    # * <tt>presentation_contexts</tt> -- A nested hash object with abstract syntaxes, presentation context ids, transfer syntaxes and result codes.
+    # * <tt>item_type</tt> -- Presentation context item (request or response).
+    # * <tt>request</tt> -- Boolean. If true, an ossociate request message is generated, if false, an asoociate accept message is generated.
+    #
+    def append_presentation_contexts(presentation_contexts, item_type, request=false)
+      # Iterate the abstract syntaxes:
+      presentation_contexts.each_pair do |abstract_syntax, context_ids|
+        # Iterate the context ids:
+        context_ids.each_pair do |context_id, syntax|
+          # PRESENTATION CONTEXT:
+          # Presentation context item type (1 byte)
+          @outgoing.encode_last(item_type, "HEX")
+          # Reserved (1 byte)
+          @outgoing.encode_last("00", "HEX")
+          # Presentation context item length (2 bytes)
+          ts_length = 4*syntax[:transfer_syntaxes].length + syntax[:transfer_syntaxes].join.length
+          # Abstract syntax item only included in requests, not accepts:
           items_length = 4 + ts_length
-        end
-        @outgoing.encode_last(items_length, "US")
-        # Presentation context ID (1 byte)
-        # Generate a number based on the index of the abstract syntax, unless one has been supplied to this method already.
-        # (NB! This number should be odd, and in the range 1..255)
-        if context_id
-          presentation_context_id = context_id
-        else
-          presentation_context_id = index*2 + 1
-        end
-        @outgoing.encode_last(presentation_context_id, "BY")
-        # Reserved (1 byte)
-        @outgoing.encode_last("00", "HEX")
-        # (1 byte) Reserved (for association request) & Result/reason (for association accept response)
-        @outgoing.encode_last(result, "BY")
-        # Reserved (1 byte)
-        @outgoing.encode_last("00", "HEX")
-        ## ABSTRACT SYNTAX SUB-ITEM: (only for request, not response)
-        if as
-          # Abstract syntax item type (1 byte)
-          @outgoing.encode_last(ITEM_ABSTRACT_SYNTAX, "HEX")
+          items_length += 4 + abstract_syntax.length if request
+          @outgoing.encode_last(items_length, "US")
+          # Presentation context ID (1 byte)
+          @outgoing.encode_last(context_id, "BY")
           # Reserved (1 byte)
           @outgoing.encode_last("00", "HEX")
-          # Abstract syntax item length (2 bytes)
-          @outgoing.encode_last(as.length, "US")
-          # Abstract syntax (variable length)
-          @outgoing.encode_last(as, "STR")
-        end
-        ## TRANSFER SYNTAX SUB-ITEM (not included if result indicates error):
-        if result == ACCEPTANCE
-          ts = [ts] if ts.is_a?(String)
-          ts.each do |t|
-            # Transfer syntax item type (1 byte)
-            @outgoing.encode_last(ITEM_TRANSFER_SYNTAX, "HEX")
+          # (1 byte) Reserved (for association request) & Result/reason (for association accept response)
+          result = (syntax[:result] ? syntax[:result] : 0)
+          @outgoing.encode_last(result, "BY")
+          # Reserved (1 byte)
+          @outgoing.encode_last("00", "HEX")
+          ## ABSTRACT SYNTAX SUB-ITEM: (only for request, not response)
+          if request
+            # Abstract syntax item type (1 byte)
+            @outgoing.encode_last(ITEM_ABSTRACT_SYNTAX, "HEX")
             # Reserved (1 byte)
             @outgoing.encode_last("00", "HEX")
-            # Transfer syntax item length (2 bytes)
-            @outgoing.encode_last(t.length, "US")
-            # Transfer syntax (variable length)
-            @outgoing.encode_last(t, "STR")
+            # Abstract syntax item length (2 bytes)
+            @outgoing.encode_last(abstract_syntax.length, "US")
+            # Abstract syntax (variable length)
+            @outgoing.encode_last(abstract_syntax, "STR")
+          end
+          ## TRANSFER SYNTAX SUB-ITEM (not included if result indicates error):
+          if result == ACCEPTANCE
+            syntax[:transfer_syntaxes].each do |t|
+              # Transfer syntax item type (1 byte)
+              @outgoing.encode_last(ITEM_TRANSFER_SYNTAX, "HEX")
+              # Reserved (1 byte)
+              @outgoing.encode_last("00", "HEX")
+              # Transfer syntax item length (2 bytes)
+              @outgoing.encode_last(t.length, "US")
+              # Transfer syntax (variable length)
+              @outgoing.encode_last(t, "STR")
+            end
           end
         end
       end