dicom 0.1

data/DOCUMENTATION

@@ -0,0 +1,66 @@
+DICOM is a small library for reading DICOM files. It is written completely in Ruby and has no external dependencies.
+
+Copyright 2008 Christoffer Lervåg (chris.lervag@gmail.com)
+
+INSTALLATION
+
+gem install dicom
+
+DOCUMENTATION
+
+CLASS DObject
+
+PUBLIC CLASS METHODS
+
+	new(filename)
+
+		Initialize a new DICOM object.
+		Example:
+			require 'dicom'
+			obj = DICOM::DObject.new("myFile.dcm")
+
+PUBLIC INSTANCE METHODS
+
+	get_frames()
+		Returns the number of frames present in the image data in the DICOM file.
+
+	get_image_magick()
+		Returns an array of RMagick image objects, where the size of the array corresponds with the number of frames in the image data.
+		To call this method the user needs to have performed " require 'RMagick' " in advance.
+		Example (retrieve object and display first frame):
+		require 'RMagick'
+		data = dicom.get_image_magick()
+		data[0].display
+
+	get_image_narray()
+		Returns a 3d NArray object where the array dimensions are related to [frames, columns, rows].
+		To call this method the user needs to have performed " require 'narray' " in advance.
+		Example (retrieve object and display first frame):
+			require 'narray'
+			require 'nimage'
+			data = obj.get_image_narray()
+			NImage.show data[0,true,true]
+
+	get_image_pos()
+		Returns the index(es) of the tag(s) that contain image data.
+
+	get_pos(label)
+		Returns the index(es) of the tag(s) in the DICOM file that match the supplied tag label.
+
+	get_raw(id)
+		Returns the raw data of the DICOM tag that matches the supplied tag ID.
+		The ID may be a tag index, tag name or tag label.
+
+	get_value(id)
+		Returns the value (processed raw data) of the DICOM tag that matches the supplied tag ID.
+		The ID may be a tag index, tag name or tag label.
+
+	print(id)
+		Prints the information of a specific tag (index, label, name, type, length, value).
+		The ID may be a tag name or tag label.
+
+	print_all()
+		Prints information of all tags stored in the DICOM object.
+
+	print_properties()
+		Prints the key structural properties of the DICOM file.

data/README

@@ -0,0 +1,57 @@
+DICOM Project for Ruby
+======================
+
+SUMMARY
+--------
+
+This is a fairly basic library for reading DICOM files in Ruby. Digital Imaging and Communications in Medicine (DICOM) is a standard for handling, storing, printing, and transmitting information in medical imaging. It includes a file format definition and a network communications protocol. The library currently only supports reading of the file format.
+
+BASIC USAGE
+-----------
+
+require 'dicom'
+# Read file:
+dcm = DICOM::DObject.new("myFile.dcm")
+# Check out the contents:
+dcm.print_all()
+# Retrieve a tag value:
+name = dcm.get_value("0010.0010")
+# Retrieve pixel data:
+pixels = dcm.get_value("7FE0.0010")
+# Load pixel data in a RMagick object and display on screen:
+image = dcm.get_image_magick()
+image[0].display
+# Load pixel data in a NArray object and display on screen:
+image = dcm.get_image_narray()
+NImage.show image[0,true,true]
+  
+COPYRIGHT
+---------
+
+Copyright 2008 Christoffer Lervåg
+
+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
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+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
+----------------
+
+Name:
+Christoffer Lervåg
+
+Location:
+Oslo, Norway
+
+Email:
+chris.lervag@gmail.com

data/lib/DObject.rb

