spriteous 0.1.0

data/LICENSE

@@ -0,0 +1,14 @@
+Copyright (C) 2012 Donnie Akers
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see http://www.gnu.org/licenses.

data/README.md

@@ -0,0 +1,61 @@
+### Description
+Spriteous is a righteous sprite extraction utility. It uses a "reverse flood fill" algorithm to naively obtain each individual sprite from a spritesheet, "sprite" here defined as a contiguous group of pixels which do not match the background color (assumed to be the first pixel) of the sheet.
+
+### Installation
+    gem install spriteous
+
+### Usage
+Spriteous currently uses the ChunkyPNG library (more specifically, the oily_png C extension), so only that format is supported at this time. On the bright side, this means that a Spriteous instance can easily be initialized either from a filename or raw PNG data:
+
+```ruby
+Spriteous.new('sheet.png')
+Spriteous.new(File.read 'sheet.png')
+mario = Spriteous.new(` curl -s http://i.imgur.com/Fmd9q.png `)
+```
+
+**#extract** is where the magic happens. If called with no parameters, it simply returns all of the extracted sprites as an array of ChunkyPNG::Images.
+
+```ruby
+sprites = mario.extract
+sprites.size # => 85
+sprites.each_with_index do |sprite, i|
+  puts "Sprite #{i} contains #{sprite.palette.size} colors."
+end
+```
+
+If you bothered to count the sprites in the linked image, you might have noticed that #size's value is unfortunately a little off. Specifically, it's over by 4, and [zooming way in](http://i.imgur.com/l9xE5.png) reveals why this is the case. The algorithm used relies on all of a sprite's pixels being contiguous, but those damned fireballs just *have* to have disjointed pixels.
+
+Alas, this seems to be an unavoidable consequence of the flood fill algorithm, and I think a major overhaul would be required to properly handle these edge cases. Of course, then the algorithm would break completely on sheets where the sprites are positioned very closely together. The only solution would be to implement content-awareness, but that is beyond the scope of this project, and‒given the plethora of potential sprite styles and sheet layouts‒perhaps even all of computer vision. ("If you seek advice, compel people to prove you wrong.")
+
+Spriteous compromises by allowing for a minimum square pixel value to be passed to #extract.
+
+```ruby
+mario.extract(min_size: 2).size # => 81
+```
+
+Lossy sprite extraction is unpleasant, sure, but it's at least a slight improvement over grabbing lots of "junk" sprites.
+
+##### Saving
+
+More often than not, the intention will simply be to save the extracted sprites rather than do something with them individually. While you could use #each_with_index to implement this functionality, it's much saner to just pass the *save_format* option to #extract.
+
+```ruby
+mario.extract(min_size: 2, save_format: 'sprites/mario/%02d.png')
+```
+
+Saving a collection of sprites by index is pretty much the only reasonable way to do it, so some form of `%d` must be present, but that's the only hard-and-fast requirement.
+
+### Roadmap
+Spriteous was predominantly created to assist in a personal project of mine, and it has served that purpose quite well. It certainly caters to a relatively small niche, as the scarcity of available options would indicate, but during my research I came upon several people seeking such a tool, only to be told (on spriting-centric forums, no less!) that their only option was to manually crop. If nothing else, I hope those previously lost souls find their way here.
+
+As is the case in any creative endeavor, this project's growth would please its designer immensely. Spriteous is by no means feature-complete, and indeed it very likely tackles the problem in a non-optimal way. Following is a list of my own criticisms and potential avenues for improvement.
+
+##### TODO
+* Implement a better algorithm. Flood fill was nice and easy, but there are numerous ways to improve upon it. I've entertained the idea of using a moving box to determine the edges of a sprite, but irregular dimensions and transparency make this difficult.
+* Support, at the very least, JPG and GIF formats, likely via RMagick.
+* Improve speed when working with large spritesheets, probably by avoiding checking the entire image for the next non-transparent pixel when looking for the next sprite, though how to do this presently escapes me.
+* Cleverly determine when the background color has changed, as is a common occurrence between sections.
+* Attempt to remove non-sprite portions of a sheet like the ripper's tag and irrelevant text, instead of it being a manual step for the user.
+
+##### Contributing
+Comments, criticisms, and code are all heartily welcome.

data/lib/spriteous.rb

@@ -0,0 +1,81 @@
+#coding: utf-8
+require 'fileutils'
+require 'oily_png'
+
+class Spriteous
+  def initialize(data)
+    # Allow for creation from either raw PNG data or a file.
+    meth = data[0] == "\x89" ? :from_string : :from_file
+    @img = ChunkyPNG::Image.send meth, data
+
+    back, @w = @img.pixels.first, @img.width
+
+    # The original image's pixels get modified in place to erase the background
+    # color, They're duplicated because the algorithm relies on "erasing" found
+    # pixels, and we eventually need the originals to construct the sprites.
+    @pixels = @img.pixels.map! { |p| p == back ? 0 : p }.dup
+  end
+
+  # A "reverse flood fill" algorithm for finding all of the pixels that belong
+  # to a given sprite. Rather than finding and replacing background pixels, it
+  # looks for a contiguous path starting from the first non-transparent pixel.
+  def traverse(pixel)
+    queue = [pixel]
+
+    # Used for checking the target's adjacent pixels. All eight directions are
+    # checked to avoid missing single diagonal pixels at the edges.
+    neighbors = [-@w - 1, -@w, -@w + 1, -1, 1, @w - 1, @w, @w + 1]
+
+    until queue.empty?
+      p = queue.pop
+
+      if @pixels[p] > 0
+        # Store this non-transparent pixel's index and then make it transparent
+        # to avoid unnecessarily checking it again from a neighbor.
+        @pixels[(@found << p).last] = 0
+
+        # Apply the eight cardinal directions to the current pixel's index and
+        # prepare them to be checked on the next iteration.
+        queue.concat neighbors.map { |n| p + n }
+      end
+    end
+  end
+
+  # Entry point for the traverse method defined above. Returns array of sprites
+  # (instances of ChunkyPNG::Image) if called without the argument. save_format
+  # should be a format string that specifies %d in some way, as this is used to
+  # generate the names of the ripped sprites. Example: 'sprites/mario/%03d.png'
+  def extract(opts = {})
+    sprites = []
+
+    # Sprites are erased as they're found, so we're done when the entire image
+    # is comprised of a single color value, 0 (transparent) in this case.
+    while @pixels.uniq.size > 1
+      @found = []
+
+      # Find the next sprite (first non-transparent pixel) and traverse from it
+      # until there is no contiguous direction to continue in. @found will then
+      # contain all of the pixel indices for the current sprite.
+      traverse @pixels.find_index { |p| p > 0 }
+
+      # @found contains pixel indices, but now we need coordinate data.
+      x, y = @found.map { |f| f % @w }, @found.map { |f| f / @w }
+
+      # Determine the sprite's bounding box (top, left, width, height), crop it
+      # from the original image, and push it to the collection unless a minimum
+      # size is desired and the resulting sprite's dimensions don't satisfy it.
+      box = [x.min, y.min, (w = x.max - x.min + 1), (h = y.max - y.min + 1)]
+      sprites << @img.crop(*box) if w * h >= opts[:min_size].to_i
+    end
+
+    return sprites unless opts[:save_format]
+
+    unless opts[:save_format].include? '%d'
+      raise ArgumentError, "%d is required to properly save extracted sprites."
+    end
+
+    dir = opts[:save_format].split('/')[0..-2].join '/'
+    FileUtils.mkdir_p dir unless dir.empty?
+    sprites.each_with_index { |s, i| s.save opts[:save_format] % i }
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: spriteous
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Donnie Akers
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-03-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: oily_png
+  requirement: &75064140 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *75064140
+description: 
+email:
+- andkerosine@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/spriteous.rb
+homepage: 
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: Naively separates a well-formatted spritesheet into its component parts.
+test_files: []