rtkit 0.7

data/lib/rtkit/collimator.rb

@@ -0,0 +1,157 @@
+module RTKIT
+
+  # Contains DICOM data and methods related to a RT Beam Limiting Device
+  # item, defined in a Beam.
+  #
+  # === Relations
+  #
+  # * A Beam has many Collimators.
+  #
+  class Collimator
+
+    # The Beam that the CollimatorSetup is defined for.
+    attr_reader :beam
+    # Collimator boundaries (for multi leaf collimators only: the number of boundaries equals the number of leaves + 1).
+    attr_reader :boundaries
+    # The number of Leaf/Jaw (Collimator) Pairs.
+    attr_reader :num_pairs
+    # Collimator type.
+    attr_reader :type
+
+    # Creates a new Collimator instance from the RT Beam Limiting Device item of the RTPlan file.
+    # Returns the Collimator instance.
+    #
+    # === Parameters
+    #
+    # * <tt>coll_item</tt> -- The patient setup item from the DObject of a RTPlan file.
+    # * <tt>beam</tt> -- The Beam instance that this Collimator belongs to.
+    #
+    def self.create_from_item(coll_item, beam)
+      raise ArgumentError, "Invalid argument 'coll_item'. Expected DICOM::Item, got #{coll_item.class}." unless coll_item.is_a?(DICOM::Item)
+      raise ArgumentError, "Invalid argument 'beam'. Expected Beam, got #{beam.class}." unless beam.is_a?(Beam)
+      options = Hash.new
+      # Values from the Beam Limiting Device Type Item:
+      type = coll_item.value(COLL_TYPE)
+      num_pairs = coll_item.value(NR_COLLIMATORS)
+      boundaries = coll_item.value(COLL_BOUNDARIES)
+      # Create the Collimator instance:
+      c = self.new(type, num_pairs, beam, :boundaries => boundaries)
+      return c
+    end
+
+    # Creates a new Collimator instance.
+    #
+    # === Parameters
+    #
+    # * <tt>type</tt> -- String. The RT Beam Limiting Device Type.
+    # * <tt>num_pairs</tt> -- Integer. The Number of Leaf/Jaw Pairs.
+    # * <tt>beam</tt> -- The Beam instance that this Collimator belongs to.
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:boundaries</tt> -- Array/String. The Leaf Position Boundaries (300A,00BE). Defaults to nil.
+    #
+    def initialize(type, num_pairs, beam, options={})
+      raise ArgumentError, "Invalid argument 'beam'. Expected Beam, got #{beam.class}." unless beam.is_a?(Beam)
+      # Set values:
+      self.type = type
+      self.num_pairs = num_pairs
+      self.boundaries = options[:boundaries]
+      # Set references:
+      @beam = beam
+      # Register ourselves with the Beam:
+      @beam.add_collimator(self)
+    end
+
+    # Returns true if the argument is an instance with attributes equal to self.
+    #
+    def ==(other)
+      if other.respond_to?(:to_collimator)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Generates a Fixnum hash value for this instance.
+    #
+    def hash
+      state.hash
+    end
+
+    # Creates and returns a Beam Limiting Device Sequence Item
+    # from the attributes of the Collimator.
+    #
+    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
+
+    # Sets new Leaf Position Boundaries  (an array of positions).
+    #
+    # === Parameters
+    #
+    # * <tt>value</tt> -- Array/String. The Leaf Position Boundaries (300A,00BE).
+    #
+    def boundaries=(value)
+      if !value
+        @boundaries = nil
+      elsif value.is_a?(Array)
+        @boundaries = value
+      else
+        # Split the string & convert to float:
+        @boundaries = value.to_s.split("\\").collect {|str| str.to_f}
+      end
+    end
+
+    # Sets a new RT Beam Limiting Device Type.
+    #
+    # === Parameters
+    #
+    # * <tt>value</tt> -- Integer. The Number of Leaf/Jaw Pairs (300A,00BC).
+    #
+    def num_pairs=(value)
+      raise ArgumentError, "Argument 'value' must be defined (got #{value.class})." unless value
+      @num_pairs = value.to_i
+    end
+
+    # Returns self.
+    #
+    def to_collimator
+      self
+    end
+
+    # Sets a new RT Beam Limiting Device Type.
+    #
+    # === Parameters
+    #
+    # * <tt>value</tt> -- String. The RT Beam Limiting Device Type (300A,00B8).
+    #
+    def type=(value)
+      raise ArgumentError, "Argument 'value' must be defined (got #{value.class})." unless value
+      @type = value.to_s
+    end
+
+
+    private
+
+
+    # Returns the attributes of this instance in an array (for comparison purposes).
+    #
+    def state
+       [@boundaries, @num_pairs, @type]
+    end
+
+  end
+end

