rtkit 0.7

data/lib/rtkit/plan.rb

@@ -0,0 +1,259 @@
+module RTKIT
+
+  # The Plan class contains methods that are specific for this modality (RTPLAN).
+  #
+  # === Inheritance
+  #
+  # * Plan inherits all methods and attributes from the Series class.
+  #
+  class Plan < Series
+
+    # An array of radiotherapy beams belonging to this Plan.
+    attr_reader :beams
+    # The DObject instance of this Plan.
+    attr_reader :dcm
+    # The patient position.
+    attr_reader :patient_position
+    #  An array of RTDose instances associated with this Plan.
+    attr_reader :rt_doses
+    #  An array of RTImage (series) instances associated with this Plan.
+    attr_reader :rt_images
+    # The referenced patient Setup instance.
+    attr_reader :setup
+    # The SOP Instance UID.
+    attr_reader :sop_uid
+    # The StructureSet that this Plan belongs to.
+    attr_reader :struct
+
+    # Creates a new Plan instance by loading the relevant information from the specified DICOM object.
+    # The SOP Instance UID string value is used to uniquely identify a Plan instance.
+    #
+    # === Parameters
+    #
+    # * <tt>dcm</tt> -- An instance of a DICOM object (DICOM::DObject) with modality 'RTPLAN'.
+    # * <tt>study</tt> -- The Study instance that this RTPlan belongs to.
+    #
+    def self.load(dcm, study)
+      raise ArgumentError, "Invalid argument 'dcm'. Expected DObject, got #{dcm.class}." unless dcm.is_a?(DICOM::DObject)
+      raise ArgumentError, "Invalid argument 'study'. Expected Study, got #{study.class}." unless study.is_a?(Study)
+      raise ArgumentError, "Invalid argument 'dcm'. Expected DObject with modality 'RTPLAN', got #{dcm.value(MODALITY)}." unless dcm.value(MODALITY) == 'RTPLAN'
+      # Required attributes:
+      sop_uid = dcm.value(SOP_UID)
+      # Optional attributes:
+      class_uid = dcm.value(SOP_CLASS)
+      date = dcm.value(SERIES_DATE)
+      time = dcm.value(SERIES_TIME)
+      description = dcm.value(SERIES_DESCR)
+      series_uid = dcm.value(SERIES_UID)
+      # Get the corresponding StructureSet:
+      struct = self.structure_set(dcm, study)
+      # Create the Plan instance:
+      plan = self.new(sop_uid, struct, :class_uid => class_uid, :date => date, :time => time, :description => description, :series_uid => series_uid)
+      plan.add(dcm)
+      return plan
+    end
+
+    # Identifies the StructureSet that the Plan object belongs to.
+    # If the referenced instances (StructureSet, ImageSeries & Frame) does not exist, they are created by this method.
+    #
+    def self.structure_set(dcm, study)
+      raise ArgumentError, "Invalid argument 'dcm'. Expected DObject, got #{dcm.class}." unless dcm.is_a?(DICOM::DObject)
+      raise ArgumentError, "Invalid argument 'study'. Expected Study, got #{study.class}." unless study.is_a?(Study)
+      raise ArgumentError, "Invalid argument 'dcm'. Expected DObject with modality 'RTPLAN', got #{dcm.value(MODALITY)}." unless dcm.value(MODALITY) == 'RTPLAN'
+      # Extract the Frame of Reference UID:
+      begin
+        frame_of_ref = dcm.value(FRAME_OF_REF)
+      rescue
+        frame_of_ref = nil
+      end
+      # Extract referenced Structure Set SOP Instance UID:
+      begin
+        ref_struct_uid = dcm[REF_STRUCT_SQ][0].value(REF_SOP_UID)
+      rescue
+        ref_struct_uid = nil
+      end
+      # Create the Frame if it doesn't exist:
+      f = study.patient.dataset.frame(frame_of_ref)
+      f = Frame.new(frame_of_ref, study.patient) unless f
+      # Create the StructureSet & ImageSeries if the StructureSet doesn't exist:
+      struct = study.fseries(ref_struct_uid)
+      unless struct
+        # Create ImageSeries (assuming modality CT):
+        is = ImageSeries.new(RTKIT.series_uid, 'CT', f, study)
+        study.add_series(is)
+        # Create StructureSet:
+        struct = StructureSet.new(ref_struct_uid, is)
+        study.add_series(struct)
+      end
+      return struct
+    end
+
+    # Creates a new Plan instance.
+    #
+    # === Parameters
+    #
+    # * <tt>sop_uid</tt> -- The SOP Instance UID string.
+    # * <tt>struct</tt> -- The StructureSet that this Plan belongs to.
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:date</tt> -- String. The Series Date (DICOM tag '0008,0021').
+    # * <tt>:time</tt> -- String. The Series Time (DICOM tag '0008,0031').
+    # * <tt>:description</tt> -- String. The Series Description (DICOM tag '0008,103E').
+    # * <tt>:series_uid</tt> -- String. The Series Instance UID (DICOM tag '0020,000E').
+    #
+    def initialize(sop_uid, struct, options={})
+      raise ArgumentError, "Invalid argument 'sop_uid'. Expected String, got #{sop_uid.class}." unless sop_uid.is_a?(String)
+      raise ArgumentError, "Invalid argument 'struct'. Expected StructureSet, got #{struct.class}." unless struct.is_a?(StructureSet)
+      # Pass attributes to Series initialization:
+      options[:class_uid] = '1.2.840.10008.5.1.4.1.1.481.5' # RT Plan Storage
+      # Get a randomized Series UID unless it has been defined in the options hash:
+      series_uid = options[:series_uid] || RTKIT.series_uid
+      super(series_uid, 'RTPLAN', struct.study, options)
+      @sop_uid = sop_uid
+      @struct = struct
+      # Default attributes:
+      @beams = Array.new
+      @rt_doses = Array.new
+      @rt_images = Array.new
+      @associated_rt_doses = Hash.new
+      # Register ourselves with the StructureSet:
+      @struct.add_plan(self)
+    end
+
+    # Returns true if the argument is an instance with attributes equal to self.
+    #
+    def ==(other)
+      if other.respond_to?(:to_plan)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Registers a DICOM Object to the Plan, and processes it
+    # to create (and reference) the fields contained in the object.
+    #
+    def add(dcm)
+      raise ArgumentError, "Invalid argument 'dcm'. Expected DObject, got #{dcm.class}." unless dcm.is_a?(DICOM::DObject)
+      @dcm = dcm
+      #load_patient_setup
+      load_beams
+    end
+
+    # Adds a Beam to this Plan.
+    # Note: Intended for internal use in the library only.
+    #
+    def add_beam(beam)
+      raise ArgumentError, "Invalid argument 'beam'. Expected Beam, got #{beam.class}." unless beam.is_a?(Beam)
+      @beams << beam unless @beams.include?(beam)
+    end
+
+    # Adds a RTDose series to this Plan.
+    # Note: Intended for internal use in the library only.
+    #
+    def add_rt_dose(rt_dose)
+      raise ArgumentError, "Invalid argument 'rt_dose'. Expected RTDose, got #{rt_dose.class}." unless rt_dose.is_a?(RTDose)
+      @rt_doses << rt_dose unless @associated_rt_doses[rt_dose.uid]
+      @associated_rt_doses[rt_dose.uid] = rt_dose
+    end
+
+    # Adds a RTImage Series to this Plan.
+    # Note: Intended for internal use in the library only.
+    #
+    def add_rt_image(rt_image)
+      raise ArgumentError, "Invalid argument 'rt_image'. Expected RTImage, got #{rt_image.class}." unless rt_image.is_a?(RTImage)
+      @rt_images << rt_image unless @rt_images.include?(rt_image)
+    end
+
+    # Sets the Setup reference for this Plan.
+    # Note: Intended for internal use in the library only.
+    #
+    def add_setup(setup)
+      raise ArgumentError, "Invalid argument 'setup'. Expected Setup, got #{setup.class}." unless setup.is_a?(Setup)
+      @setup = setup
+    end
+
+    # Generates a Fixnum hash value for this instance.
+    #
+    def hash
+      state.hash
+    end
+
+    # Returns the RTDose instance mathcing the specified Series Instance UID (if an argument is used).
+    # If a specified UID doesn't match, nil is returned.
+    # If no argument is passed, the first RTDose instance associated with the Plan is returned.
+    #
+    # === Parameters
+    #
+    # * <tt>uid</tt> -- String. The value of the Series Instance UID element.
+    #
+    def rt_dose(*args)
+      raise ArgumentError, "Expected one or none arguments, got #{args.length}." unless [0, 1].include?(args.length)
+      if args.length == 1
+        raise ArgumentError, "Expected String (or nil), got #{args.first.class}." unless [String, NilClass].include?(args.first.class)
+        return @associated_rt_doses[args.first]
+      else
+        # No argument used, therefore we return the first RTDose instance:
+        return @rt_doses.first
+      end
+    end
+
+    # Returns self.
+    #
+    def to_plan
+      self
+    end
+
+
+    private
+
+
+=begin
+    # Registers this Plan instance with the StructureSet(s) that it references.
+    #
+    def connect_to_struct
+      # Find out which Structure Set is referenced:
+      @dcm[REF_STRUCT_SQ].each do |struct_item|
+        ref_sop_uid = struct_item.value(REF_SOP_UID)
+        matched_struct = @study.associated_instance_uids[ref_sop_uid]
+        if matched_struct
+          # The referenced series exists in our dataset. Proceed with setting up the references:
+          matched_struct.add_plan(self)
+          @structs << matched_struct
+          @stuct = matched_struct unless @struct
+        end
+      end
+    end
+=end
+
+    # Loads the Beam Items contained in the RTPlan and creates Beam instances.
+    #
+    def load_beams
+      # Load the patient position.
+      # NB! (FIXME) We assume that there is only one patient setup sequence item!
+      Setup.create_from_item(@dcm[PATIENT_SETUP_SQ][0], self)
+      # Load the information in a nested hash:
+      item_group = Hash.new
+      # NB! (FIXME) We assume there is only one fraction group!
+      @dcm[FRACTION_GROUP_SQ][0][REF_BEAM_SQ].each do |fg_item|
+        item_group[fg_item.value(REF_BEAM_NUMBER)] = {:meterset => fg_item.value(BEAM_METERSET).to_f}
+      end
+      @dcm[BEAM_SQ].each do |beam_item|
+        item_group[beam_item.value(BEAM_NUMBER)][:beam] = beam_item
+      end
+      # Create a Beam instance for each set of items:
+      item_group.each_value do |beam_items|
+        Beam.create_from_item(beam_items[:beam], beam_items[:meterset], self)
+      end
+    end
+
+    # Returns the attributes of this instance in an array (for comparison purposes).
+    #
+    def state
+       [@beams, @patient_position, @rt_doses, @rt_images, @setup, @sop_uid]
+    end
+
+  end
+end

