dicom 0.9.3 → 0.9.4

data/lib/dicom/image_processor.rb

@@ -1,12 +1,14 @@
 module DICOM
+
+  # This module is the general interface between the ImageItem class and the
+  # image methods found in the specific image processor modules.
+  #
   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.
+    # @param [Array<String>, String] blobs binary string blob(s) containing compressed pixel data
+    # @return [Array<MagickImage>, FalseClass] - an array of images, or false (if decompression failed)
     #
     def decompress(blobs)
       raise ArgumentError, "Expected Array or String, got #{blobs.class}." unless [String, Array].include?(blobs.class)
@@ -20,9 +22,9 @@ module DICOM
 
     # Extracts an array of pixels (integers) from an image object.
     #
-    # === Parameters
-    #
-    # * <tt>image</tt> -- An Rmagick image object.
+    # @param [MagickImage] image a Magick image object
+    # @param [String] photometry a code describing the photometry of the pixel data (e.g. 'MONOCHROME1' or 'COLOR')
+    # @return [Array<Integer>] an array of pixel values
     #
     def export_pixels(image, photometry)
       raise ArgumentError, "Expected String, got #{photometry.class}." unless photometry.is_a?(String)
@@ -31,20 +33,21 @@ module DICOM
 
     # 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'.
+    # @param [String] blob binary string blob containing pixel data
+    # @param [Integer] columns the number of columns
+    # @param [Integer] rows the number of rows
+    # @param [Integer] depth the bit depth of the encoded pixel data
+    # @param [String] photometry a code describing the photometry of the pixel data (e.g. 'MONOCHROME1' or 'COLOR')
+    # @return [MagickImage] a Magick image object
     #
     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.
+    # Gives an array containing the image objects that are supported by the image processor.
+    #
+    # @return [Array] the valid image classes
     #
     def valid_image_objects
       return [Magick::Image, MiniMagick::Image]
@@ -54,6 +57,12 @@ module DICOM
     private
 
 
+    # Gives the specific image processor module corresponding to the specified
+    # image_processor module option.
+    #
+    # @raise [RuntimeError] if an unknown image processor is specified
+    # @return [DcmMiniMagick, DcmRMagick] the image processor module to be used
+    #
     def image_module
       case DICOM.image_processor
       when :mini_magick

data/lib/dicom/image_processor_mini_magick.rb

@@ -1,15 +1,16 @@
 module DICOM
   module ImageProcessor
+
+    # This module contains methods for interacting with pixel data using the mini_magick gem.
+    #
     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.
+        # @param [Array<String>] blobs an array of binary string blobs containing compressed pixel data
+        # @return [Array<MiniMagick::Image>, FalseClass] - an array of images, or false (if decompression failed)
         #
         def decompress(blobs)
           images = Array.new
@@ -22,39 +23,36 @@ module DICOM
 
         # 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).
+        # @note 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.
+        # @param [MiniMagick::Image] image a mini_magick image object
+        # @param [String] photometry a code describing the photometry of the pixel data (e.g. 'MONOCHROME1' or 'COLOR')
+        # @return [Array<Integer>] an array of pixel values
         #
         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
+        # Creates an image object from a binary string blob.
         #
-        # * <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'.
+        # @param [String] blob binary string blob containing pixel data
+        # @param [Integer] columns the number of columns
+        # @param [Integer] rows the number of rows
+        # @param [Integer] depth the bit depth of the encoded pixel data
+        # @param [String] photometry a code describing the photometry of the pixel data (e.g. 'MONOCHROME1' or 'COLOR')
+        # @param [String] format the image format to use
+        # @return [Magick::Image] a mini_magick image object
         #
         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
+        # Converts a given DICOM photometry string to a mini_magick pixel map string.
         #
-        # * <tt>photometry</tt> -- String describing the photometry of the pixel data. Example: 'MONOCHROME1' or 'COLOR'.
+        # @param [String] photometry a code describing the photometry of the pixel data (e.g. 'MONOCHROME1' or 'COLOR')
+        # @return [String] a mini_magick pixel map string
         #
         def im_map(photometry)
           raise ArgumentError, "Expected String, got #{photometry.class}." unless photometry.is_a?(String)

data/lib/dicom/image_processor_r_magick.rb

@@ -1,35 +1,38 @@
 module DICOM
   module ImageProcessor
+
+    # This module contains methods for interacting with pixel data using the RMagick gem.
+    #
     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
+        # === Note
         #
-        # 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.
+        # The method tries to use RMagick for unpacking, but unortunately, 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/
+        # 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 out 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"
+        # @param [Array<String>] blobs an array of binary string blobs containing compressed pixel data
+        # @return [Array<Magick::Image>, FalseClass] - an array of images, or false (if decompression failed)
         #
         def decompress(blobs)
