dicom 0.2 → 0.3

data/CHANGELOG

@@ -1,3 +1,16 @@
+= 0.3
+
+=== 12th October, 2008
+
+* The DRead class is now able to keep track of the position of the tags inside the hierarchy of sequences and items.
+* DObject class has seen a number of improvements to allow taking advantage of this hierarchy awareness:
+* Method get_pos() now can take an array of positions as an argument when searching for tags,
+  meaning it will only search for hits amongst the positions provided.
+* Method print() has been improved with new options to visualize the tree structure of the DICOM file.
+* Method print() is able to print to file as well. The text file will be put in the same folder as the DICOM file.
+* New method below(), which lets you specify a sequence or item, and this method will return the position
+  of all tags contained in this sequence/item.
+
 = 0.2
 
 === 10th August, 2008
@@ -6,8 +19,8 @@
 * 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.
+* DRead class is more resistant to breaking if it is handed a faulty file to read, and will return an error message instead of halting execution.
+* Added option to load DICOM object in verbose or silent mode.
 
 = 0.1
 

data/DOCUMENTATION

@@ -15,7 +15,9 @@ 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.
+		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()
 
@@ -35,11 +37,21 @@ PUBLIC CLASS METHODS
 
 PUBLIC INSTANCE METHODS
 
+	below(id, *options)
+		Returns the positions of all tags inside the hierarchy of a sequence or an item.
+		This is useful if you later want to get the position(s) of a certain tag,
+		restricted to the positions inside the given sequence or item.
+		Example 1: (Return all tag positions that is contained in the following sequence)
+			pos = obj.below("3006,0082")
+		Example 2: (Return all tag positions that is contained only directly beneath the following sequence)
+			pos = obj.below("3006,0082", next_only=true)
+
 	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.
+		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'
@@ -58,8 +70,12 @@ PUBLIC INSTANCE METHODS
 	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_pos(id, *options)
+		Returns the index(es) of the tag(s) in the DICOM file that match the supplied tag ID.
+		Example 1: (Find all occurences of the specified tag in the object)
+			pos = obj.get_pos("3006,0080")
+		Example 2: (Find all occurences of the specified tag inside the specified sequence)
+			pos = obj.get_pos("3006,0080", obj.below("3006,0082"))
 
 	get_raw(id)
 		Returns the raw data of the DICOM tag that matches the supplied tag ID.
@@ -69,12 +85,19 @@ PUBLIC INSTANCE METHODS
 		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(id, *options)
+		Prints the information of one or many tag(s):
+			(index, [hierarchy level,] label, name, type, length, value)
+		The method can print to both screen or to a text file. If print to file is chosen,
+		the text file will be put in the folder of the original DICOM file with a '.txt' extension.
+		The ID may be a tag name, label or position, or it might be an array of positions.
+		Example 1: (Print all tags to file, with both tree visualization and level numbers)
+			obj.print(true, levels=true, tree=true, file=true)
+		Example 2: (Print an array of tags to screen, no level or tree visualization)
+			obj.print([4,5,6])
 
 	print_all()
-		Prints information of all tags stored in the DICOM object.
+		Prints information of all tags stored in the DICOM object to the screen.
 
 	print_properties()
-		Prints the key structural properties of the DICOM file.
+		Prints the key structural properties of the DICOM file to the screen.

data/README

@@ -11,8 +11,10 @@ BASIC USAGE
 
 require 'dicom'
 # Read file:
-dcm = DICOM::DObject.new("myFile.dcm")
-# Check out the contents:
+dcm = DICOM::DObject.new("myFile.dcm")
+# Display some key information about the file:
+dcm.print_properties()
+# Print all tags to screen:
 dcm.print_all()
 # Retrieve a tag value:
 name = dcm.get_value("0010.0010")
@@ -56,3 +58,4 @@ Oslo, Norway
 Email:
 chris.lervag @nospam @gmail.com
 Please don't hesitate to email me if have any thoughts on this project!
+

data/lib/DLibrary.rb

@@ -21,6 +21,7 @@ module DICOM
       
       # Load the dictionary:
       dict = Dictionary.new()
+      
       # Data elements:
       de = dict.load_tags()
       @de_label = de[0]
@@ -91,6 +92,20 @@ module DICOM
     end
 
 
