diffux-core 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 80f32154fc059c048c223e8e2ca3646a802a8859
+  data.tar.gz: 7452b31f9989d95cbc3799d5bcacbe1e4dcd99b7
+SHA512:
+  metadata.gz: 240ad46905dfd690d5c3fcafc82eff833ba0c0128a3e786c08089dc40cf33b720efda4f9d971e70f2767eb975829d7a5971981983c5b5be2acaf352ae923a383
+  data.tar.gz: 60e6f38b354ad99791fad9c333ed52e9e038f7eee7ac823c3eebcd92ee84294dfae794436f64e0717babf168e896380dfd08ee66b92564ce23957fef2fd42a3c

data/bin/diffux-compare

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+
+require 'diffux_core'
+require 'oily_png'
+require 'optparse'
+
+options = {
+  outfile: 'diff.png'
+}
+OptionParser.new do |opts|
+  opts.banner = 'Usage: diffux-compare [options]'
+  opts.separator ''
+  opts.separator 'Options:'
+
+  opts.on('-b', '--before-image BEFORE_IMAGE',
+          'Specify a path to the before-image') do |img|
+    options[:before_image] = img
+  end
+  opts.on('-a', '--after-image AFTER_IMAGE',
+          'Specify a path to the after-image') do |img|
+    options[:after_image] = img
+  end
+
+  opts.on('-o', '--outfile OUTFILE',
+          'Specify where the diff image will be saved (if needed)') do |f|
+    options[:outfile] = f
+  end
+
+  opts.on_tail('-h', '--help', 'Show this message') do
+    puts opts
+    exit
+  end
+end.parse!(ARGV)
+
+help = '(use `diffux-compare -h` to see options)'
+unless options[:before_image]
+  puts "Missing BEFORE_IMAGE #{help}"
+  exit 1
+end
+unless options[:after_image]
+  puts "Missing AFTER_IMAGE #{help}"
+  exit 1
+end
+
+comparison = Diffux::SnapshotComparer.new(
+  ChunkyPNG::Image.from_file(options[:before_image]),
+  ChunkyPNG::Image.from_file(options[:after_image]),
+).compare!
+
+if img = comparison[:diff_image]
+  img.save(options[:outfile])
+  puts "DIFF: #{comparison[:diff_in_percent]}%"
+  exit 10
+end

data/bin/diffux-snapshot

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+
+require 'diffux_core'
+require 'optparse'
+
+options = {
+  width: 320
+}
+OptionParser.new do |opts|
+  opts.banner = 'Usage: diffux-snapshot [options]'
+  opts.separator ''
+  opts.separator 'Options:'
+
+  opts.on('-u', '--url URL',
+          'Set a URL to snapshot') do |url|
+    options[:url] = url
+  end
+
+  opts.on('-o', '--outfile OUTFILE',
+          'Specify where the snapshot will be saved') do |f|
+    options[:outfile] = f
+  end
+
+  opts.on('-w', '--width WIDTH', Integer,
+          'Set the width of the screen (defaults to 320)') do |w|
+    options[:width] = w
+  end
+
+  opts.on('-a', '--useragent USERAGENT',
+          'Set a useragent header when loading the url') do |ua|
+    options[:useragent] = ua
+  end
+
+  opts.on_tail('-h', '--help', 'Show this message') do
+    puts opts
+    exit
+  end
+end.parse!(ARGV)
+
+help = '(use `diffux-snapshot -h` to see options)'
+unless options[:url]
+  puts "Missing url #{help}"
+  exit 1
+end
+unless options[:outfile]
+  puts "Missing outfile #{help}"
+  exit 1
+end
+
+snapshot = Diffux::Snapshotter.new(
+  viewport_width: options[:width],
+  user_agent:     options[:useragent],
+  outfile:        options[:outfile],
+  url:            options[:url],
+).take_snapshot!
+

data/lib/diffux_core.rb

@@ -0,0 +1,3 @@
+require 'diffux_core/version'
+require 'diffux_core/snapshotter'
+require 'diffux_core/snapshot_comparer'

data/lib/diffux_core/diff_cluster_finder.rb

