rtkit 0.7

data/lib/rtkit/selection.rb

@@ -0,0 +1,189 @@
+module RTKIT
+
+  # Contains DICOM data and methods related to a Selection of
+  # pixels (indices) from the binary 2D NArray of a BinImage instance.
+  #
+  # === Relations
+  #
+  # * The Selection belongs to a BinImage.
+  # * A Contour has many Coordinates.
+  #
+  class Selection
+
+    # The BinImage that the Selection belongs to.
+    attr_reader :bin_image
+    # An array of (general) indices.
+    attr_reader :indices
+    # An NArray of (general) indices.
+    #attr_reader :indices_narr
+
+    # Creates a new Selection instance from an Array (or NArray) of (general) indices.
+    # Returns the Selection instance.
+    #
+    # === Parameters
+    #
+    # * <tt>arr</tt> -- An Array/NArray of general indices (Integers).
+    # * <tt>slice</tt> -- The BinImage instance that this Selection belongs to.
+    #
+    def self.create_from_array(indices, bin_image)
+      raise ArgumentError, "Invalid argument 'indices'. Expected Array/NArray, got #{indices.class}." unless [NArray, Array].include?(indices.class)
+      raise ArgumentError, "Invalid argument 'bin_image'. Expected BinImage, got #{bin_image.class}." unless bin_image.is_a?(BinImage)
+      raise ArgumentError, "Invalid argument 'indices'. Expected Array to contain only integers, got #{indices.collect{|i| i.class}.uniq}." if indices.is_a?(Array) and not indices.collect{|i| i.class}.uniq == [Fixnum]
+      # Create the Selection:
+      s = self.new(bin_image)
+      # Set the indices:
+      s.add_indices(indices)
+      return s
+    end
+
+    # Creates a new Selection instance.
+    #
+    # === Parameters
+    #
+    # * <tt>bin_image</tt> -- The BinImage instance that this Selection belongs to.
+    #
+    def initialize(bin_image)
+      raise ArgumentError, "Invalid argument 'bin_image'. Expected BinImage, got #{bin_image.class}." unless bin_image.is_a?(BinImage)
+      @bin_image = bin_image
+      @indices = Array.new
+    end
+
+    # Returns true if the argument is an instance with attributes equal to self.
+    #
+    def ==(other)
+      if other.respond_to?(:to_selection)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Adds an array of (general) indices to this Selection.
+    #
+    def add_indices(indices)
+      raise ArgumentError, "Invalid argument 'indices'. Expected Array/NArray, got #{indices.class}." unless [NArray, Array].include?(indices.class)
+      raise ArgumentError, "Invalid argument 'indices'. Expected Array to contain only integers, got #{indices.collect{|i| i.class}.uniq}." if indices.is_a?(Array) and not indices.collect{|i| i.class}.uniq == [Fixnum]
+      indices = indices.to_a if indices.is_a?(NArray)
+      @indices += indices
+    end
+
+    # Returns an array of column indices.
+    # Returns an empty array if the instance contains no indices.
+    #
+    def columns
+      return @indices.collect {|index| index % @bin_image.columns}
+    end
+
+    # Generates a Fixnum hash value for this instance.
+    #
+    def hash
+      state.hash
+    end
+
+    # Returns the length (number of indices) of this selection.
+    #
+    def length
+      return @indices.length
+    end
+
+    # Returns an array of row indices.
+    # Returns an empty array if the instance contains no indices.
+    #
+    def rows
+      return @indices.collect {|index| index / @bin_image.columns}
+    end
+
+    # Shifts the indices of this selection by the specified number of columns and rows.
+    # Positive arguments increases the column and row indices.
+    #
+    # === Restrictions
+    #
+    # NB! No out of bounds check is performed for indices
+    # that are shifted past the image boundary.
+    #
+    def shift(delta_col, delta_row)
+      raise ArgumentError, "Invalid argument 'delta_col'. Expected Integer, got #{delta_col.class}." unless delta_col.is_a?(Integer)
+      raise ArgumentError, "Invalid argument 'delta_row'. Expected Integer, got #{delta_row.class}." unless delta_row.is_a?(Integer)
+      new_columns = @indices.collect {|index| index % @bin_image.columns + delta_col}
+      new_rows = @indices.collect {|index| index / @bin_image.columns + delta_row}
+      # Set new indices:
+      @indices = Array.new(new_rows.length) {|i| new_columns[i] + new_rows[i] * @bin_image.columns}
+    end
+
+    # Shifts the indices of this selection by the specified number of columns and rows,
+    # virtually 'crops' the original image by 2*columns and 2*rows, and adapts the indices
+    # to this virtually cropped image.
+    #
+    # === Notes
+    #
+    # Negative arguments decreases the column and row indices and
+    # crops at the end of the columns and rows.
+    #
+    # Positive arguments increases the column and row indices and
+    # crops at the start of the columns and rows.
+    #
+    # === Restrictions
+    #
+    # NB! No out of bounds check is performed for indices
+    # that are shifted past the image boundary.
+    #
+    def shift_and_crop(delta_col, delta_row)
+      raise ArgumentError, "Invalid argument 'delta_col'. Expected Integer, got #{delta_col.class}." unless delta_col.is_a?(Integer)
+      raise ArgumentError, "Invalid argument 'delta_row'. Expected Integer, got #{delta_row.class}." unless delta_row.is_a?(Integer)
+      new_columns = @indices.collect {|index| index % @bin_image.columns - delta_col.abs}
+      new_rows = @indices.collect {|index| index / @bin_image.columns - delta_row.abs}
+      # Set new indices:
+      @indices = Array.new(new_rows.length) {|i| new_columns[i] + new_rows[i] * (@bin_image.columns - delta_col.abs * 2)}
+    end
+
+    # Shifts the indices of this selection by the specified number of columns.
+    # A positive argument increases the column indices.
+    #
+    # === Restrictions
+    #
+    # NB! No out of bounds check is performed for indices
+    # that are shifted past the image boundary.
+    #
+    def shift_columns(delta)
+      raise ArgumentError, "Invalid argument 'delta'. Expected Integer, got #{delta.class}." unless delta.is_a?(Integer)
+      new_columns = @indices.collect {|index| index % @bin_image.columns + delta}
+      new_rows = rows
+      # Set new indices:
+      @indices = Array.new(new_columns.length) {|i| new_columns[i] + new_rows[i] * @bin_image.columns}
+    end
+
+    # Shifts the indices of this selection by the specified number of rows.
+    # A positive argument increases the row indices.
+    #
+    # === Restrictions
+    #
+    # NB! No out of bounds check is performed for indices
+    # that are shifted past the image boundary.
+    #
+    def shift_rows(delta)
+      raise ArgumentError, "Invalid argument 'delta'. Expected Integer, got #{delta.class}." unless delta.is_a?(Integer)
+      new_columns = columns
+      new_rows = @indices.collect {|index| index / @bin_image.columns + delta}
+      # Set new indices:
+      @indices = Array.new(new_rows.length) {|i| new_columns[i] + new_rows[i] * @bin_image.columns}
+    end
+
+    # Returns self.
+    #
+    def to_selection
+      self
+    end
+
+
+    private
+
+
+    # Returns the attributes of this instance in an array (for comparison purposes).
+    #
+    def state
+       [@indices]
+    end
+
+  end
+
+end

