rtkit 0.7

data/lib/rtkit/mixins/image_parent.rb

@@ -0,0 +1,40 @@
+module RTKIT
+
+  # This is a mixin-module for the classes that are image 'parents',
+  # i.e. they contain a reference to an array of image instances.
+  #
+  # This module is mixed in by the ImageSeries and Volume classes.
+  #
+  module ImageParent
+
+    # Returns the slice spacing (a float value in units of mm), which describes
+    # the distance between two neighbouring images in this image series.
+    # NB! If the image series contains 0 or 1 image, a slice spacing can not be
+    # determined and nil is returned.
+    #
+    def slice_spacing
+      if @slice_spacing
+        # If the slice spacing has already been computed, return it instead of recomputing:
+        return @slice_spacing
+      else
+        if @images.length > 1
+          # Collect slice positions:
+          slice_positions = NArray.to_na(@images.collect{|image| image.pos_slice})
+          spacings = (slice_positions[1..-1] - slice_positions[0..-2]).abs
+          @slice_spacing = spacings.to_a.most_common_value
+        end
+      end
+    end
+
+    # Updates the position that is registered for the image for this series.
+    #
+    def update_image_position(image, new_pos)
+      raise ArgumentError, "Invalid argument 'image'. Expected Image, got #{image.class}." unless image.is_a?(Image)
+      # Remove old position key:
+      @image_positions.delete(image.pos_slice)
+      # Add the new position:
+      @image_positions[new_pos] = image
+    end
+
+  end
+end

data/lib/rtkit/patient.rb

