dimensions 1.0.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Sam Stephenson
+
+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,89 @@
+Dimensions
+==========
+
+Dimensions is a pure Ruby library for reading the width, height and
+rotation angle of GIF, PNG and JPEG images.
+
+Use the `dimensions`, `width` and `height` methods on the `Dimensions`
+module to measure image files:
+
+```ruby
+require 'dimensions'
+
+Dimensions.dimensions("upload_bird.jpg")  # => [300, 225]
+Dimensions.width("upload_bird.jpg")       # => 300
+Dimensions.height("upload_bird.jpg")      # => 225
+```
+
+Many cameras and smartphones set the EXIF orientation attribute for
+photos taken in portrait or landscape mode. The Dimensions library
+reads this attribute and swaps the `width` and `height` values
+automatically to accurately reflect how the image looks when
+rotated. You can use the `angle` method to check a JPEG image's
+orientation in degrees:
+
+```ruby
+Dimensions.angle("upload_bird.jpg")       # => 0
+Dimensions.angle("rotated.jpg")           # => 90
+```
+
+### Reading dimensions from a stream
+
+Pass an IO object to the `Dimensions` method to extend it with the
+`Dimensions::IO` module and transparently detect its dimensions and
+orientation as it is read. Once the IO has been sufficiently read, its
+`width`, `height` and `angle` methods will return non-nil values
+(assuming its contents are an image).
+
+```ruby
+require 'dimensions'
+require 'json'
+require 'securerandom'
+
+module Uploader
+  def self.call(env)
+    body = Dimensions(env["rack.input"])
+
+    # Handle the upload
+    token = SecureRandom.hex(20)
+    path  = File.join(UPLOAD_PATH, token)
+    File.open(path, "wb") { |file| file.write body.read }
+
+    # Return the width and height as JSON
+    [
+      200,
+      {"Content-Type" => "application/json"},
+      [JSON.dump(
+        "token"  => token,
+        "width"  => body.width,
+        "height" => body.height
+      )]
+    ]
+  end
+end
+```
+
+### License
+
+(The MIT License)
+
+Copyright © 2011 Sam Stephenson
+
+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/lib/dimensions.rb

@@ -0,0 +1,50 @@
+require 'dimensions/exif_scanner'
+require 'dimensions/io'
+require 'dimensions/jpeg_scanner'
+require 'dimensions/reader'
+require 'dimensions/scanner'
+require 'dimensions/version'
+
+# Extends an IO object with the `Dimensions::IO` module, which adds
+# `dimensions`, `width`, `height` and `angle` methods. The methods
+# will return non-nil values once the IO has been sufficiently read,
+# assuming its contents are an image.
+def Dimensions(io)
+  io.extend(Dimensions::IO)
+end
+
+module Dimensions
+  class << self
+    # Returns an array of [width, height] representing the dimensions
+    # of the image at the given path.
+    def dimensions(path)
+      io_for(path).dimensions
+    end
+
+    # Returns the width of the image at the given path.
+    def width(path)
+      io_for(path).width
+    end
+
+    # Returns the height of the image at the given path.
+    def height(path)
+      io_for(path).height
+    end
+
+    # Returns the rotation angle of the JPEG image at the given
+    # path. If the JPEG is rotated 90 or 270 degrees (as is often the
+    # case with photos from smartphones, for example) its width and
+    # height will be swapped to accurately reflect the rotation.
+    def angle(path)
+      io_for(path).angle
+    end
+
+    private
+      def io_for(path)
+        Dimensions(File.open(path, "rb")).tap do |io|
+          io.read
+          io.close
+        end
+      end
+  end
+end

data/lib/dimensions/exif_scanner.rb