+    # Returns the name corresponding to a given UID.
+    def get_uid(label)
+      # Find the position of the specified label in the array:
+      pos = @uid_value.index(label)
+      # Fetch the name of this UID:
+      if pos != nil
+        name = @uid_name[pos]
+      else
+        name = "Unknown UID!"
+      end
+      return name
+    end
+
+
     # Following methods are private.
     private
 

data/lib/DObject.rb

@@ -30,7 +30,7 @@ module DICOM
   # Class for handling the DICOM contents:
   class DObject
 
-    attr_reader :read_success
+    attr_reader :read_success, :modality
 
     # Initialize the DObject instance.
     def initialize(file_name=nil, verbose=false, lib=nil)
@@ -41,6 +41,7 @@ module DICOM
       @lengths = Array.new()
       @values = Array.new()
       @raw = Array.new()
+      @levels = 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:
@@ -52,6 +53,8 @@ module DICOM
       @color = false
       @explicit = true
       @file_endian = false
+      # Information about the DICOM object:
+      @modality = nil
       # Handling variables:
       @verbose = verbose
       # Control variables:
@@ -65,6 +68,7 @@ module DICOM
       end
       # If a (valid) file name string is supplied, launch the method to read DICOM file:
       if file_name != nil and file_name != ""
+        @file = file_name
         read_file(file_name)
       end
     end
@@ -90,16 +94,19 @@ module DICOM
           @lengths = data[3]
           @values = data[4]
           @raw = data[5]
+          @levels = data[6]
           # Other information:
-          @compression = data[6]
-          @color = data[7]
-          @explicit = data[8]
-          @file_endian = data[9]
+          @compression = data[7]
+          @color = data[8]
+          @explicit = data[9]
+          @file_endian = data[10]
           # Index of last element in tag arrays:
           @last_index=@names.length-1
+          # Set the modality of the DICOM object:
+          set_modality()
         end
         # The messages must be stored regardless of success or failure:
-        messages = data[10]
+        messages = data[11]
         # If any messages has been recorded, send these to the message handling method:
         if messages.size != 0
           add_msg(messages)
@@ -306,15 +313,37 @@ module DICOM
     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.
+    # Returns an array of the index(es) of the tag(s) in the DICOM file that match the supplied tag label, name or position.
+    # If no match is found, the method will return false.
+    # Additional options:
+    # If an array of positions is specified as options[0], the method will search for hits in this
+    # array of positions instead of searching for hits in the entire object.
+    # If options[0]=false, then this method should also return false.
+    def get_pos(label, *options)
+      if options[0] == false
+        return false
+      end
+      # There may be a more elegant/efficient method to do this, but I leave that for later optimization.
+      # Array that will contain the positions where the supplied label gives a match:
       indexes = Array.new()
-      (0..@last_index).each do |i|
+      # Either use the supplied array, or we will create an array that contain the indices of the entire DICOM object:
+      if options[0].is_a?(Array)
+        search_array=options[0]
+      else
+        search_array = Array.new(@names.size) {|i| i}
+      end
+      # Do the search:
+      #(0..@last_index).each do |i|
+      search_array.each do |i|
         if @labels[i] == label
           indexes += [i]
+        elsif @names[i] == label
+          indexes += [i]
+        elsif label == i
+          indexes += [i]
         end
       end
+      # Return false if no hits are found, else return the array of indices:
       if indexes.size == 0
         #puts "Notice: The requested position of label "+label+" was not identified."
         return false
@@ -324,43 +353,171 @@ module DICOM
     end
 
 
-    # Prints information of all tags stored in the DICOM object.
-    # Calls private method print_index() to do the actual printing.
-    def print_all()
-      # 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)
+    # Returns the positions of all tags inside the hierarchy of a sequence or an item.
+    # Options:
+    # If options[0] = true, then this method will only search immediately below the specified
+    # item or sequence (that is, in the level of parent 1).
+    def below(tag, *options)
+      restriction = options[0]
+      # Retrieve position of parent tag which from which we will search:
+      pos = get_pos(tag)
+      if pos == false
+        return false
+      end
+      if pos.size > 1
+        add_msg("Warning: The supplied parent tag gives multiple hits. Search will be applied to all hits. To avoid this behaviour, specify position instead of label.")
+      end
+      # First we need to establish in which positions to perform the search:
+      below_pos = Array.new()
+      pos.each do |p|
+        parent_level = @levels[p]
+        remain_array = @levels[p+1..@levels.size-1]
+        extract = true
+        remain_array.each_index do |i| 
+          if (remain_array[i] > parent_level) and (extract == true)
+            # If search is targetted at any specific level, we can just add this position:
+            if not restriction == true
+              below_pos += [p+1+i]
+            else
+              # As search is restricted to parent level + 1, do a test for this:
+              if remain_array[i] == parent_level + 1
+                below_pos += [p+1+i]
+              end
+            end
+          else
+            # If we encounter a position who's level is not deeper than the original level, we can not extract any more values:
+            extract = false
+          end
         end
       end
