sprite-factory 1.0.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Jake Gordon and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,207 @@
+Sprite Factory
+==============
+
+The sprite factory is a ruby library that can be used to generate
+[CSS sprites](http://www.alistapart.com/articles/sprites). It combines
+individual image files from a directory into a single unified sprite image
+and creates an appropriate CSS stylesheet for use in your web application.
+
+The library provides:
+
+ * both a ruby API and a command line script
+ * 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).
+
+
+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. 
+
+_(see below for instructions to install an image library if you don't already have one.)_
+
+Usage
+=====
+
+Use the `sf` command line script specifying the location of your images.
+
+    $ sf images/icons
+
+This will combine the individual image files within that directory and generate:
+
+ * images/icons.png
+ * images/icons.css
+
+You can also use the SpriteFactory class directly from your own code:
+
+    require 'sprite_factory'
+
+    SpriteFactory.run!('images/icons')
+
+The original image name is used for the CSS class to show that image in HTML:
+
+    <img src='s.gif' class='high'>
+    <img src='s.gif' class='medium'>
+    <img src='s.gif' class='low'>
+
+When using a framework such as Rails, you would usually DRY this up with a helper method:
+
+    def sprite_tag(name)
+      image_tag('s.gif', :class => name)
+    end
+
+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)
+ - `:style`    - specify output style (css or sass)
+ - `:library`  - specify image library to use (rmagick or chunkypng)
+ - `:selector` - specify custom css selector (see below)
+ - `:csspath`  - specify custom path for css image url (see below)
+ - `: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
+
+Options can be passed as command line arguments to the `sf` script:
+
+    $ sf images/icons --style sass --layout vertical
+
+Options can also be passed as the 2nd argument to the `#run!` method:
+
+    SpriteFactory.run!('images/icons', :style => :sass, :layout => :vertical)
+
+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`.
+
+Customizing the CSS Selector
+============================
+
+By default, the CSS generated is fairly simple. It assumes you will be using `<img>`
+elements for your sprites, and that the basename of each individual file is suitable for
+use as a CSS classname. For example:
+
+    img.high   { width: 16px; height: 16px; background: url(images/icons.png)   0px 0px no-repeat; }
+    img.medium { width: 16px; height: 16px; background: url(images/icons.png) -16px 0px no-repeat; }
+    img.low    { width: 16px; height: 16px; background: url(images/icons.png) -32px 0px no-repeat; }
+
+If you want to use different selectors for your rules, you can provide the `:selector` option. For
+example:
+
+    SpriteFactory.run!('images/icons', :selector => 'span.icon_')
+
+will generate:
+
+    span.icon_high   { width: 16px; height: 16px; background: url(images/icons.png)   0px 0px no-repeat; }
+    span.icon_medium { width: 16px; height: 16px; background: url(images/icons.png) -16px 0px no-repeat; }
+    span.icon_low    { width: 16px; height: 16px; background: url(images/icons.png) -32px 0px no-repeat; }
+
+Customizing the CSS Image Path
+==============================
+
+Within the generated CSS file, it can be tricky to get the correct path to your unified
+sprite image. For example, you might be hosting your images on Amazon S3, or if you are
+building a Ruby on Rails application you might need to generate URL's using the `#image_path`
+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
+option:
+
+For most CDN's, you can prepend a simple string to the image name:
+
+    SpriteFactory.run('images/icons',
+                      :csspath => "http://s3.amazonaws.com/")
+
+    # generates:  url(http://s3.amazonaws.com/icons.png)
+
+For more control, you can provide a lambda function and generate your own paths:
+
+    SpriteFactory.run('images/icons',
+                       :csspath => lambda{|image| image_path(image)})
+
+    # generates:   url(/images/icons.png?v123456)
+
+Customizing the entire CSS output 
+=================================
+
+If you want **complete** control over the generated styles, you can pass a block to the `run!` method.
+
+The block will be provided with information about each image, including the generated css attributes. 
+Whatever content the block returns will be inserted into the generated css file.
+
+    SpriteFactory.run!('images/timer') do |images|
+      rules = []
+      rules << "div.running img.button { cursor: pointer; #{images[:running][:style]} }"
+      rules << "div.stopped img.button { cursor: pointer; #{images[:stopped][:style]} }"
+      rules.join("\n")
+    end
+
+The `images` argument is a hash, where each key is the basename of an image file, and the
+value is a hash of image metadata that includes the following:
+
+ * `:style`  - the default generated style
+ * `:cssx`   - the css sprite x position
+ * `:cssy`   - the css sprite y position
+ * `:cssw`   - the css sprite width
+ * `:cssh`   - the css sprite height
+ * `:x`      - the image x position
+ * `:y`      - the image y position
+ * `:width`  - the image width
+ * `:height` - the image height
+
+(*NOTE*: the image coords can differ form the css sprite coords when padding or fixed width/height options are specified)
+
+Extending the Library
+=====================
+
+The sprite factory library can also be extended in a number of other ways.
+
+ * provide a custom layout algorithm in the `SpriteFactory::Layout` module.
+ * provide a custom style generator in the `SpriteFactory::Style` module.
+ * provide a custom image library in the `SpriteFactory::Library` module.
+
+_(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
+
+SpriteFactory can also be easily extended to use the image library of your choice.
+
+License
+=======
+
+See LICENSE file.
+
+Contact
+=======
+
+You can reach me at [jake@codeincomplete.com](mailto:jake@codeincomplete.com), or via
+my website: [Code inComplete](http://codeincomplete.com).
+
+
+
+

data/Rakefile

@@ -0,0 +1,67 @@
+require 'rake/testtask'
+
+#------------------------------------------------------------------------------
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+#------------------------------------------------------------------------------
+
+desc "run a console with SpriteFactory loaded"
+task :console do
+  system "irb -r #{File.expand_path('lib/sprite_factory', File.dirname(__FILE__))}"
+end
+
+#------------------------------------------------------------------------------
+
+desc "regenerate test reference images"
+task :reference do
+
+  require File.expand_path('lib/sprite_factory', File.dirname(__FILE__))
+
+  regenerate = lambda do |input, options = {}, &block|
+    output = options[:output] || input
+    SpriteFactory.run!(input, {:report => true}.merge(options), &block)
+    FileUtils.mv(output + "." + (                   :png).to_s, 'test/images/reference')
+    FileUtils.mv(output + "." + (options[:style] || :css).to_s, 'test/images/reference')
+  end
+
+  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.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)
+
+  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.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)
+
+  regenerate.call('test/images/custom', :output => 'test/images/custom') do |images|
+    rules = []
+    rules << "div.running img.button { cursor: pointer; #{images[:running][:style]} }"
+    rules << "div.stopped img.button { cursor: pointer; #{images[:stopped][:style]} }"
+    rules.join("\n")
+  end
+
+  regenerate.call('test/images/formats', :library => :rmagick)
+
+end
+
+#------------------------------------------------------------------------------
+
+desc "convert reference test sass files to css"
+task :sass do
+
+  `sass 'test/images/reference/regular.sassy.sass'   'test/images/reference/regular.sassy.css'`
+  `sass 'test/images/reference/irregular.sassy.sass' 'test/images/reference/irregular.sassy.css'`
+
+end
+
+#------------------------------------------------------------------------------
+