@@ -0,0 +1,61 @@
+require 'dimensions/scanner'
+
+module Dimensions
+  class ExifScanner < Scanner
+    ORIENTATIONS = [
+      :top_left,
+      :top_right,
+      :bottom_right,
+      :bottom_left,
+      :left_top,
+      :right_top,
+      :right_bottom,
+      :left_bottom
+    ]
+
+    attr_reader :orientation
+
+    def initialize(data)
+      @orientation = nil
+      super
+    end
+
+    def scan
+      scan_header
+
+      offset = read_long + 6
+      skip_to(offset)
+
+      # Note: This only checks the first IFD for orientation entries,
+      # which seems to work fine in my (limited) testing but might not
+      # play out in practice.
+      entry_count = read_short
+      entry_count.times do |i|
+        skip_to(offset + 2 + (12 * i))
+        tag = read_short
+
+        if tag == 0x0112 # orientation
+          advance(6)
+          @orientation = ORIENTATIONS[read_short - 1]
+        end
+      end
+
+      @orientation
+    end
+
+    def scan_header
+      advance(6)
+      scan_endianness
+      scan_tag_mark
+    end
+
+    def scan_endianness
+      tag = [read_char, read_char]
+      @big = tag == [0x4D, 0x4D]
+    end
+
+    def scan_tag_mark
+      raise ScanError unless read_short == 0x002A
+    end
+  end
+end

data/lib/dimensions/io.rb

@@ -0,0 +1,31 @@
+require 'dimensions/reader'
+
+module Dimensions
+  module IO
+    def self.extended(io)
+      io.instance_variable_set(:@reader, Reader.new)
+    end
+
+    def read(*args)
+      super.tap do |data|
+        @reader << data if data
+      end
+    end
+
+    def dimensions
+      [width, height] if width && height
+    end
+
+    def width
+      @reader.width
+    end
+
+    def height
+      @reader.height
+    end
+
+    def angle
+      @reader.angle
+    end
+  end
+end

data/lib/dimensions/jpeg_scanner.rb

@@ -0,0 +1,86 @@
+require 'dimensions/exif_scanner'
+
+module Dimensions
+  class JpegScanner < Scanner
+    SOF_MARKERS = [0xC0..0xC3, 0xC5..0xC7, 0xC9..0xCB, 0xCD..0xCF]
+    EOI_MARKER  = 0xD9  # end of image
+    SOS_MARKER  = 0xDA  # start of stream
+    APP1_MARKER = 0xE1  # maybe EXIF
+
+    attr_reader :width, :height, :angle
+
+    def initialize(data)
+      @width  = nil
+      @height = nil
+      @angle  = 0
+      super
+    end
+
+    def scan
+      advance(2)
+
+      while marker = read_next_marker
+        case marker
+        when *SOF_MARKERS
+          scan_start_of_frame
+        when EOI_MARKER, SOS_MARKER
+          break
+        when APP1_MARKER
+          scan_app1_frame
+        else
+          skip_frame
+        end
+      end
+
+      width && height
+    end
+
+    def read_next_marker
+      c = read_char while c != 0xFF
+      c = read_char while c == 0xFF
+      c
+    end
+
+    def scan_start_of_frame
+      length = read_short
+      depth  = read_char
+      height = read_short
+      width  = read_short
+      size   = read_char
+
+      if length == (size * 3) + 8
+        @width, @height = width, height
+      else
+        raise ScanError
+      end
+    end
+
+    def scan_app1_frame
+      frame = read_frame
+      if frame[0..5] == "Exif\000\000"
+        scanner = ExifScanner.new(frame)
+        if scanner.scan
+          case scanner.orientation
+          when :bottom_right
+            @angle = 180
+          when :left_top, :right_top
+            @angle = 90
+          when :right_bottom, :left_bottom
+            @angle = 270
+          end
+        end
+      end
+    rescue ExifScanner::ScanError
+    end
+
+    def read_frame
+      length = read_short - 2
+      read_data(length)
+    end
+
+    def skip_frame
+      length = read_short - 2
+      advance(length)
+    end
+  end
+end

data/lib/dimensions/reader.rb