+      # Positions to search in have been established, now we can perform the actual search:
+      if below_pos.size == 0
+        return false
+      else
+        return below_pos
+      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
-        add_msg("Please specify either a tag category name or a tag adress when using the print() function.")
+    # Prints information of all tags stored in the DICOM object.
+    # This method is kept for backwards compatibility.
+    # Instead of calling print_all() you may use print(true) for the same functionality.
+    def print_all()
+      print(true)
+    end
+
+
+    # Prints the tag information of the specified tags (index, [hierarchy level, tree visualisation,] label, name, type, length, value)
+    # The supplied variable may be a single position, an array of positions, or true - which will make the method print all tags in object.
+    # Tag(s) may be specified by position, label or name.
+    # Options:
+    # options[0] = true will make the method print the level numbers for each tag.
+    # options[1] = true will make the method print a tree structure for the tags.
+    # options[2] = true will make the method print to file instead of printing to screen.
+    def print(pos, *options)
+      # Convert to array if number:
+      if not pos.is_a?(Array) and pos != true
+        pos_valid = get_pos(pos)
+      elsif pos == true
+        # Create an array of positions which a
+        pos_valid = Array.new(@names.length)
+        # Fill in indices:
+        pos_valid.each_index do |i|
+          pos_valid[i]=i
+        end
       else
-        # First search the labels (Adresses):
-        match=@labels.index(id)
-        if match == nil
-          match=@names.index(id)
+        # Check that the supplied array contains valid positions:
+        pos_valid = Array.new()
+        pos.each_index do |i|
+          if pos[i] >= 0 and pos[i] <= @names.length
+            pos_valid += [pos[i]]
+          end
         end
-        if match == nil
-          add_msg("Tag " + id + " not recognised in this DICOM file.")
+      end
+      # Continue only if we have valid positions:
+      if pos_valid == false
+        return
+      elsif pos_valid.size == 0
+        return
+      end
+      # We have valid positions and are ready to start process the tags:
+      # Extract the information to be printed from the object arrays:
+      indices = Array.new()
+      levels = Array.new()
+      labels = Array.new()
+      names = Array.new()
+      types = Array.new()
+      lengths = Array.new()
+      values = Array.new()
+      # There may be a more elegant way to do this.
+      pos_valid.each_index do |i|
+        labels += [@labels[pos_valid[i]]]
+        levels += [@levels[pos_valid[i]]]
+        names += [@names[pos_valid[i]]]
+        types += [@types[pos_valid[i]]]
+        lengths += [@lengths[pos_valid[i]]]
+        values += [@values[pos_valid[i]]]
+      end
+      # We have collected the data that is to be printed, now we need to do some string manipulation if hierarchy is to be displayed:
+      if options[1] == true
+        # Tree structure requested.
+        front_symbol = "| "
+        tree_symbol = "|_"
+        labels.each_index do |i|
+          if levels[i] != 0
+            labels[i] = front_symbol*(levels[i]-1) + tree_symbol + labels[i]
+          end
+        end
+      end
+      # Extract the string lengths which are needed to make the formatting nice:
+      label_lengths = Array.new()
+      name_lengths = Array.new()
+      type_lengths = Array.new()
+      length_lengths = Array.new()
+      names.each_index do |i|
+        label_lengths[i] = labels[i].length
+        name_lengths[i] = names[i].length
+        type_lengths[i] = types[i].length
+        length_lengths[i] = lengths[i].to_s.length
+      end
+      # To give the printed output a nice format we need to check the string lengths of some of these arrays:
+      index_maxL = pos_valid.max.to_s.length
+      label_maxL = label_lengths.max
+      name_maxL = name_lengths.max
+      type_maxL = type_lengths.max
+      length_maxL = length_lengths.max
+      # Construct the strings, one for each line of output, where each line contain the information of one tag:
+      tags = Array.new()
+      labels.each_index do |i|
+        # Configure empty spaces:
+        s = " "
+        f0 = " "*(index_maxL-pos_valid[i].to_s.length)
+        f2 = " "*(label_maxL-labels[i].length+1)
+        f3 = " "*(name_maxL-names[i].length+1)
+        f4 = " "*(type_maxL-types[i].length+1)
+        f5 = " "*(length_maxL-lengths[i].to_s.length)
+        # Display levels?
+        if options[0] == true
+          lev = levels[i].to_s + s
+        else
+          lev = ""
+        end
+        # Restrict length of value string:
+        if values[i].to_s.length > 28
+          value = (values[i].to_s)[0..27]+" ..."
         else
