framework_gem 0.1.0

data/lib/lib/roi/color/color_roi.rb

@@ -0,0 +1,138 @@
+require './lib/roi/roi'
+require './lib/mixins/can_have_special_methods'
+
+# The ColorRoi class defines a color Roi and its methods
+
+class ColorRoi < Roi
+  include CanHaveSpecialMethods
+
+  attr_accessor(:red, :green, :blue, :similarity)
+
+  # Public: Initializes a color Roi.
+  #
+  # dut        - Platform (or subclass) instance to which this Roi belongs.
+  # x          - Integer x coordinate (default: nil).
+  # y          - Integer y coordinate (default: nil).
+  # width      - Integer width (default: nil).
+  # height     - Integer height (default: nil).
+  # rectangle  - Hash defining rectangle with keys :x, :y, :width, :height (default: nil).
+  # element    - Hash same as rectangle (default: nil).
+  # red        - Integer red value 0 - 255 (default: nil). Required unless rgb is given.
+  # green      - Integer green value 0 - 255 (default: nil). Required unless rgb is given.
+  # blue       - Integer blue value 0 - 255 (default: nil). Required unless rgb is given.
+  # rgb        - Integer Array of 3 values (0 - 255) for red, green, blue (default: nil).
+  #              Required unless red, green, blue are given.
+  # similarity - Integer color similarity threshold 0 - 100 (default: 85).
+  # ref_img    - String path to reference image (default: nil).
+  #
+  # Returns nothing.
+  def initialize(dut, args={})
+    super(dut, args)
+    if args[:rgb].nil?
+      self.rgb=([args.fetch(:red), args.fetch(:green), args.fetch(:blue)])
+    else
+      self.rgb=(args[:rgb])
+    end
+    @similarity = args.fetch(:similarity, 85)
+  end
+
+  # Public: Gets RGB value.
+  #
+  # Returns Integer Array of 3 values (0 - 255) for red, green, blue.
+  def rgb
+    [@red, @green, @blue]
+  end
+
+  # Public: Sets RGB value.
+  #
+  # rgb - Integer Array of 3 values (0 - 255) for red, green, blue.
+  #
+  # Returns nothing.
+  def rgb=(rgb)
+    @red = rgb[0]
+    @green = rgb[1]
+    @blue = rgb[2]
+  end
+
+  # Public: Gets color Roi info.
+  #
+  # Returns a tidy String with color Roi info.
+  def info
+    "#{super} RGB=#{@red}:#{@green}:#{@blue} Similarity=#{@similarity}"
+  end
+
+  # Public: Checks if color is displayed as defined in the given ROI.
+  #         Corresponds to: api_is_color_displayed?
+  #
+  # key          - String name of key to press to trigger evaluation (default: nil).
+  #                If default, no keys will be pressed.
+  # delay        - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # timeout      - Integer total milliseconds to allow before timing out (default: 0).
+  # verifies_for - Integer total milliseconds for which the ROI must verify in order to succeed (default: 0).
+  #                If default, the ROI must only verify once.
+  # priority     - Symbol representing evaluation priority used to throttle CPU usage (default: :normal):
+  #                :critical   - Sleep 10 milliseconds between intensive tasks (should be used sparingly).
+  #                :high       - Sleep 100 milliseconds between intensive tasks.
+  #                :normal     - Sleep 1 second between intensive tasks (default).
+  #                :low        - Sleep 10 seconds between intensive tasks.
+  #                :background - Sleep 1 minute between intensive tasks (should be used sparingly).
+  # log_every    - Integer interval in milliseconds between logs (default: 1000).
+  #
+  # Returns a Boolean true if color is displayed before the timeout, otherwise false.
+  def displayed?(args={})
+    logger.info('Checking if color is displayed')
+    raise "Bad RGB: #{rgb}" unless rgb.all?
+    frame = args[:frame]
+    values = []
+    verify(args, values) do |sims|
+      if frame.nil?
+        json = get_json_for_compare
+        sim = test_case.send(:tmc_post, "/api/roi/color/actions/#{dut.id}", json: json)['value']
+      else
+        json = get_json_for_compare(frame: frame)
+        sim = test_case.send(:tmc_post, '/api/roi/color/actions', json: json)['value']
+      end
+      sim *= 100
+      sims << sim
+      result = sim >= @similarity
+      msg = "Color is#{result ? '' : ' not'} displayed #{frame.nil? ? 'on screen' : 'in frame'} " +
+          "(similarity: #{sim.round}%)"
+      logger.roi(self, args.merge(message: msg, use_last_image: frame.nil?, screenshot: frame.nil?))
+      result
+    end
+  end
+  special_method(:displayed?)
+
+  # Public: Gets the color of the region defined in the Roi.
+  #         Corresponds to: api_read_color_from_screen
+  #
+  # Returns the color as a Hash with keys :red, :green, :blue, each being an Integer value (0 - 255).
+  def retrieve(args={})
+    logger.info('Retrieving color')
+    frame = args[:frame]
+    value(args) do
+      if frame.nil?
+        # Get the color from the screen
+        json = get_json_for_get
+        color = test_case.send(:tmc_post, "/api/roi/color/actions/#{dut.slot}", json: json)['value']
+      else
+        # Get the color from the frame
+        json = get_json_for_get(frame: frame)
+        color = test_case.send(:tmc_post, '/api/roi/color/actions', json: json)['value']
+      end
+      color = {red: color['red'], green: color['green'], blue: color['blue']}
+      logger.roi(self, args.merge(message: "Retrieved color #{color.inspect}", use_last_image: frame.nil?,
+                                  screenshot: frame.nil?))
+      color
+    end
+  end
+  special_method(:retrieve)
+
+  private
+
+  # Internal: Returns the ROI as a hash.
+  def to_json(ref_img: nil)
+    super(ref_img: ref_img).merge(threshold: @similarity, red: @red, green: @green, blue: @blue)
+  end
+
+end

data/lib/lib/roi/image/image_roi.rb

