capybara-screenshot-diff 1.10.3 → 1.12.0

data/lib/capybara/screenshot/diff/difference_finder.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "capybara/screenshot/diff/comparison"
+require "capybara/screenshot/diff/difference"
+
+module Capybara
+  module Screenshot
+    module Diff
+      # Analyzes image differences with configurable tolerance levels.
+      #
+      # This class implements the core comparison logic for detecting visual differences
+      # between images while accounting for various tolerances and optimizations.
+      #
+      # The comparison process follows these steps:
+      # 1. Dimension Check (Fastest)
+      #    - Compares image dimensions first for quick rejection
+      #    - Different dimensions always indicate a difference
+      #
+      # 2. Pixel Equality Check (Fast)
+      #    - Performs bitwise comparison if dimensions match
+      #    - Returns immediately if images are exactly identical
+      #
+      # 3. Tolerant Comparison (Slower)
+      #    - Only runs if quick checks don't determine equality
+      #    - Respects configured tolerances for color and shift differences
+      #    - Can ignore specific regions (skip_area)
+      #    - Considers anti-aliasing and sub-pixel rendering differences
+      #
+      # The class is designed to be stateless and thread-safe, with all configuration
+      # passed in through the constructor.
+      class DifferenceFinder
+        TOLERABLE_OPTIONS = [:tolerance, :color_distance_limit, :shift_distance_limit, :area_size_limit].freeze
+
+        attr_reader :driver, :options
+
+        # Creates a new DifferenceFinder instance.
+        #
+        # @param driver [Drivers::Base] The image processing driver to use.
+        #   Must implement the driver interface expected by DifferenceFinder.
+        # @param options [Hash] Configuration options for the comparison:
+        #   @option options [Numeric] :tolerance (0.001) Color tolerance threshold (0.0-1.0).
+        #   @option options [Numeric] :color_distance_limit Maximum allowed color distance.
+        #   @option options [Numeric] :shift_distance_limit Maximum allowed shift distance.
+        #   @option options [Numeric] :area_size_limit Maximum allowed difference area size.
+        #   @option options [Array<Array>] :skip_area Regions to exclude from comparison.
+        def initialize(driver, options)
+          @driver = driver
+          @options = options
+          @without_tolerable_options = (options.keys & TOLERABLE_OPTIONS).empty?
+        end
+
+        # Analyzes the comparison and determines if images are different.
+        #
+        # @param comparison [Comparison] The comparison object containing images to analyze.
+        # @param quick_mode [Boolean] When true, performs minimal checks and returns early.
+        #   In quick mode, returns [is_equal, difference] where:
+        #   - is_equal is true if images are considered equal
+        #   - difference is a Difference object or nil
+        #   When false, returns a Difference object directly.
+        # @return [Array, Difference] Result format depends on quick_mode parameter.
+        # @raise [ArgumentError] If the comparison object is invalid.
+        def call(comparison, quick_mode: true)
+          # Process the comparison and return result
+
+          # Handle dimension differences
+          unless driver.same_dimension?(comparison)
+            result = Difference.build_null(comparison, comparison.base_image_path, comparison.new_image_path, {different_dimensions: true})
+            return quick_mode ? [false, result] : result
+          end
+
+          # Handle identical pixels
+          if driver.same_pixels?(comparison)
+            result = Difference.build_null(comparison, comparison.base_image_path, comparison.new_image_path)
+            return quick_mode ? [true, result] : result
+          end
+
+          # Handle early return for non-tolerable options
+          if quick_mode && without_tolerable_options?
+            return [false, nil]
+          end
+
+          # Process difference region
+          region = driver.find_difference_region(comparison)
+
+          # Only create a proper difference object if we've completed the comparison
+          quick_mode ? [!region.different?, region] : region
+        end
+
+        private
+
+        def without_tolerable_options?
+          @without_tolerable_options
+        end
+      end
+    end
+  end
+end

data/lib/capybara/screenshot/diff/drivers/base_driver.rb

@@ -30,6 +30,10 @@ module Capybara
           def dimension(image)
             [width_for(image), height_for(image)]
           end
+
+          def supports?(feature)
+            respond_to?(feature)
+          end
         end
       end
     end

data/lib/capybara/screenshot/diff/drivers/chunky_png_driver.rb

@@ -24,10 +24,6 @@ module Capybara
             _load_images(old_bytes, new_bytes)
           end
 
-          def filter_image_with_median(_image)
-            raise NotImplementedError
-          end
-
           def add_black_box(image, _region)
             image
           end
