rtkit 0.7

data/lib/rtkit/coordinate.rb

@@ -0,0 +1,83 @@
+module RTKIT
+
+  # Contains a X,Y,Z triplet, which along with other Coordinates, defines a Contour.
+  #
+  # === Relations
+  #
+  # * The Coordinate belongs to a Contour.
+  #
+  class Coordinate
+
+    # The Contour that the Coordinate belongs to.
+    attr_reader :contour
+    # The X location (in units of mm).
+    attr_reader :x
+    # The Y location (in units of mm).
+    attr_reader :y
+    # The Z location (in units of mm).
+    attr_reader :z
+
+    # Creates a new Coordinate instance.
+    #
+    # === Parameters
+    #
+    # * <tt>x</tt> -- Float. The location of the Contour point along the x-axis (in units of mm).
+    # * <tt>y</tt> -- Float. The location of the Contour point along the y-axis (in units of mm).
+    # * <tt>z</tt> -- Float. The location of the Contour point along the z-axis (in units of mm).
+    # * <tt>contour</tt> -- The Contour instance (if any) that this Coordinate belongs to.
+    #
+    def initialize(x, y, z, contour=nil)
+      raise ArgumentError, "Invalid argument 'x'. Expected Float, got #{x.class}." unless x.is_a?(Float)
+      raise ArgumentError, "Invalid argument 'y'. Expected Float, got #{y.class}." unless y.is_a?(Float)
+      raise ArgumentError, "Invalid argument 'z'. Expected Float, got #{z.class}." unless z.is_a?(Float)
+      raise ArgumentError, "Invalid argument 'contour'. Expected Contour (or nil), got #{contour.class}." if contour && !contour.is_a?(Contour)
+      @contour = contour
+      @x = x
+      @y = y
+      @z = z
+      # Register ourselves with the Contour:
+      @contour.add_coordinate(self) if contour
+    end
+
+    # Returns true if the argument is an instance with attributes equal to self.
+    #
+    def ==(other)
+      if other.respond_to?(:to_coordinate)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Generates a Fixnum hash value for this instance.
+    #
+    def hash
+      state.hash
+    end
+
+    # Returns self.
+    #
+    def to_coordinate
+      self
+    end
+
+
+    # Returns a string where the x, y & z values are separated by a '\'.
+    #
+    def to_s
+      [@x, @y, @z].join("\\")
+    end
+
+
+    private
+
+
+    # Returns the attributes of this instance in an array (for comparison purposes).
+    #
+    def state
+       [@x, @y, @z]
+    end
+
+  end
+
+end

data/lib/rtkit/data_set.rb

