dicom 0.7 → 0.8

data/lib/dicom/DLibrary.rb

@@ -1,194 +0,0 @@
-#    Copyright 2008-2010 Christoffer Lervag
-
-module DICOM
-  # Class which holds the methods that interact with the DICOM dictionary.
-  class DLibrary
-
-    attr_reader :tags, :uid
-
-    # Initialize the DRead instance.
-    def initialize
-      # Dictionary content will be stored in a number of hash objects.
-      # Load the dictionary:
-      dic = Dictionary.new
-      # Data elements:
-      # Value of this hash is a two-element array [vr, name] (where vr itself is an array of 1-3 elements)
-      @tags = dic.load_data_elements
-      # UID (DICOM unique identifiers):
-      # Value of this hash is a two-element array [description, type]
-      @uid = dic.load_uid
-      # Photometric Interpretation: (not in use yet)
-      #@image_types = dic.load_image_types
-      # Value representation library: (not in use yet)
-      #@vr = dic.load_vr
-      # Frame of reference library: (not in use yet)
-      #@frame_of_ref = dic.load_frame_of_ref
-    end
-
-
-    # Checks whether a given string is a valid transfer syntax or not.
-    def check_ts_validity(uid)
-      result = false
-      value = @uid[uid.rstrip]
-      if value
-        if value[1] == "Transfer Syntax"
-          # Proved valid:
-          result = true
-        end
-      end
-      return result
-    end
-
-
-    # Checks if the supplied transfer syntax indicates the presence of pixel compression or not.
-    def get_compression(uid)
-      result = false
-      if uid
-        value = @uid[uid.rstrip]
-        if value
-          if value[1] == "Transfer Syntax" and not value[0].include?("Endian")
-            # It seems we have compression:
-            result = true
-          end
-        end
-      end
-      return result
-    end
-
-
-    # Returns data element name and value representation from the dictionary unless the data element
-    # is private. If a non-private tag is not recognized, "Unknown Name" and "UN" is returned.
-    def get_name_vr(tag)
-      if tag.private? and tag[5..8] != "0000"
-        name = "Private"
-        vr = "UN"
-      else
-        # Check the dictionary:
-        values = @tags[tag]
-        if values
-          name = values[1]
-          vr = values[0][0]
-        else
-          # For the tags that are not recognised, we need to do some additional testing to see if it is one of the special cases:
-          # Split tag in group and element:
-          group = tag[0..3]
-          element = tag[5..8]
-          if element == "0000"
-            # Group length:
-            name = "Group Length"
-            vr = "UL"
-          elsif tag[0..6] == "0020,31"
-            # Source Image ID's (Retired):
-            values = @tags["0020,31xx"]
-            name = values[1]
-            vr = values[0][0]
-          elsif group == "1000" and element =~ /\A\h{3}[0-5]\z/
-            # Group 1000,xxx[0-5] (Retired):
-            new_tag = group + "xx" + element[3..3]
-            values = @tags[new_tag]
-          elsif group == "1010"
-            # Group 1010,xxxx (Retired):
-            new_tag = group + "xxxx"
-            values = @tags[new_tag]
-          elsif tag[0..1] == "50" or tag[0..1] == "60"
-            # Group 50xx (Retired) and 60xx:
-            new_tag = tag[0..1]+"xx"+tag[4..8]
-            values = @tags[new_tag]
-            if values
-              name = values[1]
-              vr = values[0][0]
-            end
-          elsif tag[0..1] == "7F" and tag[5..6] == "00"
-            # Group 7Fxx,00[10,11,20,30,40] (Retired):
-            new_tag = tag[0..1]+"xx"+tag[4..8]
-            values = @tags[new_tag]
-            if values
-              name = values[1]
-              vr = values[0][0]
-            end
-          end
-          # If none of the above checks yielded a result, the tag is unknown:
-          unless name
-            name = "Unknown Name"
-            vr = "UN"
-          end
-        end
-      end
-      return [name,vr]
-    end
-
-
-    # Returns the tag that matches the supplied data element name,
-    # or if a tag is supplied, return that tag.
-    # (This method may be considered for removal: Does the usefulnes of being able to create a tag by Name,
-    # outweigh the performance impact of having this method?)
-    def get_tag(name)
-      tag = false
-      # The supplied value should be a string:
-      if name.is_a?(String)
-        if name.is_a_tag?
-          # This is a tag:
-          tag = name
-        else
-          # We have presumably been dealt a name. Search the dictionary to see if we can identify
-          # this name and return its corresponding tag:
-          @tags.each_pair do |key, value|
-            if value[1] == name
-              tag = key
-            end
-          end
-        end
-      end
-      return tag
-    end
-
-
-    # Returns the name/description corresponding to a given UID.
-    def get_uid(uid)
-      value = @uid[uid.rstrip]
-      # Fetch the name of this UID:
-      if value
-        name = value[0]
-      else
-        name = "Unknown UID!"
-      end
-      return name
-    end
-
-
-    # Checks the Transfer Syntax UID and return the encoding settings associated with this value.
-    def process_transfer_syntax(value)
-      valid = check_ts_validity(value)
-      case value
-        # Some variations with uncompressed pixel data:
-        when "1.2.840.10008.1.2"
-          # Implicit VR, Little Endian
-          explicit = false
-          endian = false
-        when "1.2.840.10008.1.2.1"
-          # Explicit VR, Little Endian
-          explicit = true
-          endian = false
-        when "1.2.840.10008.1.2.1.99"
-          # Deflated Explicit VR, Little Endian
-          #@msg += ["Warning: Transfer syntax 'Deflated Explicit VR, Little Endian' is untested. Unknown if this is handled correctly!"]
-          explicit = true
-          endian = false
-        when "1.2.840.10008.1.2.2"
-          # Explicit VR, Big Endian
-          explicit = true
-          endian = true
-        else
-          # For everything else, assume compressed pixel data, with Explicit VR, Little Endian:
-          explicit = true
-          endian = false
-      end
-      return [valid, explicit, endian]
-    end
-
-
-    # Following methods are private.
-    #private
-
-  end # of class
-end # of module

data/lib/dicom/DObject.rb