data/lib/rtkit/collimator_setup.rb

@@ -0,0 +1,143 @@
+module RTKIT
+
+  # Contains DICOM data and methods related to a RT Beam Limiting Device
+  # Position item, defined in a ControlPoint.
+  #
+  # === Relations
+  #
+  # * A ControlPoint has many CollimatorSetups.
+  #
+  class CollimatorSetup
+
+    # The ControlPoint that the Collimator is defined for.
+    attr_reader :control_point
+    # Collimator pairs of positions.
+    attr_reader :positions
+    # Collimator type.
+    attr_reader :type
+
+    # Creates a new CollimatorSetup instance from the RT Beam Limiting Device Position item of the RTPlan file.
+    # Returns the CollimatorSetup instance.
+    #
+    # === Parameters
+    #
+    # * <tt>coll_item</tt> -- The RT Beam Limiting Device Position item from the DObject of a RTPlan file.
+    # * <tt>control_point</tt> -- The ControlPoint instance that this CollimatorSetup belongs to.
+    #
+    def self.create_from_item(coll_item, control_point)
+      raise ArgumentError, "Invalid argument 'coll_item'. Expected DICOM::Item, got #{coll_item.class}." unless coll_item.is_a?(DICOM::Item)
+      raise ArgumentError, "Invalid argument 'control_point'. Expected ControlPoint, got #{control_point.class}." unless control_point.is_a?(ControlPoint)
+      options = Hash.new
+      # Values from the Beam Limiting Device Position Item:
+      type = coll_item.value(COLL_TYPE)
+      positions = coll_item.value(COLL_POS)
+      #positions = coll_item.value(COLL_POS).split("\\").collect {|str| str.to_f}
+      # Regroup the positions values so they appear in pairs:
+      #positions = positions.each_slice(2).collect{|i| i}.transpose
+      # Create the Collimator instance:
+      c = self.new(type, positions, control_point)
+      return c
+    end
+
+    # Creates a new CollimatorSetup instance.
+    #
+    # === Parameters
+    #
+    # * <tt>type</tt> -- String. The RT Beam Limiting Device Type.
+    # * <tt>positions</tt> -- Array. The collimator positions, organised in pairs of two values.
+    # * <tt>control_point</tt> -- The ControlPoint instance that this CollimatorSetup belongs to.
+    #
+    def initialize(type, positions, control_point)
+      raise ArgumentError, "Invalid argument 'control_point'. Expected ControlPoint, got #{control_point.class}." unless control_point.is_a?(ControlPoint)
+      # Set values:
+      self.type = type
+      self.positions = positions
+      # Set references:
+      @control_point = control_point
+      # Register ourselves with the ControlPoint:
+      @control_point.add_collimator(self)
+    end
+
+    # Returns true if the argument is an instance with attributes equal to self.
+    #
+    def ==(other)
+      if other.respond_to?(:to_collimator_setup)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Generates a Fixnum hash value for this instance.
+    #
+    def hash
+      state.hash
+    end
+
+    # Sets new Leaf/Jaw Positions (an array with pairs of positions).
+    #
+    # === Parameters
+    #
+    # * <tt>value</tt> -- Array. The Leaf/Jaw positions (300A,011C).
+    #
+    def positions=(value)
+      raise ArgumentError, "Argument 'value' must be defined (got #{value.class})." unless value
+      if value.is_a?(Array)
+        @positions = value
+      else
+        # Split the string, convert to float, and regroup the positions so they appear in pairs:
+        positions = value.to_s.split("\\").collect {|str| str.to_f}
+        if positions.length == 2
+          @positions = [positions]
+        else
+          @positions = positions.each_slice(2).collect{|i| i}.transpose
+        end
+      end
+    end
+
+    # Returns self.
+    #
+    def to_collimator_setup
+      self
+    end
+
+    # Creates and returns a Beam Limiting Device Position Sequence Item
+    # from the attributes of the CollimatorSetup.
+    #
+    def to_item
+      item = DICOM::Item.new
+      item.add(DICOM::Element.new(COLL_TYPE, @type))
+      item.add(DICOM::Element.new(COLL_POS, positions_string))
+      return item
+    end
+
+    # Sets a new RT Beam Limiting Device Type.
+    #
+    # === Parameters
+    #
+    # * <tt>value</tt> -- String. The RT Beam Limiting Device Type (300A,00B8).
+    #
+    def type=(value)
+      raise ArgumentError, "Argument 'value' must be defined (got #{value.class})." unless value
+      @type = value.to_s
+    end
+
+
+    private
+
+
+    # Returns the position values converted to a '\' separated string with values
+    # appearing in the order as specified by the dicom standard.
+    #
+    def positions_string
+      @positions.transpose.join("\\")
+    end
+
+    # Returns the attributes of this instance in an array (for comparison purposes).
+    #
+    def state
+       [@positions, @type]
+    end
+
+  end
+end