data/bin/sf

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.push File.expand_path("../lib", File.dirname(__FILE__)) # add sprite factory library to load path
+
+require 'sprite_factory'
+require 'optparse'
+
+options   = { :report => true }
+op        = OptionParser.new
+op.banner = "#{SpriteFactory::DESCRIPTION}\nUsage: sprite <dir> [options]"
+
+op.on("-h", "--help") do
+  puts op.to_s
+  exit
+end
+
+op.on("-v", "--version") do
+  puts SpriteFactory::VERSION
+  exit
+end
+
+output_help   = "specify output location, without any extension"
+layout_help   = "specify layout orientation   ( horizontal, vertical )"
+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 )"
+
+op.on("--output   [PATH]",        output_help)   {|value| options[:output]   = value }
+op.on("--layout   [ORIENTATION]", layout_help)   {|value| options[:layout]   = value }
+op.on("--style    [STYLE]",       style_help)    {|value| options[:style]    = value }
+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 }
+
+begin
+  op.parse!(ARGV)
+  raise "a single argument must be specified containing images to be sprited" if ARGV.empty?
+  SpriteFactory.run!(ARGV[0], options)
+rescue Exception => ex
+  puts ex.message
+  puts op.to_s
+  exit
+end
+
+

data/lib/sprite_factory.rb

@@ -0,0 +1,51 @@
+module SpriteFactory
+  
+  #----------------------------------------------------------------------------
+
+  VERSION     = "1.0.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
+
+  def self.run!(input, config = {}, &block)
+    Runner.new(input, config).run!(&block)
+  end
+
+  #
+  # fallback defaults for some options can be set at module level to
+  # avoid having to pass them to #run! every single time
+  #
+  class << self
+    attr_accessor :report
+    attr_accessor :style
+    attr_accessor :layout
+    attr_accessor :library
+    attr_accessor :selector
+    attr_accessor :csspath
+  end
+  
+  #----------------------------------------------------------------------------
+
+  module Library # abstract module for using various image libraries
+
+    autoload :RMagick,   File.join(LIB, 'sprite_factory/library/rmagick')    # concrete module for using RMagick   (loaded on demand)
+    autoload :ChunkyPng, File.join(LIB, 'sprite_factory/library/chunky_png') # concrete module for using ChunkyPng (ditto)
+
+    def self.rmagick
+      RMagick
+    end
+
+    def self.chunkypng
+      ChunkyPng
+    end
+
+  end
+
+  #----------------------------------------------------------------------------
+
+end
+

data/lib/sprite_factory/layout.rb

@@ -0,0 +1,89 @@
+module SpriteFactory
+  module Layout
+
+    #--------------------------------------------------------------------------
+
+    def self.horizontal(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
+
+    #--------------------------------------------------------------------------
+
+    def self.vertical(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
+
+    #--------------------------------------------------------------------------
+
+    def self.knapsack(images)
+
+      raise NotImplementedError, "one day, when I have time, I'll do some kind of 'best-fit' algorithm"
+
+    end
+
+    #--------------------------------------------------------------------------
+
+  end
+end