rtkit 0.7

data/lib/rtkit/bin_matcher.rb

@@ -0,0 +1,241 @@
+module RTKIT
+
+  # Contains the DICOM data and methods related to the comparison of binary volumes (i.e. segmented volumes).
+  #
+  class BinMatcher
+
+    # The reference (master) BinVolume.
+    attr_reader :master
+    # An array of BinVolumes.
+    attr_reader :volumes
+
+    # Creates a new BinMatcher instance.
+    #
+    # === Parameters
+    #
+    # * <tt>volumes</tt> -- An array of BinVolume instances to be matched.
+    # * <tt>master</tt> -- A master BinVolume which the other volumes will be compared against.
+    #
+    def initialize(volumes=nil, master=nil)
+      raise ArgumentError, "Invalid argument 'volumes'. Expected Array, got #{volumes.class}." if volumes && volumes.class != Array
+      raise ArgumentError, "Invalid argument 'master'. Expected BinVolume, got #{master.class}." if master && master.class != BinVolume
+      raise ArgumentError, "Invalid argument 'volumes'. Expected array to contain only BinVolume instances, got #{volumes.collect{|i| i.class}.uniq}." if volumes && volumes.collect{|i| i.class}.uniq != [BinVolume]
+      @volumes = volumes || Array.new
+      @master = master
+    end
+
+    # Returns true if the argument is an instance with attributes equal to self.
+    #
+    def ==(other)
+      if other.respond_to?(:to_bin_matcher)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Adds a BinVolume instance to the matcher.
+    #
+    def add(volume)
+      raise ArgumentError, "Invalid argument 'volume'. Expected BinVolume, got #{volume.class}." unless volume.is_a?(BinVolume)
+      @volumes << volume
+    end
+
+    # Returns an array of volumes, (reversly) sorted by their sensitivity score.
+    # The volumes are sorted in such a way that the best scoring volume (highest sensitivity) appears first.
+    # If no volumes are defined, an empty array is returned.
+    #
+    def by_sensitivity
+      return (@volumes.sort_by {|v| v.sensitivity}).reverse
+    end
+
+    # Returns an array of volumes, (reversly) sorted by their specificity score.
+    # The volumes are sorted in such a way that the best scoring volume (highest specificity) appears first.
+    # If no volumes are defined, an empty array is returned.
+    #
+    def by_specificity
+      return (@volumes.sort_by {|v| v.specificity}).reverse
+    end
+
+    # Ensures that a valid comparison can be done by making sure that every volume
+    # has a BinImage for any image that is referenced among the BinVolumes.
+    # If one or more BinVolumes are missing one or more BinImages,
+    # empty BinImages will be created for these BinVolumes.
+    #
+    # === Notes
+    #
+    # * The master volume (if present) is also processed in this method.
+    #
+    def fill_blanks
+      if @volumes.length > 0
+        # Register all unique images referenced by the various volumes:
+        images = Set.new
+        # Include the master volume (if it is present):
+        [@volumes, @master].flatten.compact.each do |volume|
+          volume.bin_images.each do |bin_image|
+            images << bin_image.image unless images.include?(bin_image.image)
+          end
+        end
+        # Check if any of the volumes have images missing, and if so, create empty images:
+        images.each do |image|
+          [@volumes, @master].flatten.compact.each do |volume|
+            match = false
+            volume.bin_images.each do |bin_image|
+              match = true if bin_image.image == image
+            end
+            unless match
+              # Create BinImage:
+              bin_img = BinImage.new(NArray.byte(image.columns, image.rows), image)
+              volume.add(bin_img)
+            end
+          end
+        end
+      end
+    end
+
+    # Generates a Fixnum hash value for this instance.
+    #
+    def hash
+      state.hash
+    end
+
+    # Sets the master (reference) BinVolume.
+    #
+    def master=(volume)
+      raise ArgumentError, "Invalid argument 'volume'. Expected BinVolume, got #{volume.class}." unless volume.is_a?(BinVolume)
+      @master = volume
+    end
+
+    # Returns an array of NArrays from the BinVolumes of this instance.
+    # Returns an empty array if no volumes are defined.
+    #
+    # === Notes
+    #
+    # * Only the volumes are returned. The master volume (if present) is not returned with this method.
+    #
+    def narrays(sort_slices=true)
+      n = Array.new
+      @volumes.each do |volume|
+        n << volume.narray(sort_slices)
+      end
+      return n
+    end
+
+=begin
+    # Along each dimension of the input binary volume(s), removes any index (i.e. slice, column or row)
+    # which is empty in all volumes (including the master volume, if specified). This method results
+    # in reduced volumes, corresponding to a clipbox which tightly encloses the defined (positive) volume
+    # (indices with pixel value 1 in at least one of the volumes). Such a reduced volume may yield e.g.
+    # specificity scores with better contrast.
+    #
+    def remove_empty_indices
+      # It only makes sense to run this volume reduction if the number of dimensions are 2 or more:
+      volumes = [*@volumes, master].compact
+      # For each volume the indices typically correspond to the following
+      # descriptions: slice, column & row
+      volumes.first.narray.shape.each_with_index do |size, dim_index|
+        extract = Array.new(volumes.first.narray.dim, true)
+        positive_indices = Array.new
+        size.times do |i|
+          extract[dim_index] = i
+          positive = false
+          volumes.each do |volume|
+            positive = true if volume.narray[*extract].max > 0
+          end
+          positive_indices << i if positive
+        end
+        extract[dim_index] = positive_indices
+        if positive_indices.length < size
+          volumes.each do |volume|
+            volume.narr = volume.narr[*extract]
+          end
+        end
+      end
+      volumes.each {|vol| puts vol.narr.inspect}
+      volumes.each {|vol| puts vol.narr.shape}
+      @volumes.each {|vol| puts vol.narr.shape}
+    end
+=end
+
+    # Scores the volumes of the BinMatcher instance against the reference (master) volume,
+    # by using Dice's coeffecient.
+    #
+    # For more information, see:
+    # http://en.wikipedia.org/wiki/Dice%27s_coefficient
+    #
+    def score_dice
+      if @master
+        # Find the voxel-indices for the master where the decisions are 1 and 0:
+        pos_indices_master = (@master.narray.eq 1).where
+        @volumes.each do |bin_vol|
+          pos_indices_vol = (bin_vol.narray.eq 1).where
+          num_common = (@master.narray[pos_indices_vol].eq 1).where.length
+          bin_vol.dice = 2 * num_common / (pos_indices_master.length + pos_indices_vol.length).to_f
+        end
+      end
+    end
+
+    # Scores the volumes of the BinMatcher instance against the reference (master) volume,
+    # by using Sensitivity and Specificity.
+    #
+    # For more information, see:
+    # http://en.wikipedia.org/wiki/Sensitivity_and_specificity
+    #
+    def score_ss
+      if @master
+        # Find the voxel-indices for the master where the decisions are 1 and 0:
+        pos_indices, neg_indices = (@master.narray.eq 1).where2
+        @volumes.each do |bin_vol|
+          narr = bin_vol.narray
+          bin_vol.sensitivity = (narr[pos_indices].eq 1).where.length / pos_indices.length.to_f
+          bin_vol.specificity = (narr[neg_indices].eq 0).where.length / neg_indices.length.to_f
+        end
+      end
+    end
+
+    # Rearranges the BinImages belonging to the BinVolumes of this instance,
+    # by matching the BinImages by their Image instance references,
+    # to ensure that the NArrays extracted from these volumes are truly comparable.
+    #
+    # === Notes
+    #
+    # * The master volume (if present) is not processed in this method.
+    # * Raises an exception if any irregularities in number of BinImages or Image references occurs.
+    #
+    def sort_volumes
+      # It only makes sense to sort if we have at least two volumes:
+      if @volumes.length > 1
+        raise "All volumes of the BinMatcher isntance must have the same number of BinImages (got lengths #{@volumes.collect {|v| v.bin_images.length}})." if @volumes.collect {|v| v.bin_images.length}.uniq.length > 1
+        # Collect the Image references of the BinImage's of the first volume:
+        desired_image_order = Array.new
+        @volumes.first.bin_images.collect {|bin_image| desired_image_order << bin_image.image}
+        raise "One (or more) Image references were nil in the first BinVolume instance of the BinMatcher. Unable to sort BinImages when they lack Image reference." if desired_image_order.compact.length != desired_image_order.length
+        # Sort the BinImages of the remaining volumes so that their order of images are equal to that of the first volume:
+        (1...@volumes.length).each do |i|
+          current_image_order = Array.new
+          @volumes[i].bin_images.collect {|bin_image| current_image_order << bin_image.image}
+          sort_order = current_image_order.compare_with(desired_image_order)
+          @volumes[i].bin_images.sort_by_order!(sort_order)
+          #@volumes[i].reorder_images(sort_order)
+        end
+      end
+    end
+
+    # Returns self.
+    #
+    def to_bin_matcher
+      self
+    end
+
+
+    private
+
+
+    # Returns the attributes of this instance in an array (for comparison purposes).
+    #
+    def state
+       [@volumes, @master]
+    end
+
+  end
+end

