dicom 0.1 → 0.2

data/CHANGELOG

@@ -1,3 +1,14 @@
+= 0.2
+
+=== 10th August, 2008
+
+* Data dictionary has been upgraded and is now compliant to the official standard.
+* New DLibrary class which handles all interaction with the dictionary.
+* Dictionary can be loaded before reading files, which will considerably speed up the process if reading multiple files.
+* Reading compressed pixel data into an RMagick object is supported in principle, although it lacks proper testing at this point.
+* DRead class is more resistant to breaking if it is handed a faulty file to read.
+* Added option to load DICOM object verbose or silent.
+
 = 0.1
 
 === 20th July, 2008
@@ -13,11 +24,12 @@ Features:
 * Retrieve image data as RMagick object
 * Print file properties
 * Print tag information
+
 
 Known issues:
 * 12 bit image data not supported
 * Color images not supported in NArray and RMagick retrieve methods
-* Unpacking compressed image data not supported
+* Unpacking compressed image data has basic support but is not properly tested yet.
 * Reading Big Endian files probably has some issues
 * Reading Little Endian files on a Big Endian system probably has issues as well
 * Reading of multiple frame image data is not particularly robust at this time

data/DOCUMENTATION

@@ -8,16 +8,30 @@ gem install dicom
 
 DOCUMENTATION
 
+CLASS DLibrary
+
+PUBLIC CLASS METHODS
+
+	new()
+
+		Initialize a new Library (dictionary) object.
+		Useful if you want to make a script that reads hundreds or thousands of DICOM files, because you can save time by loading the library one time at startup instead of having the library being loaded for each DICOM file being read.
+		Example:
+			lib = DLibrary.new()
+
+
 CLASS DObject
 
 PUBLIC CLASS METHODS
 
-	new(filename)
+	new(filename, *options)
 
 		Initialize a new DICOM object.
-		Example:
+		Example 1 (The simple way):
 			require 'dicom'
 			obj = DICOM::DObject.new("myFile.dcm")
+		Example 2 (Using a pre-loaded library to speed up reading when reading multiple files):
+			obj = DICOM::DObject.new("myFile.dcm", verbose=false, library=lib)
 
 PUBLIC INSTANCE METHODS
 

data/README

@@ -1,4 +1,4 @@
-DICOM Project for Ruby
+RUBY DICOM
 ======================
 
 SUMMARY
@@ -44,14 +44,15 @@ You should have received a copy of the GNU General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 
-ABOUT THE AUTHOR
-----------------
+ABOUT ME
+--------
 
 Name:
-Christoffer Lervåg
+Christoffer Lervåg
 
 Location:
 Oslo, Norway
 
 Email:
-chris.lervag@gmail.com
+chris.lervag @nospam @gmail.com
+Please don't hesitate to email me if have any thoughts on this project!

data/lib/DLibrary.rb