data/lib/rtkit/series.rb

@@ -0,0 +1,77 @@
+module RTKIT
+
+  # Contains the DICOM data and methods related to a series.
+  #
+  # === Relations
+  #
+  # * A Series belongs to a Study.
+  # * Some types of Series (e.g. CT, MR) have many Image instances.
+  #
+  class Series
+
+    # The SOP Class UID.
+    attr_reader :class_uid
+    # The Series Date.
+    attr_reader :date
+    # The Series Description.
+    attr_reader :description
+    # The Modality of the Series.
+    attr_reader :modality
+    # The Series's Study reference.
+    attr_reader :study
+    # The Series Instance UID.
+    attr_reader :series_uid
+    # The Series Time.
+    attr_reader :time
+
+    # Creates a new Series instance. The Series Instance UID string is used to uniquely identify a Series.
+    #
+    # === Parameters
+    #
+    # * <tt>series_uid</tt> -- The Series Instance UID string.
+    # * <tt>modality</tt> -- The Modality string of the Series, e.g. 'CT' or 'RTSTRUCT'.
+    # * <tt>study</tt> -- The Study instance that this Series belongs to.
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:class_uid</tt> -- String. The SOP Class UID (DICOM tag '0008,0016').
+    # * <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').
+    #
+    def initialize(series_uid, modality, study, options={})
+      raise ArgumentError, "Invalid argument 'uid'. Expected String, got #{series_uid.class}." unless series_uid.is_a?(String)
+      raise ArgumentError, "Invalid argument 'modality'. Expected String, got #{modality.class}." unless modality.is_a?(String)
+      raise ArgumentError, "Invalid argument 'study'. Expected Study, got #{study.class}." unless study.is_a?(Study)
+      # Key attributes:
+      @series_uid = series_uid
+      @modality = modality
+      @study = study
+      # Optional attributes:
+      @class_uid = options[:class_uid]
+      @date = options[:date]
+      @time = options[:time]
+      @description = options[:description]
+    end
+
+    # Returns true if the series is of a modality which means it contains multiple images (CT, MR, RTImage, RTDose).
+    # Returns false if not.
+    #
+    def image_modality?
+      if IMAGE_MODALITIES.include?(@modality)
+        return true
+      else
+        return false
+      end
+    end
+
+    # Returns the unique identifier string, which for an ImageSeries is the Series Instance UID,
+    # and for the other types of Series (e.g. StructureSet, Plan, etc) it is the SOP Instance UID.
+    #
+    def uid
+      return @sop_uid || @series_uid
+    end
+
+  end
+end