data/lib/rtkit/plane.rb

@@ -0,0 +1,165 @@
+module RTKIT
+
+  # A Plane describes a flat, two-dimensional surface.
+  # A Plane can be defined in several ways, e.g. by:
+  # * A point and a normal vector.
+  # * A point and two vectors lying on it.
+  # * 3 non-colinear points.
+  #
+  # We will describe the plane in the form of a plane equation:
+  #  ax + by +cz +d = 0
+  #
+  # === Notes
+  #
+  # * For more information on Planes, refer to:  http://en.wikipedia.org/wiki/Plane_(geometry)
+  #
+  # === Relations
+  #
+  # Since an image slice is located in a specific plane, the Plane class may be used to relate instances of such classes.
+  #
+  class Plane
+
+    # The a parameter of the plane equation.
+    attr_reader :a
+    # The b parameter of the plane equation.
+    attr_reader :b
+    # The c parameter of the plane equation.
+    attr_reader :c
+    # The d parameter of the plane equation.
+    attr_reader :d
+
+    # Calculates a plane equation from the 3 specified coordinates.
+    # Returns a Plane instance.
+    #
+    def self.calculate(c1, c2, c3)
+      raise ArgumentError, "Invalid argument 'c1'. Expected Coordinate, got #{c1.class}" unless c1.is_a?(Coordinate)
+      raise ArgumentError, "Invalid argument 'c2'. Expected Coordinate, got #{c2.class}" unless c2.is_a?(Coordinate)
+      raise ArgumentError, "Invalid argument 'c3'. Expected Coordinate, got #{c3.class}" unless c3.is_a?(Coordinate)
+      x1, y1, z1 = c1.x.to_r, c1.y.to_r, c1.z.to_r
+      x2, y2, z2 = c2.x.to_r, c2.y.to_r, c2.z.to_r
+      x3, y3, z3 = c3.x.to_r, c3.y.to_r, c3.z.to_r
+      raise ArgumentError, "Got at least two Coordinates that are equal. Expected unique Coordinates."  unless [[x1, y1, z1], [x2, y2, z2], [x3, y3, z3]].uniq.length == 3
+      det = Matrix.rows([[x1, y1, z1], [x2, y2, z2], [x3, y3, z3]]).determinant
+      if det == 0
+        # Haven't experienced this case yet. Just raise an error to avoid unexpected behaviour.
+        raise "The determinant was zero (which means the plane passes through the origin). Not able to calculate variables: a,b,c"
+        #puts "Determinant was zero. Plane passes through origin. Find direction cosines instead?"
+      else
+        det = det.to_f
+        # Find parameters a,b,c.
+        a_m = Matrix.rows([[1, y1, z1], [1, y2, z2], [1, y3, z3]])
+        b_m = Matrix.rows([[x1, 1, z1], [x2, 1, z2], [x3, 1, z3]])
+        c_m = Matrix.rows([[x1, y1, 1], [x2, y2, 1], [x3, y3, 1]])
+        d = Plane.d
+        a = -d / det * a_m.determinant
+        b = -d / det * b_m.determinant
+        c = -d / det * c_m.determinant
+        return self.new(a, b, c)
+      end
+    end
+
+    # The custom plane parameter d:
+    # This constant can be equal to any non-zero number.
+    # Returns the float value chosen in this implementation: 500.0
+    #
+    def self.d
+      500.0
+    end
+
+    # Creates a new Plane instance.
+    #
+    # === Parameters
+    #
+    # * <tt>a</tt> -- Float. The a parameter of the plane equation.
+    # * <tt>b</tt> -- Float. The b parameter of the plane equation.
+    # * <tt>c</tt> -- Float. The c parameter of the plane equation.
+    #
+    def initialize(a, b, c)
+      raise ArgumentError, "Invalid argument 'a'. Expected Float, got #{a.class}." unless a.is_a?(Float)
+      raise ArgumentError, "Invalid argument 'b'. Expected Float, got #{b.class}." unless b.is_a?(Float)
+      raise ArgumentError, "Invalid argument 'c'. Expected Float, got #{c.class}." unless c.is_a?(Float)
+      @a = a
+      @b = b
+      @c = c
+      @d = Plane.d
+    end
+
+    # Returns true if the argument is an instance with attributes equal to self.
+    #
+    def ==(other)
+      if other.respond_to?(:to_plane)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Generates a Fixnum hash value for this instance.
+    #
+    def hash
+      state.hash
+    end
+
+    # Compares the Plane instance with an array of planes, and returns the index of the Plane
+    # who's Plane equation is closest to the plane equation of self.
+    # Returns nil if no suitable match is found.
+    #
+    def match(planes)
+      raise ArgumentError, "Invalid argument 'planes'. Expected Array, got #{planes.class}." unless planes.is_a?(Array)
+      raise ArgumentError, "Invalid argument 'planes'. Expected Array containing only Planes, got #{planes.collect{|p| p.class}.uniq}." unless planes.collect{|p| p.class}.uniq == [Plane]
+      # I don't really have a feeling for what a reasonable threshold should be here. Setting it at 0.01.
+      # (So far, matched planes have been observed having a deviation in the order of 10e-5 to 10e-7,
+      # while some obviously different planes have had values in the range of 8-21)
+      deviation_threshold = 0.01
+      # Since the 'd' parameter is just a constant selected by us when determining plane equations,
+      # the comparison is carried out against the a, b & c parameters.
+      # Register deviation for each parameter for each plane:
+      a_deviations = NArray.float(planes.length)
+      b_deviations = NArray.float(planes.length)
+      c_deviations = NArray.float(planes.length)
+      planes.each_index do |i|
+        # Calculate absolute deviation for each of the three parameters:
+        a_deviations[i] = (planes[i].a - @a).abs
+        b_deviations[i] = (planes[i].b - @b).abs
+        c_deviations[i] = (planes[i].c - @c).abs
+      end
+      # Compare the deviations of each parameter with the average deviation for that parameter,
+      # taking care to adress the case where all deviations for a certain parameter may be 0:
+      a_relatives = a_deviations.mean == 0 ? a_deviations : a_deviations / a_deviations.mean
+      b_relatives = b_deviations.mean == 0 ? b_deviations : b_deviations / b_deviations.mean
+      c_relatives = c_deviations.mean == 0 ? c_deviations : c_deviations / c_deviations.mean
+      # Sum the relative deviations for each parameter, and find the index with the lowest summed relative deviation:
+      deviations = NArray.float(planes.length)
+      planes.each_index do |i|
+        deviations[i] = a_relatives[i] + b_relatives[i] + c_relatives[i]
+      end
+      index = (deviations.eq deviations.min).where[0]
+      deviation = a_deviations[index] + b_deviations[index] + c_deviations[index]
+      index = nil if deviation > deviation_threshold
+      return index
+    end
+
+    # Returns self.
+    #
+    def to_plane
+      self
+    end
+
+    # Converts the Plane instance to a readable string (containing the parameters a, b & c).
+    #
+    def to_s
+      return "a: #{@a.round(2)}  b: #{@b.round(2)} c: #{@c.round(2)}"
+    end
+
+
+    private
+
+
+    # Returns the attributes of this instance in an array (for comparison purposes).
+    #
+    def state
+       [@a, @b, @c, @d]
+    end
+
+  end
+end