-          print_index(match)
+          value = (values[i].to_s)
         end
+        if types[i] == "OB" or types[i] == "OW" or types[i] == "UN"
+          value = "(Binary data)"
+        end
+        tags += [f0 + pos_valid[i].to_s + s + lev + s + labels[i] + f2 + names[i] + f3 + types[i] + f4 + f5 + lengths[i].to_s + s + s + value]
+      end
+      # Print to either screen or file, depending on what the user requested:
+      if options[2] == true
+        print_file(tags)
+      else
+        print_screen(tags)
       end
     end
 
@@ -433,70 +590,87 @@ module DICOM
 
     # Prints the key structural properties of the DICOM file.
     def print_properties()
+      # Explicitness:
       if @explicit
-        part1 = "Explicit VR, "
+        explicit = "Explicit"
       else
-        part1 = "Implicit VR, "
+        explicit = "Implicit"
       end
+      # Endianness:
       if @file_endian
-        part2 = "Big Endian, with "
+        endian = "Big Endian"
       else
-        part2 = "Little Endian, with "
+        endian = "Little Endian"
       end
-      if @compression == false
-        part3 = "Uncompressed, "
+      # Pixel data:
+      if @compression == nil
+        pixels = "No"
       else
-        part3 = "Compressed, "
+        pixels = "Yes"
       end
+      # Colors:
       if @color
-        part4 = "Color pixel data."
+        image = "Colors"
       else
-        part4 = "Greyscale pixel data."
+        image = "Greyscale"
       end
-      if @compression == nil
-        part3 = "No pixel data."
-        part4 = ""
+      # Compression:
+      if @compression == true
+        compression = @lib.get_uid(get_value("0002,0010").rstrip)
+      else
+        compression = "No"
       end
-      puts part1 + part2 + part3 + part4
+      # Bits per pixel (allocated):
+      bits = get_value("0028,0100").to_s
+      # Print the file properties:
+      puts "Key properties of DICOM object:"
+      puts "-------------------------------"
+      puts "File:           " + @file
+      puts "Modality:       " + @modality
+      puts "Value repr.:    " + explicit
+      puts "Byte order:     " + endian
+      puts "Pixel data:     " + pixels
+      if pixels == "Yes"
+        puts "Image:          " + image
+        puts "Compression:    " + compression
+        puts "Bits per pixel: " + bits
+      end
+      puts "-------------------------------"
     end
 
 
-    # Following methods are private.
+    # ***** PS: 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 
-        add_msg("The specified index "+pos.to_s+" is outside the bounds of the tags array.")
+    # Sets the modality variable of the current DICOM object, by querying the library with the object's SOP Class UID.
+    def set_modality()
+      value = get_value("0008,0016")
+      if value == false
+        @modality = "Not specified"
       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
+        modality = @lib.get_uid(value.rstrip)
+        @modality = modality
+      end
+    end
+
+
+    # Prints the selected tags to an ascii text file.
+    # The text file will be saved in the folder of the original DICOM file,
+    # with the original file name plus a .txt extension.
+    def print_file(tags)
+      File.open( @file + '.txt', 'w' ) do |output|
+        tags.each do | line |
+          output.print line + "\n"
         end
-        # Put the pieces together and print it:
-        puts p1 + s*2 + p2 + s + p3 + s3 + p4 + t + p5 + t + p6
+      end
+    end
+
+ 
+    # Prints the selected tags to screen.
+    def print_screen(tags)
+      tags.each do | tag |
+        puts tag
       end
     end
 

data/lib/DRead.rb

@@ -6,6 +6,8 @@ module DICOM
 
     # Initialize the DRead instance.
     def initialize(file_name=nil, lib=nil)
+      @a=0
+      @b=0
       # Variables that hold data that will be returned to the person/procedure using this class:
       # Arrays that will hold information from the DICOM file:
       @names = Array.new()