@@ -0,0 +1,264 @@
+#    Copyright 2012 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/>.
+#
+module RTKIT
+
+  # Handles the DICOM data found at a particular location, typically all files contained in a specific directory.
+  # A DataSet contains all DICOM objects read from the specified source,
+  # organized in a patient - study - series - image structure.
+  #
+  class DataSet
+
+    # An array of Frame instances loaded for this DataSet.
+    attr_reader :frames
+    # An array of Patient instances loaded for this DataSet.
+    attr_reader :patients
+
+    # Creates (and returns) a new DataSet instance from an array of DICOM objects.
+    #
+    # === Parameters
+    #
+    # * <tt>objects</tt> -- An array of DICOM::DObject instances which will be loaded into the DataSet.
+    #
+    def self.load(objects)
+      raise ArgumentError, "Invalid argument 'objects'. Expected Array, got #{objects.class}." unless objects.is_a?(Array)
+      raise ArgumentError, "Invalid argument 'objects'. Expected Array to contain only DObjects, got #{objects.collect{|dcm| dcm.class}.uniq}." if objects.collect{|dcm| dcm.class}.uniq != [DICOM::DObject]
+      # We will put the objects in arrays sorted by modality, to control
+      # the sequence in which they are loaded in our data structure:
+      images = Array.new
+      structs = Array.new
+      plans = Array.new
+      doses = Array.new
+      rtimages = Array.new
+      # Read and sort:
+      objects.each do |dcm|
+        # Find out which modality our DICOM file is and handle it accordingly:
+        modality = dcm.value("0008,0060")
+        case modality
+          when *IMAGE_SERIES
+            images << dcm
+          when 'RTSTRUCT'
+            structs << dcm
+          when 'RTPLAN'
+            plans << dcm
+          when 'RTDOSE'
+            doses << dcm
+          when 'RTIMAGE'
+            rtimages << dcm
+          else
+            #puts "Notice: Unsupported modality (ignored): #{modality}"
+        end
+      end
+      # Create the DataSet:
+      ds = DataSet.new
+      # Add the objects to our data structure in a specific sequence:
+      [images, structs, plans, doses, rtimages].each do |modality|
+        modality.each do |dcm|
+          ds.add(dcm)
+        end
+      end
+      return ds
+    end
+
+    # Creates (and returns) a new DataSet instance from a specified path,
+    # by reading and loading the DICOM files found in this directory (including its sub-directories).
+    #
+    # === Parameters
+    #
+    # * <tt>path</tt> -- A path to the directory containing the DICOM files you want to load.
+    #
+    def self.read(path)
+      raise ArgumentError, "Invalid argument 'path'. Expected String, got #{path.class}." unless path.is_a?(String)
+      # Get the files:
+      files = RTKIT.files(path)
+      raise ArgumentError, "No files found in the specified folder: #{path}" unless files.length > 0
+      # Load DICOM objects:
+      objects = Array.new
+      failed = Array.new
+      files.each do |file|
+        dcm = DICOM::DObject.read(file)
+        if dcm.read?
+          objects << dcm
+        else
+          failed << file
+          #puts "Warning: A file was not successfully read as a DICOM object. (#{file})"
+        end
+      end
+      raise ArgumentError, "No DICOM files were successfully read from the specified folder: #{path}" unless objects.length > 0
+      # Create the DataSet:
+      return DataSet.load(objects)
+    end
+
+    # Creates a new DataSet instance.
+    #
+    def initialize
+      # Create instance variables:
+      @frames = Array.new
+      @patients = Array.new
+      @associated_frames = Hash.new
+      @associated_patients = Hash.new
+    end
+
+    # Returns true if the argument is an instance with attributes equal to self.
+    #
+    def ==(other)
+      if other.respond_to?(:to_data_set)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Adds a DICOM object to the dataset, by adding it
+    # to an existing Patient, or creating a new Patient.
+    #
+    # === Restrictions
+    #
+    # To ensure a correct relationship between objects of different modality, please add
+    # DICOM objects in the specific order: images, structs, plans, doses, rtimages
+    # Alternatively, use the class method DataSet.load(objects), which handles this automatically.
+    #
+    def add(dcm)
+      id = dcm.value(PATIENTS_ID)
+      p = patient(id)
+      if p
+        p.add(dcm)
+      else
+        add_patient(Patient.load(dcm, self))
+      end
+    end
+
+    # Adds a Frame to this DataSet.
+    #
+    def add_frame(frame)
+      raise ArgumentError, "Invalid argument 'frame'. Expected Frame, got #{frame.class}." unless frame.is_a?(Frame)
+      # Do not add it again if the frame already belongs to this instance:
+      @frames << frame unless @associated_frames[frame.uid]
+      @associated_frames[frame.uid] = frame
+    end
+
+    # Adds a Patient to this DataSet.
+    #
+    def add_patient(patient)
+      raise ArgumentError, "Invalid argument 'patient'. Expected Patient, got #{patient.class}." unless patient.is_a?(Patient)
+      # Do not add it again if the patient already belongs to this instance:
+      @patients << patient unless @associated_patients[patient.id]
+      @associated_patients[patient.id] = patient
+    end
+
+    # Returns the Frame instance mathcing the specified Frame's UID (if an UID argument is used).
+    # If a specified UID doesn't match, nil is returned.
+    # If no argument is passed, the first Frame instance associated with the DataSet is returned.
+    #
+    # === Parameters
+    #
+    # * <tt>uid</tt> -- String. The Frame of Reference UID.
+    #
+    def frame(*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_frames[args.first]
+      else
+        # No argument used, therefore we return the first Frame instance:
+        return @frames.first
+      end
+    end
+
+    # Generates a Fixnum hash value for this instance.
+    #
+    def hash
+      state.hash
+    end
+
+    # Returns the Patient instance mathcing the specified Patient's ID (if an ID argument is used).
+    # If a specified ID doesn't match, nil is returned.
+    # If no argument is passed, the first Patient instance associated with the DataSet is returned.
+    #
+    # === Parameters
+    #
+    # * <tt>id</tt> -- String. The value of the Patient's ID element.
+    #
+    def patient(*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_patients[args.first]
+      else
+        # No argument used, therefore we return the first Patient instance:
+        return @patients.first
+      end
+    end
+
+    # Prints the nested structure of patient - study - series - images that have been loaded to the dataset instance.
+    #
+    def print
+      @patients.each do |p|
+        puts p.name
+        p.studies.each do |st|
+          puts "  #{st.uid}"
+          st.series.each do |se|
+            puts "    #{se.modality}"
+            if se.images
+              puts "      (#{se.images.length} images)"
+            end
+          end
+        end
+      end
+    end
+
+    # Prints the nested structure of patient - study - modalities from
+    # a RT point of view, with image_series - ss - plan, etc.
+    #
+    def print_rt
+      @patients.each do |p|
+        puts p.name
+        p.studies.each do |st|
+          puts "  #{st.uid}"
+          st.image_series.each do |is|
+            puts "    #{is.modality} (#{is.images.length} images)"
+            is.structs.each do |struct|
+              puts "      StructureSet"
+              struct.plans.each do |plan|
+                puts "        RTPlan"
+                puts "          RTDose" if plan.dose
+                puts "          RTImage" if plan.rtimage
+              end
+            end
+          end
+        end
+      end
+    end
+
+    # Returns self.
+    #
+    def to_data_set
+      self
+    end
+
+
+    # Following methods are private:
+    private
+
+
+    # Returns the attributes of this instance in an array (for comparison purposes).
+    #
+    def state
+       [@frames, @patients]
+    end
+
+  end
+
+end

data/lib/rtkit/dose.rb

@@ -0,0 +1,70 @@
+module RTKIT
+
+  # NB! The Dose class is as of yet just a concept, and not in actual use
+  # by RTKIT. It will probably be put to use in a future version.
+  #
+  # Contains data and methods related to a single Dose value.
+  # The Dose value may be an average, median, max/min, etc derived
+  # from a collection of Dose values as given in a DoseDistribution.
+  #
+  # === Relations
+  #
+  # * A Dose (value) belongs to the DoseDistribution from which it was created.
+  # * The Dose class can be considered a subclass of Float (although strictly
+  #    speaking it is rather a Float delegated class.
+  #
+  require 'delegate'
+  class Dose < DelegateClass(Float)
+
+    # The DoseDistribution that the single Dose value is derived from.
+    attr_reader :distribution
+    # The Dose value.
+    attr_reader :value
+
+    # Creates a new Dose instance.
+    #
+    # === Parameters
+    #
+    # * <tt>value</tt> -- Float. A dose value.
+    # * <tt>distribution</tt> -- The DoseDistribution which this single Dose value belongs to.
+    #
+    def initialize(value, distribution)
+      raise ArgumentError, "Invalid argument 'distribution'. Expected DoseDistribution, got #{distribution.class}." unless distribution.is_a?(DoseDistribution)
+      super(value.to_f)
+      @value = value
+      @distribution = distribution
+    end
+
+    # Returns true if the argument is an instance with attributes equal to self.
+    #
+    def ==(other)
+      if other.respond_to?(:to_dose)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Generates a Fixnum hash value for this instance.
+    #
+    def hash
+      state.hash
+    end
+
+    # Returns self.
+    #
+    def to_dose
+      self
+    end
+
+
+    private
+
+    # Returns the attributes of this instance in an array (for comparison purposes).
+    #
+    def state
+       [@value, @distribution]
+    end
+
+  end
+end

data/lib/rtkit/dose_distribution.rb

@@ -0,0 +1,206 @@
+module RTKIT
+
+  # Contains DICOM data and methods related to a DoseDistribution,
+  # a collection of dose points extracted from a dose volume.
+  #
+  # === Relations
+  #
+  # * A DoseDistribution belongs to the DoseVolume from which it was created.
+  # * A DoseDistribution contains various methods to return a Dose (point) instance.
+  #
+  class DoseDistribution
+
+    # The doses values belonging to this distribution (array of floats).
+    attr_reader :doses
+    # The DoseVolume that the DoseDistribution is derived from.
+    attr_reader :volume
+
+    # Creates a new DoseDistribution instance from a BinVolume.
+    # The BinVolume is typically defined from a ROI delineation against a DoseVolume.
+    # Returns the DoseDistribution instance.
+    #
+    # === Parameters
+    #
+    # * <tt>bin_volume</tt> -- A BinVolume, referencing a DoseVolume, from which to extract a DoseDistribution.
+    #
+    def self.create(bin_volume)
+      raise ArgumentError, "Invalid argument 'bin_volume'. Expected BinVolume, got #{bin_volume.class}." unless bin_volume.is_a?(BinVolume)
+      raise ArgumentError, "Invalid argument 'bin_volume'. It must reference a DoseVolume, got #{bin_volume.bin_images.first.image.series.class}." unless bin_volume.bin_images.first.image.series.is_a?(DoseVolume)
+      dose_volume = bin_volume.bin_images.first.image.series
+      # Extract a selection of pixel values from the dose images based on the provided binary volume:
+      dose_values = NArray.sfloat(0)
+      bin_volume.bin_images.each do |bin_image|
+        slice_pixel_values = bin_image.image.pixel_values(bin_image.selection)
+        slice_dose_values = slice_pixel_values.to_type(4) * bin_image.image.series.scaling
+        dose_values = NArray[*dose_values, *slice_dose_values]
+      end
+      # Create the DoseDistribution instance:
+      dd = self.new(dose_values, dose_volume)
+      return dd
+    end
+
+    # Creates a new DoseDistribution instance.
+    #
+    # === Parameters
+    #
+    # * <tt>doses</tt> -- An array/NArray of doses (floats).
+    # * <tt>volume</tt> -- The DoseVolume which this DoseDistribution belongs to.
+    #
+    def initialize(doses, volume)
+      #raise ArgumentError, "Invalid argument 'doses'. Expected Array, got #{doses.class}." unless doses.is_a?(Array)
+      raise ArgumentError, "Invalid argument 'volume'. Expected DoseVolume, got #{volume.class}." unless volume.is_a?(DoseVolume)
+      # Store doses as a sorted (float) NArray:
+      @doses = NArray.to_na(doses).sort.to_type(4)
+      # Set references:
+      @volume = volume
+    end
+
+    # Returns true if the argument is an instance with attributes equal to self.
+    #
+    def ==(other)
+      if other.respond_to?(:to_dose_distribution)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Calculates the dose that at least the specified
+    # percentage of the volume receives.
+    # Returns a dose (Float) in units of Gy.
+    #
+    # === Parameters
+    #
+    # * <tt>percent</tt> -- Integer/Float. The percent of the volume which receives a dose higher than the returned dose.
+    #
+    # === Examples
+    #
+    #   # Calculate the near minimum dose (e.g. up to 2 % of the volume receives a dose less than this):
+    #   near_min = ptv_distribution.d(98)
+    #   # Calculate the near maximum dose (e.g. at most 2 % of the volume receives a dose higher than this):
+    #   near_max = ptv_distribution.d(2)
+    #
+    def d(percent)
+      raise RangeError, "Argument 'percent' must be in the range [0-100]." if percent.to_f < 0 or percent.to_f > 100
+      d_index = ((@doses.length - 1) * (1 - percent.to_f * 0.01)).round
+      return @doses[d_index]
+    end
+
+    # Generates a Fixnum hash value for this instance.
+    #
+    def hash
+      state.hash
+    end
+
+    # Calculates the homogeneity index of the dose distribution.
+    # A low (near zero) value corresponds to high homogeneity (e.q. 0.1).
+    # Returns the index value as a float.
+    #
+    # === Notes
+    #
+    # * The homogeneity index is defined as:
+    #  HI = ( d(2) - d(98) ) / d(50)
+    #  For more details, refer to ICRU Report No. 83, Chapter 3.7.1.
+    #
+    # === Examples
+    #
+    #   # Calculate the homogeneity index of the dose distribution of a PTV ROI for a given plan:
+    #   homogeneity_index = ptv_distribution.hindex
+    #
+    def hindex
+      return (d(2) - d(98)) / d(50).to_f
+    end
+
+    # Returns the number of dose values in the DoseDistribution.
+    #
+    def length
+      @doses.length
+    end
+
+    alias_method :size, :length
+
+    # Calculates the maximum dose.
+    #
+    def max
+      @doses.max
+    end
+
+    # Calculates the arithmethic mean (average) dose.
+    #
+    def mean
+      @doses.mean
+    end
+
+    # Calculates the median dose.
+    #
+    def median
+      @doses.median
+    end
+
+    # Calculates the minimum dose.
+    #
+    def min
+      @doses.min
+    end
+
+    # Calculates the root mean square deviation (the population standard deviation).
+    #
+    # === Notes
+    #
+    # * Uses N in the denominator for calculating the standard deviation of the sample.
+    #
+    def rmsdev
+      @doses.rmsdev
+    end
+
+    # Calculates the sample standard deviation of the dose distribution.
+    #
+    # === Notes
+    #
+    # * Uses Bessel's correction (N-1 in the denominator).
+    #
+    def stddev
+      @doses.stddev
+    end
+
+    # Returns self.
+    #
+    def to_dose_distribution
+      self
+    end
+
+    # Calculates the percentage of the volume that receives
+    # a dose higher than or equal to the specified dose.
+    # Returns a percentage (Float).
+    #
+    # === Parameters
+    #
+    # * <tt>dose</tt> -- Integer/Float. The dose threshold value to apply to the dose distribution.
+    #
+    # === Examples
+    #
+    #   # Calculate the low dose spread (e.g. the percentage of the lung that receives a dose higher than 5 Gy):
+    #   coverage_low = lung_distribution.v(5)
+    #   # Calculate the high dose spread (e.g. the percentage of the lung that receives a dose higher than 20 Gy):
+    #   coverage_high = lung_distribution.v(20)
+    #
+    def v(dose)
+      raise RangeError, "Argument 'dose' cannot be negative." if dose.to_f < 0
+      # How many dose values are higher than the threshold?
+      num_above = (@doses.ge dose.to_f).where.length
+      # Divide by total number of elements and convert to percentage:
+      return num_above / @doses.length.to_f * 100
+    end
+
+
+    private
+
+
+    # Returns the attributes of this instance in an array (for comparison purposes).
+    #
+    def state
+       [@doses.to_a, @volume]
+    end
+
+  end
+end