@@ -0,0 +1,47 @@
+require 'set'
+module Diffux
+  # This class finds clusters in a diff. A cluster is defined as rows that are
+  # different, and are closer than DIFF_ROW_THRESHOLD pixels to its neighboring
+  # diff row.
+  class DiffClusterFinder
+    MAXIMUM_ADJACENCY_GAP = 5
+
+    # @param number_of_rows [Numeric]
+    def initialize(number_of_rows)
+      @number_of_rows = number_of_rows
+      @rows_with_diff = SortedSet.new
+    end
+
+    # Tell the DiffClusterFinder about a row that is different.
+    #
+    # @param row [Numeric]
+    def row_is_different(row)
+      @rows_with_diff.add row
+    end
+
+    # @return [Float] the percent of rows that are different
+    def percent_of_rows_different
+      @rows_with_diff.length.to_f / @number_of_rows * 100
+    end
+
+    # Calculate clusters from diff-rows that are close to each other.
+    #
+    # @return [Array<Hash>] a list of clusters modeled as hashes:
+    #   `{ start: x, finish: y }`
+    def clusters
+      results = []
+      @rows_with_diff.each do |row|
+        current = results.last
+        if !current || current[:finish] + MAXIMUM_ADJACENCY_GAP < row
+          results << {
+            start:  row,
+            finish: row,
+          }
+        else
+          current[:finish] = row
+        end
+      end
+      results
+    end
+  end
+end

data/lib/diffux_core/snapshot_comparer.rb

@@ -0,0 +1,72 @@
+require 'oily_png'
+require 'diff-lcs'
+require_relative 'diff_cluster_finder'
+
+module Diffux
+  # This class is responsible for comparing two Snapshots and generating a diff.
+  class SnapshotComparer
+    # @param png_before [ChunkyPNG::Image]
+    # @param png_after  [ChunkyPNG::Image]
+    def initialize(png_before, png_after)
+      @png_after  = png_after
+      @png_before = png_before
+    end
+
+    # @return [Hash]
+    def compare!
+      sdiff      = Diff::LCS.sdiff(to_array_of_arrays(@png_before),
+                                   to_array_of_arrays(@png_after))
+      cluster_finder  = DiffClusterFinder.new(sdiff.size)
+      sprite, all_comparisons = initialize_comparison_images(
+        [@png_after.width, @png_before.width].max, sdiff.size)
+
+      sdiff.each_with_index do |row, y|
+        # each row is a Diff::LCS::ContextChange instance
+        all_comparisons.each { |image| image.render_row(y, row) }
+        cluster_finder.row_is_different(y) unless row.unchanged?
+      end
+
+      percent_changed = cluster_finder.percent_of_rows_different
+      {
+        diff_in_percent: percent_changed,
+        diff_image:      (sprite if percent_changed > 0),
+        diff_clusters:   cluster_finder.clusters,
+      }
+    end
+
+    private
+
+    # @param [ChunkyPNG::Image]
+    # @return [Array<Array<Integer>>]
+    def to_array_of_arrays(chunky_png)
+      array_of_arrays = []
+      chunky_png.height.times do |y|
+        array_of_arrays << chunky_png.row(y)
+      end
+      array_of_arrays
+    end
+
+    # @param canvas [ChunkyPNG::Image] The output image to draw pixels on
+    # @return [Array<SnapshotComparisonImage>]
+    def initialize_comparison_images(width, height)
+      gutter_width = SnapshotComparisonImage::Gutter::WIDTH
+      total_width = (width * 3) + (gutter_width * 3)
+
+      sprite = ChunkyPNG::Image.new(total_width, height)
+      offset, comparison_images = 0, []
+      comparison_images << SnapshotComparisonImage::Gutter.new(offset, sprite)
+      offset += gutter_width
+      comparison_images << SnapshotComparisonImage::Before.new(offset, sprite)
+      offset += width
+      comparison_images << SnapshotComparisonImage::Gutter.new(offset, sprite)
+      offset += gutter_width
+      comparison_images << SnapshotComparisonImage::Overlayed.new(offset, sprite)
+      offset += width
+      comparison_images << SnapshotComparisonImage::Gutter.new(offset, sprite)
+      offset += gutter_width
+      comparison_images << SnapshotComparisonImage::After.new(offset, sprite)
+
+      [sprite, comparison_images]
+    end
+  end
+end