@@ -217,22 +213,24 @@ module Capybara
 
             def color_distance_at(new_img, old_img, x, y, shift_distance_limit:)
               org_color = old_img[x, y]
-              if shift_distance_limit
-                start_x = [0, x - shift_distance_limit].max
-                end_x = [x + shift_distance_limit, new_img.width - 1].min
-                xs = (start_x..end_x).to_a
-                start_y = [0, y - shift_distance_limit].max
-                end_y = [y + shift_distance_limit, new_img.height - 1].min
-                ys = (start_y..end_y).to_a
-                new_pixels = xs.product(ys)
-
-                distances = new_pixels.map do |dx, dy|
-                  ChunkyPNG::Color.euclidean_distance_rgba(org_color, new_img[dx, dy])
+              unless shift_distance_limit
+                return ChunkyPNG::Color.euclidean_distance_rgba(org_color, new_img[x, y])
+              end
+
+              start_x = [0, x - shift_distance_limit].max
+              end_x = [x + shift_distance_limit, new_img.width - 1].min
+              start_y = [0, y - shift_distance_limit].max
+              end_y = [y + shift_distance_limit, new_img.height - 1].min
+
+              min_distance = Float::INFINITY
+              (start_y..end_y).each do |dy|
+                (start_x..end_x).each do |dx|
+                  distance = ChunkyPNG::Color.euclidean_distance_rgba(org_color, new_img[dx, dy])
+                  return 0 if distance == 0
+                  min_distance = distance if distance < min_distance
                 end
-                distances.min
-              else
-                ChunkyPNG::Color.euclidean_distance_rgba(org_color, new_img[x, y])
               end
+              min_distance
             end
 
             def shift_distance_at(new_img, old_img, x, y, color_distance_limit:)
@@ -254,10 +252,10 @@ module Capybara
                   if (x - shift_distance) >= 0 # left
                     ([0, top_row + 1].max..[y + shift_distance, new_img.height - 2].min)
                       .each do |dy|
-                      if color_matches(new_img, org_color, x - shift_distance, dy, color_distance_limit)
-                        return shift_distance
+                        if color_matches(new_img, org_color, x - shift_distance, dy, color_distance_limit)
+                          return shift_distance
+                        end
                       end
-                    end
                   else
                     bounds_breached += 1
                   end
@@ -273,10 +271,10 @@ module Capybara
                   if (x + shift_distance) < new_img.width # right
                     ([0, top_row + 1].max..[y + shift_distance, new_img.height - 2].min)
                       .each do |dy|
-                      if color_matches(new_img, org_color, x + shift_distance, dy, color_distance_limit)
-                        return shift_distance
+                        if color_matches(new_img, org_color, x + shift_distance, dy, color_distance_limit)
+                          return shift_distance
+                        end
                       end
-                    end
                   else
                     bounds_breached += 1
                   end

data/lib/capybara/screenshot/diff/drivers/vips_driver.rb

@@ -15,15 +15,18 @@ module Capybara
       # Compare two images and determine if they are equal, different, or within some comparison
       # range considering color values and difference area size.
       module Drivers
-        DEFAULT_HIGHLIGHT_COLOR = [255, 0, 0, 255].freeze
-
         class VipsDriver < BaseDriver
           def find_difference_region(comparison)
             new_image, base_image, options = comparison.new_image, comparison.base_image, comparison.options
 
-            diff_mask = VipsUtil.difference_mask(base_image, new_image, options[:color_distance_limit])
-            region = VipsUtil.difference_region_by(diff_mask)
-            region = nil if region && same_as?(region, base_image)
+            diff_mask = if options[:perceptual_threshold]
+              self.class.perceptual_difference_mask(base_image, new_image, options[:perceptual_threshold])
+            else
+              self.class.difference_mask(base_image, new_image, options[:color_distance_limit])
+            end
+            region = self.class.difference_region_by(diff_mask)
+            # TODO: schedule research when we got this case for VIPs
+            # region = nil if region && region_covers_entire_image?(region, base_image)
 
             result = Difference.new(region, {}, comparison)
 
@@ -40,7 +43,7 @@ module Capybara
           rescue Vips::Error => e
             warn(
               "[capybara-screenshot-diff] Crop has been failed for " \
-              "{ region: #{region.to_top_left_corner_coordinates.inspect}, image: #{dimension(i).join("x")} }"
+                "{ region: #{region.to_top_left_corner_coordinates.inspect}, image: #{dimension(i).join("x")} }"
             )
             raise e
           end
@@ -56,7 +59,7 @@ module Capybara
           end
 
           def difference_level(diff_mask, old_img, _region = nil)