@@ -0,0 +1,105 @@
+module DICOM
+  # Class which holds the methods that interact with the DICOM dictionary.
+  class DLibrary
+
+    attr_reader :de_label, :de_vr, :de_name, :uid_value, :uid_name, :uid_type, :pi_type, :pi_description
+
+    # Initialize the DRead instance.
+    def initialize()
+      # Instance arrays which hold library content:
+      # Data elements:
+      @de_label = Array.new()
+      @de_vr = Array.new()
+      @de_name = Array.new()
+      # UID:
+      @uid_value = Array.new()
+      @uid_name = Array.new()
+      @uid_type = Array.new()
+      # Photometric Interpretation:
+      @pi_type = Array.new()
+      @pi_description = Array.new()
+      
+      # Load the dictionary:
+      dict = Dictionary.new()
+      # Data elements:
+      de = dict.load_tags()
+      @de_label = de[0]
+      @de_vr = de[1]
+      @de_name = de[2]
+      # Photometric Interpretation:
+      pi = dict.load_image_types()
+      @pi_type = pi[0]
+      @pi_description = pi[1]
+      # UID:
+      uid = dict.load_uid()
+      @uid_value = uid[0]
+      @uid_name = uid[1]
+      @uid_type = uid[2]
+    end
+
+
+    # Returns data element name and value representation from library if tag is recognised, else it returns "Unknown Name" and "UN".
+    def get_name_vr(label)
+      pos = get_pos(label)
+      if pos != nil
+        name = @de_name[pos]
+        vr = @de_vr[pos][0]
+      else
+        # For the labels that are not recognised, we need to do some additional testing to see if it is one of the special cases:
+        # Split label in group and element:
+        group = label[0..3]
+        element = label[5..8]
+        # Check for group length:
+        if element == "0000"
+          name = "Group Length"
+          vr = "UL"
+        end
+        # Source Image ID's: (Retired)
+        if label[0..6] == "0020,31"
+          pos = get_pos("0020,31xx")
+          name = @de_name[pos]
+          vr = @de_vr[pos][0]
+        end
+        # Group 50xx (retired) and 60xx:
+        if label[0..1] == "50" or label[0..1] == "60"
+          pos = get_pos(label[0..1]+"xx"+label[4..8])
+          if pos != nil
+            name = @de_name[pos]
+            vr = @de_vr[pos][0]
+          end
+        end
+        # If none of the above checks yielded a result, the label is unknown:
+        if name == nil
+          name = "Unknown Name"
+          vr = "UN"
+        end
+      end
+      return [name,vr]
+    end
+
+
+    # Checks whether a given string is a valid transfer syntax or not.
+    def check_transfer_syntax(label)
+      pos = @uid_value.index(label)
+      if pos >= 1 and pos <= 34
+        # Valid:
+        return true
+      else
+        # Invalid:
+        return false
+      end
+    end
+
+
+    # Following methods are private.
+    private
+
+    # Returns the position of the supplied data element name in the Dictionary array.
+    def get_pos(label)
+      pos = @de_label.index(label)
+      return pos
+    end
+
+
+  end # end of class
+end # end of module

data/lib/DObject.rb

@@ -17,21 +17,23 @@
 
 # TODO:
 # -Support for writing DICOM files.
-# -Support for compressed image data.
+# -Full support for compressed image data.
 # -Read 12 bit image data correctly.
 # -Support for color image data in get_image_narray() and get_image_magick().
 # -Proper support for Big endian.
 # -Proper support for multiple frame image data.
 # -Reading of image data in files that contain two different and unrelated images (observed in some MR images)
-# -A method to retrieve the index of tags contained within a sequence.
+# -A method to retrieve the index of all tags contained within a specific sequence.
 
 module DICOM
 
   # Class for handling the DICOM contents:
   class DObject
 
+    attr_reader :read_success
+
     # Initialize the DObject instance.
-    def initialize(file_name)
+    def initialize(file_name=nil, verbose=false, lib=nil)
       # Initialize the key variables for the DICOM object:
       @names = Array.new()
       @labels = Array.new()
@@ -39,6 +41,10 @@ module DICOM
       @lengths = Array.new()
       @values = Array.new()
       @raw = Array.new()
+      # Array that will holde any messages generated while reading the DICOM file:
+      @msg = Array.new()
+      # Array to keep track of sequences/structure of the dicom tags:
+      @sequence = Array.new()
       # Index of last element in tag arrays:
       @last_index=0
       # Structural information (default values):
@@ -46,7 +52,18 @@ module DICOM
       @color = false
       @explicit = true
       @file_endian = false
-      # If a file name string is supplied, launch the method to read DICOM file:
+      # Handling variables:
+      @verbose = verbose
+      # Control variables:
+      @read_success = false
+      # Load the library class (DICOM dictionary):
+      if lib != nil
+        # Library already specified by user:
+        @lib = lib
+      else
+        @lib = DLibrary.new()
+      end
+      # If a (valid) file name string is supplied, launch the method to read DICOM file:
       if file_name != nil and file_name != ""
         read_file(file_name)
       end