data/lib/diffux_core/snapshot_comparison_image/after.rb

@@ -0,0 +1,21 @@
+module Diffux
+  module SnapshotComparisonImage
+    # This subclass of `SnapshotComparisonImage` knows how to draw the
+    # representation of the "after" image.
+    class After < SnapshotComparisonImage::Base
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_changed_row(y, row)
+        render_added_row(y, row)
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_added_row(y, row)
+        row.new_element.each_with_index do |pixel_after, x|
+          render_pixel(x, y, pixel_after)
+        end
+      end
+    end
+  end
+end

data/lib/diffux_core/snapshot_comparison_image/base.rb

@@ -0,0 +1,115 @@
+require 'chunky_png'
+module Diffux
+  module SnapshotComparisonImage
+    # This model represents a "comparison image". Basically it's just a wrapper
+    # around a ChunkyPNG image with some nice methods to make life easier in the
+    # world of diffs.
+    #
+    # This model is never persisted.
+    class Base
+      include ChunkyPNG::Color
+
+      BASE_OPACITY    = 0.1
+      BASE_ALPHA      = (255 * BASE_OPACITY).round
+      BASE_DIFF_ALPHA = BASE_ALPHA * 2
+
+      MAGENTA = ChunkyPNG::Color.from_hex '#b33682'
+      RED     = ChunkyPNG::Color.from_hex '#dc322f'
+      GREEN   = ChunkyPNG::Color.from_hex '#859900'
+
+      # @param offset [Integer] the x-offset that this comparison image should
+      #   use when rendering on the canvas image.
+      # @param canvas [ChunkyPNG::Image] The canvas image to render pixels on.
+      def initialize(offset, canvas)
+        @offset = offset
+        @canvas = canvas
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_row(y, row)
+        if row.unchanged?
+          render_unchanged_row(y, row)
+        elsif row.deleting?
+          render_deleted_row(y, row)
+        elsif row.adding?
+          render_added_row(y, row)
+        else # changing?
+          render_changed_row(y, row)
+        end
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_unchanged_row(y, row)
+        row.new_element.each_with_index do |pixel, x|
+          # Render the unchanged pixel as-is
+          render_pixel(x, y, pixel)
+        end
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_changed_row(y, row)
+        # no default implementation
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_added_row(y, row)
+        # no default implementation
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_deleted_row(y, row)
+        # no default implementation
+      end
+
+      # Could be simplified as ChunkyPNG::Color::MAX * 2, but this format mirrors
+      # the math in #pixel_diff_score
+      MAX_EUCLIDEAN_DISTANCE = Math.sqrt(ChunkyPNG::Color::MAX**2 * 4)
+
+      # Compute a score that represents the difference between 2 pixels
+      #
+      # This method simply takes the Euclidean distance between the RGBA channels
+      # of 2 colors over the maximum possible Euclidean distance. This gives us a
+      # percentage of how different the two colors are.
+      #
+      # Although it would be more perceptually accurate to calculate a proper
+      # Delta E in Lab colorspace, we probably don't need perceptual accuracy for
+      # this application, and it is nice to avoid the overhead of converting RGBA
+      # to Lab.
+      #
+      # @param pixel_after [Integer]
+      # @param pixel_before [Integer]
+      # @return [Float] number between 0 and 1 where 1 is completely different
+      #   and 0 is no difference
+      def pixel_diff_score(pixel_after, pixel_before)
+        Math.sqrt(
+          (r(pixel_after) - r(pixel_before))**2 +
+          (g(pixel_after) - g(pixel_before))**2 +
+          (b(pixel_after) - b(pixel_before))**2 +
+          (a(pixel_after) - a(pixel_before))**2
+        ) / MAX_EUCLIDEAN_DISTANCE
+      end
+
+      # @param diff_score [Float]
+      # @return [Integer] a number between 0 and 255 that represents the alpha
+      #   channel of of the difference
+      def diff_alpha(diff_score)
+        (BASE_DIFF_ALPHA + ((255 - BASE_DIFF_ALPHA) * diff_score)).round
+      end
+
+      # Renders a pixel on the specified x and y position. Uses the offset that
+      # the comparison image has been configured with.
+      #
+      # @param x [Integer]
+      # @param y [Integer]
+      # @param pixel [Integer]
+      def render_pixel(x, y, pixel)
+        @canvas.set_pixel(x + @offset, y, pixel)
+      end
+    end
+  end
+end