+          # FIXME:
+          # 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"
+          #
           images = Array.new
           # We attempt to decompress the pixels using ImageMagick:
             blobs.each do |string|
@@ -40,9 +43,9 @@ module DICOM
 
         # Extracts an array of pixels (integers) from an image object.
         #
-        # === Parameters
-        #
-        # * <tt>image</tt> -- An Rmagick image object.
+        # @param [Magick::Image] image an RMagick image object
+        # @param [String] photometry a code describing the photometry of the pixel data (e.g. 'MONOCHROME1' or 'COLOR')
+        # @return [Array<Integer>] an array of pixel values
         #
         def export_pixels(image, photometry)
           raise ArgumentError, "Expected Magick::Image, got #{image.class}." unless image.is_a?(Magick::Image)
@@ -50,22 +53,25 @@ module DICOM
           return pixels
         end
 
-        # Creates an image object from a binary string blob which contains raw pixel data.
+        # 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.
-        # * <tt>format</tt> -- String describing the image format to be used when creating the image object. Defaults to 'png'.
+        # @param [String] blob binary string blob containing pixel data
+        # @param [Integer] columns the number of columns
+        # @param [Integer] rows the number of rows
+        # @param [Integer] depth the bit depth of the encoded pixel data
+        # @param [String] photometry a code describing the photometry of the pixel data (e.g. 'MONOCHROME1' or 'COLOR')
+        # @param [String] format the image format to use
+        # @return [Magick::Image] an RMagick image object
         #
         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.
+        # Converts a given bit depth to an RMagick StorageType.
+        #
+        # @raise [ArgumentError] if given an unsupported bit depth
+        # @param [Integer] bit_depth the bit depth of the pixel data
+        # @return [Magick::CharPixel, Magick::ShortPixel] the proper storage type
         #
         def rm_data_type(bit_depth)
           return case bit_depth
@@ -78,11 +84,10 @@ module DICOM
           end
         end
 
-        # Returns an RMagick pixel map string based on the input DICOM photometry string.
-        #
-        # === Parameters
+        # Converts a given DICOM photometry string to an RMagick pixel map string.
         #
-        # * <tt>photometry</tt> -- String describing the photometry of the pixel data. Example: 'MONOCHROME1' or 'COLOR'.
+        # @param [String] photometry a code describing the photometry of the pixel data (e.g. 'MONOCHROME1' or 'COLOR')
+        # @return [String] an RMagick pixel map string
         #
         def rm_map(photometry)
           raise ArgumentError, "Expected String, got #{photometry.class}." unless photometry.is_a?(String)

data/lib/dicom/item.rb