@@ -0,0 +1,187 @@
+require './lib/roi/roi'
+require './lib/mixins/can_have_special_methods'
+
+# The ImageRoi class defines an image Roi and its methods
+
+class ImageRoi < Roi
+  include CanHaveSpecialMethods
+
+  attr_accessor(:img_x, :img_y, :img_width, :img_height, :similarity)
+
+  # Public: Initializes an image Roi.
+  #
+  # dut        - Platform (or subclass) instance to which this Roi belongs.
+  # x          - Integer x coordinate (default: nil).
+  # y          - Integer y coordinate (default: nil).
+  # width      - Integer width (default: nil).
+  # height     - Integer height (default: nil).
+  # rectangle  - Hash defining rectangle with keys :x, :y, :width, :height (default: nil).
+  # element    - Hash same as rectangle (default: nil).
+  # img_x      - Integer secondary Roi x coordinate (default: nil). Required.
+  # img_y      - Integer secondary Roi y coordinate (default: nil). Required.
+  # img_width  - Integer secondary Roi width (default: nil). Required.
+  # img_height - Integer secondary Roi height (default: nil). Required.
+  # ref_img    - String path to reference image (default: nil). Required.
+  # similarity - Integer image similarity threshold 0 - 100 (default: 80).
+  #
+  # Returns nothing.
+  def initialize(dut, args={})
+    args.fetch(:ref_img)  # required
+    super(dut, args)
+    @img_x = args.fetch(:img_x)
+    @img_y = args.fetch(:img_y)
+    @img_width = args.fetch(:img_width)
+    @img_height = args.fetch(:img_height)
+    @similarity = args.fetch(:similarity, 80)
+  end
+
+  # Public: Gets image Roi info.
+  #
+  # Returns a tidy String with image Roi info.
+  def info
+    "#{super} Img.X=#{@img_x} Img.Y=#{@img_y} Img.Width=#{@img_width} Img.Height=#{@img_height} Similarity=#{@similarity}"
+  end
+
+  # Public: Checks if image is displayed as defined in the given ROI.
+  #         Corresponds to: api_is_image_area_displayed??
+  #
+  # key          - String name of key to press to trigger evaluation (default: nil).
+  #                If default, no keys will be pressed.
+  # delay        - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # timeout      - Integer total milliseconds to allow before timing out (default: 0).
+  # scale        - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  # verifies_for - Integer total milliseconds for which the ROI must verify in order to succeed (default: 0).
+  #                If default, the ROI must only verify once.
+  # priority     - Symbol representing evaluation priority used to throttle CPU usage (default: :normal):
+  #                :critical   - Sleep 10 milliseconds between intensive tasks (should be used sparingly).
+  #                :high       - Sleep 100 milliseconds between intensive tasks.
+  #                :normal     - Sleep 1 second between intensive tasks (default).
+  #                :low        - Sleep 10 seconds between intensive tasks.
+  #                :background - Sleep 1 minute between intensive tasks (should be used sparingly).
+  # log_every    - Integer interval in milliseconds between logs (default: 1000).
+  # ref_img      - String path to reference image to override the one in the Roi (default: nil).
+  #
+  # Returns a Boolean true if image is displayed before the timeout, otherwise false.
+  def displayed?(args={})
+    logger.info('Checking if image area is displayed')
+    scale = args.fetch(:scale, false)
+    frame = args[:frame]
+    ref_img_json = ref_img_roi_to_json(ref_img: args[:ref_img])
+    verify(args) do
+      if frame.nil?
+        right_roi = to_json
+        json = get_json_for_match_2(ref_img_json, right_roi, scale: scale)
+        result = test_case.send(:tmc_post, "/api/roi/image/actions/#{dut.slot}", json: json)['value']
+        logger.roi(self, args.merge(message: "Image is#{result ? '' : ' not'} displayed on screen",
+                                    use_last_image: true))
+      else
+        right_roi = to_json(ref_img: frame)
+        json = get_json_for_match_2(ref_img_json, right_roi, scale: scale)
+        result = test_case.send(:tmc_post, '/api/roi/image/actions', json: json)['value']
+        logger.roi(self, args.merge(message: "Image is#{result ? '' : ' not'} displayed in frame", screenshot: false))
+      end
+      result
+    end
+  end
+  special_method(:displayed?)
+
+  # TODO: come up with a use for this that makes sense in the context of a specific image Roi (area)
+  def retrieve(args={})
+    logger.info('Retrieving image area')
+    raise 'ImageRoi retrieve not implemented! Did you mean dut.capture_screen?'
+  end
+  #special_method(:retrieve)
+
+  # Public: Measures the approximate time for the given image Roi to change.
+  #         Corresponds to: api_time_for_screen_to_change
+  #
+  # key       - String key press to trigger evaluation (default: nil).
+  #             If default, no key will be pressed.
+  # delay     - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # timeout   - Integer total milliseconds to allow before timing out (default: nil).
+  #             If default, timeout will be calculated as [ delay + 5000 ].
+  # scale     - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  # priority  - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #             :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #             :high       - Sleep 100 ms between intensive tasks
+  #             :normal     - Sleep 1 second between intensive tasks
+  #             :low        - Sleep 10 seconds between intensive tasks
+  #             :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  # log_every - Integer total milliseconds between logs (default: 1000).
+  # report    - Boolean indicating whether to report measurements to ITMS (default: true).
+  #
+  # Returns the Float total milliseconds for the image Roi to change.
+  def time_to_change(args={})
+    logger.info('Measuring time for image to change')
+    scale = args.fetch(:scale, false)
+    next_img = dut.capture_screen
+    measure(args) do
+      roi = to_json(ref_img: next_img)
+      json = get_json_for_match_2(roi, roi, scale: scale)
+      resp = test_case.send(:tmc_post, "/api/roi/image/actions/#{dut.id}", json: json)
+      result = !resp['value']
+      logger.roi(self, args.merge(message: "Image #{result ? 'changed' : 'did not change'}", use_last_image: true))
+      result
+    end
+  end
+  special_method(:time_to_change)
+
+  # Public: Measures the precise time for the given image Roi to change.
+  #         Corresponds to: api_hp_time_for_screen_to_change
+  #
+  # key       - String key press to trigger evaluation (default: nil).
+  #             If default, no key will be pressed.
+  # delay     - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # timeout   - Integer total milliseconds to allow before timing out (default: nil).
+  #             If default, timeout will be calculated as [ delay + 5000 ].
+  # scale     - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  # priority  - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #             :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #             :high       - Sleep 100 ms between intensive tasks
+  #             :normal     - Sleep 1 second between intensive tasks
+  #             :low        - Sleep 10 seconds between intensive tasks
+  #             :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  # log_every - Integer total milliseconds between logs (default: 1000).
+  # report    - Boolean indicating whether to report measurements to ITMS (default: true).
+  #
+  # Returns the Float total milliseconds for the image Roi to change.
+  def precise_time_to_change(args={})
+    logger.info('Measuring precise time for image to change')
+    args[:precise] = true
+    scale = args.fetch(:scale, false)
+    values = []
+    measure(args, values) do |frame, frames|
+      roi = to_json(ref_img: frame)
+      if frames.empty?
+        frames << frame
+        result = false  #TODO: do we need to implement this?
+        logger.roi(self, args.merge(message: "Image #{result ? 'changed' : 'did not change'} on screen",
+                                    use_last_image: true))
+      else
+        json = get_json_for_match_2(roi, roi, scale: scale)
+        resp = test_case.send(:tmc_post, '/api/roi/image/actions', json: json)
+        result = !resp['value']
+        logger.roi(self, args.merge(message: "Image #{result ? 'changed' : 'did not change'} in frame",
+                                    screenshot: false))
+      end
+      result
+    end
+  end
+  special_method(:precise_time_to_change)
+
+  #TODO: Corresponds to: api_time_for_screen_match_file
+
+  private
+
+  # Internal: Returns the ROI as a hash.
+  def to_json(ref_img: nil)
+    super(ref_img: ref_img).merge(threshold: @similarity)
+  end
+
+  # Internal: Returns the reference image ROI as a hash.
+  def ref_img_roi_to_json(ref_img: nil)
+    {x: @img_x, y: @img_y, width: @img_width, height: @img_height, referenceImage: ref_img || @ref_img,
+     threshold: @similarity}
+  end
+
+end

data/lib/lib/roi/roi.rb