data/lib/rtkit/roi.rb

@@ -0,0 +1,388 @@
+module RTKIT
+
+  # Contains DICOM data and methods related to a Region of Interest, defined in a Structure Set.
+  #
+  # === Relations
+  #
+  # * An image series has many ROIs, defined through a Structure Set.
+  # * An image slice has only the ROIs which are contoured in that particular slice in the Structure Set.
+  # * A ROI has many Slices.
+  #
+  class ROI
+
+    # ROI Generation Algorithm.
+    attr_reader :algorithm
+    # ROI Display Color.
+    attr_reader :color
+    # The Frame which this ROI belongs to.
+    attr_reader :frame
+    # ROI Interpreter.
+    attr_reader :interpreter
+    # ROI Name.
+    attr_reader :name
+    # ROI Number (Integer).
+    attr_reader :number
+    # An array containing the Slices that the ROI is defined in.
+    attr_reader :slices
+    # The StructureSet that the ROI is defined in.
+    attr_reader :struct
+    # RT ROI Interpreted Type.
+    attr_reader :type
+
+    # Creates a new ROI instance from the three items of the structure set
+    # which contains the information related to a particular ROI.
+    # This method also creates and connects any child structures as indicated in the items (e.g. Slices).
+    # Returns the ROI instance.
+    #
+    # === Parameters
+    #
+    # * <tt>roi_item</tt> -- The ROI's Item from the Structure Set ROI Sequence in the DObject of a Structure Set.
+    # * <tt>contour_item</tt> -- The ROI's Item from the ROI Contour Sequence in the DObject of a Structure Set.
+    # * <tt>rt_item</tt> -- The ROI's Item from the RT ROI Observations Sequence in the DObject of a Structure Set.
+    # * <tt>struct</tt> -- The StructureSet instance that this ROI belongs to.
+    #
+    def self.create_from_items(roi_item, contour_item, rt_item, struct)
+      raise ArgumentError, "Invalid argument 'roi_item'. Expected DICOM::Item, got #{roi_item.class}." unless roi_item.is_a?(DICOM::Item)
+      raise ArgumentError, "Invalid argument 'contour_item'. Expected DICOM::Item, got #{contour_item.class}." unless contour_item.is_a?(DICOM::Item)
+      raise ArgumentError, "Invalid argument 'rt_item'. Expected DICOM::Item, got #{rt_item.class}." unless rt_item.is_a?(DICOM::Item)
+      raise ArgumentError, "Invalid argument 'struct'. Expected StructureSet, got #{struct.class}." unless struct.is_a?(StructureSet)
+      # Values from the Structure Set ROI Sequence Item:
+      number = roi_item.value(ROI_NUMBER).to_i
+      frame_of_ref = roi_item.value(REF_FRAME_OF_REF)
+      name = roi_item.value(ROI_NAME) || ''
+      algorithm = roi_item.value(ROI_ALGORITHM) || ''
+      # Values from the RT ROI Observations Sequence Item:
+      type = rt_item.value(ROI_TYPE) || ''
+      interpreter = rt_item.value(ROI_INTERPRETER) || ''
+      # Values from the ROI Contour Sequence Item:
+      color = contour_item.value(ROI_COLOR)
+      # Get the frame:
+      frame = struct.study.patient.dataset.frame(frame_of_ref)
+      # If the frame didnt exist, create it (assuming the frame belongs to our patient):
+      frame = struct.study.patient.create_frame(frame_of_ref) unless frame
+      # Create the ROI instance:
+      roi = self.new(name, number, frame, struct, :algorithm => algorithm, :color => color, :interpreter => interpreter, :type => type)
+      # Create the Slices in which the ROI has contours defined:
+      roi.create_slices(contour_item[CONTOUR_SQ]) if contour_item[CONTOUR_SQ]
+      return roi
+    end
+
+    # Creates a new ROI instance.
+    #
+    # === Parameters
+    #
+    # * <tt>name</tt> -- String. The ROI Name.
+    # * <tt>number</tt> -- Integer. The ROI Number.
+    # * <tt>frame</tt> -- The Frame instance that this ROI belongs to.
+    # * <tt>struct</tt> -- The StructureSet instance that this ROI belongs to.
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:algorithm</tt> -- String. The ROI Generation Algorithm. Defaults to 'Automatic'.
+    # * <tt>:color</tt> -- String. The ROI Display Color. Defaults to a random color string (format: 'x\y\z' where [x,y,z] is a byte (0-255)).
+    # * <tt>:interpreter</tt> -- String. The ROI Interpreter. Defaults to 'RTKIT'.
+    # * <tt>:type</tt> -- String. The ROI Interpreted Type. Defaults to 'CONTROL'.
+    #
+    def initialize(name, number, frame, struct, options={})
+      raise ArgumentError, "Invalid argument 'name'. Expected String, got #{name.class}." unless name.is_a?(String)
+      raise ArgumentError, "Invalid argument 'number'. Expected Integer, got #{number.class}." unless number.is_a?(Integer)
+      raise ArgumentError, "Invalid argument 'frame'. Expected Frame, got #{frame.class}." unless frame.is_a?(Frame)
+      raise ArgumentError, "Invalid argument 'struct'. Expected StructureSet, got #{struct.class}." unless struct.is_a?(StructureSet)
+      raise ArgumentError, "Invalid option :algorithm. Expected String, got #{options[:algorithm].class}." if options[:algorithm] && !options[:algorithm].is_a?(String)
+      raise ArgumentError, "Invalid option :color. Expected String, got #{options[:color].class}." if options[:color] && !options[:color].is_a?(String)
+      raise ArgumentError, "Invalid option :interpreter. Expected String, got #{options[:interpreter].class}." if options[:interpreter] && !options[:interpreter].is_a?(String)
+      raise ArgumentError, "Invalid option :type. Expected String, got #{options[:type].class}." if options[:type] && !options[:type].is_a?(String)
+      @slices = Array.new
+      @associated_instance_uids = Hash.new
+      # Set values:
+      @number = number
+      @name = name
+      @algorithm = options[:algorithm] || 'Automatic'
+      @type = options[:type] || 'CONTROL'
+      @interpreter = options[:interpreter] || 'RTKIT'
+      @color = options[:color] || random_color
+      # Set references:
+      @frame = frame
+      @struct = struct
+      # Register ourselves with the Frame and StructureSet:
+      @frame.add_roi(self)
+      @struct.add_roi(self)
+    end
+
+    # Returns true if the argument is an instance with attributes equal to self.
+    #
+    def ==(other)
+      if other.respond_to?(:to_roi)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Adds a Slice instance to this ROI.
+    #
+    def add_slice(slice)
+      raise ArgumentError, "Invalid argument 'slice'. Expected Slice, got #{slice.class}." unless slice.is_a?(Slice)
+      @slices << slice unless @associated_instance_uids[slice.uid]
+      @associated_instance_uids[slice.uid] = slice
+    end
+
+    # Sets the algorithm attribute.
+    #
+    def algorithm=(value)
+      @algorithm = value && value.to_s
+    end
+
+    # Attaches a ROI to a specified ImageSeries, by setting the ROIs frame reference to the
+    # Frame which the ImageSeries belongs to, and setting the Image reference of each of the Slices
+    # belonging to the ROI to an Image instance which matches the coordinates of the Slice's Contour(s).
+    # Raises an exception if a suitable match is not found for any Slice.
+    #
+    # === Notes
+    #
+    # This method can be useful when you have multiple segmentations based on the same image series
+    # from multiple raters (perhaps as part of a comparison study), and the rater's software has modified
+    # the UIDs of the original image series, so that the references of the returned Structure Set does
+    # not match your original image series. This method uses coordinate information to calculate plane
+    # equations, which allows it to identify the corresponding image slice even in the case of
+    # slice geometry being non-perpendicular with respect to the patient geometry (direction cosine values != [0,1]).
+    #
+    def attach_to(series)
+      raise ArgumentError, "Invalid argument 'series'. Expected ImageSeries, got #{series.class}." unless series.is_a?(Series)
+      # Change struct association if indicated:
+      if series.struct != @struct
+        @struct.remove_roi(self)
+        series.struct.add_roi(self)
+        @struct = series.struct
+      end
+      # Change Frame if different:
+      if @frame != series.frame
+        @frame = series.frame
+      end
+      # Update slices:
+      @slices.each do |slice|
+        slice.attach_to(series)
+      end
+    end
+
+    # Creates a binary volume object consisting of a series of binary (segmented) images,
+    # extracted from the contours defined for the slices of this ROI.
+    # Returns a BinVolume instance with binary image references equal to
+    # the number of slices defined for this ROI.
+    #
+    # === Parameters
+    #
+    # * <tt>image_volume</tt> -- By default the BinVolume is created against the ImageSeries of the ROI's StructureSet. Optionally, a DoseVolume can be specified.
+    #
+    def bin_volume(image_volume=@struct.image_series.first)
+      return BinVolume.from_roi(self, image_volume)
+    end
+
+    # Sets a new color for this ROI.
+    #
+    # === Parameters
+    #
+    # * <tt>col</tt> -- String. A proper color string (3 integers 0-255, each separated by a '\').
+    #
+    def color=(col)
+      raise ArgumentError, "Invalid argument 'col'. Expected String, got #{col.class}." unless col.is_a?(String)
+      colors = col.split("\\")
+      raise ArgumentError, "Invalid argument 'col'. Expected 3 color values, got #{colors.length}." unless colors.length == 3
+      colors.each do |str|
+        c = str.to_i
+        raise ArgumentError, "Invalid argument 'col'. Expected valid integer (0-255), got #{str}." if c < 0 or c > 255
+        raise ArgumentError, "Invalid argument 'col'. Expected an integer, got #{str}." if c == 0 and str != "0"
+      end
+      @color = col
+    end
+
+    # Creates and returns a ROI Contour Sequence Item from the attributes of the ROI.
+    #
+    def contour_item
+      item = DICOM::Item.new
+      item.add(DICOM::Element.new(ROI_COLOR, @color))
+      s = DICOM::Sequence.new(CONTOUR_SQ)
+      item.add(s)
+      item.add(DICOM::Element.new(REF_ROI_NUMBER, @number.to_s))
+      # Add Contour items to the Contour Sequence (one or several items per Slice):
+      @slices.each do |slice|
+        slice.contours.each do |contour|
+          s.add_item(contour.to_item)
+        end
+      end
+      return item
+    end
+
+    # Iterates the Contour Sequence Items, collects Contour Items for each slice and passes them along to the Slice class.
+    #
+    def create_slices(contour_sequence)
+      raise ArgumentError, "Invalid argument 'contour_sequence'. Expected DICOM::Sequence, got #{contour_sequence.class}." unless contour_sequence.is_a?(DICOM::Sequence)
+      # Sort the contours by slices:
+      slice_collection = Hash.new
+      contour_sequence.each do |slice_contour_item|
+        sop_uid = slice_contour_item[CONTOUR_IMAGE_SQ][0].value(REF_SOP_UID)
+        slice_collection[sop_uid] = Array.new unless slice_collection[sop_uid]
+        slice_collection[sop_uid] << slice_contour_item
+      end
+      # Create slices:
+      slice_collection.each_pair do |sop_uid, items|
+        Slice.create_from_items(sop_uid, items, self)
+      end
+    end
+
+    # Creates a DoseDistribution based on the delineation of this ROI in the
+    # specified RTDose series.
+    #
+    # === Parameters
+    #
+    # * <tt>dose_volume</tt> -- The DoseVolume to extract the dose distribution from. Defaults to the sum of the dose volumes of the first RTDose of the first plan of the parent StructureSet.
+    #
+    def distribution(dose_volume=@struct.plan.rt_dose.sum)
+      raise ArgumentError, "Invalid argument 'dose_volume'. Expected DoseVolume, got #{dose_volume.class}." unless dose_volume.is_a?(DoseVolume)
+      raise ArgumentError, "Invalid argument 'dose_volume'. The specified DoseVolume does not belong to this ROI's StructureSet." unless dose_volume.dose_series.plan.struct == @struct
+      # Extract a binary volume from the ROI, based on the dose data:
+      bin_vol = bin_volume(dose_volume)
+      # Create a DoseDistribution from the BinVolume:
+      dose_distribution = DoseDistribution.create(bin_vol)
+      return dose_distribution
+    end
+
+    # Generates a Fixnum hash value for this instance.
+    #
+    def hash
+      state.hash
+    end
+
+    # Returns the ImageSeries instance that this ROI is defined in.
+    #
+    def image_series
+      return @struct.image_series.first
+    end
+
+    # Sets the interpreter attribute.
+    #
+    def interpreter=(value)
+      @interpreter = value && value.to_s
+    end
+
+    # Sets the name attribute.
+    #
+    def name=(value)
+      @name = value && value.to_s
+    end
+
+    # Returns the number of Contours belonging to this ROI through its Slices.
+    #
+    def num_contours
+      num = 0
+      @slices.each do |slice|
+        num += slice.contours.length
+      end
+      return num
+    end
+
+    # Sets the number attribute.
+    #
+    def number=(value)
+      @number = value.to_i
+    end
+
+    # Creates and returns a RT ROI Obervations Sequence Item from the attributes of the ROI.
+    #
+    def obs_item
+      item = DICOM::Item.new
+      item.add(DICOM::Element.new(OBS_NUMBER, @number.to_s))
+      item.add(DICOM::Element.new(REF_ROI_NUMBER, @number.to_s))
+      item.add(DICOM::Element.new(ROI_TYPE, @type))
+      item.add(DICOM::Element.new(ROI_INTERPRETER, @interpreter))
+      return item
+    end
+
+    # Removes the parent references of the ROI (StructureSet and Frame).
+    #
+    def remove_references
+      @frame = nil
+      @struct = nil
+    end
+
+    # Calculates the size (volume) of the ROI by evaluating the ROI's
+    # delination in the referenced image series.
+    # Returns a float, giving the volume in units of cubic centimeters,
+    #
+    def size
+      volume = 0.0
+      # Iterate each slice:
+      @slices.each_index do |i|
+        # Get the contoured area in this slice, convert it to volume and add to our total.
+        # If the slice is the first or last, only multiply by half of the slice thickness:
+        if i == 0 or i == @slices.length-1
+          volume += slice.area * image_series.slice_spacing * 0.5
+        else
+          volume += slice.area * image_series.slice_spacing
+        end
+      end
+      # Convert from mm^3 to cm^3:
+      return volume / 1000.0
+    end
+
+    # Returns the Slice instance mathcing the specified SOP Instance UID (if an argument is used).
+    # If a specified UID doesn't match, nil is returned.
+    # If no argument is passed, the first Slice instance associated with the ROI is returned.
+    #
+    # === Parameters
+    #
+    # * <tt>uid</tt> -- String. The value of the SOP Instance UID element.
+    #
+    def slice(*args)
+      raise ArgumentError, "Expected one or none arguments, got #{args.length}." unless [0, 1].include?(args.length)
+      if args.length == 1
+        raise ArgumentError, "Invalid argument 'uid'. Expected String (or nil), got #{args.first.class}." unless [String, NilClass].include?(args.first.class)
+        return @associated_instance_uids[args.first]
+      else
+        # No argument used, therefore we return the first Image instance:
+        return @slices.first
+      end
+    end
+
+    # Creates and returns a Structure Set ROI Sequence Item from the attributes of the ROI.
+    #
+    def ss_item
+      item = DICOM::Item.new
+      item.add(DICOM::Element.new(ROI_NUMBER, @number.to_s))
+      item.add(DICOM::Element.new(REF_FRAME_OF_REF, @frame.uid))
+      item.add(DICOM::Element.new(ROI_NAME, @name))
+      item.add(DICOM::Element.new(ROI_ALGORITHM, @algorithm))
+      return item
+    end
+
+    # Returns self.
+    #
+    def to_roi
+      self
+    end
+
+    # Sets the type attribute.
+    #
+    def type=(value)
+      @type = value && value.to_s
+    end
+
+
+    private
+
+
+    # Creates and returns a random color string (used for the ROI Display Color element).
+    #
+    def random_color
+      return "#{rand(256).to_i}\\#{rand(256).to_i}\\#{rand(256).to_i}"
+    end
+
+    # Returns the attributes of this instance in an array (for comparison purposes).
+    #
+    def state
+       [@algorithm, @color, @interpreter, @name, @number, @slices, @type]
+    end
+
+  end
+end