data/lib/rtkit/bin_volume.rb

@@ -0,0 +1,263 @@
+module RTKIT
+
+  # Contains the DICOM data and methods related to a binary volume.
+  #
+  # === Inheritance
+  #
+  # * As the BinVolume class inherits from the PixelData class, all PixelData methods are available to instances of BinVolume.
+  #
+  class BinVolume < PixelData
+
+    # An array of BinImage references.
+    attr_reader :bin_images
+    # Dice's Coeffecient.
+    attr_accessor :dice
+    # A NArray associated with this BinVolume (NB! This is a cached copy. If you want to ensure to
+    # extract an narray which corresponds to the BinVolume's Images, use the narray method instead.
+    attr_accessor :narr
+    # A score (fraction) of the segmented volume compared to a master volume, ranging from 0 (worst) to 1 (all true voxels segmented in this volume).
+    attr_accessor :sensitivity
+    # The BinVolume's series reference (e.g. ImageSeries or DoseVolume).
+    attr_reader :series
+    # A reference to the source of this BinaryVolume (ROI or Dose instance).
+    attr_reader :source
+    # A score (fraction) of the segmented volume compared to a master volume, ranging from 0 (worst) to 1 (none of the true remaining voxels are segmented in this volume).
+    attr_accessor :specificity
+
+    # Creates a new BinVolume instance from a DoseVolume.
+    # The BinVolume is typically defined from a ROI delineation against an image series,
+    # but it may also be applied to an rtdose 'image' series.
+    # Returns the BinVolume instance.
+    #
+    # === Notes
+    #
+    # * Even though listed as optional parameters, at least one of the min and max
+    #   options must be specified in order to construct a valid binary volume.
+    #
+    # === Parameters
+    #
+    # * <tt>image_volume</tt> -- The image volume which the binary volume will be based on (a DoseVolume or an ImageSeries).
+    # * <tt>min</tt> -- Float. An optional lower dose limit from which to define the the binary volume.
+    # * <tt>max</tt> -- Float. An optional upper dose limit from which to define the the binary volume.
+    #
+    def self.from_dose(dose_volume, min=nil, max=nil, image_volume)
+      raise ArgumentError, "Invalid argument 'dose_volume'. Expected DoseVolume, got #{dose_volume.class}." unless dose_volume.class == DoseVolume
+      raise ArgumentError, "Invalid argument 'image_volume'. Expected ImageSeries or DoseVolume, got #{image_volume.class}." unless [ImageSeries, DoseVolume].include?(image_volume.class)
+      raise ArgumentError "Need at least one dose limit parameter. Neither min nor max was specified." unless min or max
+      # Create the BinVolume instance:
+      bv = self.new(dose_volume) # FIXME: Specify dose limit somehow here?!
+      # Add BinImages for each of the DoseVolume's images:
+      dose_narr = dose_volume.dose_arr
+      dose_volume.images.each_index do |i|
+        #ref_image = image_volume.image(dose_img.pos_slice)
+        ref_image = image_volume.images[i]
+        dose_image = dose_narr[i, true, true]
+        # Create the bin narray:
+        narr = NArray.byte(ref_image.columns, ref_image.rows)
+        if !min
+          # Only the max limit is specified:
+          marked_indices = (dose_image.le max.to_f)
+        elsif !max
+          # Only the min limit is specified:
+          marked_indices = (dose_image.ge min.to_f)
+        else
+          # Both min and max limits are specified:
+          smaller = (dose_image.le max.to_f)
+          bigger = (dose_image.ge min.to_f)
+          marked_indices = smaller.and bigger
+        end
+        narr[marked_indices] = 1
+        bin_img = BinImage.new(narr, ref_image)
+        bv.add(bin_img)
+      end
+      return bv
+    end
+
+    # Creates a new BinVolume instance from a ROI.
+    # The BinVolume is typically defined from a ROI delineation against an image series,
+    # but it may also be applied to an rtdose 'image' series.
+    # Returns the BinVolume instance.
+    #
+    # === Parameters
+    #
+    # * <tt>roi</tt> -- A ROI from which to define the binary volume.
+    # * <tt>image_volume</tt> -- The image volume which the binary volume will be based on (an ImageSeries or a DoseVolume).
+    #
+    def self.from_roi(roi, image_volume)
+      raise ArgumentError, "Invalid argument 'roi'. Expected ROI, got #{roi.class}." unless roi.is_a?(ROI)
+      raise ArgumentError, "Invalid argument 'image_volume'. Expected ImageSeries or DoseVolume, got #{image_volume.class}." unless [ImageSeries, DoseVolume].include?(image_volume.class)
+      # Create the BinVolume instance:
+      bv = self.new(roi.image_series, :source => roi)
+      # Add BinImages for each of the ROIs slices:
+      roi.slices.each do |slice|
+        image = image_volume.image(slice.pos)
+        BinImage.from_contours(slice.contours, image, bv)
+        #bv.add(slice.bin_image)
+      end
+      return bv
+    end
+
+    # Creates a new BinVolume instance from an image series (i.e. ImageSeries or DoseVolume).
+    # A BinVolume created this way specified the entire volume: i.e. the Binvolume
+    # has the same dimensions as the image series, and all pixels are 1.
+    # Returns the BinVolume instance.
+    #
+    # === Parameters
+    #
+    # * <tt>image_volume</tt> -- The image volume which the binary volume will be based on (an ImageSeries or a DoseVolume).
+    #
+    def self.from_volume(image_volume)
+      raise ArgumentError, "Invalid argument 'image_volume'. Expected ImageSeries or DoseVolume, got #{image_volume.class}." unless [ImageSeries, DoseVolume].include?(image_volume.class)
+      # Create the BinVolume instance:
+      bv = self.new(image_volume)
+      # Add BinImages for each of the ROIs slices:
+      image_volume.images.each do |image|
+        # Make an NArray of proper size filled with ones:
+        narr = NArray.byte(image.columns, image.rows).fill(1)
+        # Create the BinImage instance and add it to the BinVolume:
+        bin_img = BinImage.new(narr, image)
+        bv.add(bin_img)
+      end
+      return bv
+    end
+
+    # Creates a new BinVolume instance.
+    #
+    # === Parameters
+    #
+    # * <tt>series</tt> -- The image series (e.g. ImageSeries or DoseVolume) which forms the reference data of the BinVolume.
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:images</tt> -- An array of BinImage instances that is assigned to this BinVolume.
+    # * <tt>:source</tt> -- The object which is the source of the binary (segmented) data (i.e. ROI or Dose/Hounsfield threshold).
+    #
+    def initialize(series, options={})
+      raise ArgumentError, "Invalid argument 'series'. Expected ImageSeries or DoseVolume, got #{series.class}." unless [ImageSeries, DoseVolume].include?(series.class)
+      raise ArgumentError, "Invalid option 'images'. Expected Array, got #{options[:images].class}." if options[:images] && options[:images].class != Array
+      raise ArgumentError, "Invalid option 'source'. Expected ROI or RTDose, got #{options[:source].class}." if options[:source] && ![ROI, RTDose].include?(options[:source].class)
+      raise ArgumentError, "Invalid option 'images'. Expected only BinImage instances in the array, got #{options[:images].collect{|i| i.class}.uniq}." if options[:images] && options[:images].collect{|i| i.class}.uniq.length > 1
+      @series = series
+      @bin_images = options[:images] || Array.new
+      @source = options[:source]
+    end
+
+    # Returns true if the argument is an instance with attributes equal to self.
+    #
+    def ==(other)
+      if other.respond_to?(:to_bin_volume)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Adds a BinImage instance to the volume.
+    #
+    def add(bin_image)
+      raise ArgumentError, "Invalid argument 'bin_image'. Expected BinImage, got #{bin_image.class}." unless bin_image.is_a?(BinImage)
+      @bin_images << bin_image
+    end
+
+    # Returns the number of columns in the images of the volume.
+    #
+    def columns
+      return @bin_images.first.columns if @bin_images.first
+    end
+
+    # Returns the number of frames (slices) in the set of images that makes up this volume.
+    #
+    def frames
+      return @bin_images.length
+    end
+
+    # Generates a Fixnum hash value for this instance.
+    #
+    def hash
+      state.hash
+    end
+
+    # Returns 3d volume array consisting of the 2d Narray images from the BinImage instances that makes up this volume.
+    # Returns nil if no BinImage instances are connected to this BinVolume.
+    #
+    def narray(sort_slices=true)
+      if @bin_images.length > 0
+        # Determine the slice position of each BinImage:
+        locations = Array.new
+        if sort_slices
+          @bin_images.collect {|image| locations << image.pos_slice}
+          images = @bin_images.sort_by_order(locations.sort_order)
+        else
+          images = @bin_images
+        end
+        # Create volume array and fill in the images:
+        volume = NArray.byte(frames, columns, rows)
+        images.each_with_index do |sorted_image, i|
+          volume[i, true, true] = sorted_image.narray
+        end
+        @narr = volume
+      end
+    end
+
+    def reorder_images(order)
+      @bin_images = @bin_images.sort_by_order(order)
+    end
+
+    # Returns the number of rows in the images of the volume.
+    #
+    def rows
+      return @bin_images.first.rows if @bin_images.first
+    end
+
+    # Returns self.
+    #
+    def to_bin_volume
+      self
+    end
+
+    # Creates a ROI instance from the segmentation of this BinVolume.
+    # Returns the ROI instance.
+    #
+    # === Parameters
+    #
+    # * <tt>struct</tt> -- A StructureSet instance which the ROI will be connected to.
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:algorithm</tt> -- String. The ROI Generation Algorithm. Defaults to 'Automatic'.
+    # * <tt>:name</tt> -- String. The ROI Name. Defaults to 'BinVolume'.
+    # * <tt>:number</tt> -- Integer. The ROI Number. Defaults to the first available ROI Number in the StructureSet.
+    # * <tt>:interpreter</tt> -- String. The ROI Interpreter. Defaults to 'RTKIT'.
+    # * <tt>:type</tt> -- String. The ROI Interpreted Type. Defaults to 'CONTROL'.
+    #
+    def to_roi(struct, options={})
+      raise ArgumentError, "Invalid argument 'struct'. Expected StructureSet, got #{struct.class}." unless struct.is_a?(StructureSet)
+      # Set values:
+      algorithm = options[:algorithm]
+      name = options[:name] || 'BinVolume'
+      number = options[:number]
+      interpreter = options[:interpreter]
+      type = options[:type]
+      # Create the ROI:
+      roi = struct.create_roi(@series.frame, :algorithm => algorithm, :name => name, :number => number, :interpreter => interpreter, :type => type)
+      # Create Slices:
+      @bin_images.each do |bin_image|
+        bin_image.to_slice(roi)
+      end
+      return roi
+    end
+
+
+    private
+
+
+    # Returns the attributes of this instance in an array (for comparison purposes).
+    #
+    def state
+       [@bin_images, @dice, @narr, @sensitivity, @specificity]
+    end
+
+  end
+end