@@ -0,0 +1,1064 @@
+require 'delegate'
+require './lib/helpers/tmc_helpers/tmc_helpers'
+require './lib/mixins/can_have_special_methods'
+
+class Roi
+  include CanHaveSpecialMethods
+
+  attr_accessor(:x, :y, :width, :height, :ref_img)
+  attr_reader(:name)
+
+  # Public: Initializes a base Roi.
+  #
+  # dut       - Platform (or subclass) instance to which this Roi belongs.
+  # x         - Integer x coordinate (default: nil).
+  # y         - Integer y coordinate (default: nil).
+  # width     - Integer width (default: nil).
+  # height    - Integer height (default: nil).
+  # rectangle - Hash defining rectangle with keys :x, :y, :width, :height (default: nil).
+  # element   - Hash same as rectangle (default: nil).
+  # ref_img   - String path to reference image (default: nil).
+  #
+  # Returns nothing.
+  def initialize(dut, args={})
+    @name = nil
+    # Determine ROI name. This will be the first method that calls `new'.
+    stack = caller
+    last_end = stack.each_index.select do |i|
+      stack[i].end_with?("in `new'")
+    end.last
+    unless last_end.nil?
+      match = stack[last_end + 1].match(/`(\w+)'/)
+      unless match.nil?
+        @name = match[1] unless match[1] == 'run'  # ignore dynamic ROIs
+      end
+    end
+    if args.include?(:element)
+      self.rectangle=args[:element]
+    else
+      self.rectangle=(args.fetch(:rectangle, args))  # Get x, y, width, and height from rectangle (if provided) or args
+    end
+    @ref_img = args.fetch(:ref_img, '')
+    @dut = dut
+    # These are declared without the convenience methods (TMC monkey patching) so as not to break syntax evaluation.
+    @priorities = {
+        :critical => 0.01,
+        :high => 0.1,
+        :normal => 1,
+        :low => 10,
+        :background => 60
+    }
+  end
+
+  # Public: Gets Roi rectangle.
+  #
+  # Returns Roi rectangle as a Hash with keys :x, :y, :width, :height.
+  def rectangle
+    {:x => @x, :y => @y, :width => @width, :height => @height}
+  end
+
+  # Public: Sets Roi rectangle.
+  #
+  # rectangle - Hash with keys :x, :y, :width, and :height from which to set Roi rectangle.
+  #
+  # Returns nothing.
+  def rectangle=(rectangle)
+    @x = rectangle[:x]
+    @y = rectangle[:y]
+    @width = rectangle[:width]
+    @height = rectangle[:height]
+  end
+
+  # Public: Gets Roi info.
+  #
+  # Returns a tidy String with Roi info.
+  def info
+    "#{self.class.name}: X=#{@x} Y=#{@y} Width=#{@width} Height=#{@height} Ref.Image=#{@ref_img}"
+  end
+
+  # Public: Placeholder for displayed?, which must be implemented by each Roi type.
+  def displayed?(*args)
+    raise "#{self.class.name} does not implement special method `displayed?'"
+  end
+
+  # Public: Placeholder for retrieve, which must be implemented by each Roi type.
+  def retrieve(*args)
+    raise "#{self.class.name} does not implement special method `retrieve'"
+  end
+
+  # Public: Waits until the given ROI is displayed.
+  #         Corresponds to api_wait_till_<ROI TYPE>_displayed?
+  #
+  # timeout      - Integer total milliseconds to allow before timing out.
+  # key          - String name of key to press to trigger evaluation (default: nil).
+  #                If default, no keys will be pressed.
+  # delay        - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # scale        - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  #                Applies to image ROIs only.
+  # verifies_for - Integer total milliseconds for which the ROI must verify in order to succeed (default: 0).
+  #                If default, the ROI must only verify once.
+  # priority     - Symbol representing evaluation priority used to throttle CPU usage (default: :normal):
+  #                :critical   - Sleep 10 milliseconds between intensive tasks (should be used sparingly).
+  #                :high       - Sleep 100 milliseconds between intensive tasks.
+  #                :normal     - Sleep 1 second between intensive tasks (default).
+  #                :low        - Sleep 10 seconds between intensive tasks.
+  #                :background - Sleep 1 minute between intensive tasks (should be used sparingly).
+  # log_every    - Integer interval in milliseconds between logs (default: 1000).
+  # message      - String message to log instead of the default (default: nil).
+  #                Default logs a tailored message.
+  #
+  # Returns Boolean true if displayed before the timeout, otherwise false.
+  def wait_until_displayed?(timeout, args={})
+    logger.info("Waiting #{timeout} ms until #{self.class.name} is displayed")
+    args[:timeout] = timeout
+    displayed?(args)
+  end
+  special_method(:wait_until_displayed?)
+
+  # Public: Presses a key until the given Roi is displayed.
+  #         Corresponds to api_press_key_till_<ROI TYPE>_displayed?
+  #
+  # key          - String name of key to press.
+  # presses      - Integer maximum number of times to press the key (default: nil).
+  # timeout      - Integer total milliseconds to allow before timing out (default: 30000).
+  # delay        - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # scale        - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  #                Applies to image ROIs only.
+  # try_every    - Integer total milliseconds to delay between key presses (default: 3000).
+  # try_timeout  - Integer total milliseconds to allow after each key press before timing out (default: nil).
+  # verifies_for - Integer total milliseconds for which the ROI must verify in order to succeed (default: 0).
+  #                If default, the ROI must only verify once.
+  # priority     - Symbol representing evaluation priority used to throttle CPU usage (default: :normal):
+  #                :critical   - Sleep 10 milliseconds between intensive tasks (should be used sparingly).
+  #                :high       - Sleep 100 milliseconds between intensive tasks.
+  #                :normal     - Sleep 1 second between intensive tasks (default).
+  #                :low        - Sleep 10 seconds between intensive tasks.
+  #                :background - Sleep 1 minute between intensive tasks (should be used sparingly).
+  # log_every    - Integer interval in milliseconds between logs (default: 1000).
+  # message      - String message to log instead of the default (default: nil).
+  #                Default logs a tailored message.
+  #
+  # Returns Boolean true if displayed before the timeout, otherwise false.
+  def press_key_until_displayed?(key, args={})
+    logger.info("Pressing key #{key.inspect} until #{self.class.name} is displayed")
+    timeout_s = args.fetch(:timeout, 30.sec) / 1.sec
+    args[:timeout] = args[:try_timeout]
+    key_delay = args.fetch(:try_every, 3.sec)
+    presses = args[:presses]
+    press_count = 0
+    start_time = Time.now
+    displayed = false
+    loop do
+      displayed = displayed?(args)
+      break if displayed
+      if presses.nil?
+        break if (Time.now - start_time) > timeout_s
+      elsif press_count == presses
+        break
+      end
+      @dut.press_key(key, :sleep_time => key_delay)
+      press_count += 1
+    end
+    displayed
+  end
+  special_method(:press_key_until_displayed?)
+
+  # Public: Measures the approximate time for the given Roi to be displayed.
+  #         Corresponds to: api_time_to_display_<ROI TYPE>
+  #
+  # key       - String key press to trigger evaluation (default: nil).
+  #             If default, no key will be pressed.
+  # delay     - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # timeout   - Integer total milliseconds to allow before timing out (default: nil).
+  #             If default, timeout will be calculated as [ delay + 5000 ].
+  # scale     - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  #             Applies to image ROIs only.
+  # expected  - Boolean expected result of evaluation or Array of expected transition values (default: true).
+  # priority  - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #             :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #             :high       - Sleep 100 ms between intensive tasks
+  #             :normal     - Sleep 1 second between intensive tasks
+  #             :low        - Sleep 10 seconds between intensive tasks
+  #             :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  # log_every - Integer total milliseconds between logs (default: 1000).
+  # report    - Boolean indicating whether to report measurements to ITMS (default: true).
+  #
+  # Returns the Float total milliseconds for the ROI to be displayed.
+  def time_to_display(args={})
+    logger.info("Measuring time to display #{self.class.name}")
+    measure(args) do
+      displayed?(:set_roi_options => args)
+    end
+  end
+  special_method(:time_to_display)
+
+  # Public: Measures the precise time for the given Roi to be displayed.
+  #         Corresponds to: api_hp_time_to_display_<ROI TYPE>
+  #
+  # key       - String key press to trigger evaluation (default: nil).
+  #             If default, no key will be pressed.
+  # delay     - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # timeout   - Integer total milliseconds to allow before timing out (default: nil).
+  #             If default, timeout will be calculated as [ delay + 5000 ].
+  # scale     - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  #             Applies to image ROIs only.
+  # priority  - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #             :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #             :high       - Sleep 100 ms between intensive tasks
+  #             :normal     - Sleep 1 second between intensive tasks
+  #             :low        - Sleep 10 seconds between intensive tasks
+  #             :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  # log_every - Integer total milliseconds between logs (default: 1000).
+  # report    - Boolean indicating whether to report measurements to ITMS (default: true).
+  #
+  # Returns the Float total milliseconds for the Roi to be displayed.
+  def precise_time_to_display(args={})
+    logger.info("Measuring precise time to display #{self.class.name}")
+    args[:precise] = true
+    args[:with_last_frame] = true
+    measure(args) do |frame, last_frame|
+      displayed?(:frame => frame, :last_frame => last_frame, :set_roi_options => args)
+    end
+  end
+  special_method(:precise_time_to_display)
+
+  # Public: Measures the precise time for the given Roi to match on the specified DUT.
+  #
+  # other_dut - Platform (or subclass) instance of DUT to match.
+  # timeout   - Integer total milliseconds to allow before timing out.
+  # key       - String key press to trigger evaluation (default: nil).
+  #             If default, no key will be pressed.
+  # delay     - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # report    - Boolean indicating whether to report measurements to ITMS (default: true). NOT YET IMPLEMENTED.
+  #
+  # Returns the Float total milliseconds for the Roi to disappear.
+  def precise_time_to_match_dut(other_dut, timeout, args={})
+    #TODO: this probably needs some work for the new EE
+    msg = "Measuring precise time for #{info} to match DUT #{other_dut.model}:#{other_dut.slot}"
+    logger.roi(self, args.merge(:message => msg, :screenshot => false))
+    key = args[:key]
+    delay = args.fetch(:delay, 0)
+    other_roi = args[:other_roi]
+    left_frames = []
+    right_frames = []
+    test_case.add_teardown('Cleaning up captured frames') do
+      json = get_json_for_test.merge(files: (left_frames + right_frames).map {|frm| frm['path']})
+      test_case.send(:tmc_delete, '/api/images', json: json )
+    end
+    # Press key if specified
+    unless key.nil?
+      do_trigger(key, :duts => [dut, other_dut])
+    end
+    # Delay if specified
+    if delay > 0
+      sleep(delay / 1000.0)  # this is native sleep
+    end
+    # Capture frames for the duration
+    json1 = get_json_for_iter.merge(durationMs: timeout)
+    threads = [
+        Thread.new do
+          resp = test_case.send(:tmc_post, "/api/images/record/#{dut.slot}", json: json1)
+          left_frames += resp.fetch('images')
+        end,
+        Thread.new do
+          resp = test_case.send(:tmc_post, "/api/images/record/#{other_dut.slot}", json: json1)
+          right_frames += resp.fetch('images')
+        end
+    ]
+    threads.each { |thr| thr.join }  # wait all threads
+    if left_frames.empty? || right_frames.empty?
+      raise 'Not enough images captured for analysis!'
+    end
+    # Send frames for processing
+    if other_roi.nil?
+      right_roi = rectangle
+    else
+      right_roi = other_roi.rectangle
+    end
+    right_roi.update(:threshold => threshold) unless right_roi.nil?
+    json2 = get_json_for_compare_2(rectangle, right_roi, left_frames: left_frames, right_frames: right_frames)
+    result = test_case.send(:tmc_post, '/api/roi/video/actions', json: json2)['value']
+    # TODO: figure out which frame(s) and display them
+    logger.roi(self, args.merge(message: "#{result.nil? ? 'no ' : ''}matching frames found".capitalize,
+                                screenshot: false))
+    logger.duration(result, message: 'Time to match') unless result.nil?
+    result
+  end
+  special_method(:precise_time_to_display)
+
+  # Public: Returns true if the given Roi disappears within the given time.
+  #         api_wait_till_<ROI TYPE>_not_displayed?
+  #
+  # timeout   - Integer total milliseconds to allow before timing out.
+  # key       - String key press to trigger evaluation (default: nil).
+  #             If default, no key will be pressed.
+  # delay     - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # scale     - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  #             Applies to image ROIs only.
+  # priority  - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #             :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #             :high       - Sleep 100 ms between intensive tasks
+  #             :normal     - Sleep 1 second between intensive tasks
+  #             :low        - Sleep 10 seconds between intensive tasks
+  #             :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  # log_every - Integer total milliseconds between logs (default: 1000).
+  #
+  # Returns a Boolean true if the Roi disappears before the timeout, otherwise false.
+  def wait_until_not_displayed?(timeout, args={})
+    logger.info("Waiting #{timeout} ms until #{self.class.name} is not displayed")
+    args[:timeout] = timeout
+    args[:expected] = false
+    displayed?(args)
+  end
+  special_method(:wait_until_not_displayed?)
+
+  # Public: Measures the approximate time for the given Roi to disappear.
+  #         Corresponds to: api_time_for_<ROI TYPE>_to_disappear
+  #
+  # key       - String key press to trigger evaluation (default: nil).
+  #             If default, no key will be pressed.
+  # delay     - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # timeout   - Integer total milliseconds to allow before timing out (default: nil).
+  #             If default, timeout will be calculated as [ delay + 5000 ].
+  # scale     - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  #             Applies to image ROIs only.
+  # priority  - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #             :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #             :high       - Sleep 100 ms between intensive tasks
+  #             :normal     - Sleep 1 second between intensive tasks
+  #             :low        - Sleep 10 seconds between intensive tasks
+  #             :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  # log_every - Integer total milliseconds between logs (default: 1000).
+  # report    - Boolean indicating whether to report measurements to ITMS (default: true).
+  #
+  # Returns the Float total milliseconds for the ROI to disappear.
+  def time_to_disappear(args={})
+    logger.info("Measuring time for #{self.class.name} to disappear")
+    measure(args) do
+      displayed?(:expected => false, :set_roi_options => args)
+    end
+  end
+  special_method(:time_to_disappear)
+
+  # Public: Measures the precise time for the given Roi to disappear.
+  #         Corresponds to: api_hp_time_for_<ROI TYPE>_to_disappear
+  #
+  # key       - String key press to trigger evaluation (default: nil).
+  #             If default, no key will be pressed.
+  # delay     - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # timeout   - Integer total milliseconds to allow before timing out (default: nil).
+  #             If default, timeout will be calculated as [ delay + 5000 ].
+  # scale     - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  #             Applies to image ROIs only.
+  # priority  - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #             :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #             :high       - Sleep 100 ms between intensive tasks
+  #             :normal     - Sleep 1 second between intensive tasks
+  #             :low        - Sleep 10 seconds between intensive tasks
+  #             :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  # log_every - Integer total milliseconds between logs (default: 1000).
+  # report    - Boolean indicating whether to report measurements to ITMS (default: true).
+  #
+  # Returns the Float total milliseconds for the Roi to disappear.
+  def precise_time_to_disappear(args={})
+    logger.info("Measuring precise time for #{self.class.name} to disappear")
+    args[:precise] = true
+    args[:with_last_frame] = true
+    measure(args) do |frame, last_frame|
+      displayed?(:frame => frame, :last_frame => last_frame, :expected => false, :set_roi_options => args)
+    end
+  end
+  special_method(:precise_time_to_disappear)
+
+  # Public: Returns true if the given Roi transitions before the specified timeout from false to true to false.
+  #         Corresponds to: api_wait_for_<ROI TYPE>_transition?
+  #
+  # timeout   - Integer total milliseconds to allow before timing out.
+  # key       - String key press to trigger evaluation (default: nil).
+  #             If default, no key will be pressed.
+  # delay     - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # expected  - Array of expected transition values (default: [true, false]).
+  # scale     - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  #             Applies to image ROIs only.
+  # priority  - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #             :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #             :high       - Sleep 100 ms between intensive tasks
+  #             :normal     - Sleep 1 second between intensive tasks
+  #             :low        - Sleep 10 seconds between intensive tasks
+  #             :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  # log_every - Integer total milliseconds between logs (default: 1000).
+  #
+  # Returns a Boolean true if the Roi transitioned before the timeout, otherwise false.
+  def wait_for_transition?(timeout, args={})
+    logger.info("Waiting #{timeout} ms for #{self.class.name} transition")
+    args[:timeout] = timeout
+    args[:expected] ||= [true, false]
+    displayed?(args)
+  end
+  special_method(:wait_for_transition?)
+
+  # Public: Measures the approximate time for the given Roi to transition from false to true to false.
+  #         Corresponds to: api_time_for_<ROI TYPE>_transition
+  #
+  # key       - String key press to trigger evaluation (default: nil).
+  #             If default, no key will be pressed.
+  # delay     - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # timeout   - Integer total milliseconds to allow before timing out (default: nil).
+  #             If default, timeout will be calculated as [ delay + 5000 ].
+  # expected  - Array of expected transition values (default: [true, false]).
+  # scale     - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  #             Applies to image ROIs only.
+  # priority  - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #             :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #             :high       - Sleep 100 ms between intensive tasks
+  #             :normal     - Sleep 1 second between intensive tasks
+  #             :low        - Sleep 10 seconds between intensive tasks
+  #             :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  # log_every - Integer total milliseconds between logs (default: 1000).
+  # report    - Boolean indicating whether to report measurements to ITMS (default: true).
+  #
+  # Returns the Float total milliseconds for the ROI to transition.
+  def time_to_transition(args={})
+    logger.info("Measuring time for #{self.class.name} to transition")
+    args[:expected] ||= [true, false]
+    measure(args) do
+      displayed?(:set_roi_options => args)
+    end
+  end
+  special_method(:time_to_transition)
+
+  # Public: Measures the precise time for the given Roi to transition from false to true to false.
+  #         Corresponds to: api_hp_time_for_<ROI TYPE>_transition
+  #
+  # key       - String key press to trigger evaluation (default: nil).
+  #             If default, no key will be pressed.
+  # delay     - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # timeout   - Integer total milliseconds to allow before timing out (default: nil).
+  #             If default, timeout will be calculated as [ delay + 5000 ].
+  # expected  - Array of expected transition values (default: [true, false]).
+  # scale     - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  #             Applies to image ROIs only.
+  # priority  - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #             :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #             :high       - Sleep 100 ms between intensive tasks
+  #             :normal     - Sleep 1 second between intensive tasks
+  #             :low        - Sleep 10 seconds between intensive tasks
+  #             :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  # log_every - Integer total milliseconds between logs (default: 1000).
+  # report    - Boolean indicating whether to report measurements to ITMS (default: true).
+  #
+  # Returns the Float total milliseconds for the Roi to transition.
+  def precise_time_to_transition(args={})
+    logger.info("Measuring precise time for #{self.class.name} to transition")
+    args[:expected] ||= [true, false]
+    args[:precise] = true
+    measure(args) do |frame|
+      displayed?(:frame => frame, :set_roi_options => args)
+    end
+  end
+  special_method(:precise_time_to_transition)
+
+  # Public: Returns true if the given Roi changes before the specified timeout.
+  #
+  # timeout   - Integer total milliseconds to allow before timing out.
+  # key       - String key press to trigger evaluation (default: nil).
+  #             If default, no key will be pressed.
+  # delay     - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # scale     - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  #             Applies to image ROIs only.
+  # priority  - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #             :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #             :high       - Sleep 100 ms between intensive tasks
+  #             :normal     - Sleep 1 second between intensive tasks
+  #             :low        - Sleep 10 seconds between intensive tasks
+  #             :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  # log_every - Integer total milliseconds between logs (default: 1000).
+  #
+  # Returns a Boolean true if the Roi changed before the timeout, otherwise false.
+  def wait_for_change?(timeout, args={})
+    logger.info("Waiting #{timeout} ms for #{self.class.name} to change")
+    args[:timeout] = timeout
+    set_roi_options(args)
+    first = retrieve
+    verify(args) do
+      retrieve != first
+    end
+  end
+  special_method(:wait_for_change?)
+
+  # Public: Measures the approximate time for the given Roi to change.
+  #         Corresponds to: api_time_to_<ROI TYPE>_change
+  #
+  # key       - String key press to trigger evaluation (default: nil).
+  #             If default, no key will be pressed.
+  # delay     - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # timeout   - Integer total milliseconds to allow before timing out (default: nil).
+  #             If default, timeout will be calculated as [ delay + 5000 ].
+  # scale     - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  #             Applies to image ROIs only.
+  # priority  - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #             :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #             :high       - Sleep 100 ms between intensive tasks
+  #             :normal     - Sleep 1 second between intensive tasks
+  #             :low        - Sleep 10 seconds between intensive tasks
+  #             :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  # log_every - Integer total milliseconds between logs (default: 1000).
+  # report    - Boolean indicating whether to report measurements to ITMS (default: true).
+  #
+  # Returns the Float total milliseconds for the Roi to change.
+  def time_to_change(args={})
+    logger.info("Measuring time for #{self.class.name} to change")
+    set_roi_options(args)
+    first = retrieve
+    measure(args) do
+      retrieve != first
+    end
+  end
+  special_method(:time_to_change)
+
+  # Public: Measures the precise time for the given Roi to change.
+  #         Corresponds to: api_hp_time_to_<ROI TYPE>_change
+  #
+  # key       - String key press to trigger evaluation (default: nil).
+  #             If default, no key will be pressed.
+  # delay     - Integer total milliseconds to delay before starting evaluation (default: 0).
+  # timeout   - Integer total milliseconds to allow before timing out (default: nil).
+  #             If default, timeout will be calculated as [ delay + 5000 ].
+  # scale     - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  #             Applies to image ROIs only.
+  # priority  - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #             :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #             :high       - Sleep 100 ms between intensive tasks
+  #             :normal     - Sleep 1 second between intensive tasks
+  #             :low        - Sleep 10 seconds between intensive tasks
+  #             :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  # log_every - Integer total milliseconds between logs (default: 1000).
+  # report    - Boolean indicating whether to report measurements to ITMS (default: true).
+  #
+  # Returns the Float total milliseconds for the Roi to change.
+  def precise_time_to_change(args={})
+    logger.info("Measuring precise time for #{self.class.name} to change")
+    args[:precise] = true
+    set_roi_options(args)
+    values = [retrieve]
+    measure(args, values) do |frame, vals|
+      value = retrieve(:frame => frame)
+      vals << value
+      value != vals.first
+    end
+  end
+  special_method(:precise_time_to_change)
+
+  # Public: Finds the frame in which the given Roi verifies.
+  #         Corresponds to: api_find_<ROI TYPE>_frame
+  #
+  # frames         - Array of frames to search, each being a Hash with the following keys:
+  #                  :filename   - String full path to the frame on the server.
+  #                  :capturedAt - Time at which the frame was captured.
+  #                  :keep       - Boolean indicating whether to keep the frame if cleanup is true. Initializes false.
+  # start_time     - Time at which frame capture began.
+  # starting_frame - Integer index of frame at which to start evaluation (default: 0).
+  # timeout        - Integer total milliseconds to allow before timing out (default: nil).
+  #                  If default, all frames will be searched.
+  # scale          - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  #                  Applies to image ROIs only.
+  # verifies_for   - Integer total milliseconds for which the ROI must continuously verify in order to be counted
+  #                  successful (default: 0).
+  #                  If default, the ROI must only verify once.
+  # priority       - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #                  :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #                  :high       - Sleep 100 ms between intensive tasks
+  #                  :normal     - Sleep 1 second between intensive tasks
+  #                  :low        - Sleep 10 seconds between intensive tasks
+  #                  :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  # log_every      - Integer total milliseconds between logs (default: 1000).
+  # report         - Boolean indicating whether to report measurements to ITMS (default: false).
+  #
+  # Returns the Integer index of the matching frame.
+  def find_frame_displayed(frames, start_time, args={})
+    logger.info("Finding frame where #{self.class.name} is displayed")
+    args[:with_last_frame] = true
+    args[:report] = false
+    if frames.count < 2
+      default_timeout = 30.sec
+    else
+      default_timeout = test_case.get_time_delta(frames.first[:capturedAt], frames.last[:capturedAt])
+    end
+    args[:timeout] ||= default_timeout
+    frame(frames, start_time, args) do |frame, last_frame|
+      displayed?(:frame => frame, :last_frame => last_frame, :set_roi_options => args)
+    end
+  end
+  special_method(:find_frame_displayed)
+
+  # Public: Finds the frame in which the given Roi does not verify.
+  #         Corresponds to: api_find_non_<ROI TYPE>_frame
+  #
+  # frames         - Array of frames to search, each being a Hash with the following keys:
+  #                  :filename   - String full path to the frame on the server.
+  #                  :capturedAt - Time at which the frame was captured.
+  #                  :keep       - Boolean indicating whether to keep the frame if cleanup is true. Initializes false.
+  # start_time     - Time at which frame capture began.
+  # starting_frame - Integer index of frame at which to start evaluation (default: 0).
+  # timeout        - Integer total milliseconds to allow before timing out (default: nil).
+  #                  If default, all frames will be searched.
+  # scale          - Boolean if the larger image should be scaled to the size of the smaller image (default: false).
+  #                  Applies to image ROIs only.
+  # verifies_for   - Integer total milliseconds for which the ROI must continuously verify in order to be counted
+  #                  successful (default: 0).
+  #                  If default, the ROI must only verify once.
+  # priority       - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #                  :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #                  :high       - Sleep 100 ms between intensive tasks
+  #                  :normal     - Sleep 1 second between intensive tasks
+  #                  :low        - Sleep 10 seconds between intensive tasks
+  #                  :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  # log_every      - Integer total milliseconds between logs (default: 1000).
+  # report         - Boolean indicating whether to report measurements to ITMS (default: false).
+  #
+  # Returns the Integer index of the matching frame.
+  def find_frame_not_displayed(frames, start_time, args={})
+    logger.info("Finding frame where #{self.class.name} is not displayed")
+    args[:with_last_frame] = true
+    args[:expected] = false
+    args[:report] = false
+    frame(frames, start_time, args) do |frame, last_frame|
+      displayed?(:frame => frame, :last_frame => last_frame, :set_roi_options => args)
+    end
+  end
+  special_method(:find_frame_not_displayed)
+
+  private
+
+  # Internal: Gets JSON for get.
+  def get_json_for_get(frame: nil, roi: nil)
+    get_json_for_action('get').merge(roi: roi || to_json(ref_img: frame))
+  end
+
+  # Internal: Gets JSON for match.
+  def get_json_for_match(frame: nil, roi: nil)
+    get_json_for_action('match').merge(roi: roi || to_json(ref_img: frame))
+  end
+
+  # Internal: Gets JSON for compare.
+  def get_json_for_compare(frame: nil, roi: nil)
+    get_json_for_action('compare').merge(roi: roi || to_json(ref_img: frame))
+  end
+
+  # Internal: Gets JSON for Left/Right match.
+  def get_json_for_match_2(left_roi, right_roi, scale: nil)
+    json = get_json_for_action('match').merge(leftRoi: left_roi, rightRoi: right_roi)
+    json.update(scale: scale) unless scale.nil?
+    json
+  end
+
+  # Internal: Gets JSON for Left/Right compare.
+  def get_json_for_compare_2(left_roi, right_roi, left_frames: nil, right_frames: nil, scale: nil)
+    json = get_json_for_action('compare').merge(leftRoi: left_roi, rightRoi: right_roi)
+    json.update(leftFrames: left_frames) unless left_frames.nil?
+    json.update(rightFrames: right_frames) unless right_frames.nil?
+    json.update(scale: scale) unless scale.nil?
+    json
+  end
+
+  # Internal: Gets JSON populated with job, test, and iteration for the specified action.
+  def get_json_for_action(action)
+    get_json_for_iter.merge(action: action)
+  end
+
+  # Internal: Gets JSON populated with job and test.
+  def get_json_for_test
+    {job: test_case.job, test: test_case.id}
+  end
+
+  # Internal: Gets JSON populated with job, test, and iteration.
+  def get_json_for_iter
+    get_json_for_test.merge(iteration: test_case.iteration)
+  end
+
+  # Internal: Returns the ROI as a hash.
+  def to_json(ref_img: nil)
+    rectangle.merge(referenceImage: ref_img || @ref_img)
+  end
+
+  # Internal: Returns the dut object.
+  def dut
+    @dut
+  end
+
+  # Internal: Returns the test case object.
+  def test_case
+    dut.send(:test_case)
+  end
+
+  # Internal: Returns the logger object.
+  def logger
+    test_case.send(:logger_for_device, @dut.id)
+  end
+
+  # Internal: Sets Roi options from the given arguments.
+  def set_roi_options(args)
+    # Individual Roi classes should use this as needed to set type-specific Roi options
+  end
+
+  # Internal: Returns true if the actual result verifies against the expected result.
+  def verifies?(expected, actual)
+    !actual.nil? && (expected.nil? || actual.eql?(expected) || (expected.is_a?(Regexp) && actual =~ expected))
+  end
+
+  # Internal: Returns true if the given Roi verifies for the specified duration, otherwise false.
+  # args       - Hash of arguments:
+  #              :key             - String key press to trigger evaluation (default: nil).
+  #                                 If default, no key will be pressed.
+  #              :expected        - Object expected value from yielding the given block (default: true).
+  #                                 If an Array is provided, the measurement will expect a transition.
+  #              :precise         - Boolean indicating whether to evaluate with high precision (default: false).
+  #              :delay           - Integer total milliseconds to delay before starting evaluation (default: 0).
+  #              :scale           - Boolean if the larger image should be scaled to the size of the smaller image
+  #                                 (default: false). Applies to image ROIs only.
+  #              :verifies_for    - Integer total milliseconds for which the ROI must continuously verify in order to be
+  #                                 counted successful (default: 0). If default, the ROI must only verify once.
+  #              :timeout         - Integer total milliseconds to allow before timing out (default: nil).
+  #                                 If default, timeout will be calculated as [ delay + verifies_for + 5000 ].
+  #              :priority        - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #                                 :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #                                 :high       - Sleep 100 ms between intensive tasks
+  #                                 :normal     - Sleep 1 second between intensive tasks
+  #                                 :low        - Sleep 10 seconds between intensive tasks
+  #                                 :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  #              :log_every       - Integer total milliseconds between logs (default: 1000).
+  #              :with_last_frame - Boolean indicating whether to pass last frame to block (default: false).
+  #              :message         - String custom message to log (default: nil).
+  # block_args - Splat Array of arguments to pass to the given block.
+  # block      - Block Reference for block to yield.
+  def verify(args, *block_args, &block)
+    args[:timeout] ||= 0.sec if args[:delay].nil? && args[:verifies_for].nil?
+    evaluate(:verify, args, *block_args, &block)
+  end
+
+  # Internal: Returns the time measured for the given Roi to verify for the specified duration, or nil.
+  # args       - Hash of arguments:
+  #              :key              - String key press to trigger evaluation (default: nil).
+  #                                  If default, no key will be pressed.
+  #              :expected         - Object expected value from yielding the given block (default: true).
+  #                                  If an Array is provided, the measurement will expect a transition.
+  #              :precise          - Boolean indicating whether to evaluate with high precision (default: false).
+  #              :delay            - Integer total milliseconds to delay before starting evaluation (default: 0).
+  #              :scale            - Boolean if the larger image should be scaled to the size of the smaller image
+  #                                  (default: false). Applies to image ROIs only.
+  #              :verifies_for     - Integer total milliseconds for which the ROI must continuously verify in order to be
+  #                                  counted successful (default: 0). If default, the ROI must only verify once.
+  #              :timeout          - Integer total milliseconds to allow before timing out (default: nil).
+  #                                  If default, timeout will be calculated as [ delay + verifies_for + 5000 ].
+  #              :priority         - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #                                  :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #                                  :high       - Sleep 100 ms between intensive tasks
+  #                                  :normal     - Sleep 1 second between intensive tasks
+  #                                  :low        - Sleep 10 seconds between intensive tasks
+  #                                  :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  #              :log_every        - Integer total milliseconds between logs (default: 1000).
+  #              :report           - Boolean indicating whether to report measurements to ITMS (default: true).
+  #              :execution_metric - String name of execution metric to report (default: nil).
+  #              :with_last_frame  - Boolean indicating whether to pass last frame to block (default: false).
+  #              :message          - String custom message to log (default: nil).
+  # block_args - Splat Array of arguments to pass to the given block.
+  # block      - Block Reference for block to yield.
+  def measure(args, *block_args, &block)
+    args[:priority] ||= :high # use a higher default priority
+    # Use a higher default timeout
+    if args[:delay].nil? && args[:verifies_for].nil?
+      args[:timeout] ||= args[:precise] ? 10.sec : 30.sec
+    end
+    evaluate(:measure, args, *block_args, &block)
+  end
+
+  # Internal: Returns the value of the given Roi.
+  # args       - Hash of arguments:
+  #              :key             - String key press to trigger evaluation (default: nil).
+  #                                 If default, no key will be pressed.
+  #              :delay           - Integer total milliseconds to delay before starting evaluation (default: 0).
+  #              :message         - String custom message to log (default: nil).
+  # block_args - Splat Array of arguments to pass to the given block.
+  # block      - Block Reference for block to yield.
+  def value(args, *block_args, &block)
+    # Override timeout if we are just retrieving the value
+    args[:timeout] = 0.sec
+    args[:timeout] += args[:delay] unless args[:delay].nil?
+    evaluate(:value, args, *block_args, &block)
+  end
+
+  # Internal: Returns the index of the frame in which the given Roi verifies, or -1.
+  # frames     - Array of frames, each being a Hash with the following keys:
+  #              :filename   - String full path to the frame on the server.
+  #              :capturedAt - Time at which the frame was captured.
+  #              :keep       - Boolean indicating whether to keep the frame if cleanup is true. Initializes false.
+  # start_time - Time at which frame capture began.
+  # args       - Hash of arguments:
+  #              :starting_frame   - Integer index of frame at which to start evaluation (default: 0).
+  #              :expected         - Object expected value from yielding the given block (default: true).
+  #                                  If an Array is provided, the measurement will expect a transition.
+  #              :verifies_for     - Integer total milliseconds for which the ROI must continuously verify in order to be
+  #                                  counted successful (default: 0). If default, the ROI must only verify once.
+  #              :timeout          - Integer total milliseconds to allow before timing out (default: nil).
+  #                                  If default, all frames will be searched.
+  #              :scale            - Boolean if the larger image should be scaled to the size of the smaller image
+  #                                  (default: false). Applies to image ROIs only.
+  #              :priority         - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #                                  :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #                                  :high       - Sleep 100 ms between intensive tasks
+  #                                  :normal     - Sleep 1 second between intensive tasks
+  #                                  :low        - Sleep 10 seconds between intensive tasks
+  #                                  :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  #              :log_every        - Integer total milliseconds between logs (default: 1000).
+  #              :report           - Boolean indicating whether to report measurements to ITMS (default: true).
+  #              :execution_metric - String name of execution metric to report (default: nil).
+  #              :with_last_frame  - Boolean indicating whether to pass last frame to block (default: false).
+  #              :message          - String custom message to log (default: nil).
+  # block_args - Splat Array of arguments to pass to the given block.
+  # block      - Block Reference for block to yield.
+  def frame(frames, start_time, args, *block_args, &block)
+    args[:precise] = true
+    args[:priority] ||= :high # use a higher default priority
+    # Use a higher default timeout
+    args[:timeout] ||= 5.min  # should search all frames unless someone went nuts with the capture
+    args[:frames] = frames
+    args[:starting_frame] ||= 0
+    args[:start_time] = start_time
+    evaluate(:frame, args, *block_args, &block)
+  end
+
+  # Internal: Evaluates the given Roi for the specified duration, or times out.
+  # args       - Hash of arguments:
+  #              :type             - Symbol type of evaluation:
+  #                                  :verify  - Return true if the Roi verifies, otherwise false.
+  #                                  :measure - Return the time in ms for the Roi to verify, or nil.
+  #                                  :value   - Return the Roi value.
+  #                                  :frame   - Return the frame in which the Roi verifies.
+  #              :key              - String key press to trigger evaluation (default: nil).
+  #                                  If default, no key will be pressed.
+  #              :expected         - Object expected value from yielding the given block (default: true).
+  #                                  If an Array is provided, the measurement will expect a transition.
+  #              :precise          - Boolean indicating whether to evaluate with high precision (default: false).
+  #              :delay            - Integer total milliseconds to delay before starting evaluation (default: 0).
+  #              :scale            - Boolean if the larger image should be scaled to the size of the smaller image
+  #                                  (default: false). Applies to image ROIs only.
+  #              :verifies_for     - Integer total milliseconds for which the ROI must continuously verify in order to be
+  #                                  counted successful (default: 0). If default, the ROI must only verify once.
+  #              :timeout          - Integer total milliseconds to allow before timing out (default: nil).
+  #                                  If default, timeout will be calculated as [ delay + verifies_for + 5000 ].
+  #              :priority         - Symbol evaluation priority used to throttle CPU usage (default: :normal):
+  #                                  :critical   - Sleep 10 ms between intensive tasks (USE SPARINGLY)
+  #                                  :high       - Sleep 100 ms between intensive tasks
+  #                                  :normal     - Sleep 1 second between intensive tasks
+  #                                  :low        - Sleep 10 seconds between intensive tasks
+  #                                  :background - Sleep 1 minute between intensive tasks (USE SPARINGLY)
+  #              :log_every        - Integer total milliseconds between logs (default: 1000).
+  #              :report           - Boolean indicating whether to report measurements to ITMS (default: true).
+  #              :execution_metric - String name of execution metric to report (default: nil).
+  #              :with_last_frame  - Boolean indicating whether to pass last frame to block (default: false).
+  #              :message          - String custom message to log (default: nil).
+  #              :frames           - Array of frames to use, each being a Hash with the following keys (default: nil):
+  #                                  :filename   - String full path to the frame on the server.
+  #                                  :capturedAt - Time at which the frame was captured.
+  #                                  :keep       - Boolean indicating whether to keep the frame if cleanup is true.
+  #                                                Initializes false.
+  #                                  If default, frames will be captured as needed.
+  #              :start_time       - Time at which evaluation began (default: nil).
+  #                                  If default, an appropriate start Time will be used.
+  # block_args - Splat Array of arguments to pass to the given block.
+  # block      - Block Reference for block to yield.
+  def evaluate(type, args, *block_args, &block)
+    case type
+      when :verify
+        log_action = 'verifying'
+        log_state = 'verified'
+      when :measure
+        log_action = 'measuring'
+        log_state = 'measured'
+      when :value
+        log_action = 'retrieving'
+        log_state = 'retrieved'
+      when :frame
+        log_action = 'finding frame for'
+        log_state = 'found in frame'
+    end
+    # DO NOT MODIFY ARGS IN THIS FUNCTION
+    msg = "#{args[:message] || log_action.capitalize} #{info}"
+    logger.roi(self, args.merge(:message => msg, :screenshot => false))
+    # Get arguments
+    with_last_frame = args.fetch(:with_last_frame, false)
+    key = args[:key]
+    expected = args.fetch(:expected, true)
+    expected = [expected] unless expected.is_a?(Array)
+    precise = args.fetch(:precise, false)
+    delay = args.fetch(:delay, 0)
+    verifies_for = args.fetch(:verifies_for, 0)
+    timeout = args[:timeout] || delay + verifies_for + 5.sec
+    #TODO: put back?
+    #if precise && timeout > (delay + 5.sec)
+    #  raise "Timeout (#{timeout} ms) cannot be greater than delay + 5 sec! Try increasing delay or using a non-precise method."
+    #end
+    if timeout < (delay + verifies_for)
+      raise "Timeout (#{timeout} ms) cannot be less than delay (#{delay} ms) + verifies_for (#{verifies_for} ms)!"
+    end
+    frames = args.fetch(:frames, [])
+    starting_frame = args.fetch(:starting_frame, 0)
+    priority = args.fetch(:priority, :normal)
+    report = args.fetch(:report, true)
+    execution_metric = args[:execution_metric]
+    log_every = args.fetch(:log_every, 1.sec)
+    min_log_every = (timeout / 100.0).round  # log a max of 100 frames
+    if log_every < min_log_every
+      logger.warn("Using `log_every': #{min_log_every} ms.")
+      log_every = min_log_every
+    end
+    next_log = log_every
+    start_time = args.fetch(:start_time, nil)
+    result = nil
+    if precise
+      # For a high-precision (HP) measurement, capture frames if necessary
+      if frames.empty?
+        cap = dut.capture_frames(timeout, :key => key)
+        frames = cap[:frames]
+        start_time = cap[:start_time]
+      end
+      raise 'Not enough images captured for analysis!' if frames.empty?
+    else
+      # For a non-high-precision evaluation, we just trigger the evaluation and start the clock
+      unless key.nil?
+        do_trigger(key)
+      end
+      start_time = Time.now
+      if delay > 0
+        sleep(delay / 1000.0)  # this is native sleep
+      end
+    end
+    i = starting_frame
+    i += 1 if with_last_frame  # start on the second frame
+    expected_now = expected.shift
+    verified = false
+    while true
+      logger.debug("Expected result: #{expected_now}")
+      skip = false
+      if precise
+        # For HP measurement, look at the next frame
+        frame_info = frames[i]
+        skip = frame_info.nil?
+        unless skip
+          now = frame_info[:capturedAt]
+          frame = [frame_info[:filename]]
+          if with_last_frame
+            frame << frames[i - 1][:filename]
+          end
+          result = block.call(*(frame + block_args))
+        end
+      else
+        # For non-HP evaluation, use the current screen image (implicit)
+        frame_info = nil
+        # TODO: We use the time of the request, rather than the time after the response, because the processing
+        # TODO: overhead is potentially much less. However, this could result in measurements that are under by a
+        # TODO: number of milliseconds. Change this to use the timestamp, when available, from the server response.
+        now = Time.now
+        result = block.call(*block_args)
+      end
+      if skip
+        verified_this_time = false
+      else
+        elapsed = test_case.get_time_delta(start_time, now)
+        found_str = now.strftime('%H:%M:%S.%N')
+        verified_this_time = verifies?(expected_now, result)
+      end
+      if verified_this_time
+        # Roi verifies, check if remaining criteria are met
+        verified_for ||= 0
+        last_verified ||= now
+        found_in_frame ||= frame_info
+        verified_for += test_case.get_time_delta(last_verified, now) * 1.sec
+        last_verified = now
+        verified = verified_for >= verifies_for
+      elsif !verified
+        # Roi does not verify, reset state
+        verified_for = nil
+        last_verified = nil
+        found_in_frame = nil
+      end
+      if verified && verified_this_time
+        if expected.empty?
+          # Roi verifies for the required duration and all transitions
+          msg = "Roi #{log_state} in #{elapsed} ms, Time=#{found_str}, #{info}"
+          if precise
+            # For HP measurement, save found frame
+            found_in_frame[:keep] = true
+            # Recalculate elapsed from matching frame
+            found_time = found_in_frame[:capturedAt]
+            found_i = frames.index(found_in_frame)
+            elapsed = test_case.get_time_delta(start_time, found_time)
+            found_str = found_time.strftime('%H:%M:%S.%N')
+            filename = found_in_frame[:filename]
+            msg += ", Frame=#{found_i}"
+            logger.roi(self, args.merge(:message => msg, :screen_image => filename))
+            if report
+              test_case.report_result(:start_time => start_time.to_f, :stop_time => found_time.to_f,
+                                      :execution_metric => execution_metric)
+            end
+            logger.duration(elapsed)
+          else
+            # Log result for evaluation
+            logger.roi(self, args.merge(:message => msg, :use_last_image => true))
+          end
+          # For measurements, the result is the time elapsed
+          if type == :measure
+            result = elapsed
+          elsif type == :verify
+            result = true
+          elsif type == :frame
+            result = found_i
+          end
+          break
+        end
+        expected_now = expected.shift
+      else
+        # Roi does not yet verify for the required duration
+        quit = precise ? i >= frames.size - 1 : elapsed >= timeout
+        if quit
+          # Set result for failure
+          if type == :measure
+            result = nil
+          elsif type == :verify
+            result = false
+          elsif type == :frame
+            result = -1
+          end
+          break
+        elsif elapsed > next_log
+          # Report screenshots at intervals
+          msg = "Roi not yet #{log_state} after #{elapsed.to_s} ms, #{info}, Time=#{found_str}"
+          if precise
+            msg += ", Frame=#{i}"
+            logger.roi(self, args.merge(:message => msg, :screen_image => frame_info[:filename]))
+            frame_info[:keep] = true
+          else
+            logger.roi(self, args.merge(:message => msg, :use_last_image => true))
+          end
+          next_log = elapsed + log_every
+        end
+      end
+      sleep(@priorities[priority])  # throttle CPU, this is native sleep
+      i += 1
+    end
+    result
+  end
+
+  # Internal: Triggers Roi evaluation.
+  def do_trigger(key, args={})
+    if args[:duts].nil?
+      dut.press_key(key.to_s, args.merge(:sleep_time => 0.ms))
+    else
+      threads = args[:duts].map do |d|
+        Thread.new { d.press_key(key.to_s, args.merge(:sleep_time => 0.ms)) }
+      end
+      threads.each { |thr| thr.join }
+    end
+  end
+
+end