size 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b27ecf1e43545195565e4ff80ca2af55ab2084680f72d71bb7717bc1a622b561
+  data.tar.gz: 9b9d435f4dad02cf291efcc8eb6676690ca051f59d9fd19cd35b8392f4b35d18
+SHA512:
+  metadata.gz: 249659309d407e2ceb90da295911eed121d9ed48737787a4db47eb1edbf848396ad62774c6b203e71a3aad69c37d825470049bbaa5445fed878ec774153542f1
+  data.tar.gz: b2232e87e7b8b0deef83c4cf1c864450d0db310171fb54552e77eac3f4fc06d4908dcc0c775b92d37313bf929bcf2e572d5ccd214e84deb9bd8a3e3078055fd1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Shannon Skipper
+
+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,54 @@
+# Size
+
+Detect AVIF, GIF, HEIF, JPEG, PNG and WebP image dimensions with minimal memory usage. Pure Ruby, no deps.
+
+## Usage
+
+```ruby
+size = Size.of("photo.jpg")
+size.width  #=> 1920
+size.height #=> 1080
+size.pixels #=> 2073600
+size.class  #=> Size::JPEG
+```
+
+Accepts a file path, `Pathname` or any readable IO:
+
+```ruby
+File.open("photo.png", "rb") { |io| Size.of(io) }
+```
+
+Pattern matching works since `Size` is a `Data` class:
+
+```ruby
+case Size.of(path)
+in Size::PNG[width:, height:]
+  "PNG: #{width}x#{height}"
+in Size::JPEG[width:, height:]
+  "JPEG: #{width}x#{height}"
+end
+```
+
+Supports AVIF, GIF, HEIF, JPEG, PNG and WebP. Raises `Size::FormatError` for unrecognized or truncated formats.
+
+## Installation
+
+```bash
+gem install size
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "size"
+```
+
+## Alternatives
+
+**[FastImage](https://github.com/sdsykes/fastimage)** is the most popular choice. It fetches dimensions from URLs, covers many more formats (BMP, TIFF, ICO, PSD, SVG and others) and has years of production use behind it. Locally it reads through a Fiber-based pipeline in 256-byte chunks.
+
+**[ImageSize](https://github.com/toy/image_size)** has the broadest format coverage, with BMP, PSD, SWF, XPM and more. It reads in cached 4,096-byte chunks.
+
+**[Size](https://github.com/havenwood/size)** covers six formats and works only with local files and I/O objects. It reads the minimum each format requires: 10 bytes for a GIF, 24 for a PNG, 25–30 for WebP and up to 512 for AVIF and HEIF. All three gems stream through JPEG markers, but FastImage begins with 256 bytes in memory, ImageSize with 4,096 and Size with 12.
+
+For URL support or broad format coverage, use FastImage or ImageSize. For the smallest possible memory usage, use Size.

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+require "standard/rake"
+
+task default: %i[test standard]
+
+Minitest::TestTask.create

data/lib/size/avif.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Size::AVIF < Size
+  BRANDS = %w[avif avis].freeze
+
+  extend Size::ISOBMFF
+end

data/lib/size/gif.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class Size::GIF < Size
+  def self.read(_io, header)
+    unless header.start_with?("GIF87a", "GIF89a")
+      raise Size::FormatError, "invalid GIF signature"
+    end
+
+    width, height = header.unpack("x6v2")
+    new(width:, height:)
+  end
+end

data/lib/size/heif.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Size::HEIF < Size
+  BRANDS = %w[heic heix hevc hevx heim heis hevm hevs].freeze
+
+  extend Size::ISOBMFF
+end

data/lib/size/isobmff.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Size::ISOBMFF
+  def read_isobmff(data) = find_ispe(data, data.unpack1("N"))
+
+  def brand?(data, ftyp_size)
+    return true if self::BRANDS.include?(data.byteslice(8, 4))
+
+    offset = 16
+    while offset + 4 <= ftyp_size
+      return true if self::BRANDS.include?(data.byteslice(offset, 4))
+
+      offset += 4
+    end
+
+    false
+  end
+
+  private
+
+  def find_ispe(data, pos)
+    format_name = name.split("::").last
+
+    while pos + 8 <= data.bytesize
+      size = data.unpack1("N", offset: pos)
+      type = data.byteslice(pos + 4, 4)
+      raise Size::FormatError, "invalid #{format_name} box" if size < 8
+
+      case type
+      when "ispe"
+        raise Size::FormatError, "truncated #{format_name}" unless pos + 20 <= data.bytesize
+        width, height = data.unpack("N2", offset: pos + 12)
+
+        return new(width:, height:)
+      when "meta"
+        pos += 12 # FullBox header
+      when "iprp", "ipco"
+        pos += 8
+      else
+        pos += size
+      end
+    end
+
+    raise Size::FormatError, "no dimensions found in #{format_name}"
+  end
+end

data/lib/size/jpeg.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+class Size::JPEG < Size
+  SOF_MARKERS = ((0xC0..0xCF).to_a - [0xC4, 0xC8, 0xCC]).freeze
+  STANDALONE = [0x00, 0x01, *0xD0..0xD9].freeze
+
+  class << self
+    def read(io, header)
+      io = Size::PrefixedIO.new(header, io)
+      raise Size::FormatError, "invalid JPEG" unless io.read(2) == "\xFF\xD8".b
+
+      loop do
+        marker = read_marker(io)
+        raise Size::FormatError, "no SOF marker before end of image" if marker == 0xD9
+
+        if SOF_MARKERS.include?(marker)
+          seg = io.read(7)
+          raise Size::FormatError, "truncated JPEG SOF" unless seg&.bytesize == 7
+
+          height, width = seg.unpack("x3n2")
+          return new(width:, height:)
+        end
+
+        skip_segment(io)
+      end
+    end
+
+    private
+
+    def read_marker(io)
+      loop do
+        byte = io.read(1)&.ord
+        raise Size::FormatError, "truncated JPEG" unless byte
+        next unless byte == 0xFF
+
+        loop do
+          marker = io.read(1)&.ord
+          raise Size::FormatError, "truncated JPEG" unless marker
+          next if marker == 0xFF
+          next if STANDALONE.include?(marker)
+
+          return marker
+        end
+      end
+    end
+
+    def skip_segment(io)
+      len_bytes = io.read(2)
+      raise Size::FormatError, "truncated JPEG" unless len_bytes&.bytesize == 2
+
+      len = len_bytes.unpack1("n")
+      skipped = io.read(len - 2)
+      raise Size::FormatError, "truncated JPEG" unless skipped&.bytesize == len - 2
+    end
+  end
+end

data/lib/size/png.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class Size::PNG < Size
+  SIGNATURE = "\x89PNG\r\n\x1A\n".b
+
+  def self.read(io, header)
+    data = header
+    rest = io.read(12)
+    data += rest if rest
+    raise Size::FormatError, "truncated PNG" unless data.bytesize == 24
+    raise Size::FormatError, "invalid PNG signature" unless data.start_with?(SIGNATURE)
+
+    width, height = data.unpack("x16N2")
+    new(width:, height:)
+  end
+end

data/lib/size/prefixed_io.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class Size::PrefixedIO
+  def initialize(prefix, io)
+    @prefix = prefix
+    @io = io
+    @pos = 0
+  end
+
+  def read(n)
+    return @io.read(n) if @pos >= @prefix.bytesize
+
+    from_prefix = @prefix.byteslice(@pos, n)
+    @pos += from_prefix.bytesize
+    remaining = n - from_prefix.bytesize
+
+    if remaining > 0
+      from_io = @io.read(remaining)
+      from_prefix += from_io if from_io
+    end
+
+    from_prefix unless from_prefix.empty?
+  end
+end

data/lib/size/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Size
+  VERSION = "0.1.0"
+end

data/lib/size/webp.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+class Size::WebP < Size
+  class << self
+    def read(io, header)
+      data = header
+      rest = io.read(18)
+      data += rest if rest
+      fourcc = data.byteslice(12, 4)
+
+      case fourcc
+      when "VP8 "
+        read_vp8(data)
+      when "VP8L"
+        read_vp8l(data)
+      when "VP8X"
+        read_vp8x(data)
+      else
+        raise Size::FormatError, "unrecognized WebP variant: #{fourcc.inspect}"
+      end
+    end
+
+    private
+
+    def read_vp8(data)
+      raise Size::FormatError, "truncated WebP VP8" unless data.bytesize >= 30
+      raise Size::FormatError, "invalid VP8 keyframe" unless data.byteslice(23, 3) == "\x9D\x01\x2A".b
+
+      width, height = data.unpack("x26v2")
+      new(width: width & 0x3FFF, height: height & 0x3FFF)
+    end
+
+    def read_vp8l(data)
+      raise Size::FormatError, "truncated WebP VP8L" unless data.bytesize >= 25
+      raise Size::FormatError, "invalid VP8L signature" unless data.getbyte(20) == 0x2F
+
+      bits = data.unpack1("V", offset: 21)
+      new(width: (bits & 0x3FFF) + 1, height: ((bits >> 14) & 0x3FFF) + 1)
+    end
+
+    def read_vp8x(data)
+      raise Size::FormatError, "truncated WebP VP8X" unless data.bytesize >= 30
+
+      w = data.getbyte(24) | (data.getbyte(25) << 8) | (data.getbyte(26) << 16)
+      h = data.getbyte(27) | (data.getbyte(28) << 8) | (data.getbyte(29) << 16)
+      new(width: w + 1, height: h + 1)
+    end
+  end
+end

data/lib/size.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+Size = Data.define(:width, :height)
+
+require_relative "size/version"
+require_relative "size/prefixed_io"
+require_relative "size/isobmff"
+require_relative "size/avif"
+require_relative "size/gif"
+require_relative "size/heif"
+require_relative "size/jpeg"
+require_relative "size/png"
+require_relative "size/webp"
+
+class Size
+  def pixels = width * height
+
+  class FormatError < StandardError
+    def initialize(message = "unrecognized image format") = super
+  end
+
+  class << self
+    def of(input)
+      case input
+      when String, Pathname
+        File.open(input, "rb") { |io| read(io) }
+      else
+        read(input)
+      end
+    end
+
+    private
+
+    def read(io)
+      header = io.read(12)
+      raise FormatError, "could not read image header" unless header&.bytesize == 12
+
+      if header.start_with?("\x89PNG".b)
+        PNG.read(io, header)
+      elsif header.start_with?("\xFF\xD8".b)
+        JPEG.read(io, header)
+      elsif header.start_with?("GIF".b)
+        GIF.read(io, header)
+      elsif header[0, 4] == "RIFF" && header[8, 4] == "WEBP"
+        WebP.read(io, header)
+      elsif header[4, 4] == "ftyp"
+        isobmff_read(io, header)
+      else
+        raise FormatError
+      end
+    end
+
+    def isobmff_read(io, header)
+      data = header
+      rest = io.read(500)
+      data += rest if rest
+      ftyp_size = data.unpack1("N")
+
+      klass = [AVIF, HEIF].find { |format| format.brand?(data, ftyp_size) }
+      raise FormatError unless klass
+
+      klass.read_isobmff(data)
+    end
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: size
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shannon Skipper
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A pure Ruby library for detecting image dimensions by reading the minimum
+  bytes from AVIF, GIF, HEIF, JPEG, PNG and WebP files
+email:
+- shannonskipper@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/size.rb
+- lib/size/avif.rb
+- lib/size/gif.rb
+- lib/size/heif.rb
+- lib/size/isobmff.rb
+- lib/size/jpeg.rb
+- lib/size/png.rb
+- lib/size/prefixed_io.rb
+- lib/size/version.rb
+- lib/size/webp.rb
+homepage: https://github.com/havenwood/size
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/havenwood/size
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.7
+specification_version: 4
+summary: Detect image dimensions with minimal reads
+test_files: []