data/lib/diffux_core/snapshot_comparison_image/before.rb

@@ -0,0 +1,21 @@
+module Diffux
+  module SnapshotComparisonImage
+    # This subclass of `SnapshotComparisonImage` knows how to draw the
+    # representation of the "before" image.
+    class Before < SnapshotComparisonImage::Base
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_changed_row(y, row)
+        render_deleted_row(y, row)
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_deleted_row(y, row)
+        row.old_element.each_with_index do |pixel_before, x|
+          render_pixel(x, y, pixel_before)
+        end
+      end
+    end
+  end
+end

data/lib/diffux_core/snapshot_comparison_image/gutter.rb

@@ -0,0 +1,34 @@
+module Diffux
+  module SnapshotComparisonImage
+    # This class renders a gutter-column with a color representing the type of
+    # change that has happened.
+    class Gutter < SnapshotComparisonImage::Base
+      WIDTH = 10
+      GRAY  = ChunkyPNG::Color.from_hex '#cccccc'
+
+      def render_row(y, row)
+        WIDTH.times do |x|
+          render_pixel(x, y, gutter_color(row))
+        end
+        # render a two-pixel empty column
+        2.times do |x|
+          render_pixel(WIDTH - 1 - x, y, WHITE)
+        end
+      end
+
+      private
+
+      def gutter_color(row)
+        if row.unchanged?
+          WHITE
+        elsif row.deleting?
+          RED
+        elsif row.adding?
+          GREEN
+        else # changed?
+          GRAY
+        end
+      end
+    end
+  end
+end

data/lib/diffux_core/snapshot_comparison_image/overlayed.rb

@@ -0,0 +1,88 @@
+module Diffux
+  module SnapshotComparisonImage
+    # This subclass of `SnapshotComparisonImage` knows how to overlay the
+    # after-image on top of the before-image, and render the difference in a
+    # scaled magenta color.
+    class Overlayed < SnapshotComparisonImage::Base
+      WHITE_OVERLAY = ChunkyPNG::Color.fade(WHITE, 1 - BASE_ALPHA)
+
+      # @param offset [Integer]
+      # @param canvas [ChunkyPNG::Image]
+      # @see SnapshotComparisonImage::Base
+      def initialize(offset, canvas)
+        @diff_pixels  = {}
+        @faded_pixels = {}
+        super
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_unchanged_row(y, row)
+        # Render translucent original pixels
+        row.new_element.each_with_index do |pixel, x|
+          render_faded_pixel(x, y, pixel)
+        end
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_deleted_row(y, row)
+        row.old_element.each_with_index do |pixel_before, x|
+          render_faded_magenta_pixel(TRANSPARENT, pixel_before, x, y)
+        end
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_added_row(y, row)
+        row.new_element.each_with_index do |pixel_after, x|
+          render_faded_magenta_pixel(pixel_after, TRANSPARENT, x, y)
+        end
+      end
+
+      # @param y [Integer]
+      # @param row [Diff::LCS:ContextChange]
+      def render_changed_row(y, row)
+        row.old_element.zip(row.new_element).each_with_index do |pixels, x|
+          pixel_before, pixel_after = pixels
+          render_faded_magenta_pixel(
+            pixel_after  || TRANSPARENT,
+            pixel_before || TRANSPARENT,
+            x, y)
+        end
+      end
+
+      private
+
+      # @param pixel_after [Integer]
+      # @param pixel_before [Integer]
+      # @param x [Integer]
+      # @param y [Integer]
+      def render_faded_magenta_pixel(pixel_after, pixel_before, x, y)
+        score = pixel_diff_score(pixel_after, pixel_before)
+        if score > 0
+          render_diff_pixel(x, y, score)
+        else
+          render_faded_pixel(x, y, pixel_after)
+        end
+      end
+
+      # @param x [Integer]
+      # @param y [Integer]
+      # @param score [Float]
+      def render_diff_pixel(x, y, score)
+        @diff_pixels[score] ||= compose_quick(fade(MAGENTA, diff_alpha(score)),
+                                              WHITE)
+        render_pixel(x, y, @diff_pixels[score])
+      end
+
+      # @param x [Integer]
+      # @param y [Integer]
+      # @param pixel [Integer]
+      def render_faded_pixel(x, y, pixel)
+        @faded_pixels[pixel] ||= compose_quick(WHITE_OVERLAY, pixel)
+        render_pixel(x, y, @faded_pixels[pixel])
+      end
+    end
+  end
+end

