!travis-ci.org/sdsykes/fastimage.png?branch=master!:https://travis-ci.org/sdsykes/fastimage

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 common image types (GIF, PNG, BMP etc.), 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 much of the image to find the size.

FastImage does this minimal fetch for image types GIF, JPEG, PNG, TIFF, BMP, ICO, CUR, PSD and WEBP. 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.

h2. Features

Fastimage can also read local (and other) files, and uses the open-uri library to do so.

FastImage will automatically read from any object that responds to :read - for instance an IO object if that is passed instead of a URI.

FastImage will follow up to 4 HTTP redirects to get the image.

FastImage will obey the http_proxy setting in your environment to route requests via a proxy.

You can add a timeout to the request which will limit the request time by passing :timeout => number_of_seconds.

FastImage normally replies will nil if it encounters an error, but you can pass :raise_on_failure => true to get an exception.

You may optionally use the ‘addressable` gem for URI parsing or a custom URI parser.

To use the ‘addressable` gem for uri parsing.

<pre lang=“ruby”> require 'addressable/uri' FastImage.use_addressable_uri_parser </pre>

To use a custom URI parser like, for example, the old URI parser in Ruby 2.2 for example use:

<pre lang=“ruby”> FastImage.uri_parser = URI::RFC2396_Parser.new </pre>

h2. Examples

<pre lang=“ruby”><code> require ‘fastimage’

FastImage.size(“”)

> [266, 56] # width, height

FastImage.type(“stephensykes.com/images/pngimage”)

> :png

FastImage.type(“/some/local/file.gif”)

> :gif

FastImage.size(“”, :raise_on_failure=>true, :timeout=>0.1)

> FastImage::ImageFetchFailure: FastImage::ImageFetchFailure

FastImage.size(“”, :raise_on_failure=>true, :timeout=>2.0)

> [9545, 6623]

</code></pre>

h2. Installation

h4. Gem

bc. gem install fastimage

h4. Rails

Add fastimage to your Gemfile, and bundle.

Then you’re off - just use @FastImage.size()@ and @FastImage.type()@ in your code as in the examples.

h2. Documentation

sdsykes.github.io/fastimage/rdoc/FastImage.html”:http://sdsykes.github.io/fastimage/rdoc/FastImage.html

h2. Benchmark

It’s way faster than conventional methods (for example the image_size gem) for most types of file when fetching over the wire.

<pre lang=“ruby”><code> irb> uri = “” irb> puts Benchmark.measure {open(uri, ‘rb’) {|fh| p ImageSize.new(fh).size}}

9545, 6623

0.680000 0.250000 0.930000 ( 7.571887)

irb> puts Benchmark.measure {p FastImage.size(uri)}

9545, 6623

0.010000 0.000000 0.010000 ( 0.090640)

</code></pre>

The file is fetched in about 7.5 seconds in this test (the number in brackets is the total time taken), but as FastImage doesn’t need to fetch the whole thing, it completes in less than 0.1s.

You’ll see similar excellent results for the other file types, except for TIFF. Unfortunately TIFFs tend to have their metadata towards the end of the file, so it makes little difference to do a minimal fetch. The result shown below is mostly dependent on the exact internet conditions during the test, and little to do with the library used.

<pre lang=“ruby”><code> irb> uri = “upload.wikimedia.org/wikipedia/commons/1/11/Shinbutsureijoushuincho.tiff” irb> puts Benchmark.measure {open(uri, ‘rb’) {|fh| p ImageSize.new(fh).size}}

1120, 1559

1.080000 0.370000 1.450000 ( 13.766962)

irb> puts Benchmark.measure {p FastImage.size(uri)}

1120, 1559

3.490000 3.810000 7.300000 ( 11.754315)

</code></pre>

h2. Tests

You’ll need to @gem install fakeweb@ and possibly also @gem install test-unit@ to be able to run the tests.

bc.. $ ruby test.rb Run options:

# Running tests:

Finished tests in 1.033640s, 23.2189 tests/s, 82.2337 assertions/s.

24 tests, 85 assertions, 0 failures, 0 errors, 0 skips

h2. References

h2. FastImage in other languages

h2. Licence

MIT, see file “MIT-LICENSE”:MIT-LICENSE

h2. Contributors

Pull requests and suggestions are always welcome. Thanks to all the contributors!