@@ -14,6 +16,14 @@ module DICOM
       @lengths = Array.new()
       @values = Array.new()
       @raw = Array.new()
+      @levels = Array.new()
+      # Keeping track of how many bytes have been read from the file up to and including each tag:
+      # This is necessary for tracking the hiearchy in some DICOM files.
+      @integrated_lengths = Array.new()
+      @header_length = 0
+      # Keep track of the hierarchy of tags (this will be used to determine when a sequence or item is finished):
+      @hierarchy = Array.new()
+      @hierarchy_error = false
       # Array that will holde any messages generated while reading the DICOM file:
       @msg = Array.new()
       # Explicitness (explicit (true) by default):
@@ -32,8 +42,6 @@ module DICOM
       # Variables used internally when reading the dicom file:
       # If tag does not exist in the library it is unknown:
       @unknown = false
-      # Does the particular tag contain any information?
-      @content = true
       # Check endianness of the system (false if little endian):
       @sys_endian=check_sys_endian()
       # Endianness of the remaining groups after the first group:
@@ -48,6 +56,8 @@ module DICOM
       @data_length = 0
       # Variable used to tell whether file was read succesfully or not:
       @success = false
+      # Keeping track of the tag level while reading through the file:
+      @current_level = 0
 
       # Open file for binary reading:
       begin
@@ -70,6 +80,11 @@ module DICOM
       if header == false
         @file.close()
         @file = File.new(file_name, "rb")
+        @header_length = 0
+      elsif header == nil
+        # Reading the file did not succeed, and we need to abort.
+        @msg += ["Error! Could not read: "+ file_name + " It might be a directory. Returning."]
+        return
       end
 
       # Initiate the process to read tags:
@@ -78,7 +93,7 @@ module DICOM
       while tag != false and temp_check== true do
         tag=process_tag()
         # Store the tag information in arrays:
-        if tag != false and @content == true
+        if tag != false
           @names+=[tag[0]]
           @labels+=[tag[1]]
           @types+=[tag[2]]
@@ -105,7 +120,7 @@ module DICOM
 
     # Returns the relevant information gathered from the read dicom procedure.
     def return_data()
-      return [@names,@labels,@types,@lengths,@values,@raw,@compression,@color,@explicit, @file_endian, @msg]
+      return [@names,@labels,@types,@lengths,@values,@raw,@levels,@compression,@color,@explicit, @file_endian, @msg]
     end
 
 
@@ -115,10 +130,17 @@ module DICOM
       # consequtive zero bytes followed by 4 bytes that spell the string 'DICM'.
       # Apparently, some providers seems to skip this in their DICOM files.
       # First 128 bytes should be zeroes:
-      bin1=@file.read(128)
+      begin
+        bin1=@file.read(128)
+        @header_length += 128
+      rescue
+        # The file could not be read. Most likely because the file name variable supplied to this instance was in fact a directory.
+        return nil
+      end
       str_header1=bin1.unpack('a' * 128).to_s
       # Next 4 bytes should spell 'DICM':
       bin2=@file.read(4)
+      @header_length += 4
       str_header2=bin2.unpack('a' * 4).to_s
       # If we dont have this expected header, we will still try to read it is a DICOM file.
       if str_header2 != 'DICM' then
@@ -173,17 +195,15 @@ module DICOM
 
 
     # Governs the process of reading tags in the DICOM file.
+    # (This method needs to be cleaned up a bit, it just isnt that easy to see whats
+    #going on here in all cases. Perhaps some day I will get the courage to have a go at it again.)
     def process_tag()
       #STEP 1: ------------------------------------------------------
-      # Read the tag label, but exit if the method signals that we have reached end of file:
-      @content = true
+      # Read the tag label, but do not continue if the method signals that we have reached end of file:
       label=read_label()
       if label == false
         return false
       end
-      if @content == false  # PS: @content switch is not active atm it seems!
-        return
-      end
       # Retrieve the tag name and type based on the label we have read from file:
       lib_data = @lib.get_name_vr(label)
       name = lib_data[0]
@@ -210,14 +230,27 @@ module DICOM
       if length == "UNDEFINED"
         if label == "7FE0,0010"
           data = "(Encapsulated pixel data)"
-          name = "Encapsulated image"
+          name = "Encapsulated image(s)"
+          type = "SQ"
+        elsif type == "SQ" or type == "()"
+          # Do not change name of tag.
+          data = "(Encapsulated tags)"
         else
           data = "(Encapsulated data)"
           name = "Encapsulated information"
         end
