sprite-factory-custom 1.6.0

data/lib/sprite_factory/layout/packed.rb

@@ -0,0 +1,118 @@
+module SpriteFactory
+  module Layout
+    module Packed
+
+      #------------------------------------------------------------------------
+
+      def self.layout(images, options = {})
+
+        raise NotImplementedError, ":packed layout does not support fixed :width/:height option" if options[:width] || options[:height]
+
+        return { :width => 0, :height => 0 } if images.empty?
+
+        hpadding = options[:hpadding] || 0
+        vpadding = options[:vpadding] || 0
+        hmargin  = options[:hmargin]  || 0
+        vmargin  = options[:vmargin]  || 0
+
+        images.each do |i|
+          i[:w] = i[:width]  + (2*hpadding) + (2*hmargin)
+          i[:h] = i[:height] + (2*vpadding) + (2*vmargin)
+        end
+
+        images.sort! do |a,b|
+          diff = [b[:w], b[:h]].max <=> [a[:w], a[:h]].max
+          diff = [b[:w], b[:h]].min <=> [a[:w], a[:h]].min if diff.zero?
+          diff = b[:h] <=> a[:h] if diff.zero?
+          diff = b[:w]  <=> a[:w]  if diff.zero?
+          diff
+        end
+
+        root = { :x => 0, :y => 0, :w => images[0][:w], :h => images[0][:h] }
+
+        images.each do |i|
+          if (node = findNode(root, i[:w], i[:h]))
+            placeImage(i, node, hpadding, vpadding, hmargin, vmargin)
+            splitNode(node, i[:w], i[:h])
+          else
+            root = grow(root, i[:w], i[:h])
+            redo
+          end
+        end
+
+        { :width => root[:w], :height => root[:h] }
+
+      end
+
+      def self.placeImage(image, node, hpadding, vpadding, hmargin, vmargin)
+        image[:cssx] = node[:x] + hmargin
+        image[:cssy] = node[:y] + vmargin
+        image[:cssw] = image[:width]  + (2*hpadding)
+        image[:cssh] = image[:height] + (2*vpadding)
+        image[:x]    = image[:cssx] + hpadding 
+        image[:y]    = image[:cssy] + vpadding
+      end
+
+      def self.findNode(root, w, h)
+        if root[:used]
+          findNode(root[:right], w, h) || findNode(root[:down], w, h)
+        elsif (w <= root[:w]) && (h <= root[:h])
+          root
+        end
+      end
+
+      def self.splitNode(node, w, h)
+        node[:used]  = true
+        node[:down]  = { :x => node[:x],     :y => node[:y] + h, :w => node[:w],     :h => node[:h] - h }
+        node[:right] = { :x => node[:x] + w, :y => node[:y],     :w => node[:w] - w, :h => h            }
+      end
+
+      def self.grow(root, w, h)
+
+        canGrowDown  = (w <= root[:w])
+        canGrowRight = (h <= root[:h])
+
+        shouldGrowRight = canGrowRight && (root[:h] >= (root[:w] + w))
+        shouldGrowDown  = canGrowDown  && (root[:w] >= (root[:h] + h))
+
+        if shouldGrowRight
+          growRight(root, w, h)
+        elsif shouldGrowDown
+          growDown(root, w, h)
+        elsif canGrowRight
+          growRight(root, w, h)
+        elsif canGrowDown
+          growDown(root, w, h)
+        else
+          raise RuntimeError, "can't fit #{w}x#{h} block into root #{root[:w]}x#{root[:h]} - this should not happen if images are pre-sorted correctly"
+        end
+
+      end
+
+      def self.growRight(root, w, h)
+        return {
+          :used  => true,
+          :x     => 0,
+          :y     => 0,
+          :w     => root[:w] + w,
+          :h     => root[:h],
+          :down  => root,
+          :right => { :x => root[:w], :y => 0, :w => w, :h => root[:h] }
+        }
+      end
+
+      def self.growDown(root, w, h)
+        return {
+          :used  => true,
+          :x     => 0,
+          :y     => 0,
+          :w     => root[:w],
+          :h     => root[:h] + h,
+          :down  => { :x => 0, :y => root[:h], :w => root[:w], :h => h },
+          :right => root
+        }
+      end
+
+      end # module Packed
+  end # module Layout
+end # module SpriteFactory

data/lib/sprite_factory/layout/vertical.rb