data/lib/diffux_core/snapshotter.rb

@@ -0,0 +1,66 @@
+require 'phantomjs'
+require 'json'
+%w(base gutter before after overlayed).each do |type|
+  require_relative "snapshot_comparison_image/#{type}"
+end
+module Diffux
+  # Snapshotter is responsible for delegating to PhantomJS to take the snapshot
+  # for a given URL and viewoprt, and then saving that snapshot to a file and
+  # storing any metadata on the Snapshot object.
+  class Snapshotter
+    SCRIPT_PATH = File.join(File.dirname(__FILE__), 'script/take-snapshot.js').to_s
+
+    # @param url [String} the URL to snapshot
+    # @param viewport_width [Integer] the width of the screen used when
+    #   snapshotting
+    # @param outfile [File] where to store the snapshot PNG.
+    # @param user_agent [String] an optional useragent string to used when
+    #   requesting the page.
+    def initialize(url:     raise, viewport_width: raise,
+                   outfile: raise, user_agent: nil)
+      @viewport_width = viewport_width
+      @user_agent     = user_agent
+      @outfile        = outfile
+      @url            = url
+    end
+
+    # Takes a snapshot of the URL and saves it in the out_file as a PNG image.
+    #
+    # @return [Hash] a hash containing the following keys:
+    #   title [String] the <title> of the page being snapshotted
+    #   log   [String] a log of events happened during the snapshotting process
+    def take_snapshot!
+      result = {}
+      opts = {
+        address: @url,
+        outfile: @outfile,
+        viewportSize: {
+          width:  @viewport_width,
+          height: @viewport_width,
+        },
+      }
+      opts[:userAgent] = @user_agent if @user_agent
+
+      run_phantomjs(opts) do |line|
+        begin
+          result = JSON.parse line, symbolize_names: true
+        rescue JSON::ParserError
+          # We only expect a single line of JSON to be output by our snapshot
+          # script. If something else is happening, it is likely a JavaScript
+          # error on the page and we should just forget about it and move on
+          # with our lives.
+        end
+      end
+      result
+    end
+
+    private
+
+    def run_phantomjs(options)
+      Phantomjs.run('--ignore-ssl-errors=true',
+                    SCRIPT_PATH, options.to_json) do |line|
+        yield line
+      end
+    end
+  end
+end

data/lib/diffux_core/version.rb

@@ -0,0 +1,4 @@
+# Defines the gem version.
+module DiffuxCore
+  VERSION = '0.0.1'
+end

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: diffux-core
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Joe Lencioni
+- Henric Trotzig
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-04-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: oily_png
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.1
+- !ruby/object:Gem::Dependency
+  name: phantomjs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.9.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.9.2.1
+- !ruby/object:Gem::Dependency
+  name: diff-lcs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.5
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.14.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.14.1
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+description: Tools for taking and comparing responsive website snapshots
+email:
+- joe.lencioni@causes.com
+- henric.trotzig@causes.com
+executables:
+- diffux-snapshot
+- diffux-compare
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/diffux-compare
+- bin/diffux-snapshot
+- lib/diffux_core.rb
+- lib/diffux_core/diff_cluster_finder.rb
+- lib/diffux_core/snapshot_comparer.rb
+- lib/diffux_core/snapshot_comparison_image/after.rb
+- lib/diffux_core/snapshot_comparison_image/base.rb
+- lib/diffux_core/snapshot_comparison_image/before.rb
+- lib/diffux_core/snapshot_comparison_image/gutter.rb
+- lib/diffux_core/snapshot_comparison_image/overlayed.rb
+- lib/diffux_core/snapshotter.rb
+- lib/diffux_core/version.rb
+homepage: 
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.0
+signing_key: 
+specification_version: 4
+summary: Diffux Core
+test_files: []