-            VipsUtil.difference_area_size_by(diff_mask).to_f / image_area_size(old_img)
+            self.class.difference_area_size_by(diff_mask).to_f / image_area_size(old_img)
           end
 
           MAX_FILENAME_LENGTH = 200
@@ -89,10 +92,6 @@ module Capybara
             result
           end
 
-          def dimension(image)
-            [width_for(image), height_for(image)]
-          end
-
           def draw_rectangles(images, region, rgba, offset: 0)
             images.map do |image|
               image.draw_rect(rgba, region.left - offset, region.top - offset, region.width + (offset * 2), region.height + (offset * 2))
@@ -107,37 +106,51 @@ module Capybara
             base_image.composite2(new_image, :over)
           end
 
-          def highlight_mask(diff_mask, merged_image, color: DEFAULT_HIGHLIGHT_COLOR)
+          def highlight_mask(diff_mask, merged_image, color: CapybaraScreenshotDiff::RED_RGBA)
             diff_mask.ifthenelse(color, merged_image * 0.75)
           end
 
           private
 
-          def same_as?(region, base_image)
-            region.x.zero? &&
-              region.y.zero? &&
-              region.height == height_for(base_image) &&
-              region.width == width_for(base_image)
-          end
-
-          class VipsUtil
-            def self.difference_area(old_image, new_image, color_distance: 0)
-              difference_mask = difference_mask(new_image, old_image, color_distance)
-              difference_area_size_by(difference_mask)
+          class << self
+            def difference_area(old_image, new_image, color_distance: 0)
+              mask = difference_mask(new_image, old_image, color_distance)
+              difference_area_size_by(mask)
             end
 
-            def self.difference_area_size_by(difference_mask)
+            def difference_area_size_by(difference_mask)
               diff_mask = difference_mask == 0
               diff_mask.hist_find.to_a[0][0].max
             end
 
-            def self.difference_mask(base_image, new_image, color_distance = nil)
+            def difference_mask(base_image, new_image, color_distance = nil)
               result = (new_image - base_image).abs
-
               color_distance ? result > color_distance : result
             end
 
-            def self.difference_region_by(diff_mask)
+            def perceptual_difference_mask(base_image, new_image, threshold = 2.0)
+              color_diff = perceptual_color_diff(base_image, new_image) > threshold
+              alpha_diff = alpha_channel_diff(base_image, new_image)
+              alpha_diff ? (color_diff | alpha_diff) : color_diff
+            end
+
+            def perceptual_color_diff(base_image, new_image)
+              base_rgb = (base_image.bands > 3) ? base_image.extract_band(0, n: 3) : base_image
+              new_rgb = (new_image.bands > 3) ? new_image.extract_band(0, n: 3) : new_image
+              base_lab = base_rgb.colourspace(:lab)
+              new_lab = new_rgb.colourspace(:lab)
+              base_lab.dE00(new_lab)
+            rescue Vips::Error
+              base_lab.dE76(new_lab)
+            end
+
+            def alpha_channel_diff(base_image, new_image)
+              return unless base_image.bands > 3 && new_image.bands > 3
+
+              (base_image.extract_band(3) - new_image.extract_band(3)).abs > 0
+            end
+
+            def difference_region_by(diff_mask)
               columns, rows = diff_mask.bandor.project
 
               left = columns.profile[1].min

data/lib/capybara/screenshot/diff/image_compare.rb

@@ -1,17 +1,41 @@
 # frozen_string_literal: true
 
+require "pathname"
+require "fileutils"
+
 require "capybara/screenshot/diff/comparison"
+require "capybara/screenshot/diff/image_preprocessor"
+require "capybara/screenshot/diff/difference_finder"
+require "capybara/screenshot/diff/reporters/default"
 
 module Capybara
   module Screenshot
     module Diff
       LOADED_DRIVERS = {}
 
-      # Compare two image and determine if they are equal, different, or within some comparison
-      # range considering color values and difference area size.
+      # Handles comparison of two images with a focus on performance and accuracy.
+      #
+      # This class implements a multi-layered optimization strategy for image comparison:
+      #
+      # 1. Early File-based Checks (Fastest):
+      #    - Verifies both images exist (raises ArgumentError if not)
+      #    - Compares file sizes (different sizes → different images)
+      #    - Performs byte-by-byte comparison for identical files (exact match)
+      #
+      # 2. Quick Comparison (Fast):
+      #    - Compares image dimensions (different dimensions → different images)
+      #    - Performs pixel-by-pixel comparison if dimensions match
+      #
+      # 3. Detailed Analysis (Slower):
+      #    - Only performed if quick comparison finds differences
+      #    - Handles anti-aliasing, color tolerance, and shift detection
+      #    - Respects skip_area and other comparison parameters
+      #
+      # This layered approach ensures optimal performance by:
+      # - Using the fastest possible method for early rejection
+      # - Only performing expensive operations when absolutely necessary
+      # - Maintaining high accuracy for complex comparisons
       class ImageCompare
