fastimage 1.2.1

data/README

@@ -0,0 +1,74 @@
+FastImage
+
+FastImage finds the size or type of an image given its uri by fetching as little as needed
+
+The problem
+
+Your app needs to find the size or type of an image.  This could be for adding width and height attributes to an image tag, for adjusting layouts or overlays to fit an image or any other of dozens of reasons.
+
+But the image is not locally stored - it's on another asset server, or in the cloud - at Amazon S3 for example.
+
+You don't want to download the entire image to your app server - it could be many tens of kilobytes, or even megabytes just to get this information.  For most image types, the size of the image is simply stored at the start of the file.  For JPEG files it's a little bit more complex, but even so you do not need to fetch most of the image to find the size.
+
+FastImage does this minimal fetch for image types GIF, JPEG, PNG and BMP.  And it doesn't rely on installing external libraries such as RMagick (which relies on ImageMagick or GraphicsMagick) or ImageScience (which relies on FreeImage).
+
+You only need supply the uri, and FastImage will do the rest.
+
+Fastimage can also read local (and other) files, and uses the open-uri library to do so.
+
+Examples
+
+  require 'fastimage'
+
+  FastImage.size("http://stephensykes.com/images/ss.com_x.gif")
+  => [266, 56]  # width, height
+  FastImage.type("http://stephensykes.com/images/pngimage")
+  => :png
+  FastImage.type("/some/local/file.gif")
+  => :gif
+
+Installation
+
+h4. Gem
+
+  sudo gem install sdsykes-fastimage -s http://gems.github.com
+
+h4. Rails
+
+Install the gem as above, and configure it in your environment.rb file as below:
+
+  ...
+  Rails::Initializer.run do |config|
+    ...
+    config.gem "sdsykes-fastimage", :lib=>"fastimage"
+    ...
+  end
+  ...
+
+Then you're off - just use FastImage.size() and FastImage.type() in your code as in the examples.
+
+Documentation
+
+"http://rdoc.info/projects/sdsykes/fastimage":http://rdoc.info/projects/sdsykes/fastimage
+
+Tests
+
+You'll need to 'sudo gem install fakeweb' to be able to run the tests.
+
+  ruby test/test.rb
+  Loaded suite test/test
+  Started
+  ...............
+  Finished in 0.059392 seconds.
+
+  15 tests, 27 assertions, 0 failures, 0 errors
+
+
+References
+* "http://pennysmalls.com/2008/08/19/find-jpeg-dimensions-fast-in-ruby/":http://pennysmalls.com/2008/08/19/find-jpeg-dimensions-fast-in-ruby/
+* "http://snippets.dzone.com/posts/show/805":http://snippets.dzone.com/posts/show/805
+* "http://www.anttikupila.com/flash/getting-jpg-dimensions-with-as3-without-loading-the-entire-file/":http://www.anttikupila.com/flash/getting-jpg-dimensions-with-as3-without-loading-the-entire-file/
+* "http://imagesize.rubyforge.org/":http://imagesize.rubyforge.org/
+
+
+(c) 2009 Stephen Sykes

data/README.textile