@@ -0,0 +1,439 @@
+#    Copyright 2008 Christoffer Lerv�g
+
+#    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
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+
+#    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:
+# -Support for writing DICOM files.
+# -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.
+
+module DICOM
+
+  # Class for handling the DICOM contents:
+  class DObject
+
+    # Initialize the DObject instance.
+    def initialize(file_name)
+      # Initialize the key variables for the DICOM object:
+      @names = Array.new()
+      @labels = Array.new()
+      @types = Array.new()
+      @lengths = Array.new()
+      @values = Array.new()
+      @raw = Array.new()
+      # Index of last element in tag arrays:
+      @last_index=0
+      # Structural information (default values):
+      @compression = false
+      @color = false
+      @explicit = true
+      @file_endian = false
+      # If a file name string is supplied, launch the method to read DICOM file:
+      if file_name != nil and file_name != ""
+        read_file(file_name)
+      end
+    end
+
+
+    # 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.
+    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."
+        return false
+      else
+        dcm = DRead.new(file_name)
+        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
+      end
+    end
+
+
+    # Returns a 3d NArray object where the array dimensions are related to [frames, columns, rows].
+		# To call this method the user needs to have performed " require 'narray' " in advance.
+    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."
+        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."
+        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."
+        return false
+      end
+      # Gather information about the dimensions of the image data:
+      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:
+      image = NArray.int(frames,columns,rows)
+      image_temp = NArray.int(columns,rows)
+      # Handling of image data will depend on whether we have one or more frames,
+      # and if it is located in one or more tags:
+      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|
+          (0..columns*rows-1).each do |j|
+            image_temp[j] = image_data[j+i*columns*rows]
+          end
+          image[i,true,true] = image_temp
+        end
+      else
+        # Image data is encapsulated in items:
+        (0..frames-1).each do |i|
+          image_data=get_value(image_pos[i])
+          (0..columns*rows-1).each do |j|
+            image_temp[j] = image_data[j+i*columns*rows]
+          end
+          image[i,true,true] = image_temp
+        end
+      end
+      # Turn around the images to get the expected orientation when displaying on the screen:
+      (0..frames-1).each do |i|
+        temp_image=image[i,true,true]
+        #Transpose the images:
+        temp_image.transpose(1,0)
+        #Need to mirror the y-axis:
+        (0..temp_image.shape[0]-1).each do |j|
+          temp_image[j,0..temp_image.shape[1]-1] = temp_image[j,temp_image.shape[1]-1..0]
+        end
+        # Put the reoriented image back in the image matrixx:
+        image[i,true,true]=temp_image
+      end
+      return image
+    end
+
+
+    # Returns an array of RMagick image objects, where the size of the array corresponds with the number of frames in the image data.
+		# To call this method the user needs to have performed " require 'RMagick' " in advance.
+    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."
+        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."
+        return false
+      end
+      # Gather information about the dimensions of the image data:
+      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:
+      image_arr = Array.new(frames)
+      # 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
+        end
+      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_arr[i] = image
+        end
+      end
+      return image_arr
+    end
+
+
+    # Returns the number of frames present in the image data in the DICOM file.
+    def get_frames()
+      frames = get_value("0028.0008")
+      if frames == false
+        # If file does not specify number of tags, assume 1 image frame.
+        frames = 1
+      end
+      return frames.to_i
+    end
+
+
+    # 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")
+      # Proceed only if image tag actually exists:
+      if image_tag_pos == false
+        return false
+      else
+        # Check if we have item tags:
+        if item_pos == false
+          return image_tag_pos
+        else
+          # Extract item positions that occur after the image tag position:
+          late_item_pos = item_pos.select {|item| image_tag_pos[0] < item}
+          # Check if there are items appearing after the image tag.
+          if late_item_pos.size == 0
+            # None occured after the image tag position:
+            return image_tag_pos
+          else
+            # 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
+              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."
+                return false
+              end
+            else
+              puts "Warning: Number of frames tag not found. Method get_image_pos() will return false."
+              return false
+            end
+          end
+        end
+      end
+    end
+
+
+    # Returns the index(es) of the tag(s) in the DICOM file that match the supplied tag label.
+    def get_pos(label)
+      # There is probably a more elegant method to do this, but I havent found it at this time.
+      indexes = Array.new()
+      (0..@last_index).each do |i|
+        if @labels[i] == label
+          indexes += [i]
+        end
+      end
+      if indexes.size == 0
+        #puts "Notice: The requested position of label "+label+" was not identified."
+        return false
+      else
+        return indexes
+      end
+    end
+
+
+    # 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)
+      end
+    end
+
+
+    # Prints the information of a specific tag (index, label, name, type, length, value).
+		# The ID may be a tag name or tag label.
+    # 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."
+      else
+        # First search the labels (Adresses):
+        match=@labels.index(id)
+        if match == nil
+          match=@names.index(id)
+        end
+        if match == nil
+          puts "Tag " + id + " not recognised in this DICOM file."
+        else
+          print_index(match)
+        end
+      end
+    end
+
+
+    # Returns the value (processed raw data) of the DICOM tag that matches the supplied tag ID.
+		# 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!"
+        return false
+      else
+        # Assume we have been fed a tag label:
+        pos=@labels.index(id)
+        # If this does not give a hit, assume we have been fed a tag name:
+        if pos==nil
+          pos=@names.index(id)
+        end
+        # If we still dont have a hit, check if it is a valid number within the array range:
+        if pos == nil 
+          if (id.is_a? Integer)
+            if id >= 0 and id <= @last_index
+              # The id supplied is a valid position, return its corresponding value:
+              return @values[id]
+            else
+              return false
+            end
+          else
+            return false
+          end
+        else
+          # We have a valid position, return the value:
+          return @values[pos]
+        end
+      end
+    end
+
+
+    # Returns the raw data of the DICOM tag that matches the supplied tag ID.
+		# 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!"
+        return false
+      else
+        # Assume we have been fed a tag label:
+        pos=@labels.index(id)
+        # If this does not give a hit, assume we have been fed a tag name:
+        if pos==nil
+          pos=@names.index(id)
+        end
+        # If we still dont have a hit, check if it is a valid number within the array range:
+        if pos == nil 
+          if (id.is_a? Integer)
+            if id >= 0 and id <= @last_index
+              # The id supplied is a valid position, return its corresponding value:
+              return @raw[id]
+            else
+              return false
+            end
+          else
+            return false
+          end
+        else
+          # We have a valid position, return the value:
+          return @raw[pos]
+        end
+      end
+    end
+
+
+    # Prints the key structural properties of the DICOM file.
+    def print_properties()
+      if @explicit
+        part1 = "Explicit VR, "
+      else
+        part1 = "Implicit VR, "
+      end
+      if @file_endian
+        part2 = "Big Endian, with "
+      else
+        part2 = "Little Endian, with "
+      end
+      if @compression == false
+        part3 = "Uncompressed, "
+      else
+        part3 = "Compressed, "
+      end
+      if @color
+        part4 = "Color pixel data."
+      else
+        part4 = "Greyscale pixel data."
+      end
+      if @compression == nil
+        part3 = "No pixel data."
+        part4 = ""
+      end
+      puts part1 + part2 + part3 + part4
+    end
+
+
+    # Following methods are private.
+    private
+
+
+    # Private method.
+    # Prints the information of a specific tag to the screen, identified by its index.
+    # 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."
+      else
+        if maxL[0] == nil
+          maxL=@names[pos].length
+        else
+          maxL=maxL[0]
+        end
+        s = " "
+        t = "\t"
+        if pos < 10 then p1 = " "+pos.to_s else p1 = pos.to_s end
+        p2 = @labels[pos]
+        p3 = @names[pos]
+        s3 = " "*(maxL-@names[pos].length+1)
+        p4 = @types[pos]
+        p5 = @lengths[pos].to_s
+        # We dont want to print tag contents if it is binary data:
+        if @types[pos] == "OB" or @types[pos] == "OW" or @types[pos] == "UN"
+          p6 = "(binary data)"
+        else
+          if @values[pos].to_s.length > 28
+            p6 = (@values[pos].to_s)[0..27]+" ..."
+          else
+            p6 = (@values[pos].to_s)
+          end
+        end
+        # Put the pieces together and print it:
+        puts p1 + s*2 + p2 + s + p3 + s3 + p4 + t + p5 + t + p6
+      end
+    end
+
+
+  end # End of class.
+end # End of module.