dicom 0.8 → 0.9

data/lib/dicom/d_library.rb

@@ -1,11 +1,13 @@
-#    Copyright 2008-2010 Christoffer Lervag
-
 module DICOM
 
   # This class contains methods that interact with Ruby DICOM's dictionary.
   #
   class DLibrary
 
+    # A hash with element name strings as key and method name symbols as value.
+    attr_reader :methods_from_names
+    # A hash with element method name symbols as key and name strings as value.
+    attr_reader :names_from_methods
     # A hash containing tags as key and an array as value, where the array contains data element vr and name.
     attr_reader :tags
     # A hash containing UIDs as key and an array as value, where the array contains name and type.
@@ -20,6 +22,58 @@ module DICOM
       # Load UID hash (DICOM unique identifiers), where the keys are UID strings,
       # and values are two-element arrays [description, type]:
       @uid = Dictionary.load_uid
+      create_method_conversion_tables
+    end
+
+    # Returns the method (symbol) corresponding to the specified string value (which may represent a element tag, name or method).
+    # Returns nil if no match is found.
+    #
+    def as_method(value)
+      case true
+      when value.tag?
+        name, vr = get_name_vr(value)
+        @methods_from_names[name]
+      when value.dicom_name?
+        @methods_from_names[value]
+      when value.dicom_method?
+        @names_from_methods.has_key?(value.to_sym) ? value.to_sym : nil
+      else
+        nil
+      end
+    end
+
+    # Returns the name (string) corresponding to the specified string value (which may represent a element tag, name or method).
+    # Returns nil if no match is found.
+    #
+    def as_name(value)
+      case true
+      when value.tag?
+        name, vr = get_name_vr(value)
+        name
+      when value.dicom_name?
+        @methods_from_names.has_key?(value) ? value.to_s : nil
+      when value.dicom_method?
+        @names_from_methods[value.to_sym]
+      else
+        nil
+      end
+    end
+
+    # Returns the tag (string) corresponding to the specified string value (which may represent a element tag, name or method).
+    # Returns nil if no match is found.
+    #
+    def as_tag(value)
+      case true
+      when value.tag?
+        name, vr = get_name_vr(value)
+        name.nil? ? nil : value
+      when value.dicom_name?
+        get_tag(value)
+      when value.dicom_method?
+        get_tag(@names_from_methods[value.to_sym])
+      else
+        nil
+      end
     end
 
     # Checks whether a given string is a valid transfer syntax or not.
@@ -64,12 +118,12 @@ module DICOM
     # * <tt>uid</tt> -- String. A DICOM UID value.
     #
     def get_compression(uid)
+      raise ArgumentError, "Expected String, got #{uid.class}" unless uid.is_a?(String)
       result = false
-      if uid
-        value = @uid[uid]
-        if value
-          result = true if value[1] == "Transfer Syntax" and not value[0].include?("Endian")
-        end
+      value = @uid[uid]
+      if value
+        first_word = value[0].split(" ").first
+        result = true if value[1] == "Transfer Syntax" and not ["Implicit", "Explicit"].include?(first_word)
       end
       return result
     end
@@ -151,9 +205,15 @@ module DICOM
     #
     def get_tag(name)
       tag = nil
+      name = name.to_s.downcase
+      @tag_name_pairs_cache ||= Hash.new
+      return @tag_name_pairs_cache[name] unless @tag_name_pairs_cache[name].nil?
       @tags.each_pair do |key, value|
-        tag = key if value[1] == name
+        next unless value[1].downcase == name
+        tag = key
+        break
       end
+      @tag_name_pairs_cache[name]=tag
       return tag
     end
 
@@ -204,5 +264,25 @@ module DICOM
       return valid, explicit, endian
     end
 
+
+    private
+
+
+    # Creates the instance hashes that are used for name to/from method conversion.
+    #
+    def create_method_conversion_tables
+      if @methods_from_names.nil?
+        @methods_from_names = Hash.new
+        @names_from_methods = Hash.new
+        # Fill the hashes:
+        @tags.each_pair do |key, value|
+          name = value[1]
+          method_name = name.dicom_methodize
+          @methods_from_names[name] = method_name.to_sym
+          @names_from_methods[method_name.to_sym] = name
+        end
+      end
+    end
+
   end
 end