-        TOLERABLE_OPTIONS = [:tolerance, :color_distance_limit, :shift_distance_limit, :area_size_limit].freeze
-
         attr_reader :driver, :driver_options
         attr_reader :image_path, :base_image_path
         attr_reader :difference, :error_message
@@ -20,41 +44,48 @@ module Capybara
           @image_path = Pathname.new(image_path)
           @base_image_path = Pathname.new(base_image_path)
 
-          @driver_options = options.dup
+          ensure_files_exist!
 
+          @driver_options = options.freeze
           @driver = Drivers.for(@driver_options)
         end
 
-        # Compare the two image files and return `true` or `false` as quickly as possible.
-        # Return falsely if the old file does not exist or the image dimensions do not match.
+        # Performs a quick comparison of two image files.
+        #
+        # This method is optimized for speed and will return as soon as a difference is found.
+        # It's used for fast rejection before performing more expensive comparisons.
+        #
+        # @return [Boolean]
+        #   - `true` if images are exactly identical (byte-for-byte match)
+        #   - `false` if images are different or if a quick difference is detected
+        #
+        # @note This method will raise ArgumentError if either image file is missing.
         def quick_equal?
-          require_images_exists!
-
-          # NOTE: This is very fuzzy logic, but so far it's helps to support current performance.
-          return true if new_file_size == old_file_size
-
-          comparison = load_and_process_images
-
-          unless driver.same_dimension?(comparison)
-            self.difference = build_failed_difference(comparison, {different_dimensions: true})
-            return false
+          if base_image_path.size == image_path.size
+            return true if files_identical?(base_image_path, image_path)
           end
 
-          if driver.same_pixels?(comparison)
-            self.difference = build_no_difference(comparison)
-            return true
-          end
-
-          # NOTE: Could not make any difference to be tolerable, so skip and return as not equal.
-          return false if without_tolerable_options?
-
-          self.difference = driver.find_difference_region(comparison)
+          result, difference = find_difference(quick_mode: true)
+          self.difference = difference
+          result
+        end
 
-          !difference.different?
+        def ensure_files_exist!
+          raise ArgumentError, "There is no original (base) screenshot located at #{@base_image_path}" unless @base_image_path.exist?
+          raise ArgumentError, "There is no new screenshot located at #{@image_path}" unless @image_path.exist?
         end
 
-        # Compare the two image referenced by this object, and return `true` if they are different,
-        # and `false` if they are the same.
+        # Determines if the images are different according to the comparison rules.
+        #
+        # This method performs a full comparison if not already done, including any
+        # configured tolerances for color differences and shift distances.
+        #
+        # @return [Boolean]
+        #   - `true` if the images are different beyond configured tolerances
+        #   - `false` if the images are considered identical
+        #
+        # @see #processed
+        # @see DifferenceFinder
         def different?
           processed.difference.different?
         end
@@ -64,10 +95,7 @@ module Capybara
         end
 
         def reporter
-          @reporter ||= begin
-            current_difference = difference || build_no_difference(nil)
-            Capybara::Screenshot::Diff::Reporters::Default.new(current_difference)
-          end
+          @reporter ||= build_reporter
         end
 
         def processed?
@@ -75,122 +103,83 @@ module Capybara
         end
 
         def processed
-          self.difference = find_difference unless processed?
+          self.difference = find_difference(quick_mode: false) unless processed?
           @error_message ||= reporter.generate
           self
         end
 
         private
 
-        def find_difference
-          require_images_exists!
-
-          comparison = load_and_process_images
-
-          unless driver.same_dimension?(comparison)
-            return build_failed_difference(comparison, {different_dimensions: true})
-          end
-
-          if driver.same_pixels?(comparison)
-            build_no_difference(comparison)
-          else
-            driver.find_difference_region(comparison)
-          end
-        end
-
-        def require_images_exists!
-          raise ArgumentError, "There is no original (base) screenshot version to compare, located: #{base_image_path}" unless base_image_path.exist?
-          raise ArgumentError, "There is no new screenshot version to compare, located: #{image_path}" unless image_path.exist?
-        end
-
-        def difference=(new_difference)
-          @error_message = nil
-          @reporter = nil
-          @difference = new_difference
-        end
-
-        def image_files_exist?
-          @base_image_path.exist? && @image_path.exist?
+        def difference_finder
+          @difference_finder ||= DifferenceFinder.new(driver, driver_options)
         end
 