@@ -1,1579 +0,0 @@
-#    Copyright 2008-2010 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
-#    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:
-# -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?
-# -Could the usage of arrays in DObject be replaced with something better, or at least improved upon, to give cleaner code and more efficient execution?
-# -A curious observation: Loading the DLibrary 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
-
-  # Class for interacting with the DICOM object.
-  class DObject
-
-    attr_reader :read_success, :write_success, :modality, :errors, :segments,
-                      :names, :tags, :vr, :lengths, :values, :bin, :levels
-
-    # Initialize the DObject instance.
-    def initialize(string=nil, options={})
-      # Process option values, setting defaults for the ones that are not specified:
-      @verbose = options[:verbose]
-      segment_size = options[:segment_size]
-      bin = options[:bin]
-      syntax = options[:syntax]
-      # Default verbosity is true:
-      @verbose = true if @verbose == nil
-
-      # Initialize variables that will be used for the DICOM object:
-      @names = Array.new
-      @tags = Array.new
-      @vr = Array.new
-      @lengths = Array.new
-      @values = Array.new
-      @bin = Array.new
-      @levels = Array.new
-      # Array that will holde any messages generated while reading the DICOM file:
-      @errors = Array.new
-      # Array to keep track of sequences/structure of the dicom elements:
-      @sequence = Array.new
-      # Structural information (default values):
-      @compression = false
-      @color = false
-      @explicit = true
-      @file_endian = false
-      # Information about the DICOM object:
-      @modality = nil
-      # Control variables:
-      @read_success = false
-      # Initialize a Stream instance which is used for encoding/decoding:
-      @stream = Stream.new(nil, @file_endian, @explicit)
-
-      # If a (valid) file name string is supplied, call the method to read the DICOM file:
-      if string.is_a?(String) and string != ""
-        @file = string
-        read(string, :bin => bin, :segment_size => segment_size, :syntax => syntax)
-      end
-    end # of initialize
-
-
-    # Returns a DICOM object by reading the file specified.
-    # This is accomplished by initliazing the DRead class, which loads DICOM information to arrays.
-    # 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 may have to be called manually.
-    def read(string, options = {})
-      r = DRead.new(string, :sys_endian => @sys_endian, :bin => options[:bin], :syntax => options[:syntax])
-      # Store the data to the instance variables if the readout was a success:
-      if r.success
-        @read_success = true
-        @names = r.names
-        @tags = r.tags
-        @vr = r.vr
-        @lengths = r.lengths
-        @values = r.values
-        @bin = r.bin
-        @levels = r.levels
-        @explicit = r.explicit
-        @file_endian = r.file_endian
-        # Update Stream instance with settings from this DICOM file:
-        @stream.set_endian(@file_endian)
-        @stream.explicit = @explicit
-        # Update status variables for this object:
-        check_properties
-        # Set the modality of the DICOM object:
-        set_modality
-      else
-        @read_success = false
-      end
-      # Check if a partial extraction has been requested (used for network communication purposes)
-      if options[:segment_size]
-        @segments = r.extract_segments(options[:segment_size])
-      end
-      # If any messages has been recorded, send these to the message handling method:
-      add_msg(r.msg) if r.msg.length > 0
-    end
-
-
-    # Transfers necessary information from the DObject to the DWrite class, which
-    # will attempt to write this information to a valid DICOM file.
-    def write(file_name, transfer_syntax = nil)
-      w = set_write_object(file_name, transfer_syntax)
-      w.write
-      # Write process succesful?
-      @write_success = w.success
-      # If any messages has been recorded, send these to the message handling method:
-      add_msg(w.msg) if w.msg.length > 0
-    end
-
-
-    # Encodes the DICOM object into a series of binary string segments with a specified maximum length.
-    def encode_segments(size)
-      w = set_write_object
-      @segments = w.encode_segments(size)
-      # Write process succesful?
-      @write_success = w.success
-      # If any messages has been recorded, send these to the message handling method:
-      add_msg(w.msg) if w.msg.length > 0
-    end
-
-
-    #################################################
-    # START OF METHODS FOR READING INFORMATION FROM DICOM OBJECT:
-    #################################################
-
-
-    # Returns the image pixel data in a standard Ruby array.
-    # Returns false if it fails to retrieve image data.
-    # The array does not carry the dimensions of the pixel data, it will be a one dimensional array (vector).
-    # :rescale => true  - Return processed, rescaled presentation values instead of the original, full pixel range.
-    def get_image(options={})
-      pixel_data = false
-      pixel_element_pos = get_image_pos
-      # A hack for the special case (some MR files), where two images are stored (one is a smaller thumbnail image):
-      pixel_element_pos = [pixel_element_pos.last] if pixel_element_pos.length > 1 and get_value("0028,0011", :array => true).length > 1
-      # For now we only support returning pixel data if the image is located in a single pixel data element:
-      if pixel_element_pos.length == 1
-        # All of the pixel data is located in one element:
-        pixel_data = get_pixels(pixel_element_pos[0])
-      else
-        add_msg("Warning: Method get_image() does not currently support returning pixel data from encapsulated images!")
-      end
-      # Remap the image from pixel values to presentation values if the user has requested this:
-      if options[:rescale] == true and pixel_data
-        # Process pixel data for presentation according to the image information in the DICOM object:
-        center, width, intercept, slope = window_level_values
-        if options[:narray] == true
-          # Use numerical array (faster):
-          pixel_data = process_presentation_values_narray(pixel_data, center, width, slope, intercept, -65535, 65535).to_a
-        else
-          # Use standard Ruby array (slower):
-          pixel_data = process_presentation_values(pixel_data, center, width, slope, intercept, -65535, 65535)
-        end
-      end
-      return pixel_data
-    end
-
-
-    # Returns a 3d NArray object where the array dimensions corresponds to [frames, columns, rows].
-    # Returns false if it fails to retrieve image data.
-    # To call this method the user needs to loaded the NArray library in advance (require 'narray').
-    # Options:
-    # :rescale => true  - Return processed, rescaled presentation values instead of the original, full pixel range.
-    def get_image_narray(options={})
-      # Are we able to make a pixel array?
-      if @compression == nil
-        add_msg("It seems pixel data is not present in this DICOM object.")
-        return false
-      elsif @compression == true
-        add_msg("Reading compressed data to a NArray object not supported yet.")
-        return false
-      elsif @color
-        add_msg("Warning: Unpacking color pixel data is not supported yet for this method.")
-        return false
-      end
-      # Gather information about the dimensions of the pixel data:
-      rows = get_value("0028,0010", :array => true)[0]
-      columns = get_value("0028,0011", :array => true)[0]
-      frames = get_frames
-      pixel_element_pos = get_image_pos
-      # A hack for the special case (some MR files), where two images are stored (one is a smaller thumbnail image):
-      pixel_element_pos = [pixel_element_pos.last] if pixel_element_pos.length > 1 and get_value("0028,0011", :array => true).length > 1
-      # Creating a NArray object using int to make sure we have the necessary range for our numbers:
-      pixel_data = NArray.int(frames,columns,rows)
-      pixel_frame = NArray.int(columns,rows)
-      # Handling of pixel data will depend on whether we have one or more frames,
-      # and if it is located in one or more data elements:
-      if pixel_element_pos.length == 1
-        # All of the pixel data is located in one element:
-        pixel_array = get_pixels(pixel_element_pos[0])
-        frames.times do |i|
-          (columns*rows).times do |j|
-            pixel_frame[j] = pixel_array[j+i*columns*rows]
-          end
-          pixel_data[i,true,true] = pixel_frame
-        end
-      else
-        # Pixel data is encapsulated in items:
-        frames.times do |i|
-          pixel_array = get_pixels(pixel_element_pos[i])
-          (columns*rows).times do |j|
-            pixel_frame[j] = pixel_array[j+i*columns*rows]
-          end
-          pixel_data[i,true,true] = pixel_frame
-        end
-      end
-      # Remap the image from pixel values to presentation values if the user has requested this:
-      if options[:rescale] == true
-        # Process pixel data for presentation according to the image information in the DICOM object:
-        center, width, intercept, slope = window_level_values
-        pixel_data = process_presentation_values_narray(pixel_data, center, width, slope, intercept, -65535, 65535)
-      end
-      return pixel_data
-    end # of get_image_narray
-
-
-    # Returns an array of RMagick image objects, where the size of the array corresponds to the number of frames in the image data.
-    # Returns false if it fails to retrieve image data.
-    # To call this method the user needs to have loaded the ImageMagick library in advance (require 'RMagick').
-    # Options:
-    # :rescale => true  - Return processed, rescaled presentation values instead of the original, full pixel range.
-    # :narray => true  - Use NArray when rescaling pixel values (faster than using RMagick/Ruby array).
-    def get_image_magick(options={})
-      # Are we able to make an image?
-      if @compression == nil
-        add_msg("Notice: It seems pixel data is not present in this DICOM object.")
-        return false
-      elsif @color
-        add_msg("Warning: Unpacking color pixel data is not supported yet for this method.")
-        return false
-      end
-      # Gather information about the dimensions of the image data:
-      rows = get_value("0028,0010", :array => true)[0]
-      columns = get_value("0028,0011", :array => true)[0]
-      frames = get_frames
-      pixel_element_pos = get_image_pos
-      # Array that will hold the RMagick image objects, one object for each frame:
-      images = Array.new(frames)
-      # A hack for the special case (some MR files), where two images are stored (one is a smaller thumbnail image):
-      pixel_element_pos = [pixel_element_pos.last] if pixel_element_pos.length > 1 and get_value("0028,0011", :array => true).length > 1
-      # Handling of pixel data will depend on whether we have one or more frames,
-      # and if it is located in one or more data elements:
-      if pixel_element_pos.length == 1
-        # All of the pixel data is located in one data element:
-        if frames > 1
-          add_msg("Unfortunately, this method only supports reading the first image frame for 3D pixel data as of now.")
-        end
-        images = read_image_magick(pixel_element_pos[0], columns, rows, frames, options)
-        images = [images] unless images.is_a?(Array)
-      else
-        # Image data is encapsulated in items:
-        frames.times do |i|
-          image = read_image_magick(pixel_element_pos[i], columns, rows, 1, options)
-          images[i] = image
-        end
-      end
-      return images
-    end # of get_image_magick
-
-
-    # Returns the number of frames present in the image data in the DICOM file.
-    def get_frames
-      frames = get_value("0028,0008", :silent => true)
-      # If the DICOM object does not specify the number of frames explicitly, assume 1 image frame:
-      frames = 1 unless frames
-      return frames.to_i
-    end
-
-
-    # Returns the index(es) of the element(s) that contain image data.
-    def get_image_pos
-      image_element_pos = get_pos("7FE0,0010")
-      item_pos = get_pos("FFFE,E000")
-      # Proceed only if an image element actually exists:
-      if image_element_pos.length == 0
-        return false
-      else
-        # Check if we have item elements:
-        if item_pos.length == 0
-          return image_element_pos
-        else
-          # Extract item positions that occur after the image element position:
-          late_item_pos = item_pos.select {|item| image_element_pos[0] < item}
-          # Check if there are items appearing after the image element.
-          if late_item_pos.length == 0
-            # None occured after the image element position:
-            return image_element_pos
-          else
-            # Determine which of these late item elements contain image data.
-            # Usually, there are frames+1 late items, and all except
-            # the first item contain an image frame:
-            frames = get_frames
-            if frames != false  # note: function get_frames will never return false
-              if late_item_pos.length == frames.to_i+1
-                return late_item_pos[1..late_item_pos.length-1]
-              else
-                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.")
-                return Array.new
-              end
-            else
-              add_msg("Warning: 'Number of Frames' data element not found.")
-              return Array.new
-            end
-          end
-        end
-      end
-    end
-
-
-    # Returns an array of the index(es) of the element(s) in the DICOM file that match the supplied element position, tag or name.
-    # If no match is found, the method will return false.
-    # Additional options:
-    # :selection => mySelection - tells the method to search for matches in this specific array of positions instead of searching
-    #                                  through the entire DICOM object. If mySelection is empty, the returned array will also be empty.
-    # :partial => true - get_pos will not only search for exact matches, but will search the names and tags arrays for strings that contain the given search string.
-    # :parent => element  - This method will return only matches that are children of the specified (parent) data element.
-    def get_pos(query, options={})
-      search_array = Array.new
-      indexes = Array.new
-      # For convenience, allow query to be a one-element array (its value will be extracted):
-      if query.is_a?(Array)
-        if query.length > 1 or query.length == 0
-          add_msg("Warning: Invalid array length supplied to method get_pos().")
-          return Array.new
-        else
-          query = query[0]
-        end
-      end
-      # Check if query is a number (some methods want to have the ability to call get_pos with a number):
-      if query.is_a?(Integer)
-        # Return the position if it is valid:
-        if query >= 0 and query < @names.length
-          indexes = [query]
-        else
-          add_msg("Error: The specified array position (#{query}) is out of range (valid: 0-#{@tags.length}).")
-        end
-      elsif query.is_a?(String)
-        # Has the user specified an array to search within?
-        search_array = options[:selection] if options[:selection].is_a?(Array)
-        # Has the user specified a specific parent which will restrict our search to only it's children?
-        if options[:parent]
-          parent_pos = get_pos(options[:parent], :next_only => options[:next_only])
-          if parent_pos.length == 0
-            add_msg("Error: Invalid parent supplied to method get_pos().")
-            return Array.new
-          elsif parent_pos.length > 1
-            add_msg("Error: The parent you supplied to method get_pos() gives multiple hits. A more precise parent specification is needed.")
-            return Array.new
-          end
-          # Find the children of this particular tag:
-          children_pos = children(parent_pos)
-          # If selection has also been specified along with parent, we need to extract the array positions that are common to the two arrays:
-          if search_array.length > 0
-            search_array = search_array & children_pos
-          else
-            search_array = children_pos
-          end
-        end
-        # Search the entire DICOM object if no restrictions have been set:
-        search_array = Array.new(@names.length) {|i| i} unless options[:selection] or options[:parent]
-        # Perform search:
-        if options[:partial] == true
-          # Search for partial string matches:
-          partial_indexes = search_array.all_indices_partial_match(@tags, query.upcase)
-          if partial_indexes.length > 0
-            indexes = partial_indexes
-          else
-            indexes = search_array.all_indices_partial_match(@names, query)
-          end
-        else
-          # Search for identical matches:
-          if query[4..4] == ","
-            indexes = search_array.all_indices(@tags, query.upcase)
-          else
-            indexes = search_array.all_indices(@names, query)
-          end
-        end
-      end
-      return indexes
-    end # of get_pos
-
-
-    # Dumps the binary content of the Pixel Data element to file.
-    def image_to_file(file)
-      pos = get_image_pos
-      # Pixel data may be located in several elements:
-      pos.each_index do |i|
-        pixel_data = get_bin(pos[i])
-        if pos.length == 1
-          f = File.new(file, "wb")
-        else
-          f = File.new(file + i.to_s, "wb")
-        end
-        f.write(pixel_data)
-        f.close
-      end
-    end
-
-
-    # Returns the positions of all data elements inside the hierarchy of a sequence or an item.
-    # Options:
-    # :next_only => true - The method will only search immediately below the specified item or sequence (that is, in the level of parent + 1).
-    def children(element, options={})
-      # Process option values, setting defaults for the ones that are not specified:
-      opt_next_only = options[:next_only] || false
-      children_pos = Array.new
-      # Retrieve array position:
-      pos = get_pos(element)
-      if pos.length == 0
-        add_msg("Warning: Invalid data element provided to method children().")
-      elsif pos.length > 1
-        add_msg("Warning: Method children() does not allow a query which yields multiple array hits. Please use array position instead of tag/name.")
-      else
-        # Proceed to find the value:
-        # First we need to establish in which positions to perform the search:
-        pos.each do |p|
-          parent_level = @levels[p]
-          remain_array = @levels[p+1..@levels.length-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 opt_next_only == true
-                children_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
-                  children_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
-      end
-      return children_pos
-    end
-
-
-    # Returns the value (processed binary data) of the requested DICOM data element.
-    # Data element may be specified by array position, tag or name.
-    # Options:
-    # :array => true - Allows the query of the value of a tag that occurs more than one time in the
-    #                  DICOM object. Values will be returned in an array with length equal to the number
-    #                  of occurances of the tag. If keyword is not specified, the method returns false in this case.
-    # :silent => true - As this method is also used internally, we want the possibility of warnings not being
-    #                  raised even if verbose is set to true by the user, in order to avoid unnecessary confusion.
-    def get_value(element, options={})
-      value = false
-      # Retrieve array position:
-      pos = get_pos(element)
-      if pos.length == 0
-        add_msg("Warning: Invalid data element provided to method get_value() (#{element}).") unless options[:silent]
-      elsif pos.length > 1
-        # Multiple 'hits':
-        if options[:array] == true
-          # Retrieve all values into an array:
-          value = Array.new
-          pos.each do |i|
-            value << @values[i]
-          end
-        else
-          add_msg("Warning: Method get_value() does not allow a query which yields multiple array hits (#{element}). Please use array position instead of tag/name, or use option (:array => true) to return all values.") unless options[:silent]
-        end
-      else
-        # One single match:
-        value = @values[pos[0]]
-        # Return the single value in an array if keyword :array used:
-        value = [value] if options[:array]
-      end
-      return value
-    end
-
-
-    # Returns the unprocessed, binary string of the requested DICOM data element.
-    # Data element may be specified by array position, tag or name.
-    # Options:
-    # :array => true - Allows the query of the (binary) value of a tag that occurs more than one time in the
-    #                  DICOM object. Values will be returned in an array with length equal to the number
-    #                  of occurances of the tag. If keyword is not specified, the method returns false in this case.
-    def get_bin(element, options={})
-      value = false
-      # Retrieve array position:
-      pos = get_pos(element)
-      if pos.length == 0
-        add_msg("Warning: Invalid data element provided to method get_bin().")
-      elsif pos.length > 1
-        # Multiple 'hits':
-        if options[:array] == true
-          # Retrieve all values into an array:
-          value = Array.new
-          pos.each do |i|
-            value << @bin[i]
-          end
-        else
-          add_msg("Warning: Method get_bin() does not allow a query which yields multiple array hits. Please use array position instead of tag/name, or use keyword (:array => true).")
-        end
-      else
-        # One single match:
-        value = @bin[pos[0]]
-        # Return the single value in an array if keyword :array used:
-        value = [value] if options[:array]
-      end
-      return value
-    end
-
-
-    # Returns the position of (possible) parents of the specified data element in the hierarchy structure of the DICOM object.
-    def parents(element)
-      parent_pos = Array.new
-      # Retrieve array position:
-      pos = get_pos(element)
-      if pos.length == 0
-        add_msg("Warning: Invalid data element provided to method parents().")
-      elsif pos.length > 1
-        add_msg("Warning: Method parents() does not allow a query which yields multiple array hits. Please use array position instead of tag/name.")
-      else
-        # Proceed to find the value:
-        # Get the level of our element:
-        level = @levels[pos[0]]
-        # Element can obviously only have parents if it is not a top level element:
-        unless level == 0
-          # Search backwards, and record the position every time we encounter an upwards change in the level number.
-          prev_level = level
-          search_arr = @levels[0..pos[0]-1].reverse
-          search_arr.each_index do |i|
-            if search_arr[i] < prev_level
-              parent_pos << search_arr.length-i-1
-              prev_level = search_arr[i]
-            end
-          end
-          # When the element has several generations of parents, we want its top parent to be first in the returned array:
-          parent_pos = parent_pos.reverse
-        end
-      end
-      return parent_pos
-    end
-
-
-    ##############################################
-    ####### START OF METHODS FOR PRINTING INFORMATION:######
-    ##############################################
-
-
-    # Prints the information of all elements 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 information of the specified elements: Index, [hierarchy level, tree visualisation,] tag, name, vr, length, value
-    # The supplied variable may be a single position, an array of positions, or true - which will make the method print all elements.
-    # Optional arguments:
-    # :levels => true - method will print the level numbers for each element.
-    # :tree => true -   method will print a tree structure for the elements.
-    # :file => true -    method will print to file instead of printing to screen.
-    def print(pos, options={})
-      # Process option values, setting defaults for the ones that are not specified:
-      opt_levels = options[:levels] || false
-      opt_tree = options[:tree] || false
-      opt_file = options[:file] || false
-      if pos == true
-        # Create a complete array of indices:
-        pos_valid = Array.new(@names.length) {|i| i}
-      elsif not pos.is_a?(Array)
-        # Convert number to array:
-        pos_valid = [pos]
-      else
-        # Use the supplied array of numbers:
-        pos_valid = pos
-      end
-      # Extract the information to be printed from the object arrays:
-      indices = Array.new
-      levels = Array.new
-      tags = 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 do |pos|
-        tags << @tags[pos]
-        levels << @levels[pos].to_s
-        names << @names[pos]
-        types << @vr[pos]
-        lengths << @lengths[pos].to_s
-        values << @values[pos].to_s
-      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 opt_tree
-        # Tree structure requested.
-        front_symbol = "| "
-        tree_symbol = "|_"
-        tags.each_index do |i|
-          if levels[i] != "0"
-            tags[i] = front_symbol*(levels[i].to_i-1) + tree_symbol + tags[i]
-          end
-        end
-      end
-      # Extract the string lengths which are needed to make the formatting nice:
-      tag_lengths = Array.new
-      lev_lengths = Array.new
-      name_lengths = Array.new
-      type_lengths = Array.new
-      length_lengths = Array.new
-      names.each_index do |i|
-        tag_lengths[i] = tags[i].length
-        lev_lengths[i] = levels[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
-      lev_maxL = lev_lengths.max
-      tag_maxL = tag_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 data element:
-      elements = Array.new
-      # Start of loop which formats the element data:
-      # (This loop is what consumes most of the computing time of this method)
-      tags.each_index do |i|
-        # Configure empty spaces:
-        s = " "
-        f0 = " "*(index_maxL-pos_valid[i].to_s.length)
-        f1 = " "*(lev_maxL-levels[i].length)
-        f2 = " "*(tag_maxL-tags[i].length+1)
-        f3 = " "*(name_maxL-names[i].length+1)
-        f4 = " "*(type_maxL-types[i].length+1)
-        f5 = " "*(length_maxL-lengths[i].length)
-        # Display levels?
-        if opt_levels
-          lev = levels[i] + f1
-        else
-          lev = ""
-        end
-        # Restrict length of value string:
-        if values[i].length > 28
-          value = (values[i])[0..27]+" ..."
-        else
-          value = (values[i])
-        end
-        # Insert descriptive text for elements that hold binary data:
-        case types[i]
-          when "OW","OB","UN"
-            value = "(Binary Data)"
-          when "SQ"
-            value = "(Encapsulated Elements)"
-          when "()"
-            if tags[i].include?("FFFE,E000") # (Item)
-              value = "(Encapsulated Elements)"
-            else
-              value = ""
-            end
-        end
-        elements << (f0 + pos_valid[i].to_s + s + lev + s + tags[i] + f2 + names[i] + f3 + types[i] + f4 + f5 + lengths[i].to_s + s + s + value.rstrip)
-      end
-      # Print to either screen or file, depending on what the user requested:
-      if opt_file
-        print_file(elements)
-      else
-        print_screen(elements)
-      end
-    end # of print
-
-
-    # Prints the key structural properties of the DICOM file.
-    def print_properties
-      # Explicitness:
-      if @explicit
-        explicit = "Explicit"
-      else
-        explicit = "Implicit"
-      end
-      # Endianness:
-      if @file_endian
-        endian = "Big Endian"
-      else
-        endian = "Little Endian"
-      end
-      # Pixel data:
-      if @compression == nil
-        pixels = "No"
-      else
-        pixels = "Yes"
-      end
-      # Colors:
-      if @color
-        image = "Colors"
-      else
-        image = "Greyscale"
-      end
-      # Compression:
-      if @compression == true
-        compression = LIBRARY.get_uid(get_value("0002,0010").rstrip)
-      else
-        compression = "No"
-      end
-      # Bits per pixel (allocated):
-      bits = get_value("0028,0100", :array => true, :silent => true)
-      bits = bits[0].to_s if bits
-      # Print the file properties:
-      puts "Key properties of DICOM object:"
-      puts "-------------------------------"
-      puts "File:           " + @file
-      puts "Modality:       " + @modality.to_s
-      puts "Value repr.:    " + explicit
-      puts "Byte order:     " + endian
-      puts "Pixel data:     " + pixels
-      if pixels == "Yes"
-        puts "Image:          " + image if image
-        puts "Compression:    " + compression if compression
-        puts "Bits per pixel: " + bits if bits
-      end
-      puts "-------------------------------"
-    end # of print_properties
-
-
-    ####################################################
-    ### START OF METHODS FOR WRITING INFORMATION TO THE DICOM OBJECT:
-    ####################################################
-
-
-    # Writes pixel data from a Ruby Array object to the pixel data element.
-    def set_image(pixel_array)
-      # Encode this array using the standard class method:
-      set_value(pixel_array, "7FE0,0010", :create => true)
-    end
-
-
-    # Reads binary information from file and inserts it in the pixel data element.
-    def set_image_file(file)
-      # Try to read file:
-      begin
-        f = File.new(file, "rb")
-        bin = f.read(f.stat.size)
-      rescue
-        # Reading file was not successful. Register an error message.
-        add_msg("Reading specified file was not successful for some reason. No data has been added.")
-        return
-      end
-      if bin.length > 0
-        pos = @tags.index("7FE0,0010")
-        # Modify element:
-        set_value(bin, "7FE0,0010", :create => true, :bin => true)
-      else
-        add_msg("Content of file is of zero length. Nothing to store.")
-      end
-    end
-
-
-    # Transfers pixel data from a RMagick object to the pixel data element.
-    # NB! Because of rescaling when importing pixel values to a RMagick object, and the possible
-    # difference between presentation values and pixel values, the use of set_image_magick() may
-    # result in pixel data that is completely different from what is expected.
-    # This method should be used only with great care!
-    # If value rescaling is wanted, both :min and :max must be set!
-    # Options:
-    # :max => value  - Pixel values will be rescaled using this as the new maximum value.
-    # :min => value  - Pixel values will be rescaled, using this as the new minimum value.
-    def set_image_magick(magick_obj, options={})
-      # Export the RMagick object to a standard Ruby array of numbers:
-      pixel_array = magick_obj.export_pixels(x=0, y=0, columns=magick_obj.columns, rows=magick_obj.rows, map="I")
-      # Rescale pixel values?
-      if options[:min] and options[:max]
-        p_min = pixel_array.min
-        p_max = pixel_array.max
-        if p_min != options[:min] or p_max != options[:max]
-          wanted_range = options[:max] - options[:min]
-          factor = wanted_range.to_f/(pixel_array.max - pixel_array.min).to_f
-          offset = pixel_array.min - options[:min]
-          pixel_array.collect!{|x| ((x*factor)-offset).round}
-        end
-      end
-      # Encode this array using the standard class method:
-      set_value(pixel_array, "7FE0,0010", :create => true)
-    end
-
-
-    # Transfers pixel data from a NArray object to the pixel data element.
-    # If value rescaling is wanted, both :min and :max must be set!
-    # Options:
-    # :max => value  - Pixel values will be rescaled using this as the new maximum value.
-    # :min => value  - Pixel values will be rescaled, using this as the new minimum value.
-    def set_image_narray(narray, options={})
-      # Rescale pixel values?
-      if options[:min] and options[:max]
-        n_min = narray.min
-        n_max = narray.max
-        if n_min != options[:min] or n_max != options[:max]
-          wanted_range = options[:max] - options[:min]
-          factor = wanted_range.to_f/(n_max - n_min).to_f
-          offset = n_min - options[:min]
-          narray = narray*factor-offset
-        end
-      end
-      # Export the NArray object to a standard Ruby array of numbers:
-      pixel_array = narray.to_a.flatten!
-      # Encode this array using the standard class method:
-      set_value(pixel_array, "7FE0,0010", :create => true)
-    end
-
-
-    # Removes an element from the DICOM object.
-    # Options:
-    # :ignore_children => true  - Force the method to ignore children when removing an element.
-    #    (default behaviour is to remove any children if a sequence or item is removed)
-    def remove(element, options={})
-      positions = get_pos(element)
-      if positions.length == 0
-        add_msg("Warning: The given data element (#{element}) could not be found in the DICOM object. Method remove() has no data element to remove.")
-      elsif positions.length > 1
-        add_msg("Warning: Method remove() does not allow an element query which yields multiple array hits (#{element}). Please use array position instead of tag/name. Value(s) NOT removed.")
-      else
-        # Check if the tag selected for removal has children (relevant for sequence/item tags):
-        unless options[:ignore_children]
-          child_pos = children(positions)
-          # Add the positions of the children (if they exist) to our original tag's position array:
-          positions << child_pos if child_pos.length > 0
-        end
-        positions.flatten!
-        # Loop through all positions (important to do this in reverse to retain predictable array positions):
-        positions.reverse.each do |pos|
-          # Update group length
-          # (Possible weakness: Group length tag contained inside a sequence/item. Code needs a slight rewrite to make it more robust)
-          if @tags[pos][5..8] != "0000"
-            # Note: When removing an item/sequence, its length value must not be used for 'change' (it's value is in reality nil):
-            if @vr[pos] == "()" or @vr[pos] == "SQ"
-              change = 0
-            else
-              change = @lengths[pos]
-            end
-            vr = @vr[pos]
-            update_group_and_parents_length(pos, vr, change, -1)
-          end
-          # Remove entry from arrays:
-          @tags.delete_at(pos)
-          @levels.delete_at(pos)
-          @names.delete_at(pos)
-          @vr.delete_at(pos)
-          @lengths.delete_at(pos)
-          @values.delete_at(pos)
-          @bin.delete_at(pos)
-        end
-      end
-    end
-
-
-    # Removes all private data elements from the DICOM object.
-    def remove_private
-      # Private data elemements have a group tag that is odd.
-      odd_group = ["1,","3,","5,","7,","9,","B,","D,","F,"]
-      odd_group.each do |odd|
-        positions = get_pos(odd, :partial => true)
-        # Delete all entries (important to do this in reverse order).
-        positions.reverse.each do |pos|
-          remove(pos)
-        end
-      end
-    end
-
-
-    # Sets the value of a data element by modifying an existing element or creating a new one.
-    # If the supplied value is not binary, it will attempt to encode the value to binary itself.
-    # Options:
-    # :create => false  - Only update the specified element (do not create if missing).
-    # :bin => bin_data  - Value is already encoded as a binary string.
-    # :vr => string  - If creating a private element, the value representation must be provided to ensure proper encoding.
-    # :parent => element  - If an element is to be created inside a sequence/item, it's parent must be specified to ensure proper placement.
-    def set_value(value, element, options={})
-      # Options:
-      bin = options[:bin] # =true means value already encoded
-      vr = options[:vr] # a string which tells us what kind of type an unknown data element is
-      # Retrieve array position:
-      pos = get_pos(element, options)
-      # We do not support changing multiple data elements:
-      if pos.length > 1
-        add_msg("Warning: Method set_value() does not allow an element query (#{element}) which yields multiple array hits. Please use array position instead of tag/name. Value(s) NOT saved.")
-        return
-      end
-      if pos.length == 0 and options[:create] == false
-        # Since user has requested an element shall only be updated, we can not do so as the element position is not valid:
-        add_msg("Warning: Invalid data element (#{element}) provided to method set_value(). Value NOT updated.")
-      elsif options[:create] == false
-        # Modify element:
-        modify_element(value, pos[0], :bin => bin)
-      else
-        # User wants to create an element (or modify it if it is already present).
-        unless pos.length == 0
-          # The data element already exist, so we modify instead of creating:
-          modify_element(value, pos[0], :bin => bin)
-        else
-          # We need to create element:
-          # In the case that name has been provided instead of a tag, check with the library first:
-          tag = LIBRARY.get_tag(element)
-          # If this doesnt give a match, we may be dealing with a private tag:
-          tag = element unless tag
-          unless element.is_a?(String)
-            add_msg("Warning: Invalid data element (#{element}) provided to method set_value(). Value NOT updated.")
-          else
-            unless element.is_a_tag?
-              add_msg("Warning: Method set_value could not create data element, because the data element tag (#{element}) is invalid (Expected format of tags is 'GGGG,EEEE').")
-            else
-              # As we wish to create a new data element, we need to find out where to insert it in the element arrays:
-              # We will do this by finding the array position of the last element that will (alphabetically/numerically) stay in front of this element.
-              if @tags.length > 0
-                if options[:parent]
-                  # Parent specified:
-                  parent_pos = get_pos(options[:parent])
-                  if parent_pos.length > 1
-                    add_msg("Error: Method set_value() could not create data element, because the specified parent element (#{options[:parent]}) returns multiple hits.")
-                    return
-                  end
-                  indexes = children(parent_pos, :next_only => true)
-                  level = @levels[parent_pos.first]+1
-                else
-                  # No parent (fetch top level elements):
-                  full_array = Array.new(@levels.length) {|i| i}
-                  indexes = full_array.all_indices(@levels, 0)
-                  level = 0
-                end
-                # Loop through the selection:
-                index = -1
-                quit = false
-                while quit != true do
-                  if index+1 >= indexes.length # We have reached end of array.
-                    quit = true
-                  elsif tag < @tags[indexes[index+1]]
-                    quit = true
-                  else # Increase index in anticipation of a 'hit'.
-                    index += 1
-                  end
-                end
-                # Determine the index to pass on:
-                if index == -1
-                  # Empty parent tag or new tag belongs in front of our indexes:
-                  if indexes.length == 0
-                    full_index = parent_pos.first
-                  else
-                    full_index = indexes.first-1
-                  end
-                else
-                  full_index = indexes[index]
-                end
-              else
-                # We are dealing with an empty DICOM object:
-                full_index = nil
-                level = 0
-              end
-              # The necessary information is gathered; create new data element:
-              create_element(value, tag, full_index, level, :bin => bin, :vr => vr)
-            end
-          end
-        end
-      end
-    end # of set_value
-
-
-    ##################################################
-    ############## START OF PRIVATE METHODS:  ########
-    ##################################################
-    private
-
-
-    # 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)
-      puts msg if @verbose
-      @errors << msg
-      @errors.flatten
-    end
-
-
-    # Checks the status of the pixel data that has been read from the DICOM file: whether it exists at all and if its greyscale or color.
-    # Modifies instance variable @color if color image is detected and instance variable @compression if no pixel data is detected.
-    def check_properties
-      # Check if pixel data is present:
-      if @tags.index("7FE0,0010") == nil
-        # No pixel data in DICOM file:
-        @compression = nil
-      else
-        @compression = LIBRARY.get_compression(get_value("0002,0010", :silent => true))
-      end
-      # Set color variable as true if our object contain a color image:
-      col_string = get_value("0028,0004", :silent => true)
-      if col_string != false
-        if (col_string.include? "RGB") or (col_string.include? "COLOR") or (col_string.include? "COLOUR")
-          @color = true
-        end
-      end
-    end
-
-
-    # Creates a new data element:
-    def create_element(value, tag, last_pos, level, options={})
-      bin_only = options[:bin]
-      vr = options[:vr].upcase if options[:vr].is_a?(String)
-      # Fetch the VR:
-      info = LIBRARY.get_name_vr(tag)
-      vr = info[1] unless vr
-      name = info[0]
-      # Encode binary (if a binary is not provided):
-      if bin_only == true
-        # Data already encoded.
-        bin = value
-        value = nil
-      else
-        if vr != "UN"
-          # Encode:
-          bin = encode(value, vr)
-        else
-          add_msg("Error. Unable to encode data element value with unknown Value Representation!")
-        end
-      end
-      # Put the information of this data element into the arrays:
-      if bin
-        # 4 different scenarios: Array is empty, or: element is put in front, inside array, or at end of array:
-        # NB! No support for hierarchy at this time! Defaulting to level = 0.
-        if last_pos == nil
-          # We have empty DICOM object:
-          @tags = [tag]
-          @levels = [level]
-          @names = [name]
-          @vr = [vr]
-          @lengths = [bin.length]
-          @values = [value]
-          @bin = [bin]
-          pos = 0
-        elsif last_pos == -1
-          # Insert in front of arrays:
-          @tags = [tag] + @tags
-          @levels = [level] + @levels
-          @names = [name] + @names
-          @vr = [vr] + @vr
-          @lengths = [bin.length] + @lengths
-          @values = [value] + @values
-          @bin = [bin] + @bin
-          pos = 0
-        elsif last_pos == @tags.length-1
-          # Insert at end arrays:
-          @tags = @tags + [tag]
-          @levels = @levels + [level]
-          @names = @names + [name]
-          @vr = @vr + [vr]
-          @lengths = @lengths + [bin.length]
-          @values = @values + [value]
-          @bin = @bin + [bin]
-          pos = @tags.length-1
-        else
-          # Insert somewhere inside the array:
-          @tags = @tags[0..last_pos] + [tag] + @tags[(last_pos+1)..(@tags.length-1)]
-          @levels = @levels[0..last_pos] + [level] + @levels[(last_pos+1)..(@levels.length-1)]
-          @names = @names[0..last_pos] + [name] + @names[(last_pos+1)..(@names.length-1)]
-          @vr = @vr[0..last_pos] + [vr] + @vr[(last_pos+1)..(@vr.length-1)]
-          @lengths = @lengths[0..last_pos] + [bin.length] + @lengths[(last_pos+1)..(@lengths.length-1)]
-          @values = @values[0..last_pos] + [value] + @values[(last_pos+1)..(@values.length-1)]
-          @bin = @bin[0..last_pos] + [bin] + @bin[(last_pos+1)..(@bin.length-1)]
-          pos = last_pos + 1
-        end
-        # Update group length (as long as it was not a top-level group length element that was created):
-        if @tags[pos][5..8] != "0000" or level != 0
-          change = bin.length
-          update_group_and_parents_length(pos, vr, change, 1)
-        end
-      else
-        add_msg("Binary is nil. Nothing to save.")
-      end
-    end # of create_element
-
-
-    # Encodes a value to binary (used for inserting values into a DICOM object).
-    # Future development: Encoding of tags should be moved to the Stream class,
-    # and encoding of image data should be 'outsourced' to a method of its own (encode_image).
-    def encode(value, vr)
-      # VR will decide how to encode this value:
-      case vr
-        when "AT" # (Data element tag: Assume it has the format "GGGG,EEEE"
-          if value.is_a_tag?
-            bin = @stream.encode_tag(value)
-          else
-            add_msg("Invalid tag format (#{value}). Expected format: 'GGGG,EEEE'")
-          end
-        # We have a number of VRs that are encoded as string:
-        when 'AE','AS','CS','DA','DS','DT','IS','LO','LT','PN','SH','ST','TM','UI','UT'
-          # In case we are dealing with a number string element, the supplied value might be a number
-          # instead of a string, and as such, we convert to string just to make sure this will work nicely:
-          value = value.to_s
-          bin = @stream.encode_value(value, "STR")
-        # Image related value representations:
-        when "OW"
-          # What bit depth to use when encoding the pixel data?
-          bit_depth = get_value("0028,0100", :array => true)[0]
-          if bit_depth == false
-            # Data element not specified:
-            add_msg("Attempted to encode pixel data, but the 'Bit Depth' Data Element (0028,0100) is missing.")
-          else
-            # 8, 12 or 16 bits per pixel?
-            case bit_depth
-              when 8
-                bin = @stream.encode(value, "BY")
-              when 12
-                # 12 bit not supported yet!
-                add_msg("Encoding 12 bit pixel values not supported yet. Please change the bit depth to 8 or 16 bits.")
-              when 16
-                # Signed or unsigned integer?
-                pixel_representation = get_value("0028,0103", :array => true)[0]
-                if pixel_representation
-                  if pixel_representation.to_i == 1
-                    # Signed integers:
-                    bin = @stream.encode(value, "SS")
-                  else
-                    # Unsigned integers:
-                    bin = @stream.encode(value, "US")
-                  end
-                else
-                  add_msg("Attempted to encode pixel data, but the 'Pixel Representation' Data Element (0028,0103) is missing.")
-                end
-              else
-                # Unknown bit depth:
-                add_msg("Unknown bit depth #{bit_depth}. No data encoded.")
-            end
-          end
-        # All other VR's:
-        else
-          # Just encode:
-          bin = @stream.encode(value, vr)
-      end
-      return bin
-    end # of encode
-
-
-    # Find the position(s) of the group length tag(s) that the given tag is associated with.
-    # If a group length tag does not exist, return an empty array.
-    def find_group_length(pos)
-      positions = Array.new
-      group = @tags[pos][0..4]
-      # Check if our tag is part of a sequence/item:
-      if @levels[pos] > 0
-        # Add (possible) group length of top parent:
-        parent_positions = parents(pos)
-        first_parent_gl_pos = find_group_length(parent_positions.first)
-        positions << first_parent_gl_pos.first if first_parent_gl_pos.length > 0
-        # Add (possible) group length at current tag's level:
-        valid_positions = children(parent_positions.last)
-        level_gl_pos = get_pos(group+"0000", :array => valid_positions)
-        positions << level_gl_pos.first if level_gl_pos.length > 0
-      else
-        # We are dealing with a top level tag:
-        gl_pos = get_pos(group+"0000")
-        # Note: Group level tags of this type may be found elsewhere in the DICOM object inside other
-        # sequences/items. We must make sure that such tags are not added to our list:
-        gl_pos.each do |gl|
-          positions << gl if @levels[gl] == 0
-        end
-      end
-      return positions
-    end
-
-
-    # Unpacks and returns pixel data from a specified data element array position:
-    def get_pixels(pos)
-      pixels = false
-      # We need to know what kind of bith depth and integer type the pixel data is saved with:
-      bit_depth = get_value("0028,0100", :array => true)[0]
-      pixel_representation = get_value("0028,0103", :array => true)[0]
-      unless bit_depth == false
-        # Load the binary pixel data to the Stream instance:
-        @stream.set_string(get_bin(pos))
-        # Number of bytes used per pixel will determine how to unpack this:
-        case bit_depth
-          when 8
-            pixels = @stream.decode_all("BY") # Byte/Character/Fixnum (1 byte)
-          when 16
-            if pixel_representation
-              if pixel_representation.to_i == 1
-                pixels = @stream.decode_all("SS") # Signed short (2 bytes)
-              else
-                pixels = @stream.decode_all("US") # Unsigned short (2 bytes)
-              end
-            else
-              add_msg("Error: Attempted to decode pixel data, but the 'Pixel Representation' Data Element (0028,0103) is missing.")
-            end
-          when 12
-            # 12 BIT SIMPLY NOT WORKING YET!
-            # This one is a bit more tricky to extract.
-            # I havent really given this priority so far as 12 bit image data is rather rare.
-            add_msg("Warning: Decoding bit depth 12 is not implemented yet! Please contact the author.")
-          else
-            raise "Bit depth ["+bit_depth.to_s+"] has not received implementation in this procedure yet. Please contact the author."
-        end
-      else
-        add_msg("Error: Attempted to decode pixel data, but the 'Bit Depth' Data Element (0028,0010) is missing.")
-      end
-      return pixels
-    end
-
-
-    # Modifies existing data element:
-    def modify_element(value, pos, options={})
-      bin_only = options[:bin]
-      # Fetch the VR and old length:
-      vr = @vr[pos]
-      old_length = @lengths[pos]
-      # Encode binary (if a binary is not provided):
-      if bin_only == true
-        # Data already encoded.
-        bin = value
-        value = nil
-      else
-        if vr != "UN"
-          # Encode:
-          bin = encode(value, vr)
-        else
-          add_msg("Error. Unable to encode data element with unknown Value Representation!")
-        end
-      end
-      # Update the arrays with this new information:
-      if bin
-        # Replace array entries for this element:
-        #@vr[pos] = vr # for the time being there is no logic for updating/changing vr.
-        @lengths[pos] = bin.length
-        @values[pos] = value
-        @bin[pos] = bin
-        # Update group length (as long as it was not the group length that was modified):
-        if @tags[pos][5..8] != "0000"
-          change = bin.length - old_length
-          update_group_and_parents_length(pos, vr, change, 0)
-        end
-      else
-        add_msg("Binary is nil. Nothing to save.")
-      end
-    end
-
-
-    # Prints the selected elements 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(elements)
-      File.open( @file + '.txt', 'w' ) do |output|
-        elements.each do | line |
-          output.print line + "\n"
-        end
-      end
-    end
-
-
-    # Prints the selected elements to screen.
-    def print_screen(elements)
-      elements.each do |element|
-        puts element
-      end
-    end
-
-
-    # Converts original pixel data values to presentation values.
-    def process_presentation_values(pixel_data, center, width, slope, intercept, min_allowed, max_allowed)
-      # Rescale:
-      # PixelOutput = slope * pixel_values + intercept
-      if intercept != 0 or slope != 1
-        pixel_data.collect!{|x| (slope * x) + intercept}
-      end
-      # Contrast enhancement by black and white thresholding:
-      if center and width
-        low = center - width/2
-        high = center + width/2
-        pixel_data.each_index do |i|
-          if pixel_data[i] < low
-            pixel_data[i] = low
-          elsif pixel_data[i] > high
-            pixel_data[i] = high
-          end
-        end
-      end
-      # Need to introduce an offset?
-      min_pixel_value = pixel_data.min
-      if min_allowed
-        if min_pixel_value < min_allowed
-          offset = min_pixel_value.abs
-          pixel_data.collect!{|x| x + offset}
-        end
-      end
-      # Downscale pixel range?
-      max_pixel_value = pixel_data.max
-      if max_allowed
-        if max_pixel_value > max_allowed
-          factor = (max_pixel_value.to_f/max_allowed.to_f).ceil
-          pixel_data.collect!{|x| x / factor}
-        end
-      end
-      return pixel_data
-    end
-
-
-    # Converts original pixel data values to a RMagick image object containing presentation values.
-    def process_presentation_values_magick(pixel_data, center, width, slope, intercept, max_allowed, columns, rows)
-      # Rescale:
-      # PixelOutput = slope * pixel_values + intercept
-      if intercept != 0 or slope != 1
-        pixel_data.collect!{|x| (slope * x) + intercept}
-      end
-      # Need to introduce an offset?
-      offset = 0
-      min_pixel_value = pixel_data.min
-      if min_pixel_value < 0
-        offset = min_pixel_value.abs
-        pixel_data.collect!{|x| x + offset}
-      end
-      # Downscale pixel range?
-      factor = 1
-      max_pixel_value = pixel_data.max
-      if max_allowed
-        if max_pixel_value > max_allowed
-          factor = (max_pixel_value.to_f/max_allowed.to_f).ceil
-          pixel_data.collect!{|x| x / factor}
-        end
-      end
-      image = Magick::Image.new(columns,rows).import_pixels(0, 0, columns, rows, "I", pixel_data)
-      # Contrast enhancement by black and white thresholding:
-      if center and width
-        low = (center - width/2 + offset) / factor
-        high = (center + width/2 + offset) / factor
-        image = image.level(low, high)
-      end
-      return image
-    end
-
-
-    # Converts original pixel data values to presentation values, using the faster numerical array.
-    # If a Ruby array is supplied, this returns a one-dimensional NArray object (i.e. no columns & rows).
-    # If a NArray is supplied, the NArray is returned with its original dimensions.
-    def process_presentation_values_narray(pixel_data, center, width, slope, intercept, min_allowed, max_allowed)
-      if pixel_data.is_a?(Array)
-        n_arr = NArray.to_na(pixel_data)
-      else
-        n_arr = pixel_data
-      end
-      # Rescale:
-      # PixelOutput = slope * pixel_values + intercept
-      if intercept != 0 or slope != 1
-        n_arr = slope * n_arr + intercept
-      end
-      # Contrast enhancement by black and white thresholding:
-      if center and width
-        low = center - width/2
-        high = center + width/2
-        n_arr[n_arr < low] = low
-        n_arr[n_arr > high] = high
-      end
-      # Need to introduce an offset?
-      min_pixel_value = n_arr.min
-      if min_allowed
-        if min_pixel_value < min_allowed
-          offset = min_pixel_value.abs
-          n_arr = n_arr + offset
-        end
-      end
-      # Downscale pixel range?
-      max_pixel_value = n_arr.max
-      if max_allowed
-        if max_pixel_value > max_allowed
-          factor = (max_pixel_value.to_f/max_allowed.to_f).ceil
-          n_arr = n_arr / factor
-        end
-      end
-      return n_arr
-    end
-
-
-    # Returns one or more RMagick image objects from the binary string pixel data,
-    # performing decompression of data if necessary.
-    def read_image_magick(pos, columns, rows, frames, options={})
-      if columns == false or rows == false
-        add_msg("Error: Method read_image_magick() does not have enough data available to build an image object.")
-        return false
-      end
-      unless @compression
-        # Non-compressed, just return the array contained on the particular element:
-        pixel_data = get_pixels(pos)
-        # Remap the image from pixel values to presentation values if the user has requested this:
-        if options[:rescale] == true
-          # Process pixel data for presentation according to the image information in the DICOM object:
-          center, width, intercept, slope = window_level_values
-          # What tools will be used to process the pixel presentation values?
-          if options[:narray] == true
-            # Use numerical array (fast):
-            pixel_data = process_presentation_values_narray(pixel_data, center, width, slope, intercept, 0, Magick::QuantumRange).to_a
-            image = Magick::Image.new(columns,rows).import_pixels(0, 0, columns, rows, "I", pixel_data)
-          else
-            # Use a combination of ruby array and RMagick processing:
-            image = process_presentation_values_magick(pixel_data, center, width, slope, intercept, Magick::QuantumRange, columns, rows)
-          end
-        else
-          # Load original pixel values to a RMagick object:
-          image = Magick::Image.new(columns,rows).import_pixels(0, 0, columns, rows, "I", pixel_data)
-        end
-        return image
-      else
-        # Image data is compressed, we will attempt to deflate it using RMagick (ImageMagick):
-        begin
-          image = Magick::Image.from_blob(@bin[pos])
-          return image
-        rescue
-          add_msg("RMagick did not succeed in decoding the compressed image data.")
-          return false
-        end
-      end
-    end
-
-
-    # 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", :silent => true)
-      if value == false
-        @modality = "Not specified"
-      else
-        modality = LIBRARY.get_uid(value.rstrip)
-        @modality = modality
-      end
-    end
-
-
-    # Handles the creation of a DWrite object, and returns this object to the calling method.
-    def set_write_object(file_name = nil, transfer_syntax = nil)
-      unless transfer_syntax
-        transfer_syntax = get_value("0002,0010", :silent => true)
-        transfer_syntax = "1.2.840.10008.1.2" if not transfer_syntax # Default is implicit, little endian
-      end
-      w = DWrite.new(file_name, :sys_endian => @sys_endian, :transfer_syntax => transfer_syntax)
-      w.tags = @tags
-      w.vr = @vr
-      w.lengths = @lengths
-      w.bin = @bin
-      w.rest_endian = @file_endian
-      w.rest_explicit = @explicit
-      return w
-    end
-
-
-    # Updates the group length value when a data element has been updated, created or removed.
-    # If the tag is part of a sequence/item, and its parent have length values, these parents' lengths are also updated.
-    # The variable value_change_length holds the change in value length for the updated data element.
-    # (value_change_length should be positive when a data element is removed - it will only be negative when editing an element to a shorter value)
-    # The variable existance is -1 if data element has been removed, +1 if element has been added and 0 if it has been updated.
-    # There is some repetition of code in this method, so there is possible a potential to clean it up somewhat.
-    def update_group_and_parents_length(pos, vr, value_change_length, existance)
-      update_positions = Array.new
-      # Is this a tag with parents?
-      if @levels[pos] > 0
-        parent_positions = parents(pos)
-        parent_positions.each do |parent|
-          # If the parent has a length value, then it must be added to our list of tags that will have its length updated:
-          # Items/sequences that use delimitation items, have their lengths set to "UNDEFINED" by Ruby DICOM.
-          # Obviously, these items/sequences will not have their lengths changed.
-          unless @lengths[parent].is_a?(String)
-            if @lengths[parent] > 0
-              update_positions << parent
-            else
-              # However, a (previously) empty sequence/item that does not use delimiation items, should also have its length updated:
-              # The search for a delimitation item is somewhat slow, so only do this if the length was 0.
-              children_positions = children(parent, :next_only => true)
-              update_positions << parent if children_positions.length == 1 and @tags[children_positions[0]][0..7] != "FFFE,E0"
-            end
-          end
-        end
-      end
-      # Check for a corresponding group length tag:
-      gl_pos = find_group_length(pos)
-      # Join the arrays if group length tag(s) were actually discovered (Operator | can be used here for simplicity, but seems to be not working in Ruby 1.8)
-      gl_pos.each do |gl|
-        update_positions << gl
-      end
-      existance = 0 unless existance
-      # If group length(s)/parent(s) to be updated exists, calculate change:
-      if update_positions
-        values = Array.new
-        if existance == 0
-          # Element has only been updated, so we only need to think about the change in length of its value:
-          update_positions.each do |up|
-            # If we have a group length, value will be changed, if it is a sequence/item, length will be changed:
-            if @tags[up][5..8] == "0000"
-              values << @values[up] + value_change_length
-            else
-              values << @lengths[up] + value_change_length
-            end
-          end
-        else
-          # Element has either been created or removed. This means we need to calculate the length of its other parts.
-          if @explicit
-            # In the explicit scenario it is slightly complex to determine this value:
-            element_length = 0
-            # VR?:
-            unless @tags[pos] == "FFFE,E000" or @tags[pos] == "FFFE,E00D" or @tags[pos] == "FFFE,E0DD"
-              element_length += 2
-            end
-            # Length value:
-            case @vr[pos]
-              when "OB","OW","SQ","UN"
-                if pos > @tags.index("7FE0,0010").to_i and @tags.index("7FE0,0010").to_i != 0
-                  element_length += 4
-                else
-                  element_length += 6
-                end
-              when "()"
-                element_length += 4
-              else
-                element_length += 2
-            end
-          else
-            # In the implicit scenario it is easier:
-            element_length = 4
-          end
-          # Update group length for creation/deletion scenario:
-          change = (4 + element_length + value_change_length) * existance
-          update_positions.each do |up|
-            # If we have a group length, value will be changed, if it is a sequence/item, length will be changed:
-            if @tags[up][5..8] == "0000"
-              values << @values[up] + change
-            else
-              values << @lengths[up] + change
-            end
-          end
-        end
-        # Write the new Group Length(s)/parent(s) value(s):
-        update_positions.each_index do |i|
-          # If we have a group length, value will be changed, if it is a sequence/item, length will be changed:
-          if @tags[update_positions[i]][5..8] == "0000"
-            # Encode the new value to binary:
-            bin = encode(values[i], "UL")
-            # Update arrays:
-            @values[update_positions[i]] = values[i]
-            @bin[update_positions[i]] = bin
-          else
-            @lengths[update_positions[i]] = values[i]
-          end
-        end
-      end
-    end # of update_group_and_parents_length
-
-
-    # Gathers and returns the window level values needed to convert the original pixel values to presentation values.
-    def window_level_values
-      center = get_value("0028,1050", :silent => true)
-      width = get_value("0028,1051", :silent => true)
-      intercept = get_value("0028,1052", :silent => true) || 0
-      slope = get_value("0028,1053", :silent => true) || 1
-      center = center.to_i if center
-      width = width.to_i if width
-      intercept = intercept.to_i
-      slope = slope.to_i
-      return center, width, intercept, slope
-    end
-
-
-  end # of class
-end # of module