data/lib/dicom/d_object.rb

@@ -1,4 +1,18 @@
-#    Copyright 2008-2010 Christoffer Lervag
+# === TODO:
+#
+# * The retrieve file network functionality (get_image() in DClient class) has not been tested.
+# * Make the networking code more intelligent in its handling of unexpected network communication.
+# * Full support for compressed image data.
+# * Read/Write 12 bit image data.
+# * Full color support (RGB and PALETTE COLOR with get_object_magick() already implemented).
+# * Support for extraction of multiple encapsulated pixel data frames in get_image() and get_image_narray().
+# * Image handling currently ignores DICOM tags like Pixel Aspect Ratio, Image Orientation and (to some degree) Photometric Interpretation.
+# * More robust and flexible options for reorienting extracted pixel arrays?
+# * A curious observation: Creating a DLibrary instance is exceptionally slow on Ruby 1.9.1: 0.4 seconds versus ~0.01 seconds on Ruby 1.8.7!
+# * Add these as github issues and remove this list!
+
+
+#    Copyright 2008-2011 Christoffer Lervag
 #
 #    This program is free software: you can redistribute it and/or modify
 #    it under the terms of the GNU General Public License as published by
@@ -13,20 +27,6 @@
 #    You should have received a copy of the GNU General Public License
 #    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
-
-# === TODO:
-#
-# * The retrieve file network functionality (get_image() in DClient class) has not been tested.
-# * Make the networking code more intelligent in its handling of unexpected network communication.
-# * Full support for compressed image data.
-# * Read/Write 12 bit image data.
-# * Support for color image data.
-# * Complete support for Big endian (Everything but signed short and signed long has been implemented).
-# * Complete support for multiple frame image data to NArray and RMagick objects (partial support already featured).
-# * Image handling does not take into consideration DICOM tags which specify orientation, samples per pixel and photometric interpretation.
-# * More robust and flexible options for reorienting extracted pixel arrays?
-# * A curious observation: Creating a DLibrary instance is exceptionally slow on my Ruby 1.9.1 install: 0.4 seconds versus ~0.01 seconds on my Ruby 1.8.7 install!
-
 module DICOM
 
   # The DObject class is the main class for interacting with the DICOM object.
@@ -34,10 +34,10 @@ module DICOM
   #
   # === Inheritance
   #
-  # As the DObject class inherits from the SuperItem class, which itself inherits from the SuperParent class,
-  # all SuperItem and SuperParent methods are also available to instances of DObject.
+  # As the DObject class inherits from the ImageItem class, which itself inherits from the Parent class,
+  # all ImageItem and Parent methods are also available to instances of DObject.
   #
-  class DObject < SuperItem
+  class DObject < ImageItem
 
     # An array which contain any notices/warnings/errors that have been recorded for the DObject instance.
     attr_reader :errors
@@ -50,9 +50,12 @@ module DICOM
     # A boolean which is set as true if a DObject instance has been successfully written to file (or successfully encoded).
     attr_reader :write_success
 
+    alias_method :read?, :read_success
+    alias_method :written?, :write_success
+
     # Creates a DObject instance (DObject is an abbreviation for "DICOM object").
     #
-    # The DObject instance holds references to the different types of objects (DataElement, Item, Sequence)
+    # The DObject instance holds references to the different types of objects (Element, Item, Sequence)
     # that makes up a DICOM object. A DObject is typically buildt by reading and parsing a file or a
     # binary string, but can also be buildt from an empty state by the user.
     #
@@ -63,7 +66,7 @@ module DICOM
     #
     # === Options
     #
-    # * <tt>:bin</tt> -- Boolean. If set to true, string parameter will be interpreted as a binary DICOM string, and not a path string, which is the default behaviour.
+    # * <tt>:bin</tt> -- Boolean. If true, the string parameter will be interpreted as a binary DICOM string instead of a path string.
     # * <tt>:syntax</tt> -- String. If a syntax string is specified, the DRead class will be forced to use this transfer syntax when decoding the file/binary string.
     # * <tt>:verbose</tt> -- Boolean. If set to false, the DObject instance will run silently and not output warnings and error messages to the screen. Defaults to true.
     #
@@ -89,15 +92,17 @@ module DICOM
       @explicit = true
       @file_endian = false
       # Control variables:
-      @read_success = false
+      @read_success = nil
       # Initialize a Stream instance which is used for encoding/decoding:
       @stream = Stream.new(nil, @file_endian)
       # The DObject instance is the top of the hierarchy and unlike other elements it has no parent:
       @parent = nil
       # For convenience, call the read method if a string has been supplied:
-      if string.is_a?(String) and string != ""
+      if string.is_a?(String)
         @file = string unless options[:bin]
         read(string, options)
+      elsif string
+        raise ArgumentError, "Invalid argument. Expected String (or nil), got #{string.class}."
       end
     end
 
@@ -108,12 +113,16 @@ module DICOM
     # === Parameters
     #
     # * <tt>max_size</tt> -- An integer (Fixnum) which specifies the maximum allowed size of the binary data strings which will be encoded.
+    # * <tt>transfer_syntax</tt> -- The transfer syntax string to be used when encoding the DICOM object to string segments. When this method is used for making network packets, the transfer_syntax is not part of the object, and thus needs to be specified. Defaults to the DObject's transfer syntax/Implicit little endian.
     #
     # === Examples
     #
     #  encoded_strings = obj.encode_segments(16384)
     #
-    def encode_segments(max_size)
+    def encode_segments(max_size, transfer_syntax=transfer_syntax)
+      raise ArgumentError, "Invalid argument. Expected an Integer, got #{max_size.class}." unless max_size.is_a?(Integer)
+      raise ArgumentError, "Argument too low (#{max_size}), please specify a bigger Integer." unless max_size > 16
+      raise "Can not encode binary segments for an empty DICOM object." if children.length == 0
       w = DWrite.new(self, transfer_syntax, file_name=nil)
       w.encode_segments(max_size)
       # Write process succesful?
@@ -123,59 +132,97 @@ module DICOM
       return w.segments
     end
 
+    # Prints information of interest related to the DICOM object.
+    # Calls the print() method of Parent as well as the information() method of DObject.
+    #
+    def print_all
+      puts ""
+      print(:value_max => 30)
+      summary
+    end
+
+    # Fills a DICOM object by reading and parsing the specified DICOM file,
+    # and transfers the DICOM data to the DICOM object (self).
+    #
+    # === Notes
+    #
+    # This method is called automatically when initializing the DObject class with a file parameter.
+    # In practice this method is rarely called by the user.
+    #
+    # === Parameters
+    #
+    # * <tt>string</tt> -- A string which specifies either the path of a DICOM file to be loaded, or a binary DICOM string to be parsed.
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:bin</tt> -- Boolean. If true, the string parameter will be interpreted as a binary DICOM string instead of a path string.
+    # * <tt>:syntax</tt> -- String. If a syntax string is specified, the DRead class will be forced to use this transfer syntax when decoding the file/binary string.
+    #
+    def read(string, options={})
+      raise ArgumentError, "Invalid argument. Expected String, got #{string.class}." unless string.is_a?(String)
+      # Clear any existing DObject tags, then read:
+      @tags = Hash.new
+      r = DRead.new(self, string, options)
+      # If reading failed, and no transfer syntax was detected, we will make another attempt at reading the file while forcing explicit (little endian) decoding.
+      # This will help for some rare cases where the DICOM file is saved (erroneously, Im sure) with explicit encoding without specifying the transfer syntax tag.
+      if !r.success and !exists?("0002,0010")
+        # Clear the existing DObject tags:
+        @tags = Hash.new
+        r_explicit = DRead.new(self, string, :bin => options[:bin], :syntax => EXPLICIT_LITTLE_ENDIAN)
+        # Only extract information from this new attempt if it was successful:
+        r = r_explicit if r_explicit.success
+      end
+      # Store the data to the instance variables if the readout was a success:
+      if r.success
+        @read_success = true
+        # Update instance variables based on the properties of the DICOM object:
+        @explicit = r.explicit
+        @file_endian = r.file_endian
+        @signature = r.signature
+        @stream.endian = @file_endian
+      else
+        @read_success = false
+      end
+      # If any messages has been recorded, send these to the message handling method:
+      add_msg(r.msg) if r.msg.length > 0
+    end
+
     # Gathers key information about the DObject as well as some system data, and prints this information to the screen.
     #
     # This information includes properties like encoding, byte order, modality and various image properties.
     #
     #--