@@ -0,0 +1,44 @@
+module SpriteFactory
+  module Layout
+    module Vertical
+
+      def self.layout(images, options = {})
+        width     = options[:width]
+        height    = options[:height]
+        hpadding  = options[:hpadding] || 0
+        vpadding  = options[:vpadding] || 0
+        hmargin   = options[:hmargin]  || 0
+        vmargin   = options[:vmargin]  || 0
+        max_width = width || (2 * (hpadding + hmargin) + images.map{|i| i[:width]}.max)
+        y = 0
+        images.each do |i|
+
+          if width
+            i[:cssw] = width
+            i[:cssx] = 0
+            i[:x]    = 0 + (width - i[:width]) / 2
+          else
+            i[:cssw] = i[:width]  + (2 * hpadding)  # image width plus padding
+            i[:cssx] = (max_width - i[:cssw]) / 2   # centered horizontally
+            i[:x]    = i[:cssx] + hpadding          # image drawn offset to account for padding
+          end
+
+          if height
+            i[:cssh] = height
+            i[:cssy] = y
+            i[:y]    = y + (height - i[:height]) / 2
+          else
+            i[:cssh] = i[:height] + (2 * vpadding)   # image height plus padding
+            i[:cssy] = y + vmargin                   # anchored at y
+            i[:y]    = i[:cssy] + vpadding           # image drawn offset to account for padding
+          end
+
+          y += i[:cssh] + 2 * vmargin
+
+        end
+        { :width => max_width, :height => y }
+      end
+
+    end
+  end
+end

data/lib/sprite_factory/library/chunky_png.rb

@@ -0,0 +1,31 @@
+require 'chunky_png'
+
+module SpriteFactory
+  module Library
+    module ChunkyPng
+
+      VALID_EXTENSIONS = :png
+
+      def self.load(files)
+        files.map do |filename|
+          image = ChunkyPNG::Image.from_file(filename)
+          {
+            :filename => filename,
+            :image    => image,
+            :width    => image.width,
+            :height   => image.height
+          }
+        end
+      end
+
+      def self.create(filename, images, width, height)
+        target = ChunkyPNG::Image.new(width, height, ChunkyPNG::Color::TRANSPARENT)
+        images.each do |image|
+          target.compose!(image[:image], image[:x], image[:y])
+        end
+        target.save(filename)
+      end
+
+    end # module ChunkyPng
+  end # module Library
+end # module SpriteFactory

data/lib/sprite_factory/library/image_magick.rb

@@ -0,0 +1,74 @@
+module SpriteFactory
+  module Library
+    module ImageMagick
+
+      # Represents an error from an underlying ImageMagick call
+      class Error < RuntimeError
+        attr_reader :command
+        attr_reader :args
+        attr_reader :output
+        
+        def initialize(msg, command, args, output)
+          super(msg)
+          @command = command
+          @args = args
+          @output = output
+        end
+      end
+
+      VALID_EXTENSIONS = [:png, :jpg, :jpeg, :gif, :ico]
+
+      def self.load(files)
+        files.map do |filename|
+          path = "#{filename}[0]"   # layer 0
+          output = run("identify", ['-format', '%wx%h', path])
+          
+          width, height = output.chomp.split(/x/).map(&:to_i)
+          {
+            :filename => filename,
+            :path     => path,
+            :width    => width,
+            :height   => height
+          }
+        end
+      end
+
+      def self.create(filename, images, width, height)
+        # we want to invoke:
+        # convert -size #{width}x#{height} xc:none
+        #   #{input} -geometry +#{x}+#{y} -composite
+        # #{output}
+        
+        args = ["-size", "#{width}x#{height}", "xc:none"]
+        images.each do |image|
+          args +=  [image[:path], "-geometry", "+#{image[:x]}+#{image[:y]}", "-composite"]
+        end
+        args << filename
+        
+        run("convert", args)
+        true
+      end
+      
+      protected
+      def self.run(command, args)
+        full_command = [command] + args.map(&:to_s)
+        
+        r, w = IO.pipe
+        pid = Process.spawn(*full_command, {[:out, :err] => w})
+        
+        w.close
+        output = r.read
+        
+        Process.waitpid(pid)
+        success = $?.exitstatus == 0 ? true : false
+        
+        if !success
+          raise Error.new("error running `#{command}` (check $!.args/$!.output for more information)", command, args, output)
+        end
+        
+        output
+      end
+      
+    end # module ImageMagick
+  end # module Library
+end # module SpriteFactory