@@ -1,121 +1,134 @@
-module DICOM
-
-  # The Item class handles information related to items - the elements contained in sequences.
-  #
-  # === 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 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
-
-    # Creates an Item instance.
-    #
-    # === Notes
-    #
-    # Normally, an Item contains data elements and/or sequences. However, in some cases, an Item will instead/also
-    # carry binary string data, like the pixel data of an encapsulated image fragment.
-    #
-    # === Parameters
-    #
-    # * <tt>options</tt> -- A hash of parameters.
-    #
-    # === Options
-    #
-    # * <tt>:bin</tt> -- A binary string to be carried by the Item.
-    # * <tt>:index</tt> -- Fixnum. If the Item is to be inserted at a specific index (Item number), this option parameter needs to set.
-    # * <tt>:length</tt> -- Fixnum. The Item length (which either refers to the length of the encoded string of children of this Item, or the length of its binary data).
-    # * <tt>:name</tt> - String. The name of the Item may be specified upon creation. If it is not, a default name is chosen.
-    # * <tt>:parent</tt> - Sequence or DObject instance which the Item instance shall belong to.
-    # * <tt>:vr</tt> -- String. The value representation of the Item may be specified upon creation. If it is not, a default vr is chosen.
-    #
-    # === Examples
-    #
-    #   # Create an empty Item and connect it to the "Structure Set ROI Sequence":
-    #   item = Item.new(:parent => dcm["3006,0020"])
-    #   # Create a "Pixel Data Item" which carries an encapsulated image frame (a pre-encoded binary):
-    #   pixel_item = Item.new(:bin => processed_pixel_data, :parent => dcm["7FE0,0010"][1])
-    #
-    def initialize(options={})
-      # Set common parent variables:
-      initialize_parent
-      # Set instance variables:
-      @tag = ITEM_TAG
-      @value = nil
-      @name = options[:name] || "Item"
-      @vr = options[:vr] || ITEM_VR
-      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], :no_follow => true)
-      end
-    end
-
-    # Returns true if the argument is an instance with attributes equal to self.
-    #
-    def ==(other)
-      if other.respond_to?(:to_item)
-        other.send(:state) == state
-      end
-    end
-
-    alias_method :eql?, :==
-
-    # Sets the binary string that the Item will contain.
-    #
-    # === Parameters
-    #
-    # * <tt>new_bin</tt> -- A binary string of encoded data.
-    #
-    # === Examples
-    #
-    #   # Insert a custom jpeg in the (encapsulated) pixel data element, in it's first pixel data item:
-    #   dcm["7FE0,0010"][1].children.first.bin = jpeg_binary_string
-    #
-    def bin=(new_bin)
-      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.odd?
-        @bin = new_bin + "\x00"
-      else
-        @bin = new_bin
-      end
-      @value = nil
-      @length = @bin.length
-    end
-
-    # Generates a Fixnum hash value for this instance.
-    #
-    def hash
-      state.hash
-    end
-
-    # Returns self.
-    #
-    def to_item
-      self
-    end
-
-
-    private
-
-
-    # Returns the attributes of this instance in an array (for comparison purposes).
-    #
-    def state
-      [@vr, @name, @tags]
-    end
-
-  end
+module DICOM
+
+  # The Item class handles information related to items - the elements contained in sequences.
+  #
+  # === 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 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
+
+    # Creates an Item instance.
+    #
+    # Normally, an Item contains data elements and/or sequences. However,
+    # in some cases, an Item will instead/also carry binary string data,
+    # like the pixel data of an encapsulated image fragment.
+    #
+    # @param [Hash] options the options to use for creating the item
+    # @option options [String] :bin a binary string to be carried by the item
+    # @option options [String] :indexif the item is to be inserted at a specific index (Item number), this option parameter needs to set
+    # @option options [String] :length theiItem length (which either refers to the length of the encoded string of children of this item, or the length of its binary data)
+    # @option options [String] :name the name of the item may be specified upon creation  (if not, a default name is used)
+    # @option options [String] :parent a Sequence or DObject instance which the item instance shall belong to
+    # @option options [String] :vr the value representation of the item may be specified upon creation (if not, a default vr is used)
+    #
+    # @example Create an empty Item and connect it to the "Structure Set ROI Sequence"
+    #   item = Item.new(:parent => dcm["3006,0020"])
+    # @example Create a "Pixel Data Item" which carries an encapsulated image frame (a pre-encoded binary)
+    #   pixel_item = Item.new(:bin => processed_pixel_data, :parent => dcm["7FE0,0010"][1])
+    #
+    def initialize(options={})
+      # Set common parent variables:
+      initialize_parent
+      # Set instance variables:
+      @tag = ITEM_TAG
+      @value = nil
+      @name = options[:name] || "Item"
+      @vr = options[:vr] || ITEM_VR
+      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], :no_follow => true)
+      end
+    end
+
+    # Checks for equality.
+    #
+    # Other and self are considered equivalent if they are
+    # of compatible types and their attributes are equivalent.
+    #
+    # @param other an object to be compared with self.
+    # @return [Boolean] true if self and other are considered equivalent
+    #
+    def ==(other)
+      if other.respond_to?(:to_item)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Sets the binary string that the Item will contain.
+    #
+    # @param [String] new_bin a binary string of encoded data
+    # @example Insert a custom jpeg in the (encapsulated) pixel data element (in it's first pixel data item)
+    #   dcm['7FE0,0010'][1].children.first.bin = jpeg_binary_string
+    #
+    def bin=(new_bin)
+      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.odd?
+        @bin = new_bin + "\x00"
+      else
+        @bin = new_bin
+      end
+      @value = nil
+      @length = @bin.length
+    end
+
+    # Computes a hash code for this object.
+    #
+    # @note Two objects with the same attributes will have the same hash code.
+    #
+    # @return [Fixnum] the object's hash code
+    #
+    def hash
+      state.hash
+    end
+
+    # Loads data from an encoded DICOM string and creates
+    # sequences and elements which are linked to this instance.
+    #
+    # @param [String] bin an encoded binary string containing DICOM information
+    # @param [String] syntax the transfer syntax to use when decoding the DICOM string
+    #
+    def parse(bin, syntax)
+      raise ArgumentError, "Invalid argument 'bin'. Expected String, got #{bin.class}." unless bin.is_a?(String)
+      raise ArgumentError, "Invalid argument 'syntax'. Expected String, got #{syntax.class}." unless syntax.is_a?(String)
+      read(bin, signature=false, :syntax => syntax)
+    end
+
+    # Returns self.
+    #
+    # @return [Item] self
+    #
+    def to_item
+      self
+    end
+
+
+    private
+
+
+    # Collects the attributes of this instance.
+    #
+    # @return [Array<String, Sequence, Element>] an array of attributes
+    #
+    def state
+      [@vr, @name, @tags]
+    end
+
+  end
 end