-    # FIXME: Perhaps this method should be split up in one or two separate methods which just builds the information arrays,
-    # and a third method for printing this to the screen.
+    # FIXME: Perhaps this method should be split up in one or two separate methods
+    # which just builds the information arrays, and a third method for printing this to the screen.
     #
-    def information
+    def summary
       sys_info = Array.new
       info = Array.new
       # Version of Ruby DICOM used:
       sys_info << "Ruby DICOM version:   #{VERSION}"
       # System endian:
-      if CPU_ENDIAN
-        cpu = "Big Endian"
-      else
-        cpu = "Little Endian"
-      end
+      cpu = (CPU_ENDIAN ? "Big Endian" : "Little Endian")
       sys_info << "Byte Order (CPU):     #{cpu}"
       # File path/name:
       info << "File:                 #{@file}"
       # Modality:
-      sop_class_uid = self["0008,0016"]
-      if sop_class_uid
-        modality = LIBRARY.get_syntax_description(sop_class_uid.value) || "Unknown UID!"
-      else
-        modality = "SOP Class not specified!"
-      end
+      modality = (exists?("0008,0016") ? LIBRARY.get_syntax_description(self["0008,0016"].value) : "SOP Class unknown or not specified!")
       info << "Modality:             #{modality}"
       # Meta header presence (Simply check for the presence of the transfer syntax data element), VR and byte order:
       transfer_syntax = self["0002,0010"]
       if transfer_syntax
         syntax_validity, explicit, endian = LIBRARY.process_transfer_syntax(transfer_syntax.value)
         if syntax_validity
-          meta_comment = ""
-          explicit_comment = ""
-          encoding_comment = ""
+          meta_comment, explicit_comment, encoding_comment = "", "", ""
         else
           meta_comment = " (But unknown/invalid transfer syntax: #{transfer_syntax})"
           explicit_comment = " (Assumed)"
           encoding_comment = " (Assumed)"
         end
-        if explicit
-          explicitness = "Explicit"
-        else
-          explicitness = "Implicit"
-        end
-        if endian
-          encoding = "Big Endian"
-        else
-          encoding = "Little Endian"
-        end
+        explicitness = (explicit ? "Explicit" : "Implicit")
+        encoding = (endian ? "Big Endian" : "Little Endian")
+        meta = "Yes#{meta_comment}"
       else
         meta = "No"
         explicitness = (@explicit == true ? "Explicit" : "Implicit")
@@ -183,11 +230,9 @@ module DICOM
         explicit_comment = " (Assumed)"
         encoding_comment = " (Assumed)"
       end
-      meta = "Yes#{meta_comment}"
-      explicit = "#{explicitness}#{explicit_comment}"
-      encoding = "#{encoding}#{encoding_comment}"
-      info << "Value Representation: #{explicit}"
-      info << "Byte Order (File):    #{encoding}"
+      info << "Meta Header:          #{meta}"
+      info << "Value Representation: #{explicitness}#{explicit_comment}"
+      info << "Byte Order (File):    #{encoding}#{encoding_comment}"
       # Pixel data:
       pixels = self[PIXEL_TAG]
       unless pixels
@@ -195,23 +240,23 @@ module DICOM
       else
         info << "Pixel Data:           Yes"
         # Image size:
-        cols = self["0028,0011"] || "Columns missing"
-        rows = self["0028,0010"] || "Rows missing"
-        info << "Image Size:           #{cols.value}*#{rows.value}"
+        cols = (exists?("0028,0011") ? self["0028,0011"].value : "Columns missing")
+        rows = (exists?("0028,0010") ? self["0028,0010"].value : "Rows missing")
+        info << "Image Size:           #{cols}*#{rows}"
         # Frames:
-        frames = self["0028,0008"] || "1"
-        if frames != "1"
+        frames = value("0028,0008") || "1"
+        unless frames == "1" or frames == 1
           # Encapsulated or 3D pixel data:
-          if pixels.is_a?(DataElement)
-            frames = frames.value + " (3D Pixel Data)"
+          if pixels.is_a?(Element)
+            frames = frames.to_s + " (3D Pixel Data)"
           else