@@ -0,0 +1,88 @@
+h1. FastImage
+
+h4. FastImage finds the size or type of an image given its uri by fetching as little as needed
+
+h2. The problem
+
+Your app needs to find the size or type of an image.  This could be for adding width and height attributes to an image tag, for adjusting layouts or overlays to fit an image or any other of dozens of reasons.
+
+But the image is not locally stored - it's on another asset server, or in the cloud - at Amazon S3 for example.
+
+You don't want to download the entire image to your app server - it could be many tens of kilobytes, or even megabytes just to get this information.  For most image types, the size of the image is simply stored at the start of the file.  For JPEG files it's a little bit more complex, but even so you do not need to fetch most of the image to find the size.
+
+FastImage does this minimal fetch for image types GIF, JPEG, PNG and BMP.  And it doesn't rely on installing external libraries such as RMagick (which relies on ImageMagick or GraphicsMagick) or ImageScience (which relies on FreeImage).
+
+You only need supply the uri, and FastImage will do the rest.
+
+Fastimage can also read local (and other) files, and uses the open-uri library to do so.
+
+h2. Examples
+
+<pre>
+<code>
+require 'fastimage'
+
+FastImage.size("http://stephensykes.com/images/ss.com_x.gif")
+=> [266, 56]  # width, height
+FastImage.type("http://stephensykes.com/images/pngimage")
+=> :png
+FastImage.type("/some/local/file.gif")
+=> :gif
+</code>
+</pre>
+
+h2. Installation
+
+h4. Gem
+
+<pre>
+<code>
+  sudo gem install sdsykes-fastimage -s http://gems.github.com
+</code>
+</pre>
+
+h4. Rails
+
+Install the gem as above, and configure it in your environment.rb file as below:
+<pre>
+<code>
+...
+Rails::Initializer.run do |config|
+  ...
+  config.gem "sdsykes-fastimage", :lib=>"fastimage"
+  ...
+end
+...
+</code>
+</pre>
+Then you're off - just use FastImage.size() and FastImage.type() in your code as in the examples.
+
+h2. Documentation
+
+"http://rdoc.info/projects/sdsykes/fastimage":http://rdoc.info/projects/sdsykes/fastimage
+
+h2. Tests
+
+You'll need to 'sudo gem install fakeweb' to be able to run the tests.
+
+<pre>
+<code>
+ruby test/test.rb
+Loaded suite test/test
+Started
+...............
+Finished in 0.059392 seconds.
+
+15 tests, 27 assertions, 0 failures, 0 errors
+</code>
+</pre>
+
+
+h2. References
+* "http://pennysmalls.com/2008/08/19/find-jpeg-dimensions-fast-in-ruby/":http://pennysmalls.com/2008/08/19/find-jpeg-dimensions-fast-in-ruby/
+* "http://snippets.dzone.com/posts/show/805":http://snippets.dzone.com/posts/show/805
+* "http://www.anttikupila.com/flash/getting-jpg-dimensions-with-as3-without-loading-the-entire-file/":http://www.anttikupila.com/flash/getting-jpg-dimensions-with-as3-without-loading-the-entire-file/
+* "http://imagesize.rubyforge.org/":http://imagesize.rubyforge.org/
+
+
+(c) 2009 Stephen Sykes

data/Rakefile