data/lib/sprite_factory/library/rmagick.rb

@@ -0,0 +1,32 @@
+require 'RMagick'
+
+module SpriteFactory
+  module Library
+    module RMagick
+
+      VALID_EXTENSIONS = [:png, :jpg, :jpeg, :gif, :ico]
+
+      def self.load(files)
+        files.map do |filename|
+          image = Magick::Image.read(filename)[0]
+          {
+            :filename => filename,
+            :image    => image,
+            :width    => image.columns,
+            :height   => image.rows
+          }
+        end
+      end
+
+      def self.create(filename, images, width, height)
+        target = Magick::Image.new(width,height)
+        target.opacity = Magick::MaxRGB
+        images.each do |image|
+          target.composite!(image[:image], image[:x], image[:y], Magick::SrcOverCompositeOp)
+        end
+        target.write(filename)
+      end
+
+    end # module RMagick
+  end # module Library
+end # module SpriteFactory

data/lib/sprite_factory/runner.rb

@@ -0,0 +1,287 @@
+require 'pathname'
+require 'fileutils'
+
+module SpriteFactory
+  class Runner
+
+    #----------------------------------------------------------------------------
+
+    PSEUDO_CLASS_ORDER = [nil, ':link', ':visited', ':focus', ':hover', ':active'] # TODO: allow caller to specify this order ?
+
+    #----------------------------------------------------------------------------
+
+    attr :input
+    attr :config
+
+    def initialize(input, config = {})
+      @input  = input.to_s[-1] == "/" ? input[0...-1] : input # gracefully ignore trailing slash on input directory name
+      @config = config
+      @config[:style]      ||= SpriteFactory.style    || :css
+      @config[:layout]     ||= SpriteFactory.layout   || :horizontal
+      @config[:library]    ||= SpriteFactory.library  || :rmagick
+      @config[:selector]   ||= SpriteFactory.selector || 'img.'
+      @config[:cssurl]     ||= SpriteFactory.cssurl
+      @config[:report]     ||= SpriteFactory.report
+      @config[:pngcrush]   ||= SpriteFactory.pngcrush
+      @config[:nocomments] ||= SpriteFactory.nocomments
+    end
+
+    #----------------------------------------------------------------------------
+
+    def run!(&block)
+
+      raise RuntimeError, "unknown layout #{layout_name}"     if !Layout.respond_to?(layout_name)
+      raise RuntimeError, "unknown style #{style_name}"       if !Style.respond_to?(style_name)
+      raise RuntimeError, "unknown library #{library_name}"   if !Library.respond_to?(library_name)
+
+      raise RuntimeError, "input must be a single directory"  if input.nil?  || input.to_s.empty? || !File.directory?(input)
+      raise RuntimeError, "no image files found"              if image_files.empty?
+      raise RuntimeError, "no output file specified"          if output.to_s.empty?
+      raise RuntimeError, "no output image file specified"    if output_image_file.to_s.empty?
+      raise RuntimeError, "no output style file specified"    if output_style_file.to_s.empty?
+
+      raise RuntimeError, "set :width for fixed width, or :hpadding for horizontal padding, but not both." if width  && !hpadding.zero?
+      raise RuntimeError, "set :height for fixed height, or :vpadding for vertical padding, but not both." if height && !vpadding.zero?
+      raise RuntimeError, "set :width for fixed width, or :hmargin for horizontal margin, but not both." if width  && !hmargin.zero?
+      raise RuntimeError, "set :height for fixed height, or :vmargin for vertical margin, but not both." if height && !hmargin.zero?
+
+      raise RuntimeError, "The legacy :csspath attribute is no longer supported, please use :cssurl instead (see README)" unless @config[:csspath].nil?
+
+      images = load_images
+      max    = layout_images(images)
+      header = summary(images, max)
+
+      report(header)
+
+      css = []
+      css << style_comment(header) unless nocomments?                       # header comment
+      css << style(selector, css_url, images, &block)                       # generated styles
+      css << IO.read(custom_style_file) if File.exists?(custom_style_file)  # custom styles
+      css = css.join("\n")
+
+      create_sprite(images, max[:width], max[:height])
+
+      unless nocss?
+        css_file = File.open(output_style_file, "w+")
+        css_file.puts css
+        css_file.close
+      end
+
+      if config[:return] == :images
+        images # if caller explicitly asked for detailed images hash instead of generated CSS
+      else
+        css    # otherwise, default is to return the generated CSS to caller in string form
+      end
+
+    end
+
+    #----------------------------------------------------------------------------
+
+    private
+
+    def selector
+      config[:selector]
+    end
+
+    def style_name
+      config[:style]
+    end
+
+    def custom_styles
+      config[:custom_styles]
+    end
+
+    def layout_name
+      config[:layout]
+    end
+
+    def library_name
+      config[:library]
+    end
+
+    def hpadding
+      config[:hpadding] || config[:padding] || 0
+    end
+
+    def vpadding
+      config[:vpadding] || config[:padding] || 0
+    end
+
+    def hmargin
+      config[:hmargin] || config[:margin] || 0
+    end
+
+    def vmargin
+      config[:vmargin] || config[:margin] || 0
+    end
+
+    def width
+      config[:width]
+    end
+
+    def height
+      config[:height]
+    end
+
+    def output
+      config[:output] || input
+    end
+
+    def output_image_file
+      config[:output_image] || "#{output}.png"
+    end
+
+    def output_style_file
+      config[:output_style] || "#{output}.#{style_name}"
+    end
+
+    def nocss?
+      config[:nocss] # set true if you dont want an output style file generated (e.g. you will take the #run! output and store it yourself)
+    end
+
+    def nocomments?
+      config[:nocomments] # set true if you dont want any comments in the output style file
+    end
+
+    def custom_style_file
+      File.join(input, File.basename(input) + ".#{style_name}")
+    end
+
+    def css_url
+      base = File.basename(output_image_file)
+      custom = config[:cssurl]
+      if custom
+        if custom.is_a?(Proc)
+          custom.call(base)                 # allow custom url using a lambda
+        elsif custom.include?('$IMAGE')
+          custom.sub('$IMAGE', base)        # allow custom url with simple token replacement
+        else
+          "url(#{File.join(custom, base)})" # allow custom url with simple prepend
+        end
+      else
+        "url(#{base})"                      # otherwise, just default to basename of the output image file
+      end
+    end
+
+    def image_files
+      return [] if input.nil?
+      valid_extensions = library::VALID_EXTENSIONS
+      expansions = Array(valid_extensions).map{|ext| File.join(input, "**", "*.#{ext}")}
+      SpriteFactory.find_files(*expansions)
+    end
+
+    #----------------------------------------------------------------------------
+
+    def library
+      @library ||= Library.send(library_name)
+    end
+
+    def load_images
+      input_path = Pathname.new(input)
+      images = library.load(image_files)
+      images.each do |i|
+        i[:name], i[:ext] = map_image_filename(i[:filename], input_path)
+        raise RuntimeError, "image #{i[:name]} does not fit within a fixed width of #{width}" if width && (width < i[:width])
+        raise RuntimeError, "image #{i[:name]} does not fit within a fixed height of #{height}" if height && (height < i[:height])
+      end
+      images.sort_by {|i| [image_name_without_pseudo_class(i), image_pseudo_class_priority(i)] }
+    end
+
+    def map_image_filename(filename, input_path)
+      name = Pathname.new(filename).relative_path_from(input_path).to_s.gsub(File::SEPARATOR, "_")
+      name = name.gsub('--', ':')
+      name = name.gsub('__', ' ')
+      ext  = File.extname(name)
+      name = name[0...-ext.length] unless ext.empty?
+      [name, ext]
+    end
+
+    def image_name_without_pseudo_class(image)
+      image[:name].split(':').first
+    end
+
+    def image_pseudo_class(image)
+      image[:name].slice(/:.*?\Z/)
+    end
+
+    def image_pseudo_class_priority(image)
+      PSEUDO_CLASS_ORDER.index(image_pseudo_class(image))
+    end
+
+    #----------------------------------------------------------------------------
+
+    def create_sprite(images, width, height)
+      library.create(output_image_file, images, width, height)
+      pngcrush(output_image_file)
+    end
+
+    #----------------------------------------------------------------------------
+
+    def layout_strategy
+      @layout_strategy ||= Layout.send(layout_name)
+    end
+
+    def layout_images(images)
+      layout_strategy.layout(images, :width => width, :height => height, :hpadding => hpadding, :vpadding => vpadding, :hmargin => hmargin, :vmargin => vmargin)
+    end
+
+    #----------------------------------------------------------------------------
+
+    def style(selector, url, images, &block)
+      defaults = Style.generate(style_name, selector, url, images, custom_styles) # must call, even if custom block is given, because it stashes generated css style into image[:style] attributes
+      if block_given?
+        yield images.inject({}) {|h,i| h[i[:name].to_sym] = i; h} # provide custom rule builder a hash by image name
+      else
+        defaults
+      end
+    end
+
+    def style_comment(comment)
+      Style.comment(style_name, comment)
+    end
+
+    #----------------------------------------------------------------------------
+
+    SUPPORTS_PNGCRUSH = !`which pngcrush`.empty? rescue false # rescue on environments without `which` (windows)
+
+    def pngcrush(image)
+      if SUPPORTS_PNGCRUSH && config[:pngcrush]
+        crushed = "#{image}.crushed"
+        `pngcrush -rem alla -reduce -brute #{image} #{crushed}`
+        FileUtils.mv(crushed, image)
+      end
+    end
+
+    #----------------------------------------------------------------------------
+
+    def summary(images, max)
+      return <<-EOF
+
+        Creating a sprite from following images:
+        \n#{images.map{|i| "        #{report_path(i[:filename])} (#{i[:width]}x#{i[:height]})" }.join("\n")}
+
+        Output files:
+          #{report_path(output_image_file)}
+          #{report_path(output_style_file)}
+
+        Output size:
+          #{max[:width]}x#{max[:height]}
+
+      EOF
+    end
+
+    def report(msg)
+      puts msg if config[:report]
+    end
+
+    def report_path(path) # always report paths relative to . to avoid machine specific information in report (to avoid DIFF issues in tests and version control)
+      @cwd ||= Pathname.new(File.expand_path('.'))
+      path = Pathname.new(path)
+      path = path.relative_path_from(@cwd) if path.absolute?
+      path.to_s
+    end
+
+    #----------------------------------------------------------------------------
+
+  end # class Runner
+end # module SpriteFactory