data/lib/rtkit/setup.rb

@@ -0,0 +1,198 @@
+module RTKIT
+
+  # Contains DICOM data and methods related to a patient Setup item, defined in a Plan.
+  #
+  # === Relations
+  #
+  # * A Plan has a Setup.
+  #
+  class Setup
+
+    # Patient setup number (Integer).
+    attr_reader :number
+    # Table top lateral setup displacement (Float).
+    attr_reader :offset_lateral
+    # Table top longitudinal setup displacement (Float).
+    attr_reader :offset_longitudinal
+    # Table top vertical setup displacement (Float).
+    attr_reader :offset_vertical
+    # The Plan that the Setup is defined for.
+    attr_reader :plan
+    # Patient position (orientation).
+    attr_reader :position
+    # Setup technique.
+    attr_reader :technique
+
+    # Creates a new Setup instance from the patient setup item of the RTPlan file.
+    # Returns the Setup instance.
+    #
+    # === Parameters
+    #
+    # * <tt>setup_item</tt> -- The patient setup item from the DObject of a RTPlan file.
+    # * <tt>plan</tt> -- The Plan instance that this Setup belongs to.
+    #
+    def self.create_from_item(setup_item, plan)
+      raise ArgumentError, "Invalid argument 'setup_item'. Expected DICOM::Item, got #{setup_item.class}." unless setup_item.is_a?(DICOM::Item)
+      raise ArgumentError, "Invalid argument 'plan'. Expected Plan, got #{plan.class}." unless plan.is_a?(Plan)
+      options = Hash.new
+      # Values from the Patient Setup Item:
+      position = setup_item.value(PATIENT_POSITION) || ''
+      number = setup_item.value(PATIENT_SETUP_NUMBER).to_i
+      options[:technique] = setup_item.value(SETUP_TECHNIQUE)
+      options[:offset_vertical] = setup_item.value(OFFSET_VERTICAL).to_f
+      options[:offset_longitudinal] = setup_item.value(OFFSET_LONG).to_f
+      options[:offset_lateral] = setup_item.value(OFFSET_LATERAL).to_f
+      # Create the Setup instance:
+      s = self.new(position, number, plan, options)
+      return s
+    end
+
+    # Creates a new Setup instance.
+    #
+    # === Parameters
+    #
+    # * <tt>position</tt> -- String. The patient position (orientation).
+    # * <tt>number</tt> -- Integer. The Setup number.
+    # * <tt>plan</tt> -- The Plan instance that this Beam belongs to.
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:technique</tt> -- String. Setup technique.
+    # * <tt>:offset_vertical</tt> -- Float. Table top vertical setup displacement.
+    # * <tt>:offset_longitudinal</tt> -- Float. Table top longitudinal setup displacement.
+    # * <tt>:offset_lateral</tt> -- Float. Table top lateral setup displacement.
+    #
+    def initialize(position, number, plan, options={})
+      raise ArgumentError, "Invalid argument 'plan'. Expected Plan, got #{plan.class}." unless plan.is_a?(Plan)
+      # Set values:
+      self.position = position
+      self.number = number
+      # Set options:
+      self.technique = options[:technique] if options[:technique]
+      self.offset_vertical = options[:offset_vertical] if options[:offset_vertical]
+      self.offset_longitudinal = options[:offset_longitudinal] if options[:offset_longitudinal]
+      self.offset_lateral = options[:offset_lateral] if options[:offset_lateral]
+      # Set references:
+      @plan = plan
+      # Register ourselves with the Plan:
+      @plan.add_setup(self)
+    end
+
+    # Returns true if the argument is an instance with attributes equal to self.
+    #
+    def ==(other)
+      if other.respond_to?(:to_setup)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Generates a Fixnum hash value for this instance.
+    #
+    def hash
+      state.hash
+    end
+
+    # Sets a new patient setup number.
+    #
+    # === Parameters
+    #
+    # * <tt>value</tt> -- Float. The patient setup number.
+    #
+    def number=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected Integer, got #{value.class}." unless value.is_a?(Integer)
+      @number = value
+    end
+
+    # Sets a new table top lateral setup displacement.
+    #
+    # === Parameters
+    #
+    # * <tt>value</tt> -- Float. The table top lateral setup displacement.
+    #
+    def offset_lateral=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected Float, got #{value.class}." unless value.is_a?(Float)
+      @offset_lateral = value
+    end
+
+    # Sets a new table top longitudinal setup displacement.
+    #
+    # === Parameters
+    #
+    # * <tt>value</tt> -- Float. The table top longitudinal setup displacement.
+    #
+    def offset_longitudinal=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected Float, got #{value.class}." unless value.is_a?(Float)
+      @offset_longitudinal = value
+    end
+
+    # Sets a new table top vertical setup displacement.
+    #
+    # === Parameters
+    #
+    # * <tt>value</tt> -- Float. The table top vertical setup displacement.
+    #
+    def offset_vertical=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected Float, got #{value.class}." unless value.is_a?(Float)
+      @offset_vertical = value
+    end
+
+    # Sets a new patient position.
+    #
+    # === Parameters
+    #
+    # * <tt>value</tt> -- String. The patient position.
+    #
+    def position=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @position = value
+    end
+
+    # Sets a new setup technique.
+    #
+    # === Parameters
+    #
+    # * <tt>value</tt> -- String. The setup technique.
+    #
+    def technique=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @technique = value
+    end
+
+    # Creates and returns a Patient Setup Sequence Item from the attributes of the Setup.
+    #
+    def to_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
+
+    # Returns self.
+    #
+    def to_setup
+      self
+    end
+
+
+    private
+
+
+    # Returns the attributes of this instance in an array (for comparison purposes).
+    #
+    def state
+       [@number, @offset_lateral, @offset_longitudinal, @offset_vertical, @position, @technique]
+    end
+
+  end
+end