rtkit 0.7

data/lib/rtkit/image_series.rb

@@ -0,0 +1,290 @@
+module RTKIT
+
+  # The ImageSeries class contains methods that are specific for the slice based image modalites (e.g. CT, MR).
+  #
+  # === Inheritance
+  #
+  # * ImageSeries inherits all methods and attributes from the Series class.
+  #
+  class ImageSeries < Series
+
+    include ImageParent
+
+    # The Frame (of Reference) which this ImageSeries belongs to.
+    attr_accessor :frame
+    # An array of Image references.
+    attr_reader :images
+    # A hash containing SOP Instance UIDs as key and Slice Positions as value.
+    attr_reader :slices
+    # A hash containing Slice Positions as key and SOP Instance UIDS as value.
+    attr_accessor :sop_uids
+    # An array of Structure Sets associated with this Image Series.
+    attr_reader :structs
+
+    # Creates a new ImageSeries instance by loading series information from the specified DICOM object.
+    # The Series' UID string value is used to uniquely identify an ImageSeries.
+    #
+    # === Parameters
+    #
+    # * <tt>dcm</tt> -- An instance of a DICOM object (DICOM::DObject) with an image type modality (e.g. CT or MR).
+    # * <tt>study</tt> -- The Study instance that this ImageSeries belongs to.
+    #
+    def self.load(dcm, study)
+      raise ArgumentError, "Invalid argument 'dcm'. Expected DObject, got #{dcm.class}." unless dcm.is_a?(DICOM::DObject)
+      raise ArgumentError, "Invalid argument 'study'. Expected Study, got #{study.class}." unless study.is_a?(Study)
+      raise ArgumentError, "Invalid argument 'dcm'. Expected DObject with an Image Series type modality, got #{dcm.value(MODALITY)}." unless IMAGE_SERIES.include?(dcm.value(MODALITY))
+      # Required attributes:
+      modality = dcm.value(MODALITY)
+      series_uid = dcm.value(SERIES_UID)
+      # Optional attributes:
+      class_uid = dcm.value(SOP_CLASS)
+      date = dcm.value(SERIES_DATE)
+      time = dcm.value(SERIES_TIME)
+      description = dcm.value(SERIES_DESCR)
+      # Check if a Frame with the given UID already exists, and if not, create one:
+      frame = study.patient.dataset.frame(dcm.value(FRAME_OF_REF)) || frame = study.patient.create_frame(dcm.value(FRAME_OF_REF), dcm.value(POS_REF_INDICATOR))
+      # Create the ImageSeries instance:
+      is = self.new(series_uid, modality, frame, study, :class_uid => class_uid, :date => date, :time => time, :description => description)
+      is.add(dcm)
+      # Add our ImageSeries instance to its corresponding Frame:
+      frame.add_series(is)
+      return is
+    end
+
+    # Creates a new ImageSeries instance.
+    #
+    # === Parameters
+    #
+    # * <tt>series_uid</tt> -- The Series Instance UID string.
+    # * <tt>modality</tt> -- The Modality string of the ImageSeries, e.g. 'CT' or 'MR'.
+    # * <tt>frame</tt> -- The Frame instance that this ImageSeries belongs to.
+    # * <tt>study</tt> -- The Study instance that this ImageSeries 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, frame, study, options={})
+      raise ArgumentError, "Invalid argument 'series_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 'frame'. Expected Frame, got #{frame.class}." unless frame.is_a?(Frame)
+      raise ArgumentError, "Invalid argument 'study'. Expected Study, got #{study.class}." unless study.is_a?(Study)
+      raise ArgumentError, "Invalid argument 'modality'. Expected an Image Series type modality, got #{modality}." unless IMAGE_SERIES.include?(modality)
+      # Pass attributes to Series initialization:
+      super(series_uid, modality, study, options)
+      # Key attributes:
+      @frame = frame
+      # Default attributes:
+      @slices = Hash.new
+      @sop_uids = Hash.new
+      @images = Array.new
+      @structs = Array.new
+      @image_positions = Hash.new
+      # A hash with the associated StructureSet's UID as key and the instance of the StructureSet that belongs to this ImageSeries as value:
+      @associated_structs = Hash.new
+      # Register ourselves with the study & frame:
+      @study.add_series(self)
+      @frame.add_series(self)
+    end
+
+    # Returns true if the argument is an instance with attributes equal to self.
+    #
+    def ==(other)
+      if other.respond_to?(:to_image_series)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Adds a DICOM object (Image) to the ImageSeries, by creating a new Image instance linked to this ImageSeries.
+    #
+    def add(dcm)
+      Image.load(dcm, self)
+    end
+
+    # Adds an Image to this ImageSeries.
+    #
+    def add_image(image)
+      raise ArgumentError, "Invalid argument 'image'. Expected Image, got #{image.class}." unless image.is_a?(Image)
+      @images << image unless @frame.image(image.uid)
+      @slices[image.uid] = image.pos_slice
+      @sop_uids[image.pos_slice] = image.uid
+      # The link between image uid and image instance is kept in the Frame, instead of the ImageSeries:
+      @frame.add_image(image) unless @frame.image(image.uid)
+    end
+
+    # Adds a StructureSet to this ImageSeries.
+    #
+    def add_struct(struct)
+      raise ArgumentError, "Invalid argument 'struct'. Expected StructureSet, got #{struct.class}." unless struct.is_a?(StructureSet)
+      # Do not add it again if the struct already belongs to this instance:
+      @structs << struct unless @associated_structs[struct.uid]
+      @associated_structs[struct.uid] = struct
+    end
+
+=begin
+    # Returns the array position in the sorted array of slices that is closest to the provided slice.
+    # If slice value is out of bounds (it is further from boundaries than the slice interval), false is returned.
+    def corresponding_slice(slice, slices)
+      above_pos = (0...slices.length).select{|x| slices[x]>=slice}.first
+      below_pos = (0...slices.length).select{|x| slices[x]<=slice}.last
+      # With Ruby 1.9 this can supposedly be simplified to:  below_pos = slices.index{|x| x<=slice}
+      # Exact match or between two slices?
+      if above_pos == below_pos
+        # Exact match (both point to the same index).
+        slice_index = above_pos
+      else
+        # Value in between. Return the index of the value that is closest to our value.
+        if (slice-slices[above_pos]).abs < (slice-slices[below_pos]).abs
+          slice_index = above_pos
+        else
+          slice_index = below_pos
+        end
+      end
+      return slice_index
+    end
+=end
+
+    # Generates a Fixnum hash value for this instance.
+    #
+    def hash
+      state.hash
+    end
+
+    # Returns the Image instance mathcing the specified SOP Instance UID (if an argument is used).
+    # If a specified UID doesn't match, nil is returned.
+    # If no argument is passed, the first Image instance associated with the ImageSeries is returned.
+    #
+    # === Parameters
+    #
+    # * <tt>uid</tt> -- String. The value of the SOP Instance UID element of the Image.
+    #
+    def image(*args)
+      raise ArgumentError, "Expected one or none arguments, got #{args.length}." unless [0, 1].include?(args.length)
+      if args.length == 1
+        if args.first.is_a?(Float)
+          # Presumably an image position:
+          return @image_positions[args.first]
+        else
+          # Presumably a uid string:
+          return @frame.image(args.first)
+        end
+      else
+        # No argument used, therefore we return the first Image instance:
+        return @images.first
+      end
+    end
+
+    # Analyses the Image instances belonging to this ImageSeries to determine
+    # if there is an Image which matches the specified Plane.
+    # Returns the Image if a match is found, nil if not.
+    #
+    # === Parameters
+    #
+    # * <tt>plane</tt> -- The Plane instance which images will be matched against.
+    #
+    def match_image(plane)
+      raise ArgumentError, "Invalid argument 'plane'. Expected Plane, got #{plane.class}." unless plane.is_a?(Plane)
+      matching_image = nil
+      planes_in_series = Array.new
+      @images.each do |image|
+        # Get three coordinates from the image:
+        col_indices = NArray.to_na([0,image.columns/2, image.columns-1])
+        row_indices = NArray.to_na([image.rows/2, image.rows-1, 0])
+        x, y, z = image.coordinates_from_indices(col_indices, row_indices)
+        coordinates = Array.new
+        x.length.times do |i|
+          coordinates << Coordinate.new(x[i], y[i], z[i])
+        end
+        # Determine the image plane:
+        planes_in_series << Plane.calculate(coordinates[0], coordinates[1], coordinates[2])
+      end
+      # Search for a match amongst the planes of this series:
+      index = plane.match(planes_in_series)
+      matching_image = @images[index] if index
+      return matching_image
+    end
+
+    # Returns all ROIs having the same Frame of Reference as this
+    # image series from the structure set(s) belonging to this series.
+    # Returns the ROIs in an Array. If no ROIs are matched, an empty array is returned.
+    #
+    def rois
+      frame_rois = Array.new
+      structs.each do |struct|
+        frame_rois << struct.rois_in_frame(@frame.uid)
+      end
+      return frame_rois.flatten
+    end
+
+    # Sets the resolution of all images in this image series.
+    # The images will either be expanded or cropped depending on whether
+    # the specified resolution is bigger or smaller than the existing one.
+    #
+    # === Parameters
+    #
+    # * <tt>columns</tt> -- Integer. The number of columns applied to the cropped/expanded image series.
+    # * <tt>rows</tt> -- Integer. The number of rows applied to the cropped/expanded image series.
+    #
+    # === Options
+    #
+    # * <tt>:hor</tt> -- Symbol. The side (in the horisontal image direction) to apply the crop/border (:left, :right or :even (default)).
+    # * <tt>:ver</tt> -- Symbol. The side (in the vertical image direction) to apply the crop/border (:bottom, :top or :even (default)).
+    #
+    def set_resolution(columns, rows, options={})
+      @images.each do |img|
+        img.set_resolution(columns, rows, options)
+      end
+    end
+
+    # Returns the StructureSet instance mathcing the specified SOP Instance UID (if an argument is used).
+    # If a specified UID doesn't match, nil is returned.
+    # If no argument is passed, the first StructureSet instance associated with the ImageSeries is returned.
+    #
+    # === Parameters
+    #
+    # * <tt>uid</tt> -- String. The value of the SOP Instance UID element.
+    #
+    def struct(*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_structs[args.first]
+      else
+        # No argument used, therefore we return the first StructureSet instance:
+        return @structs.first
+      end
+    end
+
+    # Returns self.
+    #
+    def to_image_series
+      self
+    end
+
+    # Writes all images in this image series to DICOM files in the specified folder.
+    # The file names are set by the image's UID string, followed by a '.dcm' extension.
+    #
+    def write(path)
+      @images.each do |img|
+        img.write(path + img.uid + '.dcm')
+      end
+    end
+
+
+    private
+
+
+    # Returns the attributes of this instance in an array (for comparison purposes).
+    #
+    def state
+       [@images, @series_uid, @structs]
+    end
+
+  end
+end

data/lib/rtkit/logging.rb

@@ -0,0 +1,158 @@
+module RTKIT
+
+  # This module handles logging functionality.
+  #
+  # Logging functionality uses the Standard library's Logger class.
+  # To properly handle progname, which inside the RTKIT module is simply
+  # "RTKIT", in all cases, we use an implementation with a proxy class.
+  #
+  # === Examples
+  #
+  #   require 'rtkit'
+  #   include RTKIT
+  #
+  #   # Logging to STDOUT with DEBUG level:
+  #   RTKIT.logger = Logger.new(STDOUT)
+  #   RTKIT.logger.level = Logger::DEBUG
+  #
+  #   # Logging to a file:
+  #   RTKIT.logger = Logger.new('my_logfile.log')
+  #
+  #   # Combine an external logger with RTKIT:
+  #   logger = Logger.new(STDOUT)
+  #   logger.progname = "MY_APP"
+  #   RTKIT.logger = logger
+  #   # Now you can call the logger in the following ways:
+  #   RTKIT.logger.info "Message"               # => "RTKIT: Message"
+  #   RTKIT.logger.info("MY_MODULE) {"Message"} # => "MY_MODULE: Message"
+  #   logger.info "Message"                     # => "MY_APP: Message"
+  #
+  #   For more information, please read the Standard library Logger documentation.
+  #
+  module Logging
+
+    require 'logger'
+
+    # Inclusion hook to make the ClassMethods available to whatever
+    # includes the Logging module, i.e. the RTKIT module.
+    #
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+
+      # We use our own ProxyLogger to achieve the features wanted for RTKIT logging,
+      # e.g. using RTKIT as progname for messages logged within the RTKIT module
+      # (for both the Standard logger as well as the Rails logger), while still allowing
+      # a custom progname to be used when the logger is called outside the RTKIT module.
+      #
+      class ProxyLogger
+
+        # Creating the ProxyLogger instance.
+        #
+        # === Parameters
+        #
+        # * <tt>target</tt> -- A Logger instance (e.g. Standard Logger or ActiveSupport::BufferedLogger).
+        #
+        def initialize(target)
+          @target = target
+        end
+
+        # Catches missing methods.
+        # In our case, the methods of interest are the typical logger methods,
+        # i.e. log, info, fatal, error, debug, where the arguments/block are
+        # redirected to the logger in a specific way so that our stated logger
+        # features are achieved (this behaviour depends on the logger
+        # (Rails vs Standard) and in the case of Standard logger,
+        # whether or not a block is given).
+        #
+        # === Examples
+        #
+        #   # Inside the RTKIT module or an external class with 'include RTKIT::Logging':
+        #   logger.info "message"
+        #
+        #   # Calling from outside the RTKIT module:
+        #   RTKIT.logger.info "message"
+        #
+        def method_missing(method_name, *args, &block)
+          if method_name.to_s =~ /(log|debug|info|warn|error|fatal)/
+            # Rails uses it's own buffered logger which does not
+            # work with progname + block as the standard logger does:
+            if defined?(Rails)
+              @target.send(method_name, "RTKIT: #{args.first}")
+            elsif block_given?
+              @target.send(method_name, *args) { yield }
+            else
+              @target.send(method_name, "RTKIT") { args.first }
+            end
+          else
+            @target.send(method_name, *args, &block)
+          end
+        end
+
+      end
+
+      # The logger class variable (must be initialized
+      # before it is referenced by the object setter).
+      #
+      @@logger = nil
+
+      # The logger object setter.
+      # This method is used to replace the default logger instance with
+      # a custom logger of your own.
+      #
+      # === Parameters
+      #
+      # * <tt>l</tt> -- A Logger instance (e.g. a custom standard Logger).
+      #
+      # === Examples
+      #
+      #   # Create a logger which ages logfile once it reaches a certain size,
+      #   # leaves 10 "old log files" with each file being about 1,024,000 bytes:
+      #   RTKIT.logger = Logger.new('foo.log', 10, 1024000)
+      #
+      def logger=(l)
+        @@logger = ProxyLogger.new(l)
+      end
+
+      # The logger object getter.
+      # Returns the logger class variable, if defined.
+      # If not defined, sets up the Rails logger (if in a Rails environment),
+      # or a Standard logger if not.
+      #
+      # === Examples
+      #
+      #   # Inside the RTKIT module (or a class with 'include RTKIT::Logging'):
+      #   logger # => Logger instance
+      #
+      #   # Accessing from outside the RTKIT module:
+      #   RTKIT.logger # => Logger instance
+      #
+      def logger
+        @@logger ||= lambda {
+          if defined?(Rails)
+            ProxyLogger.new(Rails.logger)
+          else
+            l = Logger.new(STDOUT)
+            l.level = Logger::INFO
+            ProxyLogger.new(l)
+          end
+        }.call
+      end
+
+    end
+
+    # A logger object getter.
+    # Forwards the call to the logger class method of the Logging module.
+    #
+    def logger
+      self.class.logger
+    end
+
+  end
+
+  # Include the Logging module so we can use RTKIT.logger.
+  include Logging
+
+end

data/lib/rtkit/methods.rb

@@ -0,0 +1,105 @@
+module RTKIT
+
+  class << self
+
+    #--
+    # Module methods:
+    #++
+
+    # Finds all files contained in the specified folder or folders (including any sub-folders).
+    # Returns an array containing the discovered file strings.
+    #
+    # === Parameters
+    #
+    # * <tt>path_or_paths</tt> -- String or Array of strings. The path(s) in which to find all files.
+    #
+    def files(path_or_paths)
+      raise ArgumentError, "Invalid argument 'path_or_paths'. Expected String or Array, got #{paths.class}." unless [String, Array].include?(path_or_paths.class)
+      raise ArgumentError, "Invalid argument 'path_or_paths'. Expected Array to contain only strings, got #{path_or_paths.collect{|p| p.class}.uniq}." if path_or_paths.is_a?(Array) && path_or_paths.collect{|p| p.class}.uniq != [String]
+      paths = path_or_paths.is_a?(Array) ? path_or_paths : [path_or_paths]
+      files = Array.new
+      # Iterate the folders (and their subfolders) to extract all files:
+      for dir in paths
+        Find.find(dir) do |path|
+          if FileTest.directory?(path)
+            next
+          else
+            # Store the file in our array:
+            files << path
+          end
+        end
+      end
+      return files
+    end
+
+    # Generates and returns a random Frame Instance UID string.
+    #
+    def frame_uid
+      return self.generate_uids('9').first
+    end
+
+    # Generates one or several random UID strings.
+    # The UIDs are based on the RTKIT dicom_root attribute, a type prefix, a datetime part,
+    # a random number part, and an index part (when multiple UIDs are requested,
+    # e.g. for a SOP Instances in a Series).
+    # Returns the UIDs in a string array.
+    #
+    # === Parameters
+    #
+    # * <tt>prefix</tt> -- String. A (numerical) type string which sits between the dicom root and the random part of the UID.
+    # * <tt>instances</tt> -- Integer. The number of UIDs to generate. Defaults to 1.
+    #
+    def generate_uids(prefix, instances=1)
+      raise ArgumentError, "Invalid argument 'prefix'. Expected (integer) String, got #{prefix.class}." unless prefix.is_a?(String)
+      raise ArgumentError, "Invalid argument 'instances'. Expected Integer (when defined), got #{instances.class}." if instances && !instances.is_a?(Integer)
+      raise ArgumentError, "Invalid argument 'prefix'. Expected non-zero Integer (String), got #{prefix}." if prefix.to_i == 0
+      raise ArgumentError, "Invalid argument 'instances'. Expected positive Integer (when defined), got #{instances}." if instances && instances < 0
+      prefix = prefix.to_i
+      # NB! For UIDs, leading zeroes after a dot is not allowed, and must be removed:
+      date = Time.now.strftime("%Y%m%d").to_i.to_s
+      time = Time.now.strftime("%H%M%S").to_i.to_s
+      random = rand(99999) + 1 # (Minimum 1, max. 99999)
+      base_uid = [RTKIT.dicom_root, prefix, date, time, random].join('.')
+      uids = Array.new
+      if instances == 1
+        uids << base_uid
+      else
+        (1..instances).to_a.each do |i|
+          uids << "#{base_uid}.#{i}"
+        end
+      end
+      return uids
+    end
+
+    # Generates and returns a random Series Instance UID string.
+    #
+    def series_uid
+      return self.generate_uids('2').first
+    end
+
+    # Generates and returns a random SOP Instance UID string.
+    #
+    def sop_uid
+      return self.generate_uids('3').first
+    end
+
+    # Generates and returns a collection of random SOP Instance UID strings.
+    #
+    # === Parameters
+    #
+    # * <tt>instances</tt> -- Integer. The number of UIDs to generate.
+    #
+    def sop_uids(instances)
+      raise ArgumentError, "Invalid argument 'instances'. Expected Integer, got #{instances.class}." unless instances.is_a?(Integer)
+      return self.generate_uids('3', instances)
+    end
+
+    # Generates and returns a random Study Instance UID string.
+    #
+    def study_uid
+      return self.generate_uids('1').first
+    end
+
+  end
+
+end