@@ -0,0 +1,18 @@
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "fastimage"
+    s.summary = "FastImage - Image info fast"
+    s.email = "sdsykes@gmail.com"
+    s.homepage = "http://github.com/sdsykes/fastimage"
+    s.description = "FastImage finds the size or type of an image given its uri by fetching as little as needed."
+    s.authors = ["Stephen Sykes"]
+    s.files = FileList["[A-Z]*", "{lib,test}/**/*"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://
+gems.github.com"
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 1
+:minor: 2
+:patch: 1

data/lib/fastimage.rb

@@ -0,0 +1,280 @@
+# FastImage finds the size or type of an image given its uri.
+# It is careful to only fetch and parse as much of the image as is needed to determine the result.
+# It does this by using a feature of Net::HTTP that yields strings from the resource being fetched
+# as soon as the packets arrive.
+#
+# No external libraries such as ImageMagick are used here, this is a very lightweight solution to 
+# finding image information.
+#
+# FastImage knows about GIF, JPEG, BMP and PNG files.
+#
+# FastImage can also read files from the local filesystem by supplying the path instead of a uri.
+# In this case FastImage uses the open-uri library to read the file in chunks of 256 bytes until
+# it has enough. This is possibly a useful bandwidth-saving feature if the file is on a network
+# attached disk rather than truly local.
+#
+# === Examples
+#   require 'fastimage'
+#
+#   FastImage.size("http://stephensykes.com/images/ss.com_x.gif")
+#   => [266, 56]
+#   FastImage.type("http://stephensykes.com/images/pngimage")
+#   => :png
+#   FastImage.type("/some/local/file.gif")
+#   => :gif
+#
+# === References
+# * http://snippets.dzone.com/posts/show/805
+# * http://www.anttikupila.com/flash/getting-jpg-dimensions-with-as3-without-loading-the-entire-file/
+# * http://pennysmalls.com/2008/08/19/find-jpeg-dimensions-fast-in-ruby/
+# * http://imagesize.rubyforge.org/
+#
+require 'net/https'
+require 'open-uri'
+
+class FastImage
+  attr_reader :size, :type
+
+  class FastImageException < StandardError # :nodoc:
+  end
+  class MoreCharsNeeded < FastImageException # :nodoc:
+  end
+  class UnknownImageType < FastImageException # :nodoc:
+  end
+  class ImageFetchFailure < FastImageException # :nodoc:
+  end
+  class SizeNotFound < FastImageException # :nodoc:
+  end
+
+  DefaultTimeout = 2
+  
+  LocalFileChunkSize = 256
+
+  # Returns an array containing the width and height of the image.
+  # It will return nil if the image could not be fetched, or if the image type was not recognised.
+  #
+  # By default there is a timeout of 2 seconds for opening and reading from a remote server.
+  # This can be changed by passing a :timeout => number_of_seconds in the options.
+  #
+  # If you wish FastImage to raise if it cannot size the image for any reason, then pass
+  # :raise_on_failure => true in the options.
+  #
+  # FastImage knows about GIF, JPEG, BMP and PNG files.
+  #
+  # === Example
+  #
+  #   require 'fastimage'
+  #
+  #   FastImage.size("http://stephensykes.com/images/ss.com_x.gif")
+  #   => [266, 56]
+  #   FastImage.size("http://stephensykes.com/images/pngimage")
+  #   => [16, 16]
+  #   FastImage.size("http://farm4.static.flickr.com/3023/3047236863_9dce98b836.jpg")
+  #   => [500, 375]
+  #   FastImage.size("http://www-ece.rice.edu/~wakin/images/lena512.bmp")
+  #   => [512, 512]
+  #   FastImage.size("test/fixtures/test.jpg")
+  #   => [882, 470]
+  #   FastImage.size("http://pennysmalls.com/does_not_exist")
+  #   => nil
+  #   FastImage.size("http://pennysmalls.com/does_not_exist", :raise_on_failure=>true)
+  #   => raises FastImage::ImageFetchFailure
+  #   FastImage.size("http://stephensykes.com/favicon.ico", :raise_on_failure=>true)
+  #   => raises FastImage::UnknownImageType
+  #   FastImage.size("http://stephensykes.com/favicon.ico", :raise_on_failure=>true, :timeout=>0.01)
+  #   => raises FastImage::ImageFetchFailure
+  #   FastImage.size("http://stephensykes.com/images/faulty.jpg", :raise_on_failure=>true)
+  #   => raises FastImage::SizeNotFound
+  #
+  # === Supported options
+  # [:timeout]
+  #   Overrides the default timeout of 2 seconds.  Applies both to reading from and opening the http connection.
+  # [:raise_on_failure]
+  #   If set to true causes an exception to be raised if the image size cannot be found for any reason.
+  #
+  def self.size(uri, options={})
+    new(uri, options).size
+  end
+
+  # Returns an symbol indicating the image type fetched from a uri.
+  # It will return nil if the image could not be fetched, or if the image type was not recognised.
+  #
+  # By default there is a timeout of 2 seconds for opening and reading from a remote server.
+  # This can be changed by passing a :timeout => number_of_seconds in the options.
+  #
+  # If you wish FastImage to raise if it cannot find the type of the image for any reason, then pass
+  # :raise_on_failure => true in the options.
+  #
+  # === Example
+  #
+  #   require 'fastimage'
+  #
+  #   FastImage.type("http://stephensykes.com/images/ss.com_x.gif")
+  #   => :gif
+  #   FastImage.type("http://stephensykes.com/images/pngimage")
+  #   => :png
+  #   FastImage.type("http://farm4.static.flickr.com/3023/3047236863_9dce98b836.jpg")
+  #   => :jpeg
+  #   FastImage.type("http://www-ece.rice.edu/~wakin/images/lena512.bmp")
+  #   => :bmp
+  #   FastImage.type("test/fixtures/test.jpg")
+  #   => :jpeg
+  #   FastImage.type("http://pennysmalls.com/does_not_exist")
+  #   => nil
+  #
+  # === Supported options
+  # [:timeout]
+  #   Overrides the default timeout of 2 seconds.  Applies both to reading from and opening the http connection.
+  # [:raise_on_failure]
+  #   If set to true causes an exception to be raised if the image type cannot be found for any reason.
+  #
+  def self.type(uri, options={})
+    new(uri, options.merge(:type_only=>true)).type
+  end
+
+  def initialize(uri, options={})
+    @property = options[:type_only] ? :type : :size
+    @timeout = options[:timeout] || DefaultTimeout
+    @uri = uri
+    @parsed_uri = URI.parse(uri)
+    if @parsed_uri.scheme == "http" || @parsed_uri.scheme == "https"
+      fetch_using_http
+    else
+      fetch_using_open_uri
+    end
+    raise SizeNotFound if options[:raise_on_failure] && @property == :size && !@size
+  rescue Timeout::Error, SocketError, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ECONNRESET, ImageFetchFailure
+    raise ImageFetchFailure if options[:raise_on_failure]
+  rescue Errno::ENOENT
+    raise ImageFetchFailure if options[:raise_on_failure]    
+  rescue UnknownImageType
+    raise UnknownImageType if options[:raise_on_failure]
+  end
+
+  private
+
+  def fetch_using_http
+    setup_http
+    @http.request_get(@parsed_uri.request_uri) do |res|
+      raise ImageFetchFailure unless res.is_a?(Net::HTTPSuccess)
+      res.read_body do |str|
+        break if parse_packet(str)
+      end
+    end
+  end
+
+  def setup_http
+    @http = Net::HTTP.new(@parsed_uri.host, @parsed_uri.port)
+    @http.use_ssl = (@parsed_uri.scheme == "https")
+    @http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+    @http.open_timeout = @timeout
+    @http.read_timeout = @timeout
+  end
+
+  def fetch_using_open_uri
+    open(@uri) do |s|
+      while str = s.read(LocalFileChunkSize)
+        break if parse_packet(str)
+      end
+    end
+  end
+
+  # returns true once result is achieved
+  #
+  def parse_packet(str)
+    @str = (@unused_str || "") + str
+    @strpos = 0
+    begin
+      result = send("parse_#{@property}")
+      if result 
+        instance_variable_set("@#{@property}", result)
+        true
+      end
+    rescue MoreCharsNeeded
+      false
+    end
+  end
+
+  def parse_size
+    @type = parse_type unless @type
+    send("parse_size_for_#{@type}")
+  end
+
+  def get_chars(n)
+    if @strpos + n - 1 >= @str.size
+      @unused_str = @str[@strpos..-1]
+      raise MoreCharsNeeded
+    else
+      result = @str[@strpos..(@strpos + n - 1)]
+      @strpos += n
+      result
+    end
+  end
+
+  def get_byte
+    get_chars(1).unpack("C")[0]
+  end
+
+  def read_int(str)
+    size_bytes = str.unpack("CC")
+    (size_bytes[0] << 8) + size_bytes[1]
+  end
+
+  def parse_type
+    case get_chars(2)
+    when "BM"
+      :bmp
+    when "GI"
+      :gif
+    when 0xff.chr + 0xd8.chr
+      :jpeg
+    when 0x89.chr + "P"
+      :png
+    else
+      raise UnknownImageType
+    end
+  end
+
+  def parse_size_for_gif
+    get_chars(9)[4..8].unpack('SS')
+  end
+
+  def parse_size_for_png
+    get_chars(23)[14..22].unpack('NN')
+  end
+
+  def parse_size_for_jpeg
+    loop do
+      @state = case @state
+      when nil
+        get_chars(2)
+        :started
+      when :started
+        get_byte == 0xFF ? :sof : :started          
+      when :sof
+        c = get_byte
+        if (0xe0..0xef).include?(c)
+          :skipframe
+        elsif [0xC0..0xC3, 0xC5..0xC7, 0xC9..0xCB, 0xCD..0xCF].detect {|r| r.include? c}
+          :readsize
+        else
+          :skipframe
+        end
+      when :skipframe
+        @skip_chars = read_int(get_chars(2)) - 2
+        :do_skip
+      when :do_skip
+        get_chars(@skip_chars)
+        :started
+      when :readsize
+        s = get_chars(7)
+        return [read_int(s[5..6]), read_int(s[3..4])]
+      end
+    end
+  end
+
+  def parse_size_for_bmp
+    d = get_chars(27)[12..26]
+    d[0] == 40 ? d[4..-1].unpack('LL') : d[4..8].unpack('SS')
+  end
+end

data/test/test.rb

@@ -0,0 +1,112 @@
+require 'rubygems'
+
+require 'test/unit'
+
+PathHere = File.dirname(__FILE__)
+
+require File.join(PathHere, "..", "lib", 'fastimage')
+
+require 'fakeweb'
+
+FixturePath = File.join(PathHere, "fixtures")
+
+GoodFixtures = {
+  "test.bmp"=>[:bmp, [40, 27]],
+  "test.gif"=>[:gif, [17, 32]],
+  "test.jpg"=>[:jpeg, [882, 470]],
+  "test.png"=>[:png, [30, 20]]
+  }
+
+BadFixtures = [
+  "faulty.jpg",
+  "test.ico"
+]
+
+TestUrl = "http://example.nowhere/"
+
+GoodFixtures.each do |fn, info|
+  FakeWeb.register_uri(:get, "#{TestUrl}#{fn}", :file => File.join(FixturePath, fn))
+end
+BadFixtures.each do |fn|
+  FakeWeb.register_uri(:get, "#{TestUrl}#{fn}", :file => File.join(FixturePath, fn))
+end
+
+class FasImageTest < Test::Unit::TestCase
+  def test_should_report_type_correctly
+    GoodFixtures.each do |fn, info|
+      assert_equal info[0], FastImage.type(TestUrl + fn)
+      assert_equal info[0], FastImage.type(TestUrl + fn, :raise_on_failure=>true)
+    end
+  end
+
+  def test_should_report_size_correctly
+    GoodFixtures.each do |fn, info|
+      assert_equal info[1], FastImage.size(TestUrl + fn)
+      assert_equal info[1], FastImage.size(TestUrl + fn, :raise_on_failure=>true)
+    end    
+  end
+  
+  def test_should_return_nil_on_fetch_failure
+    assert_nil FastImage.size(TestUrl + "does_not_exist")
+  end
+  
+  def test_should_return_nil_for_faulty_jpeg_where_size_cannot_be_found
+    assert_nil FastImage.size(TestUrl + "faulty.jpg")
+  end
+
+  def test_should_return_nil_when_image_type_not_known
+    assert_nil FastImage.size(TestUrl + "test.ico")
+  end
+  
+  def test_should_return_nil_if_timeout_occurs
+    assert_nil FastImage.size("http://example.com/does_not_exist", :timeout=>0.001)
+  end
+  
+  def test_should_raise_when_asked_to_when_size_cannot_be_found
+    assert_raises(FastImage::SizeNotFound) do
+      FastImage.size(TestUrl + "faulty.jpg", :raise_on_failure=>true)
+    end
+  end
+
+  def test_should_raise_when_asked_to_when_timeout_occurs
+    assert_raises(FastImage::ImageFetchFailure) do
+      FastImage.size("http://example.com/does_not_exist", :timeout=>0.001, :raise_on_failure=>true)
+    end
+  end
+
+  def test_should_raise_when_asked_when_image_type_not_known
+    assert_raises(FastImage::UnknownImageType) do
+      FastImage.size(TestUrl + "test.ico", :raise_on_failure=>true)
+    end
+  end
+  
+  def test_should_report_type_correctly_for_local_files
+    GoodFixtures.each do |fn, info|
+      assert_equal info[0], FastImage.type(File.join(FixturePath, fn))
+    end    
+  end
+  
+  def test_should_report_size_correctly_for_local_files
+    GoodFixtures.each do |fn, info|
+      assert_equal info[1], FastImage.size(File.join(FixturePath, fn))
+    end    
+  end
+  
+  def test_should_return_nil_on_fetch_failure_for_local_path
+    assert_nil FastImage.size("does_not_exist")
+  end
+  
+  def test_should_return_nil_for_faulty_jpeg_where_size_cannot_be_found_for_local_file
+    assert_nil FastImage.size(File.join(FixturePath, "faulty.jpg"))
+  end
+
+  def test_should_return_nil_when_image_type_not_known_for_local_file
+    assert_nil FastImage.size(File.join(FixturePath, "test.ico"))
+  end
+  
+  def test_should_raise_when_asked_to_when_size_cannot_be_found_for_local_file
+    assert_raises(FastImage::SizeNotFound) do
+      FastImage.size(File.join(FixturePath, "faulty.jpg"), :raise_on_failure=>true)
+    end
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: fastimage
+version: !ruby/object:Gem::Version 
+  version: 1.2.1
+platform: ruby
+authors: 
+- Stephen Sykes
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-10 00:00:00 +03:00
+default_executable: 
+dependencies: []
+
+description: FastImage finds the size or type of an image given its uri by fetching as little as needed.
+email: sdsykes@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- README.textile
+files: 
+- README
+- README.textile
+- Rakefile
+- VERSION.yml
+- lib/fastimage.rb
+- test/fixtures/faulty.jpg
+- test/fixtures/test.bmp
+- test/fixtures/test.gif
+- test/fixtures/test.ico
+- test/fixtures/test.jpg
+- test/fixtures/test.png
+- test/test.rb
+has_rdoc: true
+homepage: http://github.com/sdsykes/fastimage
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: FastImage - Image info fast
+test_files: 
+- test/test.rb