@@ -56,27 +73,70 @@ module DICOM
     # Returns a DICOM object by reading the file specified.
     # This is accomplished by initliazing the DRead class, which returns the DICOM object, if successful.
     # For the time being, this method is called automatically when initializing the DObject class,
-    # but in the future, when write support is added, this method will have to be activated or called manually.
+    # but in the future, when write support is added, this method may have to be called manually.
     def read_file(file_name)
       if file_name == nil or file_name == ""
-        puts "Warning: A valid file name string was not supplied to method read_file(). Returning false."
+        add_msg("Warning: A valid file name string was not supplied to method read_file(). Returning false.")
         return false
       else
-        dcm = DRead.new(file_name)
+        dcm = DRead.new(file_name, @lib)
         data = dcm.return_data()
-        @names = data[0]
-        @labels = data[1]
-        @types = data[2]
-        @lengths = data[3]
-        @values = data[4]
-        @raw = data[5]
-        # Other information:
-        @compression = data[6]
-        @color = data[7]
-        @explicit = data[8]
-        @file_endian = data[9]
-        # Index of last element in tag arrays:
-        @last_index=@names.length-1
+        # Store the data to the instance variables if the readout was a success:
+        if dcm.success
+          @read_success = true
+          @names = data[0]
+          @labels = data[1]
+          @types = data[2]
+          @lengths = data[3]
+          @values = data[4]
+          @raw = data[5]
+          # Other information:
+          @compression = data[6]
+          @color = data[7]
+          @explicit = data[8]
+          @file_endian = data[9]
+          # Index of last element in tag arrays:
+          @last_index=@names.length-1
+        end
+        # The messages must be stored regardless of success or failure:
+        messages = data[10]
+        # If any messages has been recorded, send these to the message handling method:
+        if messages.size != 0
+          add_msg(messages)
+        end
+      end
+    end
+
+
+    # Adds a warning or error message to the instance array holding messages, and if verbose variable is true, prints the message as well.
+    def add_msg(msg)
+      if @verbose
+        puts msg
+      end
+      if (msg.is_a? String)
+        msg=[msg]
+      end
+      @msg += msg
+    end
+
+
+    # Returns image data from the provided tag index, performing decompression of data if necessary.
+    def read_image_magick(pos, columns, rows)
+      if @compression != true
+        # Non-compressed, just return the array contained in the particular tag:
+        image_data=get_value(pos)
+        image = Magick::Image.new(columns,rows)
+        image.import_pixels(0, 0, columns, rows, "I", image_data)
+        return image
+      else
+        # Image data is compressed, we will attempt to unpack it using RMagick (ImageMagick):
+        begin
+          image = Magick::Image.from_blob(@raw[pos])
+          return image
+        rescue
+          add_msg("RMagick did not succeed in decoding the compressed image data. Returning false.")
+          return false
+        end
       end
     end
 
@@ -86,22 +146,22 @@ module DICOM
     def get_image_narray()
       # Does pixel data exist at all in the DICOM object?
       if @compression == nil
-        puts "It seems pixel data is not present in this DICOM object: returning false."
+        add_msg("It seems pixel data is not present in this DICOM object: returning false.")
         return false
       end
       # No support yet for retrieving compressed data:
-      if @compression != false and @compression != nil
-        puts "Warning: Unpacking compressed pixel data is not supported yet for this method: returning false."
+      if @compression == true
+        add_msg("Reading compressed data to a NArray object not supported yet: returning false.")
         return false
       end
       # No support yet for retrieving color pixel data:
       if @color
-        puts "Warning: Unpacking color pixel data is not supported yet for this method: returning false."
+        add_msg("Warning: Unpacking color pixel data is not supported yet for this method: returning false.")
         return false
       end
       # Gather information about the dimensions of the image data:
-      rows = get_value("0028.0010")
-      columns = get_value("0028.0011")
+      rows = get_value("0028,0010")
+      columns = get_value("0028,0011")
       frames = get_frames()
       image_pos = get_image_pos()
       # Creating a NArray object using int to make sure we have a big enough range for our numbers:
@@ -112,6 +172,7 @@ module DICOM
       if image_pos.size == 1
         # All of the image data is located in one tag:
         image_data = get_value(image_pos[0])
+        #image_data = get_image_data(image_pos[0])
         (0..frames-1).each do |i|
           (0..columns*rows-1).each do |j|
             image_temp[j] = image_data[j+i*columns*rows]
@@ -122,6 +183,7 @@ module DICOM
         # Image data is encapsulated in items:
         (0..frames-1).each do |i|
           image_data=get_value(image_pos[i])
+          #image_data = get_image_data(image_pos[i])
           (0..columns*rows-1).each do |j|
             image_temp[j] = image_data[j+i*columns*rows]
           end
@@ -149,22 +211,17 @@ module DICOM
     def get_image_magick()
       # Does pixel data exist at all in the DICOM object?
       if @compression == nil
-        puts "It seems pixel data is not present in this DICOM object: returning false."
-        return false
-      end
-      # No support yet for retrieving compressed data:
-      if @compression != false and @compression != nil
-        puts "Warning: Unpacking compressed pixel data is not supported yet for this method: aborting."
+        add_msg("It seems pixel data is not present in this DICOM object: returning false.")
         return false
       end
       # No support yet for color pixel data:
       if @color
-        puts "Warning: Unpacking color pixel data is not supported yet for this method: aborting."
+        add_msg("Warning: Unpacking color pixel data is not supported yet for this method: aborting.")
         return false
       end
       # Gather information about the dimensions of the image data:
-      rows = get_value("0028.0010")
-      columns = get_value("0028.0011")
+      rows = get_value("0028,0010")
+      columns = get_value("0028,0011")
       frames = get_frames()
       image_pos = get_image_pos()
       # Array that will hold the RMagick image objects, one image object for each frame:
@@ -172,18 +229,25 @@ module DICOM
       # Handling of image data will depend on whether we have one or more frames,
       if image_pos.size == 1
         # All of the image data is located in one tag:
-        image_data = get_value(image_pos[0])
-        (0..frames-1).each do |i|
-          image = Magick::Image.new(columns,rows)
-          image.import_pixels(0, 0, columns, rows, "I", image_data)
-          image_arr[i] = image
+        #image_data = get_image_data(image_pos[0])
+        #(0..frames-1).each do |i|
+         # image = Magick::Image.new(columns,rows)
+         # image.import_pixels(0, 0, columns, rows, "I", image_data)
+         # image_arr[i] = image
+        #end
+        if frames > 1
+          add_msg("Unfortunately, this method only supports reading the first image frame as of now.")
         end
+        image = read_image_magick(image_pos[0], columns, rows)
+        image_arr[0] = image
+        #image_arr[i] = image
       else
         # Image data is encapsulated in items:
         (0..frames-1).each do |i|
-          image_data=get_value(image_pos[i])
-          image = Magick::Image.new(columns,rows)
-          image.import_pixels(0, 0, columns, rows, "I", image_data)
+          #image_data=get_image_data(image_pos[i])
+          #image = Magick::Image.new(columns,rows)
+          #image.import_pixels(0, 0, columns, rows, "I", image_data)
+          image = read_image_magick(image_pos[i], columns, rows)
           image_arr[i] = image
         end
       end
@@ -193,7 +257,7 @@ module DICOM
 
     # Returns the number of frames present in the image data in the DICOM file.
     def get_frames()
-      frames = get_value("0028.0008")
+      frames = get_value("0028,0008")
       if frames == false
         # If file does not specify number of tags, assume 1 image frame.
         frames = 1
@@ -204,8 +268,8 @@ module DICOM
 
     # Returns the index(es) of the tag(s) that contain image data.
     def get_image_pos()
-      image_tag_pos = get_pos("7FE0.0010")
-      item_pos = get_pos("FFFE.E000")
+      image_tag_pos = get_pos("7FE0,0010")
+      item_pos = get_pos("FFFE,E000")
       # Proceed only if image tag actually exists:
       if image_tag_pos == false
         return false