+        # Set hiearchy level:
+        set_level(type, length, label)
         return [name,label,type,length,data]
       end
-      # Some special handling for item related tags:
+      # Add the length of the content of the tag to the last element in the integrated_lengths array:
+      # (but not if it is a sequence or item, as in this case the length of the tag is its sub-tags)
+      if length.to_i != 0 and type != "SQ" and type != "()"
+        @integrated_lengths[@integrated_lengths.size-1] += length
+      end
+      # Set hiearchy level:
+      set_level(type, length, label)
+      # Some special handling for item related tags, which may result in returning without reading data:
       if type == "()"
         # If length is zero, just return:
         if length == 0
@@ -233,26 +266,29 @@ module DICOM
           if @sq_length != true
             # Treat the item as containing image data:
             type = "OW" # A more general approach should be implemented here.
+            # For this special case, where item contains the data itself, instead of in sub-tags,
+            # we declare that there is to be no sub-level after all.
+            # This handling is not particularly obvious or elegant, and perhaps in the future I will
+            # be able to rewrite this whole process_tag method to something more sane.
+            @current_level = @current_level - 1
           end
         end
       end
       # STEP 3: ----------------------------------------
       # Finally read the tag data.
-      if @content == true
-        tag_data = read_data(type,length)
-        value = tag_data[0]
-        raw = tag_data[1]
-        # Check for the Transfer Syntax UID tag, and process it:
-        if label == "0002,0010"
-          process_syntax(value)
-        end
-        if type == "SQ" or type == "()"
-          @data_length = length # To avoid false errors. In time perhaps a better way of handling this will be found.
-        else
-          @data_length = raw.length
-        end
-        return [name,label,type,length,value,raw]
+      tag_data = read_data(type,length)
+      value = tag_data[0]
+      raw = tag_data[1]
+      # Check for the Transfer Syntax UID tag, and process it:
+      if label == "0002,0010"
+        process_syntax(value)
+      end
+      if type == "SQ" or type == "()"
+        @data_length = length # To avoid false errors. In time perhaps a better way of handling this will be found.
+      else
+        @data_length = raw.length
       end
+      return [name,label,type,length,value,raw]
     end
     # END READ TAG
 
@@ -262,9 +298,18 @@ module DICOM
       bin1=@file.read(2)
       bin2=@file.read(2)
       # Check if we have reached end of file before proceeding:
-      if bin1 == nil
+      if bin1 == nil or bin2 == nil
         return false
       end
+      # Add the length of the tag label. If this was the first label read from file, we need to add the header length too:
+      if @integrated_lengths.length == 0
+        # Increase the array with the length of the header + the 4 bytes:
+        @integrated_lengths += [@header_length + 4]
+      else
+        # For the remaining tags, increase the array with the integrated length of the previous tags + the 4 bytes:
+        @integrated_lengths += [@integrated_lengths[@integrated_lengths.length-1] + 4]
+      end
+      # Unpack the blobs:
       label1=bin1.unpack('h*').to_s.reverse.upcase
       label2=bin2.unpack('h*').to_s.reverse.upcase
       # Special treatment of tags that are of the first "0002" group:
@@ -310,10 +355,12 @@ module DICOM
         # It seems we need to have a special case for item labels in the explicit scenario:
         if label == "FFFE,E000" or label == "FFFE,E00D" or label == "FFFE,E0DD"
           bin=@file.read(4)
+          @integrated_lengths[@integrated_lengths.length-1] += 4
           length = get_SL(bin)
         else
           # Read tag type field (2 bytes - since we are not dealing with an item related tag):
           bin=@file.read(2)
+          @integrated_lengths[@integrated_lengths.length-1] += 2
           type=bin.unpack('a*').to_s
         end
         # Two (three) possible structures for value length here, dependent on tag type:
@@ -321,20 +368,24 @@ module DICOM
         when "OB","OW","SQ","UN"
           # Two empty bytes should occur here, according to the standard:
           bin=@file.read(2)
+          @integrated_lengths[@integrated_lengths.length-1] += 2
           # Read value length (4 bytes):
           bin=@file.read(4)
+          @integrated_lengths[@integrated_lengths.length-1] += 4
           length=get_SL(bin)
         when "()"
           #An empty entry for the item related tags (As it has already been processed).
         else
           # For all the other tag types: Read value length (2 bytes):
           bin=@file.read(2)