data/lib/sprite_factory/style.rb

@@ -0,0 +1,74 @@
+module SpriteFactory
+  module Style
+
+    #----------------------------------------------------------------------------
+
+    def self.css(selector, name, attributes)
+      "#{selector}#{name} { #{css_style(attributes)}; }"
+    end
+
+    def self.css_style(attributes)
+      attributes.join("; ")
+    end
+
+    def self.css_comment(comment)
+      return "/*\n#{comment}\n*/"
+    end
+
+    #----------------------------------------------------------------------------
+
+    def self.scss(selector, name, attributes)
+      css(selector, name, attributes) # scss is a superset of css, but we dont actually need any of the extra bits, so just defer to the css generator instead
+    end
+
+    def self.scss_style(attributes)
+      css_style(attributes)
+    end
+
+    def self.scss_comment(comment)
+      css_comment(comment)
+    end
+
+    #----------------------------------------------------------------------------
+
+    def self.sass(selector, name, attributes)
+      "#{selector}#{name}\n" + sass_style(attributes)
+    end
+
+    def self.sass_style(attributes)
+      attributes.map{|a| "  #{a}"}.join("\n") + "\n"
+    end
+
+    def self.sass_comment(comment)
+      return "/* #{comment.rstrip} */" # SASS has peculiar indenting requirements in order to recognise closing block comment
+    end
+
+    #----------------------------------------------------------------------------
+
+    def self.generate(style_name, selector, url, images, custom_styles="")
+      styles = []
+      images.each do |image|
+        attr = [
+          "width: #{image[:cssw]}px",
+          "height: #{image[:cssh]}px",
+          "background: #{url} #{-image[:cssx]}px #{-image[:cssy]}px no-repeat",
+          custom_styles
+        ]
+        image[:selector] = selector                          # make selector available for (optional) custom rule generators
+        image[:style]    = send("#{style_name}_style", attr) # make pure style available for (optional) custom rule generators (see usage of yield inside Runner#style)
+        styles << send(style_name, selector, image[:name], attr)
+      end
+      styles << ""
+      styles.join("\n")
+    end
+
+    #----------------------------------------------------------------------------
+
+    def self.comment(style_name, comment)
+      send("#{style_name}_comment", comment)
+    end
+
+    #----------------------------------------------------------------------------
+
+  end
+end