@@ -224,17 +288,16 @@ module DICOM
             # Determine which of these late item tags contain image data.
             # Usually, there are frames+1 late items, and all except
             # the first item contain an image frame:
-            frames = get_value("0028.0008")
-            if frames != false
+            frames = get_frames()
+            if frames != false  # note: function get_frames will never return false
               if late_item_pos.size == frames.to_i+1
                 return late_item_pos[1..late_item_pos.size-1]
               else
-                puts "Warning: Unexpected behaviour in DICOM file for method get_image_pos()."
-                puts "Expected number of image data items not equal to number of frames+1, returning false."
+                add_msg("Warning: Unexpected behaviour in DICOM file for method get_image_pos(). Expected number of image data items not equal to number of frames+1, returning false.")
                 return false
               end
             else
-              puts "Warning: Number of frames tag not found. Method get_image_pos() will return false."
+              add_msg("Warning: Number of frames tag not found. Method get_image_pos() will return false.")
               return false
             end
           end
@@ -264,16 +327,19 @@ module DICOM
     # Prints information of all tags stored in the DICOM object.
     # Calls private method print_index() to do the actual printing.
     def print_all()
-      # Extract information on the largest string in the array:
-      str_lengths=Array.new(@last_index+1,0)
-      (0..@last_index).each do |i|
-        str_lengths[i]=@names[i].length
-      end
-      maxL=str_lengths.max
-      # Print to screen in a neat way:
-      puts " "
-      (0..@last_index).each do |i|
-        print_index(i,maxL)
+      # Only proceed if some tags have been loaded:
+      if @names.length > 0
+        # Extract information on the largest string in the array:
+        str_lengths=Array.new(@last_index+1,0)
+        (0..@last_index).each do |i|
+          str_lengths[i]=@names[i].length
+        end
+        maxL=str_lengths.max
+        # Print to screen in a neat way:
+        puts " "
+        (0..@last_index).each do |i|
+          print_index(i,maxL)
+        end
       end
     end
 
@@ -283,7 +349,7 @@ module DICOM
     # Calls private method print_index() to do the actual printing.
     def print(id)
       if id == nil
-        puts "Please specify either a tag category name or a tag adress when using the print() function."
+        add_msg("Please specify either a tag category name or a tag adress when using the print() function.")
       else
         # First search the labels (Adresses):
         match=@labels.index(id)
@@ -291,7 +357,7 @@ module DICOM
           match=@names.index(id)
         end
         if match == nil
-          puts "Tag " + id + " not recognised in this DICOM file."
+          add_msg("Tag " + id + " not recognised in this DICOM file.")
         else
           print_index(match)
         end
@@ -303,7 +369,7 @@ module DICOM
 		# The ID may be a tag index, tag name or tag label.
     def get_value(id)
       if id == nil
-        puts "A tag label, category name or index number must be specified when calling the get_value() method!"
+        add_msg("A tag label, category name or index number must be specified when calling the get_value() method!")
         return false
       else
         # Assume we have been fed a tag label:
@@ -336,7 +402,7 @@ module DICOM
 		# The ID may be a tag index, tag name or tag label.
     def get_raw(id)
       if id == nil
-        puts "A tag label, category name or index number must be specified when calling the get_raw() method!"
+        add_msg("A tag label, category name or index number must be specified when calling the get_raw() method!")
         return false
       else
         # Assume we have been fed a tag label:
@@ -404,7 +470,7 @@ module DICOM
     # Optional argument [maxL] is used to format the printing, making it look nicer on screen.
     def print_index(pos,*maxL)
       if pos < 0 or pos > @last_index 
-        puts "The specified index "+pos.to_s+" is outside the bounds of the tags array."
+        add_msg("The specified index "+pos.to_s+" is outside the bounds of the tags array.")
       else
         if maxL[0] == nil
           maxL=@names[pos].length