+          @integrated_lengths[@integrated_lengths.length-1] += 2
           length=get_US(bin)
         end
       else
         #IMPLICIT:
         # Read value length (4 bytes):
         bin=@file.read(4)
+        @integrated_lengths[@integrated_lengths.length-1] += 4
         length = get_SL(bin)
       end
       # For encapsulated data, the tag length will not be defined. To convey this,
@@ -471,7 +522,7 @@ module DICOM
         end
 
       # For everything else, assume string type information:
-      when 'AE','AS','CS','DA','DS','IS','LO','LT','PN','SH','ST','TM','UI','VR'
+      when 'AE','AS','CS','DA','DS','DT','IS','LO','LT','PN','SH','ST','TM','UI','UT' #,'VR'
         bin=@file.read(length)
         data=bin.unpack('a*').to_s
       else
@@ -486,6 +537,79 @@ module DICOM
     # END TAG DATA
 
 
+    # Sets the level of the current tag in the hiearchy.
+    # The default (top) level is zero.
+    def set_level(type, length, label)
+      # Set the level of this tag:
+      @levels += [@current_level]
+      # Determine if there is a level change for the following tag:
+      # If tag is a sequence, the level of the following tags will be increased by one.
+      # If tag is an item, the level of the following tags will be increased by one.
+      # Note the following exception:
+      # If label is "Item", and it contains data (image fragment) directly, which is to say,
+      # not in its sub-tags, we should not increase the level. (This is fixed in the process_tag method.)
+      if type == "SQ"
+        increase = true
+      elsif label =="FFFE,E000"
+        increase = true
+      else
+        increase = false
+      end
+      if increase == true
+        @current_level = @current_level + 1
+        # If length of sequence/item is specified, we must note this length + the current tag position in the arrays:
+        if length.to_i != 0
+          @hierarchy += [[length,@integrated_lengths.last]]
+        else
+          @hierarchy += [type]
+        end
+      end
+      # Need to check whether a previous sequence or item has ended, if so the level must be decreased by one:
+      # In the case of tag specification:
+      if (label == "FFFE,E00D") or (label == "FFFE,E0DD")
+        @current_level = @current_level - 1
+      end
+      # In the case of sequence and item length specification:
+      # Check the last position in the hieararchy array.
+      # If it is an array (of length and position), then we need to check the integrated_lengths array
+      # to see if the current sub-level has expired.
+      if @hierarchy.size > 0
+        check_level_end()
+      end
+    end
+    
+    
+    # Checks how far we've read in the DICOM file to determine if we have reached a point
+    # where sub-levels are ending. This method is recursive, as multiple sequences/items might end at the same point.
+    def check_level_end()
+      # The test is only meaningful to perform if we are not expecting an 'end of sequence/item' tag to signal the level-change.
+      if (@hierarchy.last).is_a?(Array)
+        described_length = (@hierarchy.last)[0]
+        previous_length = (@hierarchy.last)[1]
+        current_length = @integrated_lengths.last
+        current_diff = current_length - previous_length
+        if current_diff == described_length
+          # Decrease level by one:
+          @current_level = @current_level - 1
+          # Also we need to delete the last entry of the @hierarchy array:
+          if (@hierarchy.size > 1)
+            @hierarchy = @hierarchy[0..(@hierarchy.size-2)]
+            # There might be numerous levels that ends at this particular point, so we need to do a recursive repeat to check.
+            check_level_end()
+          else
+            @hierarchy = Array.new()
+          end
+        elsif current_diff > described_length
+          # Only register this type of error one time per file to avoid a spamming effect:
+          if not @hierarchy_error
+            @msg += ["Unexpected hierarchy incident: Current length difference is greater than the expected value, which should not occur. This will not pose any problems unless you intend to query the object for tags in the hierarchy."]
+            @hierarchy_error = true
+          end
+        end
+      end
+    end
+
+
     # Returns the (processed) value of a DICOM tag based on an input tag label, category name or array index.
     def get_value(id)
       # Assume we have been fed a tag label:

data/lib/Dictionary.rb

@@ -17,6 +17,44 @@ module DICOM
       return [a,b]
     end
 