@@ -0,0 +1,84 @@
+require 'dimensions/jpeg_scanner'
+
+module Dimensions
+  class Reader
+    GIF_HEADER  = [0x47, 0x49, 0x46, 0x38]
+    PNG_HEADER  = [0x89, 0x50, 0x4E, 0x47]
+    JPEG_HEADER = [0xFF, 0xD8, 0xFF]
+
+    attr_reader :type, :width, :height, :angle
+
+    def initialize
+      @process = :determine_type
+      @type    = nil
+      @width   = nil
+      @height  = nil
+      @angle   = nil
+      @size    = 0
+      @data    = ""
+      @data.force_encoding("BINARY") if @data.respond_to?(:force_encoding)
+    end
+
+    def <<(data)
+      if @process
+        @data << data
+        @size = @data.length
+        process
+      end
+    end
+
+    def process(process = @process)
+      send(@process) if @process = process
+    end
+
+    def determine_type
+      if @size >= 4
+        bytes = @data.unpack("C4")
+
+        if match_header(GIF_HEADER, bytes)
+          @type = :gif
+        elsif match_header(PNG_HEADER, bytes)
+          @type = :png
+        elsif match_header(JPEG_HEADER, bytes)
+          @type = :jpeg
+        end
+
+        process @type ? :"extract_#{type}_dimensions" : nil
+      end
+    end
+
+    def extract_gif_dimensions
+      if @size >= 10
+        @width, @height = @data.unpack("x6v2")
+        process nil
+      end
+    end
+
+    def extract_png_dimensions
+      if @size >= 24
+        @width, @height = @data.unpack("x16N2")
+        process nil
+      end
+    end
+
+    def extract_jpeg_dimensions
+      scanner = JpegScanner.new(@data)
+      if scanner.scan
+        @width  = scanner.width
+        @height = scanner.height
+        @angle  = scanner.angle
+
+        if @angle == 90 || @angle == 270
+          @width, @height = @height, @width
+        end
+
+        process nil
+      end
+    rescue JpegScanner::ScanError
+    end
+
+    def match_header(header, bytes)
+      bytes[0, header.length] == header
+    end
+  end
+end

data/lib/dimensions/scanner.rb

@@ -0,0 +1,46 @@
+module Dimensions
+  class Scanner
+    class ScanError < ::StandardError; end
+
+    def initialize(data)
+      @data = data.dup
+      @data.force_encoding("BINARY") if @data.respond_to?(:force_encoding)
+      @size = @data.length
+      @pos  = 0
+      @big  = true  # endianness
+    end
+
+    def read_char
+      read(1, "C")
+    end
+
+    def read_short
+      read(2, @big ? "n" : "v")
+    end
+
+    def read_long
+      read(4, @big ? "N" : "V")
+    end
+
+    def read(size, format)
+      data = read_data(size)
+      data.unpack(format)[0]
+    end
+
+    def read_data(size)
+      data = @data[@pos, size]
+      advance(size)
+      data
+    end
+
+    def advance(length)
+      @pos += length
+      raise ScanError if @pos > @size
+    end
+
+    def skip_to(pos)
+      @pos = pos
+      raise ScanError if @pos > @size
+    end
+  end
+end

data/lib/dimensions/version.rb

@@ -0,0 +1,3 @@
+module Dimensions
+  VERSION = "1.0.0"
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: dimensions
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: 
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Sam Stephenson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-01 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: A pure Ruby library for measuring the dimensions and rotation angles of GIF, PNG and JPEG images.
+email: 
+- sstephenson@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.md
+- LICENSE
+- lib/dimensions/exif_scanner.rb
+- lib/dimensions/io.rb
+- lib/dimensions/jpeg_scanner.rb
+- lib/dimensions/reader.rb
+- lib/dimensions/scanner.rb
+- lib/dimensions/version.rb
+- lib/dimensions.rb
+has_rdoc: true
+homepage: https://github.com/sstephenson/dimensions
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.0
+signing_key: 
+specification_version: 3
+summary: Pure Ruby dimension measurement for GIF, PNG and JPEG images
+test_files: []
+