-            frames = frames.value + " (Encapsulated Multiframe Image)"
+            frames = frames.to_s + " (Encapsulated Multiframe Image)"
           end
         end
         info << "Number of frames:     #{frames}"
         # Color:
-        colors = self["0028,0004"] || "Not specified"
-        info << "Photometry:           #{colors.value}"
+        colors = (exists?("0028,0004") ? self["0028,0004"].value : "Not specified")
+        info << "Photometry:           #{colors}"
         # Compression:
         if transfer_syntax
           compression = LIBRARY.get_compression(transfer_syntax.value)
@@ -225,14 +270,13 @@ module DICOM
         end
         info << "Compression:          #{compression}"
         # Pixel bits (allocated):
-        bits = self["0028,0100"] || "Not specified"
-        info << "Bits per Pixel:       #{bits.value}"
+        bits = (exists?("0028,0100") ? self["0028,0100"].value : "Not specified")
+        info << "Bits per Pixel:       #{bits}"
       end
       # Print the DICOM object's key properties:
       separator = "-------------------------------------------"
-      puts "\n"
       puts "System Properties:"
-      puts separator
+      puts separator + "\n"
       puts sys_info
       puts "\n"
       puts "DICOM Object Properties:"
@@ -242,52 +286,6 @@ module DICOM
       return info
     end
 
-    # Prints information of interest related to the DICOM object.
-    # Calls the print() method of SuperParent as well as the information() method of DObject.
-    #
-    def print_all
-      puts ""
-      print(:value_max => 30)
-      information
-    end
-
-    # Returns a DICOM object by reading and parsing the specified file.
-    # This is accomplished by initializing the DRead class, which loads DICOM information to arrays.
-    #
-    # === Notes
-    #
-    # This method is called automatically when initializing the DObject class with a file parameter,
-    # and in practice should not be called by users.
-    #
-    #--
-    # FIXME: It should be considered whether this should be a private method.
-    #
-    def read(string, options={})
-      r = DRead.new(self, string, options)
-      # If reading failed, and no transfer syntax was detected, we will make another attempt at reading the file while forcing explicit (little endian) decoding.
-      # This will help for some rare cases where the DICOM file is saved (erroneously, Im sure) with explicit encoding without specifying the transfer syntax tag.
-      unless r.success or exists?("0002,0010")
-        # Clear the existing DObject tags:
-        @tags = Hash.new
-        r_explicit = DRead.new(self, string, :bin => options[:bin], :syntax => EXPLICIT_LITTLE_ENDIAN)
-        # Only extract information from this new attempt if it was successful:
-        r = r_explicit if r_explicit.success
-      end
-      # Store the data to the instance variables if the readout was a success:
-      if r.success
-        @read_success = true
-        # Update instance variables based on the properties of the DICOM object:
-        @explicit = r.explicit
-        @file_endian = r.file_endian
-        @signature = r.signature
-        @stream.endian = @file_endian
-      else
-        @read_success = false
-      end
-      # If any messages has been recorded, send these to the message handling method:
-      add_msg(r.msg) if r.msg.length > 0
-    end
-
     # Returns the transfer syntax string of the DObject.
     #
     # If a transfer syntax has not been defined in the DObject, a default tansfer syntax is assumed and returned.
@@ -296,7 +294,7 @@ module DICOM
       return value("0002,0010") || IMPLICIT_LITTLE_ENDIAN
     end
 
-    # Changes the transfer syntax DataElement of the DObject instance, and performs re-encoding of all
+    # Changes the transfer syntax Element of the DObject instance, and performs re-encoding of all
     # numerical values if a switch of endianness is implied.
     #
     # === Restrictions
@@ -309,28 +307,20 @@ module DICOM
     # * <tt>new_syntax</tt> -- The new transfer syntax string which will be applied to the DObject.
     #
     def transfer_syntax=(new_syntax)