@@ -0,0 +1,229 @@
+module RTKIT
+
+  # Contains the DICOM data and methods related to a patient.
+  #
+  # === Relations
+  #
+  # * A Patient has many Study instances.
+  #
+  class Patient
+
+    # The Patient's birth date.
+    attr_reader :birth_date
+    # The DataSet which this Patient belongs to.
+    attr_reader :dataset
+    # An array of Frame (of Reference) instances belonging to this Patient.
+    attr_reader :frames
+    # The Patient's ID (string).
+    attr_reader :id
+    # The Patient's name.
+    attr_reader :name
+    # The Patient's sex.
+    attr_reader :sex
+    # An array of Study references.
+    attr_reader :studies
+
+    # Creates a new Patient instance by loading patient information from the specified DICOM object.
+    # The Patient's ID string value is used to uniquely identify a patient.
+    #
+    # === Parameters
+    #
+    # * <tt>dcm</tt> -- An instance of a DICOM object (DICOM::DObject).
+    # * <tt>dataset</tt> -- The DataSet instance that this Patient belongs to.
+    #
+    def self.load(dcm, dataset)
+      raise ArgumentError, "Invalid argument 'dcm'. Expected DObject, got #{dcm.class}." unless dcm.is_a?(DICOM::DObject)
+      raise ArgumentError, "Invalid argument 'dataset'. Expected DataSet, got #{dataset.class}." unless dataset.is_a?(DataSet)
+      name = dcm.value(PATIENTS_NAME)
+      id = dcm.value(PATIENTS_ID)
+      birth_date = dcm.value(BIRTH_DATE)
+      sex = dcm.value(SEX)
+      pat = self.new(name, id, dataset, :birth_date => birth_date, :sex => sex)
+      pat.add(dcm)
+      return pat
+    end
+
+    # Creates a new Patient instance. The Patient's ID string is used to uniquely identify a patient.
+    #
+    # === Parameters
+    #
+    # * <tt>name</tt> -- String. The Name of the Patient.
+    # * <tt>id</tt> -- String. The ID of the Patient.
+    # * <tt>dataset</tt> -- The DataSet instance which the Patient is associated with.
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:birth_date</tt> -- A Date String of the Patient's birth date.
+    # * <tt>:sex</tt> -- A code string indicating the Patient's sex.
+    #
+    def initialize(name, id, dataset, options={})
+      raise ArgumentError, "Invalid argument 'name'. Expected String, got #{name.class}." unless name.is_a?(String)
+      raise ArgumentError, "Invalid argument 'id'. Expected String, got #{id.class}." unless id.is_a?(String)
+      raise ArgumentError, "Invalid argument 'dataset'. Expected DataSet, got #{dataset.class}." unless dataset.is_a?(DataSet)
+      raise ArgumentError, "Invalid option ':birth_date'. Expected String, got #{options[:birth_date].class}." if options[:birth_date] && !options[:birth_date].is_a?(String)
+      raise ArgumentError, "Invalid option ':sex'. Expected String, got #{options[:sex].class}." if options[:sex] && !options[:sex].is_a?(String)
+      # Key attributes:
+      @name = name
+      @id = id
+      @dataset = dataset
+      # Default attributes:
+      @frames = Array.new
+      @studies = Array.new
+      @associated_frames = Hash.new
+      @associated_studies = Hash.new
+      # Optional attributes:
+      @birth_date = options[:birth_date]
+      @sex = options[:sex]
+      # Register ourselves with the dataset:
+      @dataset.add_patient(self)
+    end
+
+    # Returns true if the argument is an instance with attributes equal to self.
+    #
+    def ==(other)
+      if other.respond_to?(:to_patient)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Adds a DICOM object to the patient, by adding it
+    # to an existing Study, or creating a new Study.
+    #
+    def add(dcm)
+      s = study(dcm.value(STUDY_UID))
+      if s
+        s.add(dcm)
+      else
+        add_study(Study.load(dcm, self))
+      end
+    end
+
+    # Adds a Frame to this Patient.
+    #
+    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 Study to this Patient.
+    #
+    def add_study(study)
+      raise ArgumentError, "Invalid argument 'study'. Expected Study, got #{study.class}." unless study.is_a?(Study)
+      # Do not add it again if the study already belongs to this instance:
+      @studies << study unless @associated_studies[study.uid]
+      @associated_studies[study.uid] = study
+    end
+
+    # Sets the birth_date attribute.
+    #
+    def birth_date=(value)
+      @birth_date = value && value.to_s
+    end
+
+    # Creates (and returns) a Frame instance added to this Patient.
+    #
+    # === Parameters
+    #
+    # * <tt>uid</tt> -- The Frame of Reference UID string.
+    # * <tt>indicator</tt> -- The Position Reference Indicator string. Defaults to nil.
+    #
+    def create_frame(uid, indicator=nil)
+      raise ArgumentError, "Invalid argument 'uid'. Expected String, got #{uid.class}." unless uid.is_a?(String)
+      raise ArgumentError, "Invalid argument 'indicator'. Expected String or nil, got #{indicator.class}." unless [String, NilClass].include?(indicator.class)
+      frame = Frame.new(uid, self, :indicator => indicator)
+      add_frame(frame)
+      @dataset.add_frame(frame)
+      return frame
+    end
+
+    # Returns the Frame instance mathcing the specified Frame Instance UID (if an 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 Patient is returned.
+    #
+    # === Parameters
+    #
+    # * <tt>uid</tt> -- String. The value of the Frame Instance UID element.
+    #
+    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
+
+    # Sets the id attribute.
+    #
+    def id=(value)
+      @id = value && value.to_s
+    end
+
+    # Sets the name attribute.
+    #
+    def name=(value)
+      @name = value && value.to_s
+    end
+
+    # Sets the sex attribute.
+    #
+    def sex=(value)
+      @sex = value && value.to_s
+    end
+
+    # Returns the Study instance mathcing the specified Study Instance UID (if an argument is used).
+    # If a specified UID doesn't match, nil is returned.
+    # If no argument is passed, the first Study instance associated with the Patient is returned.
+    #
+    # === Parameters
+    #
+    # * <tt>uid</tt> -- String. The value of the Study Instance UID element.
+    #
+    def study(*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_studies[args.first]
+      else
+        # No argument used, therefore we return the first Study instance:
+        return @studies.first
+      end
+    end
+
+    # Returns self.
+    #
+    def to_patient
+      self
+    end
+
+    # Returns the unique identifier string, which for this class is the Patient's ID.
+    #
+    def uid
+      return @id
+    end
+
+
+    private
+
+
+    # Returns the attributes of this instance in an array (for comparison purposes).
+    #
+    def state
+       [@birth_date, @frames, @id, @name, @sex, @studies]
+    end
+
+  end
+end

data/lib/rtkit/pixel_data.rb

@@ -0,0 +1,237 @@
+module RTKIT
+
+  # A collection of methods for dealing with pixel data in both 2D images and 3D volumes.
+  #
+  # === Inheritance
+  #
+  # These methods are available to instances of the following classes:
+  # * Image
+  # * Dose
+  #
+  class PixelData
+
+    # Converts from two NArrays of image X & Y indices to physical coordinates X, Y & Z (in mm).
+    # The X, Y & Z coordinates are returned in three NArrays of equal size as the input index NArrays.
+    # The image coordinates are calculated using the direction cosines of the Image Orientation (Patient) element (0020,0037).
+    #
+    # === Notes
+    #
+    # * For details about Image orientation, refer to the DICOM standard: PS 3.3 C.7.6.2.1.1
+    #
+    def coordinates_from_indices(column_indices, row_indices)
+      raise ArgumentError, "Invalid argument 'column_indices'. Expected NArray, got #{column_indices.class}." unless column_indices.is_a?(NArray)
+      raise ArgumentError, "Invalid argument 'row_indices'. Expected NArray, got #{row_indices.class}." unless row_indices.is_a?(NArray)
+      raise ArgumentError, "Invalid arguments. Expected NArrays of equal length, got #{column_indices.length} and #{row_indices.length}." unless column_indices.length == row_indices.length
+      raise "Invalid attribute 'cosines'. Expected a 6 element Array, got #{cosines.class} #{cosines.length if cosines.is_a?(Array)}." unless cosines.is_a?(Array) && cosines.length == 6
+      raise "Invalid attribute 'pos_x'. Expected Float, got #{pos_x.class}." unless pos_x.is_a?(Float)
+      raise "Invalid attribute 'pos_y'. Expected Float, got #{pos_y.class}." unless pos_y.is_a?(Float)
+      raise "Invalid attribute 'pos_slice'. Expected Float, got #{pos_slice.class}." unless pos_slice.is_a?(Float)
+      raise "Invalid attribute 'col_spacing'. Expected Float, got #{col_spacing.class}." unless col_spacing.is_a?(Float)
+      raise "Invalid attribute 'row_spacing'. Expected Float, got #{row_spacing.class}." unless row_spacing.is_a?(Float)
+      # Convert indices integers to floats:
+      column_indices = column_indices.to_f
+      row_indices = row_indices.to_f
+      # Calculate the coordinates by multiplying indices with the direction cosines and applying the image offset:
+      x = pos_x + (column_indices * col_spacing * cosines[0]) + (row_indices * row_spacing * cosines[3])
+      y = pos_y + (column_indices * col_spacing * cosines[1]) + (row_indices * row_spacing * cosines[4])
+      z = pos_slice + (column_indices * col_spacing * cosines[2]) + (row_indices * row_spacing * cosines[5])
+      return x, y, z
+    end
+
+    # Converts from three (float) NArrays of X, Y & Z physical coordinates (in mm) to image slice indices X & Y.
+    # The X & Y indices are returned in two NArrays of equal size as the input coordinate NArrays.
+    # The image indices are calculated using the direction cosines of the Image Orientation (Patient) element (0020,0037).
+    #
+    # === Notes
+    #
+    # * For details about Image orientation, refer to the DICOM standard: PS 3.3 C.7.6.2.1.1
+    #
+    def coordinates_to_indices(x, y, z)
+      raise ArgumentError, "Invalid argument 'x'. Expected NArray, got #{x.class}." unless x.is_a?(NArray)
+      raise ArgumentError, "Invalid argument 'y'. Expected NArray, got #{y.class}." unless y.is_a?(NArray)
+      raise ArgumentError, "Invalid argument 'z'. Expected NArray, got #{z.class}." unless z.is_a?(NArray)
+      raise ArgumentError, "Invalid arguments. Expected NArrays of equal length, got #{x.length}, #{y.length} and #{z.length}." unless [x.length, y.length, z.length].uniq.length == 1
+      raise "Invalid attribute 'cosines'. Expected a 6 element Array, got #{cosines.class} #{cosines.length if cosines.is_a?(Array)}." unless cosines.is_a?(Array) && cosines.length == 6
+      raise "Invalid attribute 'pos_x'. Expected Float, got #{pos_x.class}." unless pos_x.is_a?(Float)
+      raise "Invalid attribute 'pos_y'. Expected Float, got #{pos_y.class}." unless pos_y.is_a?(Float)
+      raise "Invalid attribute 'pos_slice'. Expected Float, got #{pos_slice.class}." unless pos_slice.is_a?(Float)
+      raise "Invalid attribute 'col_spacing'. Expected Float, got #{col_spacing.class}." unless col_spacing.is_a?(Float)
+      raise "Invalid attribute 'row_spacing'. Expected Float, got #{row_spacing.class}." unless row_spacing.is_a?(Float)
+      # Calculate the indices by multiplying coordinates with the direction cosines and applying the image offset:
+      column_indices = ((x-pos_x)/col_spacing*cosines[0] + (y-pos_y)/col_spacing*cosines[1] + (z-pos_slice)/col_spacing*cosines[2]).round
+      row_indices = ((x-pos_x)/row_spacing*cosines[3] + (y-pos_y)/row_spacing*cosines[4] + (z-pos_slice)/row_spacing*cosines[5]).round
+      return column_indices, row_indices
+    end
+
+    # Fills the provided image array with lines of a specified value, based on two vectors of column and row indices.
+    # The image is expected to be a (two-dimensional) NArray.
+    # Returns the processed image array.
+    #
+    def draw_lines(column_indices, row_indices, image, value)
+      raise ArgumentError, "Invalid argument 'column_indices'. Expected Array, got #{column_indices.class}." unless column_indices.is_a?(Array)
+      raise ArgumentError, "Invalid argument 'row_indices'. Expected Array, got #{row_indices.class}." unless row_indices.is_a?(Array)
+      raise ArgumentError, "Invalid arguments. Expected Arrays of equal length, got #{column_indices.length}, #{row_indices.length}." unless column_indices.length == row_indices.length
+      raise ArgumentError, "Invalid argument 'image'. Expected NArray, got #{image.class}." unless image.is_a?(NArray)
+      raise ArgumentError, "Invalid number of dimensions for argument 'image'. Expected 2, got #{image.shape.length}." unless image.shape.length == 2
+      raise ArgumentError, "Invalid argument 'value'. Expected Integer, got #{value.class}." unless value.is_a?(Integer)
+      column_indices.each_index do |i|
+        image = draw_line(column_indices[i-1], column_indices[i], row_indices[i-1], row_indices[i], image, value)
+      end
+      return image
+    end
+
+    # Iterative, queue based flood fill algorithm.
+    # Replaces all pixels of a specific value that are contained by pixels of different value.
+    # The replacement value along with the starting coordinates are passed as parameters to this method.
+    # It seems a recursive method is not suited for Ruby due to its limited stack space (a problem in general for scripting languages).
+    #
+    def flood_fill(col, row, image, fill_value)
+      existing_value = image[col, row]
+      queue = Array.new
+      queue.push([col, row])
+      until queue.empty?
+        col, row = queue.shift
+        if image[col, row] == existing_value
+          west_col, west_row = ff_find_border(col, row, existing_value, :west, image)
+          east_col, east_row = ff_find_border(col, row, existing_value, :east, image)
+          # Fill the line between the two border pixels (i.e. not touching the border pixels):
+          image[west_col..east_col, row] = fill_value
+          q = west_col
+          while q <= east_col
+            [:north, :south].each do |direction|
+              same_col, next_row = ff_neighbour(q, row, direction)
+              begin
+                queue.push([q, next_row]) if image[q, next_row] == existing_value
+              rescue
+                # Out of bounds. Do nothing.
+              end
+            end
+            q, same_row = ff_neighbour(q, row, :east)
+          end
+        end
+      end
+      return image
+    end
+
+    # Converts general image indices to specific column and row indices based on the
+    # provided image indices and the number of columns in the image.
+    #
+    def indices_general_to_specific(indices, n_cols)
+      if indices.is_a?(Array)
+        row_indices = indices.collect{|i| i/n_cols}
+        column_indices = [indices, row_indices].transpose.collect{|i| i[0] - i[1] * n_cols}
+      else
+        # Assume Fixnum or NArray:
+        row_indices = indices/n_cols # Values are automatically rounded down.
+        column_indices = indices-row_indices*n_cols
+      end
+      return column_indices, row_indices
+    end
+
+    # Converts specific x and y indices to general image indices based on the provided specific indices and x size of the NArray image.
+    #
+    def indices_specific_to_general(column_indices, row_indices, n_cols)
+      if column_indices.is_a?(Array)
+        indices = Array.new
+        column_indices.each_index {|i| indices << column_indices[i] + row_indices[i] * n_cols}
+        return indices
+      else
+        # Assume Fixnum or NArray:
+        return column_indices + row_indices * n_cols
+      end
+    end
+
+    # A convenience method for printing image information.
+    # NB! This has been used only for debugging, and will soon be removed.
+    #
+    def print_img(narr=@narray)
+      puts "Image dimensions: #{@columns}*#{@rows}"
+      narr.shape[0].times do |i|
+        puts narr[true, i].to_a.to_s
+      end
+    end
+
+
+    private
+
+
+    # Draws a single line in the (NArray) image matrix based on a start- and an end-point.
+    # The method uses an iterative Bresenham Line Algorithm.
+    # Returns the processed image array.
+    #
+    def draw_line(x0, x1, y0, y1, image, value)
+      steep = ((y1-y0).abs) > ((x1-x0).abs)
+      if steep
+        x0,y0 = y0,x0
+        x1,y1 = y1,x1
+      end
+      if x0 > x1
+        x0,x1 = x1,x0
+        y0,y1 = y1,y0
+      end
+      deltax = x1-x0
+      deltay = (y1-y0).abs
+      error = (deltax / 2).to_i
+      y = y0
+      ystep = nil
+      if y0 < y1
+        ystep = 1
+      else
+        ystep = -1
+      end
+      for x in x0..x1
+        if steep
+          begin
+            image[y,x] = value # (switching variables)
+          rescue
+            # Our line has gone outside the image. Do nothing for now, but the proper thing to do would be to at least return some status boolean indicating that this has occured.
+          end
+        else
+          begin
+            image[x,y] = value
+          rescue
+            # Our line has gone outside the image.
+          end
+        end
+        error -= deltay
+        if error < 0
+          y += ystep
+          error += deltax
+        end
+      end
+      return image
+    end
+
+    # Searches left and right to find the 'border' in a row of pixels the image array.
+    # Returns a column and row index. Used by the flood_fill() method.
+    #
+    def ff_find_border(col, row, existing_value, direction, image)
+      next_col, next_row = ff_neighbour(col, row, direction)
+      begin
+        while image[next_col, next_row] == existing_value
+          col, row = next_col, next_row
+          next_col, next_row = ff_neighbour(col, row, direction)
+        end
+      rescue
+        # Out of bounds. Do nothing.
+      end
+      col = 0 if col < 1
+      row = 0 if row < 1
+      return col, row
+    end
+
+    # Returns the neighbour index based on the specified direction.
+    # Used by the flood_fill() method and its dependency; the ff_find_border() method.
+    # :east => to the right when looking at an array image printout on the screen
+    #
+    def ff_neighbour(col, row, direction)
+      case direction
+        when :north then return col, row-1
+        when :south then return col, row+1
+        when :east  then return col+1, row
+        when :west  then return col-1, row
+      end
+    end
+
+  end
+end