data/lib/rtkit/constants.rb

@@ -0,0 +1,215 @@
+module RTKIT
+
+  # Instance Creation Date.
+  IMAGE_DATE = '0008,0012'
+  # Instance Creation Time.
+  IMAGE_TIME = '0008,0013'
+  # SOP Class UID.
+  SOP_CLASS = '0008,0016'
+  # SOP Instance UID.
+  SOP_UID = '0008,0018'
+  # Study Date.
+  STUDY_DATE = '0008,0020'
+  # Series Date.
+  SERIES_DATE = '0008,0021'
+  # Study Time.
+  STUDY_TIME = '0008,0030'
+  # Series Time.
+  SERIES_TIME = '0008,0031'
+  # Modality.
+  MODALITY = '0008,0060'
+  # Study description.
+  STUDY_DESCR = '0008,1030'
+  # Series description.
+  SERIES_DESCR = '0008,103E'
+  # Referenced SOP Class UID.
+  REF_SOP_CLASS_UID = '0008,1150'
+  # Referenced SOP Instance UID.
+  REF_SOP_UID = '0008,1155'
+  # Patient's Name.
+  PATIENTS_NAME = '0010,0010'
+  # Patient's Name.
+  PATIENTS_ID = '0010,0020'
+  # Patient's Name.
+  BIRTH_DATE = '0010,0030'
+  # Patient's Name.
+  SEX = '0010,0040'
+  # Patient Position.
+  PATIENT_POSITION = '0018,5100'
+  # Study Instance UID.
+  STUDY_UID = '0020,000D'
+  # Series Instance UID.
+  SERIES_UID = '0020,000E'
+  # Study ID.
+  STUDY_ID = '0020,0010'
+  # Image Position (Patient).
+  IMAGE_POSITION = '0020,0032'
+  # Image Orientation (Patient):
+  IMAGE_ORIENTATION = '0020,0037'
+  # Frame of Reference UID.
+  FRAME_OF_REF = '0020,0052'
+  # Position Reference Indicator.
+  POS_REF_INDICATOR = '0020,1040'
+  # Number of Frames.
+  NR_FRAMES = '0028,0008'
+  # Rows.
+  ROWS = '0028,0010'
+  # Columns.
+  COLUMNS = '0028,0011'
+  # Pixel Spacing.
+  SPACING = '0028,0030'
+  # Image Plane Pixel Spacing.
+  IMAGE_PLANE_SPACING = '3002,0011'
+  # RT Image Position.
+  RT_IMAGE_POSITION = '3002,0012'
+  # Grid Frame Offset Vector.
+  GRID_FRAME_OFFSETS = '3004,000C'
+  # Dose Grid Scaling.
+  DOSE_GRID_SCALING = '3004,000E'
+  # Referenced Frame of Reference Sequence.
+  REF_FRAME_OF_REF_SQ = '3006,0010'
+  # RT Referenced Study Sequence.
+  RT_REF_STUDY_SQ = '3006,0012'
+  # RT Referenced Series Sequence.
+  RT_REF_SERIES_SQ = '3006,0014'
+  # Contour Image Sequence.
+  CONTOUR_IMAGE_SQ = '3006,0016'
+  # Structure Set ROI Sequence.
+  STRUCTURE_SET_ROI_SQ = '3006,0020'
+  # ROI Number.
+  ROI_NUMBER = '3006,0022'
+  # Referenced Frame of Reference UID.
+  REF_FRAME_OF_REF = '3006,0024'
+  # ROI Name.
+  ROI_NAME = '3006,0026'
+  # ROI Display Color.
+  ROI_COLOR = '3006,002A'
+  # ROI Generation Algorithm.
+  ROI_ALGORITHM = '3006,0036'
+  # ROI Contour Sequence.
+  ROI_CONTOUR_SQ = '3006,0039'
+  # Contour Sequence.
+  CONTOUR_SQ = '3006,0040'
+  # Contour Geometric Type.
+  CONTOUR_GEO_TYPE = '3006,0042'
+  # Number of Contour Points.
+  NR_CONTOUR_POINTS = '3006,0046'
+  # Contour Number.
+  CONTOUR_NUMBER = '3006,0048'
+  # Contour Data.
+  CONTOUR_DATA = '3006,0050'
+  # RT ROI Observations Sequence.
+  RT_ROI_OBS_SQ = '3006,0080'
+  # Obervation Number.
+  OBS_NUMBER = '3006,0082'
+  # Referenced ROI Number.
+  REF_ROI_NUMBER = '3006,0084'
+  # RT ROI Interpreted Type.
+  ROI_TYPE = '3006,00A4'
+  # ROI Interpreter.
+  ROI_INTERPRETER = '3006,00A6'
+  # Frame of Reference Relationship Sequence.
+  FRAME_OF_REF_REL_SQ = '3006,00C0'
+  # Fraction Group Sequence.
+  FRACTION_GROUP_SQ = '300A,0070'
+  # Fraction Group Number.
+  FRACTION_GROUP_NUMBER = '300A,0071'
+  # Beam Meterset.
+  BEAM_METERSET = '300A,0086'
+  # Beam Sequence.
+  BEAM_SQ = '300A,00B0'
+  # Treatment Machine Name.
+  MACHINE_NAME = '300A,00B2'
+  # Primary Dosimeter Unit.
+  DOSIMETER_UNIT = '300A,00B3'
+  # Source-Axis Distance.
+  SAD = '300A,00B4'
+  # RT Beam Limiting Device Sequence.
+  COLL_SQ = '300A,00B6'
+  # RT Beam Limiting Device Type.
+  COLL_TYPE = '300A,00B8'
+  # Number of Leaf/Jaw Pairs.
+  NR_COLLIMATORS = '300A,00BC'
+  # Leaf Position Boundaries.
+  COLL_BOUNDARIES = '300A,00BE'
+  # Beam Number.
+  BEAM_NUMBER = '300A,00C0'
+  # Beam Name.
+  BEAM_NAME = '300A,00C2'
+  # Beam Description.
+  BEAM_DESCR = '300A,00C3'
+  # Beam Type.
+  BEAM_TYPE = '300A,00C4'
+  # Radiation Type.
+  RAD_TYPE = '300A,00C6'
+  # Treatment Delivery Type.
+  DELIVERY_TYPE = '300A,00CE'
+  # Final Cumulative Meterset Weight.
+  FINAL_METERSET_WEIGHT = '300A,010E'
+  # Control Point Sequence.
+  CONTROL_POINT_SQ = '300A,0111'
+  # Cumulative Meterset Weight.
+  CONTROL_POINT_INDEX = '300A,0112'
+  # Nominal Beam Energy.
+  BEAM_ENERGY = '300A,0114'
+  # RT Beam Limiting Device Type Sequence.
+  COLL_POS_SQ = '300A,011A'
+  # Leaf/Jaw Positions.
+  COLL_POS = '300A,011C'
+  # Gantry Angle.
+  GANTRY_ANGLE = '300A,011E'
+  # Gantry Rotation Direction.
+  GANTRY_DIRECTION = '300A,011F'
+  # Beam Limiting Device Angle.
+  COLL_ANGLE = '300A,0120'
+  # Beam Limiting Device Rotation Direction.
+  COLL_DIRECTION = '300A,0121'
+  # Patient Support Angle.
+  PEDESTAL_ANGLE = '300A,0122'
+  # Patient Support Rotation Direction.
+  PEDESTAL_DIRECTION = '300A,0123'
+  # Table Top Eccentric Angle.
+  TABLE_TOP_ANGLE = '300A,0125'
+  # Table Top Eccentric Rotation Direction.
+  TABLE_TOP_DIRECTION = '300A,0126'
+  # Table Top Vertical Position.
+  TABLE_TOP_VERTICAL = '300A,0128'
+  # Table Top Longitudinal Position.
+  TABLE_TOP_LONGITUDINAL = '300A,0129'
+  # Table Top Lateral Position.
+  TABLE_TOP_LATERAL = '300A,012A'
+  # Isocenter Position.
+  ISO_POS = '300A,012C'
+  # Source to Surface Distance.
+  SSD = '300A,0130'
+  # Cumulative Meterset Weight.
+  CUM_METERSET_WEIGHT = '300A,0134'
+  # Patient Setup Sequence.
+  PATIENT_SETUP_SQ = '300A,0180'
+  # Patient Setup Number.
+  PATIENT_SETUP_NUMBER = '300A,0182'
+  # Setup technique.
+  SETUP_TECHNIQUE = '300A,01B0'
+  # Table Top Vertical Setup Displacement.
+  OFFSET_VERTICAL = '300A,01D2'
+  # Table Top Longitudinal Setup Displacement.
+  OFFSET_LONG = '300A,01D4'
+  # Table Top Lateral Setup Displacement.
+  OFFSET_LATERAL = '300A,01D6'
+  # Referenced RT Plan Sequence.
+  REF_PLAN_SQ = '300C,0002'
+  # Referenced Beam Sequence.
+  REF_BEAM_SQ = '300C,0004'
+  # Referenced Beam Number.
+  REF_BEAM_NUMBER = '300C,0006'
+  # Referenced Structure Set Sequence.
+  REF_STRUCT_SQ = '300C,0060'
+
+  # The modalities that contain multiple images per series.
+  IMAGE_SERIES = ['CT', 'MR']
+  # The modalities that contain pixel data:
+  IMAGE_MODALITIES = ['CT', 'MR', 'RTDOSE', 'RTIMAGE']
+  # The modalities supported by RTKIT.
+  SUPPORTED_MODALITIES = ['CT', 'MR', 'RTDOSE', 'RTIMAGE', 'RTPLAN', 'RTSTRUCT']
+
+end