-      valid, new_explicit, new_endian = LIBRARY.process_transfer_syntax(new_syntax)
-      if valid
-        # Get the old transfer syntax and write the new one to the DICOM object:
-        old_syntax = transfer_syntax
-        valid, old_explicit, old_endian = LIBRARY.process_transfer_syntax(old_syntax)
-        if exists?("0002,0010")
-          self["0002,0010"].value = new_syntax
-        else
-          add(DataElement.new("0002,0010", new_syntax))
-        end
-        # Update our Stream instance with the new encoding:
-        @stream.endian = new_endian
-        # Determine if re-encoding is needed:
-        if old_endian != new_endian
-          # Re-encode all Data Elements with number values:
-          encode_children(old_endian)
-        else
-          add_msg("New transfer syntax #{new_syntax} does not change encoding: No re-encoding needed.")
-        end
+      valid_ts, new_explicit, new_endian = LIBRARY.process_transfer_syntax(new_syntax)
+      raise ArgumentError, "Invalid transfer syntax specified: #{new_syntax}" unless valid_ts
+      # Get the old transfer syntax and write the new one to the DICOM object:
+      old_syntax = transfer_syntax
+      valid_ts, old_explicit, old_endian = LIBRARY.process_transfer_syntax(old_syntax)
+      if exists?("0002,0010")
+        self["0002,0010"].value = new_syntax
       else
-        raise "Invalid transfer syntax specified: #{new_syntax}"
+        add(Element.new("0002,0010", new_syntax))
       end
+      # Update our Stream instance with the new encoding:
+      @stream.endian = new_endian
+      # If endianness is changed, re-encode elements (only elements depending on endianness will actually be re-encoded):
+      encode_children(old_endian) if old_endian != new_endian
     end
 
     # Passes the DObject to the DWrite class, which traverses the data element
@@ -350,6 +340,7 @@ module DICOM
     #   obj.write(path + "test.dcm")
     #
     def write(file_name, options={})
+      raise ArgumentError, "Invalid file_name. Expected String, got #{file_name.class}." unless file_name.is_a?(String)
       insert_missing_meta unless options[:add_meta] == false
       w = DWrite.new(self, transfer_syntax, file_name, options)
       w.write
@@ -374,7 +365,7 @@ module DICOM
     def add_msg(msg)
       puts msg if @verbose
       @errors << msg
-      @errors.flatten
+      @errors.flatten!
     end
 
     # Adds any missing meta group (0002,xxxx) data elements to the DICOM object,
@@ -382,23 +373,24 @@ module DICOM
     #
     def insert_missing_meta
       # File Meta Information Version:
-      DataElement.new("0002,0001", [0,1], :parent => self) unless exists?("0002,0001")
+      Element.new("0002,0001", [0,1], :parent => self) unless exists?("0002,0001")
       # Media Storage SOP Class UID:
-      DataElement.new("0002,0002", value("0008,0016"), :parent => self) unless exists?("0002,0002")
+      Element.new("0002,0002", value("0008,0016"), :parent => self) unless exists?("0002,0002")
       # Media Storage SOP Instance UID:
-      DataElement.new("0002,0003", value("0008,0018"), :parent => self) unless exists?("0002,0003")
+      Element.new("0002,0003", value("0008,0018"), :parent => self) unless exists?("0002,0003")
       # Transfer Syntax UID:
-      DataElement.new("0002,0010", transfer_syntax, :parent => self) unless exists?("0002,0010")
-      # Implementation Class UID:
-      DataElement.new("0002,0012", UID, :parent => self) unless exists?("0002,0012")
-      # Implementation Version Name:
-      DataElement.new("0002,0013", NAME, :parent => self) unless exists?("0002,0013")
+      Element.new("0002,0010", transfer_syntax, :parent => self) unless exists?("0002,0010")
+      if !exists?("0002,0012") and !exists?("0002,0013")
+        # Implementation Class UID:
+        Element.new("0002,0012", UID, :parent => self)
+        # Implementation Version Name:
+        Element.new("0002,0013", NAME, :parent => self)
+      end
       # Source Application Entity Title:
-      DataElement.new("0002,0016", SOURCE_APP_TITLE, :parent => self) unless exists?("0002,0016")
-      # Group length:
-      # Remove old group length (if it exists) before creating a new one:
+      Element.new("0002,0016", DICOM.source_app_title, :parent => self) unless exists?("0002,0016")
+      # Group Length: Remove the old one (if it exists) before creating a new one.
       remove("0002,0000")
-      DataElement.new("0002,0000", meta_group_length, :parent => self)
+      Element.new("0002,0000", meta_group_length, :parent => self)
     end
 
     # Determines and returns the length of the meta group in the DObject instance.