sprite-factory 1.0.0 → 1.2.0

data/.gitignore

@@ -0,0 +1,10 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+*.swp
+.sass-cache
+test/images/*.png
+test/images/*.css
+test/images/*.sass
+test/images/*.scss

data/README.md

@@ -12,6 +12,7 @@ The library provides:
  * many customizable options
  * support for any stylesheet syntax, including [CSS](http://www.w3.org/Style/CSS/) and [Sass](http://sass-lang.com/).
  * support for any image library, including [RMagick](http://rmagick.rubyforge.org/) and [ChunkyPNG](https://github.com/wvanbergen/chunky_png).
+ * support for pngcrush'n the generated image file
 
 
 Installation
@@ -20,11 +21,18 @@ Installation
     $ gem install sprite-factory
 
 An image library is also required. SpriteFactory comes with built in support for
-[RMagick](http://rmagick.rubyforge.org/) or
-[ChunkyPng](https://github.com/wvanbergen/chunky_png) and is easily extensible to
-use any image library of your choice. 
+[RMagick](http://rmagick.rubyforge.org/) or [ChunkyPng](https://github.com/wvanbergen/chunky_png).
 
-_(see below for instructions to install an image library if you don't already have one.)_
+RMagick is the most common image libary to use, installation instructions for ubuntu:
+
+    $ sudo aptitude install imageMagick libMagickWand-dev
+    $ sudo gem install rmagick
+
+ChunkyPng is lighter weight but only supports .png format:
+
+    $ gem install chunky_png
+
+SpriteFactory can also be easily extended to use the image library of your choice.
 
 Usage
 =====
@@ -62,7 +70,7 @@ Customization
 Much of the behavior can be customized by overriding the following options:
 
  - `:output`   - specify output location for generated files
- - `:layout`   - specify layout algorithm (horizontal or vertical)
+ - `:layout`   - specify layout algorithm (horizontal, vertical or packed)
  - `:style`    - specify output style (css or sass)
  - `:library`  - specify image library to use (rmagick or chunkypng)
  - `:selector` - specify custom css selector (see below)
@@ -70,18 +78,32 @@ Much of the behavior can be customized by overriding the following options:
  - `:padding`  - add padding to each sprite
  - `:width`    - fix width of each sprite to a specific size
  - `:height`   - fix height of each sprite to a specific size
+ - `:pngcrush` - pngcrush the generated output image (if pngcrush is available)
 
 Options can be passed as command line arguments to the `sf` script:
 
-    $ sf images/icons --style sass --layout vertical
+    $ sf images/icons --style sass --layout packed
 
 Options can also be passed as the 2nd argument to the `#run!` method:
 
-    SpriteFactory.run!('images/icons', :style => :sass, :layout => :vertical)
+    SpriteFactory.run!('images/icons', :style => :sass, :layout => :packed)
 
 You can see the results of many of these options by viewing the sample page that
 comes with the gem in `test/images/reference/index.html`.
 
+Layout
+======
+
+The generated image can be laid out in a horizontal or a vertical strip by
+providing a `:layout` option (defaults to horizontal). A **new option in v1.2.0** is
+to use a  **:packed** layout which will attempt to generate an optimized packed
+square-ish layout.
+
+For more details on the bin-packing algorithm used:
+
+ * You can find a [description here](http://codeincomplete.com/posts/2011/5/7/bin_packing/)
+ * You can find a [demo here](http://codeincomplete.com/posts/2011/5/7/bin_packing/example/)
+
 Customizing the CSS Selector
 ============================
 
@@ -113,7 +135,7 @@ building a Ruby on Rails application you might need to generate URL's using the
 helper method to ensure it gets the appopriate cache-busting query parameter.
 
 By default, the SpriteFactory generates simple url's that contain only the basename of the
-unified sprite image, but you can control the generation of these url's using the :csspath
+unified sprite image, but you can control the generation of these url's using the `:csspath`
 option:
 
 For most CDN's, you can prepend a simple string to the image name:
@@ -171,37 +193,23 @@ The sprite factory library can also be extended in a number of other ways.
 
 _(see existing code for examples of each)._
 
-Installing an Image Library
-===========================
-
-SpriteFactory comes with built in support for
-[RMagick](http://rmagick.rubyforge.org/) or
-[ChunkyPng](https://github.com/wvanbergen/chunky_png)
-
-RMagick is the most flexible image libary to use, but requires ImageMagick
-binaries, installation instructions for ubuntu:
-
-    $ sudo aptitude install imageMagick libMagickWand-dev
-    $ sudo gem install rmagick
-
-ChunkyPng is lighter weight and has no binary requirements, but only supports
-.png format. Installation is a simple gem install:
-
-    $ gem install chunky_png
+License
+=======
 
-SpriteFactory can also be easily extended to use the image library of your choice.
+See [LICENSE](https://github.com/jakesgordon/sprite-factory/blob/master/LICENSE) file.
 
-License
+Credits
 =======
 
-See LICENSE file.
+Thanks to my employer, [LiquidPlanner](http://liquidplanner.com) for allowing me to take this idea from our
+online project management web application and release it into the wild.
 
 Contact
 =======
 
-You can reach me at [jake@codeincomplete.com](mailto:jake@codeincomplete.com), or via
-my website: [Code inComplete](http://codeincomplete.com).
-
+If you have any ideas, feedback, requests or bug reports, you can reach me at
+[jake@codeincomplete.com](mailto:jake@codeincomplete.com), or via
+my website: [Code inComplete](http://codeincomplete.com/posts/2011/4/29/sprite_factory/).
 
 
 

data/Rakefile

@@ -31,6 +31,7 @@ task :reference do
   regenerate.call('test/images/regular')
   regenerate.call('test/images/regular', :output => 'test/images/regular.horizontal', :selector => 'img.horizontal_', :layout => :horizontal)
   regenerate.call('test/images/regular', :output => 'test/images/regular.vertical',   :selector => 'img.vertical_',   :layout => :vertical)
+  regenerate.call('test/images/regular', :output => 'test/images/regular.packed',     :selector => 'img.packed_',     :layout => :packed)
   regenerate.call('test/images/regular', :output => 'test/images/regular.padded',     :selector => 'img.padded_',     :padding => 10)
   regenerate.call('test/images/regular', :output => 'test/images/regular.fixed',      :selector => 'img.fixed_',      :width => 100, :height => 100)
   regenerate.call('test/images/regular', :output => 'test/images/regular.sassy',      :selector => 'img.sassy_',      :style => :sass)
@@ -38,6 +39,7 @@ task :reference do
   regenerate.call('test/images/irregular')
   regenerate.call('test/images/irregular', :output => 'test/images/irregular.horizontal', :selector => 'img.horizontal_', :layout => :horizontal)
   regenerate.call('test/images/irregular', :output => 'test/images/irregular.vertical',   :selector => 'img.vertical_',   :layout => :vertical)
+  regenerate.call('test/images/irregular', :output => 'test/images/irregular.packed',     :selector => 'img.packed_',     :layout => :packed)
   regenerate.call('test/images/irregular', :output => 'test/images/irregular.padded',     :selector => 'img.padded_',     :padding => 10)
   regenerate.call('test/images/irregular', :output => 'test/images/irregular.fixed',      :selector => 'img.fixed_',      :width => 100, :height => 100)
   regenerate.call('test/images/irregular', :output => 'test/images/irregular.sassy',      :selector => 'img.sassy_',      :style => :sass)

data/bin/sf

@@ -20,11 +20,12 @@ op.on("-v", "--version") do
 end
 
 output_help   = "specify output location, without any extension"
-layout_help   = "specify layout orientation   ( horizontal, vertical )"
+layout_help   = "specify layout orientation   ( horizontal, vertical, packed )"
 style_help    = "specify output style format  ( css, sass )"
 library_help  = "specify image library to use ( rmagic, chunkypng )"
 selector_help = "specify custom selector to use for each css rule ( default: 'img.' )"
 csspath_help  = "specify custom path to use for css image urls ( default: output file's basename )"
+pngcrush_help = "use pngcrush to optimize generated image"
 
 op.on("--output   [PATH]",        output_help)   {|value| options[:output]   = value }
 op.on("--layout   [ORIENTATION]", layout_help)   {|value| options[:layout]   = value }
@@ -32,6 +33,7 @@ op.on("--style    [STYLE]",       style_help)    {|value| options[:style]    = v
 op.on("--library  [LIBRARY]",     library_help)  {|value| options[:library]  = value }
 op.on("--selector [SELECTOR]",    selector_help) {|value| options[:selector] = value }
 op.on("--csspath  [CSSPATH]",     csspath_help)  {|value| options[:csspath]  = value }
+op.on("--pngcrush",               pngcrush_help) {|value| options[:pngcrush] = value }
 
 begin
   op.parse!(ARGV)
@@ -39,7 +41,6 @@ begin
   SpriteFactory.run!(ARGV[0], options)
 rescue Exception => ex
   puts ex.message
-  puts op.to_s
   exit
 end
 

data/lib/sprite_factory.rb

@@ -2,14 +2,13 @@ module SpriteFactory
   
   #----------------------------------------------------------------------------
 
-  VERSION     = "1.0.0"
+  VERSION     = "1.2.0"
   SUMMARY     = "Automatic CSS sprite generator"
   DESCRIPTION = "Combines individual images from a directory into a single sprite image file and creates an appropriate CSS stylesheet"
   LIB         = File.dirname(__FILE__)
 
   autoload :Runner,  File.join(LIB, 'sprite_factory/runner')  # controller that glues everything together
-  autoload :Layout,  File.join(LIB, 'sprite_factory/layout')  # layout calculations
-  autoload :Style,   File.join(LIB, 'sprite_factory/style')   # style generators
+  autoload :Style,   File.join(LIB, 'sprite_factory/style')   # style generators all live in a single module (for now)
 
   def self.run!(input, config = {}, &block)
     Runner.new(input, config).run!(&block)
@@ -26,6 +25,29 @@ module SpriteFactory
     attr_accessor :library
     attr_accessor :selector
     attr_accessor :csspath
+    attr_accessor :pngcrush
+  end
+
+  #----------------------------------------------------------------------------
+
+  module Layout # abstract module for various layout strategies
+
+    autoload :Horizontal, File.join(LIB, 'sprite_factory/layout/horizontal') # concrete module for layout in a single horizontal strip
+    autoload :Vertical,   File.join(LIB, 'sprite_factory/layout/vertical')   # concrete module for layout in a single vertical strip
+    autoload :Packed,     File.join(LIB, 'sprite_factory/layout/packed')     # concrete module for layout in a bin-packed square
+
+    def self.horizontal
+      Horizontal
+    end
+
+    def self.vertical
+      Vertical
+    end
+
+    def self.packed
+      Packed
+    end
+
   end
   
   #----------------------------------------------------------------------------

data/lib/sprite_factory/layout/horizontal.rb

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

data/lib/sprite_factory/layout/packed.rb

@@ -0,0 +1,107 @@
+module SpriteFactory
+  module Layout
+    module Packed
+
+      #------------------------------------------------------------------------
+
+      def self.layout(images, options = {})
+
+        raise NotImplementedError, ":packed layout does not support the :padding option" if (options[:padding].to_i > 0) || (options[:hpadding].to_i > 0) || (options[:vpadding].to_i > 0)
+        raise NotImplementedError, ":packed layout does not support fixed :width/:height option" if options[:width] || options[:height]
+
+        return { :width => 0, :height => 0 } if images.empty?
+
+        images.sort! do |a,b|
+          diff = [b[:width], b[:height]].max <=> [a[:width], a[:height]].max
+          diff = [b[:width], b[:height]].min <=> [a[:width], a[:height]].min if diff.zero?
+          diff = b[:height] <=> a[:height] if diff.zero?
+          diff = b[:width]  <=> a[:width]  if diff.zero?
+          diff
+        end
+
+        root = { :x => 0, :y => 0, :w => images[0][:width], :h => images[0][:height] }
+
+        images.each do |i|
+          if (node = findNode(root, i[:width], i[:height]))
+            placeImage(i, node)
+            splitNode(node, i[:width], i[:height])
+          else
+            root = grow(root, i[:width], i[:height])
+            redo
+          end
+        end
+
+        { :width => root[:w], :height => root[:h] }
+
+      end
+
+      def self.placeImage(image, node)
+        image[:cssx] = image[:x] = node[:x]  # TODO
+        image[:cssy] = image[:y] = node[:y]  #   * support for :padding option
+        image[:cssw] = image[:width]         #   * support for fixed :width/:height option
+        image[:cssh] = image[:height]
+      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,42 @@
+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
+        max_width = width || ((2 * hpadding) + 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                            # anchored at y
+            i[:y]    = i[:cssy] + vpadding          # image drawn offset to account for padding
+          end
+
+          y = y + i[:cssh]
+
+        end
+        { :width => max_width, :height => y }
+      end
+
+    end
+  end
+end

data/lib/sprite_factory/runner.rb

@@ -1,4 +1,5 @@
 require 'pathname'
+require 'fileutils'
 
 module SpriteFactory
   class Runner
@@ -17,6 +18,7 @@ module SpriteFactory
       @config[:selector] ||= SpriteFactory.selector || 'img.'
       @config[:csspath]  ||= SpriteFactory.csspath
       @config[:report]   ||= SpriteFactory.report
+      @config[:pngcrush] ||= SpriteFactory.pngcrush
     end
   
     #----------------------------------------------------------------------------
@@ -146,12 +148,17 @@ module SpriteFactory
 
     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.send(layout_name, images, :width => width, :height => height, :hpadding => hpadding, :vpadding => vpadding)
+      layout_strategy.layout(images, :width => width, :height => height, :hpadding => hpadding, :vpadding => vpadding)
     end
 
     #----------------------------------------------------------------------------
@@ -171,6 +178,18 @@ module SpriteFactory
 
     #----------------------------------------------------------------------------
 
+    SUPPORTS_PNGCRUSH = !`which pngcrush`.empty?
+
+    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