-        def without_tolerable_options?
-          (@driver_options.keys & TOLERABLE_OPTIONS).empty?
+        def load_images_and_build_comparison(base_path, new_path, options)
+          base_img, new_img = driver.load_images(base_path, new_path)
+          Comparison.new(new_img, base_img, options, driver, new_path, base_path)
         end
 
-        def build_failed_difference(comparison, failed_by)
-          Difference.new(
-            nil,
-            {difference_level: nil, max_color_distance: 0},
-            comparison,
-            failed_by
-          )
+        def image_preprocessor
+          @image_preprocessor ||= ImagePreprocessor.new(driver, driver_options)
         end
 
-        def load_and_process_images
-          images = driver.load_images(base_image_path, image_path)
-          base_image, new_image = preprocess_images(images)
-          Comparison.new(new_image, base_image, @driver_options, driver, image_path, base_image_path)
-        end
+        def find_difference(quick_mode: false)
+          # Validate images exist
+          return build_null_difference("missing_image") unless images_exist?
 
-        def skip_area
-          @driver_options[:skip_area]
-        end
-
-        def median_filter_window_size
-          @driver_options[:median_filter_window_size]
-        end
+          # Create comparison with preprocessed images
+          comparison = load_comparison(base_image_path, image_path, driver_options)
 
-        def preprocess_images(images)
-          images.map { |image| preprocess_image(image) }
+          # Use difference finder to analyze the comparison
+          difference_finder.call(comparison, quick_mode: quick_mode)
         end
 
-        def preprocess_image(image)
-          result = image
-
-          if skip_area
-            result = ignore_skipped_area(result)
-          end
-
-          if median_filter_window_size
-            if driver.is_a?(Drivers::VipsDriver)
-              result = blur_image_by(image, median_filter_window_size)
-            else
-              warn(
-                "[capybara-screenshot-diff] Median filter has been skipped for #{image_path} " \
-                  "because it is not supported by #{driver.class.name}"
-              )
-            end
-          end
-
-          result
-        end
-
-        def blur_image_by(image, size)
-          driver.filter_image_with_median(image, size)
+        def difference=(new_difference)
+          @error_message = nil
+          @reporter = nil
+          @difference = new_difference
         end
 
-        def ignore_skipped_area(image)
-          skip_area&.reduce(image) { |memo, region| driver.add_black_box(memo, region) }
+        def build_reporter
+          current_difference = difference || build_null_difference
+          Reporters::Default.new(current_difference)
         end
 
-        def old_file_size
-          base_image_path.size
+        # Loads and preprocesses images for detailed comparison.
+        #
+        # This method is responsible for:
+        # 1. Loading both images using the configured driver
+        # 2. Applying any necessary preprocessing (cropping, normalization)
+        # 3. Creating a Comparison object that holds the image data
+        #
+        # @param base_path [String,Pathname] Path to the baseline/reference image
+        # @param new_path [String,Pathname] Path to the new/candidate image
+        # @param options [Hash] Comparison options including:
+        #   - :crop [Array<Integer>] Optional crop area [x, y, width, height]
+        #   - :skip_area [Array<Array>] Areas to exclude from comparison
+        #   - :tolerance [Numeric] Color tolerance threshold
+        # @return [Comparison] Prepared comparison object ready for analysis
+        # @raise [ArgumentError] If image files are invalid or unreadable
+        def load_comparison(base_path, new_path, options)
+          comparison = load_images_and_build_comparison(base_path, new_path, options)
+          image_preprocessor.process_comparison(comparison)
         end
 
-        def new_file_size
-          image_path.size
+        def build_null_difference(failed_by = nil)
+          comparison = Comparison.new(nil, nil, driver_options, driver, image_path, base_image_path).freeze
+          Difference.build_null(comparison, base_image_path, image_path, failed_by)
         end
 
-        def build_no_difference(comparison = nil)
-          Difference.new(
-            nil,
-            {difference_level: nil, max_color_distance: 0},
-            comparison || build_comparison
-          ).freeze
+        # Check if both images exist
+        def images_exist?
+          base_image_path.exist? && image_path.exist?
         end
 
-        def build_comparison
-          Capybara::Screenshot::Diff::Comparison.new(nil, nil, driver_options, driver, image_path, base_image_path).freeze
+        # Check if files are identical by content
+        def files_identical?(file1, file2)
+          FileUtils.compare_file(file1, file2)
+        rescue SystemCallError, IOError
+          false
         end
       end
     end