+
+    # Loads the value representation library.
+    # Consists of VR name, meaning and data format.
+    def load_vr()
+      d = Array.new()
+      e = Array.new()
+      f = Array.new()
+      d+=["AE"] and e+=["Application entity"] and f+=["String"]
+      d+=["AS"] and e+=["Age string"] and f+=["String"]
+      d+=["AT"] and e+=["Attribute tag"] and f+=["Two 2-byte integers"]
+      d+=["CS"] and e+=["Code string"] and f+=["String"]
+      d+=["DA"] and e+=["Date"] and f+=["String"]
+      d+=["DS"] and e+=["Decimal string"] and f+=["String"]
+      d+=["DT"] and e+=["Date time"] and f+=["String"]
+      d+=["FL"] and e+=["Floating point single"] and f+=["4-byte floating point"]
+      d+=["FD"] and e+=["Floating point double"] and f+=["8-byte floating point"]
+      d+=["IS"] and e+=["Integer string"] and f+=["String"]
+      d+=["LO"] and e+=["Long string"] and f+=["String"]
+      d+=["LT"] and e+=["Long text"] and f+=["String"]
+      d+=["OB"] and e+=["Other byte string"] and f+=["1-byte integers"]
+      d+=["OF"] and e+=["Other float string"] and f+=["4-byte floating point numbers"]
+      d+=["OW"] and e+=["Other word string"] and f+=["2-byte integers"]
+      d+=["PN"] and e+=["Person name"] and f+=["String"]
+      d+=["SH"] and e+=["Short string"] and f+=["String"]
+      d+=["SL"] and e+=["Signed long"] and f+=["4-byte integer"]
+      d+=["SQ"] and e+=["Sequence of items"] and f+=["Unknown"]
+      d+=["SS"] and e+=["Signed short"] and f+=["2-byte integer"]
+      d+=["ST"] and e+=["Short text"] and f+=["String"]
+      d+=["TM"] and e+=["Time"] and f+=["String"]
+      d+=["UI"] and e+=["Unique identifier"] and f+=["String"]
+      d+=["UL"] and e+=["Unsigned long"] and f+=["4-byte integer"]
+      d+=["UN"] and e+=["Unknown"] and f+=["Unknown"]
+      d+=["US"] and e+=["Unsigned short"] and f+=["2-byte integer"]
+      d+=["UT"] and e+=["Unlimited text"] and f+=["String"]
+      return [d,e,f]
+    end
+
+
     # Table A.1 UID Values (DICOM Part 6, Annex A: Registry of DICOM unique identifiers)
     def load_uid()
       r = Array.new()

metadata

@@ -1,33 +1,26 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.4
-specification_version: 1
 name: dicom
 version: !ruby/object:Gem::Version 
-  version: "0.2"
-date: 2008-08-10 00:00:00 +02:00
-summary: Library for reading DICOM files.
-require_paths: 
-- lib
-email: chris.lervag@gmail.com
-homepage: http://rubyforge.org/projects/dicom/
-rubyforge_project: dicom
-description: DICOM is a standard widely used throughout the world to store and transfer medical image data. This project aims to make a library that is able to handle DICOM in the Ruby language, to the benefit of any student or professional who would like to use Ruby to process their DICOM files.
-autorequire: 
-default_executable: 
-bindir: bin
-has_rdoc: false
-required_ruby_version: !ruby/object:Gem::Version::Requirement 
-  requirements: 
-  - - ">"
-    - !ruby/object:Gem::Version 
-      version: 0.0.0
-  version: 
+  version: "0.3"
 platform: ruby
-signing_key: 
-cert_chain: 
-post_install_message: 
 authors: 
-- "Christoffer Lerv\xE5g"
+- Christoffer Lervag
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-10-12 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: DICOM is a standard widely used throughout the world to store and transfer medical image data. This project aims to make a library that is able to handle DICOM in the Ruby language, to the benefit of any student or professional who would like to use Ruby to process their DICOM files.
+email: chris.lervag@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
 files: 
 - lib/DObject.rb
 - lib/DLibrary.rb
@@ -38,17 +31,31 @@ files:
 - COPYING
 - README
 - DOCUMENTATION
-test_files: []
-
+has_rdoc: false
+homepage: http://dicom.rubyforge.org/
+post_install_message: 
 rdoc_options: []
 
-extra_rdoc_files: []
-
-executables: []
-
-extensions: []
-
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
 requirements: []
 
-dependencies: []
+rubyforge_project: dicom
+rubygems_version: 1.3.0
+signing_key: 
+specification_version: 2
+summary: Library for reading DICOM files.
+test_files: []