flipbook 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21a1c656c9c85bbfdc6ace9cc7c09f3cbc8546c4f716d899d9bc72a1ec42e30b
-  data.tar.gz: fd9bda09b22c184e7f95933a9a795edfe4739e965eb1d0fc254d7eb35705a14b
+  metadata.gz: ed6c3ae7ae41a6819cbd15890ebe7002b9637c2a2afb51e1f185ac7cf4c4b39c
+  data.tar.gz: 59c4fcbf5f6fce4baa22c359a54334d873403bf2ee6904ab483770cca41a5ab1
 SHA512:
-  metadata.gz: fdd1e8f6929f091b6dad1e8de5fc892ae6e17704d53ac564911962a2671c70e3f2864d751860ea66be5908b065a2276256b2a38e1ef6b4cb35db15fe68a6773c
-  data.tar.gz: cd3b12ca02ee239a641db540dede16bcc59647087e083a1cf78205d3b01ec2364c961d412dd9426ced032a839366d98c703f8d1b890b9a1e9d93338d02c5a91c
+  metadata.gz: 3047e42608ce4f1d5653fa4573fc2d9c210e5b732557bb65cf2f41f8087aa8f6b81c1a3e895f4cadc3e03c8c83b532bfaa8ea51a47bd557bcf890bd0fb42e949
+  data.tar.gz: 44abccb00089ba9fe0d6b16657c36c2967d506a69e923e42d31971260b09461d405f755e3d195f6fd5a50aadea68971686b0ba101217d1b74bf524887183f375

data/CHANGELOG.md

@@ -1,10 +1,7 @@
 # Changelog
 
-## [0.2.0] - 2026-09-25
+## [0.3.0] - 2026-09-24
 
-- Add APNG writing with rational frame delays, alpha, and changed-region cropping.
-- Crop unchanged regions in opaque GIF frames to reduce animation size.
-
-## [0.1.0] - 2026-09-25
-
-Initial release
+- Add GIF89a encoding, animated PNG encoding, and GIF decoding.
+- Add streaming writers, cumulative frame timing, palette quantization, transparency, and frame-difference output.
+- Add the `Flipbook.write` and `Flipbook.read` APIs.

data/README.md

@@ -1,6 +1,6 @@
 <h1 align="center">Flipbook</h1>
 
-<p align="center">Write optimized animated GIF and APNG files from Ruby images.</p>
+<p align="center">Turn a sequence of RGBA images into animated GIF or APNG files.</p>
 
 <p align="center">
   <a href="https://rubygems.org/gems/flipbook"><img src="https://badge.fury.io/rb/flipbook.svg" alt="Gem version"></a>
@@ -8,20 +8,20 @@
   <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-750014.svg" alt="License"></a>
 </p>
 
-[Formats](#formats) · [Installation](#installation) · [API](#api) · [Examples](#examples) · [Development](#development)
+[Formats](#formats) · [Installation](#installation) · [API](#api) · [Development](#development)
 
 ---
 
-Flipbook writes animated GIFs and APNGs from [`Tessel::Image`](https://github.com/rbgfx/tessel) frames. GIF palettes use Tessel's shared quantizer; APNG keeps full RGBA color. Both writers can crop unchanged frame regions.
+Flipbook writes animated GIF and APNG from [`Tessel::Image`](https://github.com/rbgfx/tessel) frames. GIF palettes use Tessel's shared quantizer. The library has no runtime dependency beyond Tessel and Ruby's standard library.
 
 ## Formats
 
-| Format | Colors | Transparency | Encoding |
+| Format | Color | Transparency | Reading |
 | --- | --- | --- | --- |
-| GIF | Up to 256 palette entries | One transparent palette index | GIF89a output with global or per-frame palettes and LZW |
-| APNG (`.png`, `.apng`) | Full RGBA | Full alpha | PNG-compatible first frame, `acTL` / `fcTL` / `fdAT` animation chunks |
+| GIF | Up to 256 palette entries | One transparent palette index | GIF87a/GIF89a frames, local and global palettes, interlace, and disposal methods |
+| APNG | RGBA8 | Full alpha | First frame through Tessel's PNG reader |
 
-GIF uses a single global palette by default so colors stay stable across frames. Use `palette: :per_frame` when streaming frames with different color ranges. Delta cropping is most effective for opaque GIF frames; APNG supports alpha-safe cropped updates.
+GIF uses a single global palette by default so colors stay stable across frames. Animated frames with transparent pixels are written as full frames with background disposal so pixels can become transparent correctly. Opaque animations use difference rectangles by default.
 
 ## Installation
 
@@ -43,6 +43,9 @@ frames = 60.times.map do |index|
 end
 
 Flipbook.write("animation.gif", frames, fps: 30, loop: true)
+Flipbook.write("animation.png", frames, fps: 30, loop: true)
+
+decoded_frames = Flipbook.read("animation.gif")
 ~~~
 
 Use `delay:` in seconds instead of `fps:`. It accepts one duration or one duration per frame; `Rational(1, 30)` avoids floating-point timing drift. GIF delays use cumulative centisecond rounding. Viewers may lengthen delays below 1/50 second.
@@ -55,30 +58,15 @@ Flipbook::GIF::Writer.open("recording.gif", width: 320, height: 240, palette: :p
 end
 ~~~
 
-Use a `.png` or `.apng` path for full-color animation. The first frame remains a valid PNG for viewers that do not animate APNG:
-
-~~~ruby
-Flipbook.write("animation.png", frames, fps: 30, loop: true)
-~~~
-
-`optimize: false` writes full-size frames. The default crops each changed frame to its smallest bounding rectangle. GIF cropping is used for opaque frames; APNG cropping preserves alpha changes.
+APNG also supports streaming output and patches its frame count when the destination can seek. Otherwise it buffers the animation until close.
 
 ### API contracts
 
-- `Flipbook.write(path, frames, fps: or delay:)` requires one or more same-sized `Tessel::Image` objects and a `.gif`, `.png`, or `.apng` output path.
-- `GIF::Writer#add` raises `TypeError` for non-image frames and `ArgumentError` for invalid dimensions or timing.
-- `APNG::Writer#add` accepts positive numeric delays in seconds and raises for frames that do not match the canvas dimensions.
+- `Flipbook.write(path, frames, fps: or delay:)` requires one or more same-sized `Tessel::Image` objects. The `.gif` extension selects GIF; `.png` and `.apng` select APNG.
+- `Flipbook.read(path)` returns composited GIF frames as `Tessel::Image` objects. `Flipbook::GIF::Reader#delays` returns each frame delay as a `Rational` in seconds.
+- `GIF::Writer#add` and `APNG::Writer#add` raise `TypeError` for non-image frames and `ArgumentError` for invalid dimensions or timing.
 - GIF palette colors are RGB triples of integer channels from 0 to 255. GIF transparency is binary; partial alpha is encoded as an opaque palette color.
-
-## Examples
-
-Generate a rotating square, a color gradient, and transparent GIF/APNG samples:
-
-~~~sh
-ruby examples/generate.rb
-~~~
-
-Pass an output directory as the first argument to choose where the files are written.
+- APNG chunks use RGBA8 pixels. The first frame is also a valid static PNG image.
 
 GIF format acknowledgement: The Graphics Interchange Format© is the Copyright property of CompuServe Incorporated. GIF® is a Service Mark property of CompuServe Incorporated.
 

data/docs/verification.md

@@ -1,14 +1,14 @@
 # File verification
 
-The test suite checks GIF LZW code-width growth and dictionary resets, frame timing, transparent palette entries, cropped frame bounds, APNG sequence numbers, and PNG chunk CRCs.
+The test suite checks GIF LZW code-width growth and dictionary resets, decodes generated animations, and validates APNG chunk ordering and sequence numbers.
 
 For an independent local check, install ImageMagick or gifsicle and inspect sample output:
 
 ~~~sh
-identify animation.gif
+identify animation.gif animation.png
 magick animation.gif -coalesce /tmp/flipbook-gif-%02d.png
+magick animation.png -coalesce /tmp/flipbook-apng-%02d.png
 gifsicle --info animation.gif
-magick identify animation.png
 ~~~
 
 These tools are optional and are not runtime dependencies.

data/lib/flipbook/apng/writer.rb

@@ -6,7 +6,7 @@ module Flipbook
   module APNG
     class Writer
       def self.open(path, **options)
-        io = File.open(path, "wb")
+        io = File.open(path, "wb+")
         writer = new(io, **options)
         writer.instance_variable_set(:@owns_io, true)
         return writer unless block_given?
@@ -22,54 +22,61 @@ module Flipbook
         raise
       end
 
-      def initialize(io, width:, height:, loop: true, optimize: true, buffered: nil)
+      def initialize(io, width:, height:, loop: true, optimize: true, level: Zlib::DEFAULT_COMPRESSION, filter: :none)
         @io = io
         @width = Integer(width)
         @height = Integer(height)
-        raise ArgumentError, "APNG dimensions must be between 1 and 2147483647" unless @width.between?(1, 2_147_483_647) && @height.between?(1, 2_147_483_647)
-        raise TypeError, "optimize must be true or false" unless [true, false].include?(optimize)
+        raise ArgumentError, "APNG dimensions must be positive" unless @width.positive? && @height.positive?
+        raise ArgumentError, "unknown PNG filter: #{filter}" unless %i[none sub up average paeth adaptive].include?(filter)
 
-        @loop = loop_count(loop)
+        @loop = plays(loop)
         @optimize = optimize
-        @buffered = buffered.nil? ? !seekable?(io) : buffered
-        @frames = []
-        @previous_image = nil
-        @frame_count = 0
+        @level = level
+        @filter = filter
+        @seekable = io.respond_to?(:pos) && io.respond_to?(:seek)
+        @storage = @seekable ? io : StringIO.new("".b)
+        @frames = 0
         @sequence = 0
+        @previous = nil
         @closed = false
-        write_header unless @buffered
+        @storage << Tessel::SIGNATURE
+        Tessel::PNG::Chunk.write(@storage, "IHDR", [@width, @height, 8, 6, 0, 0, 0].pack("N2C5"))
+        @animation_offset = @storage.pos
+        write_chunk("acTL", [0, @loop].pack("N2"))
       end
 
       def add(image, delay:)
         raise IOError, "APNG writer is closed" if @closed
         raise TypeError, "frame must be a Tessel::Image" unless image.is_a?(Tessel::Image)
-        raise ArgumentError, "frame dimensions must match the canvas" unless image.width == @width && image.height == @height
+        raise ArgumentError, "frame dimensions must match the animation" unless image.width == @width && image.height == @height
 
         seconds = Timing.duration(delay)
-        if @buffered
-          @frames << [image.dup, seconds]
+        left, top, width, height = @optimize ? Diff.bounds(@previous, image) : [0, 0, @width, @height]
+        frame = image.crop(left, top, width, height)
+        numerator, denominator = Timing.apng_fraction(seconds)
+        compressed = idat_data(frame)
+        raise Error, "APNG frame count exceeds the format limit" if @frames >= 0xFFFF_FFFF
+        control = [@sequence, width, height, left, top, numerator, denominator, 0, 0].pack("N5n2C2")
+        write_chunk("fcTL", control)
+        @sequence += 1
+        if @frames.zero?
+          write_chunk("IDAT", compressed)
         else
-          write_frame(image, seconds)
+          write_chunk("fdAT", [@sequence].pack("N") + compressed)
+          @sequence += 1
         end
-        @frame_count += 1
-        @previous_image = image.dup
+        @frames += 1
+        @previous = image.dup
         self
       end
 
       def close
-        return self if @closed
-        raise Error, "APNG contains no frames" if @frame_count.zero?
+        return if @closed
+        raise Error, "APNG contains no frames" if @frames.zero?
 
-        if @buffered
-          output = StringIO.new("".b)
-          writer = self.class.new(output, width: @width, height: @height, loop: @loop, optimize: @optimize, buffered: false)
-          @frames.each { |image, delay| writer.add(image, delay:) }
-          writer.close
-          @io.write(output.string)
-        else
-          write_chunk("IEND", "".b)
-          patch_animation_control
-        end
+        write_chunk("IEND", "".b)
+        finish_animation_control
+        @io << @storage.string if @storage != @io
         @closed = true
         @io.close if @owns_io && !@io.closed?
         self
@@ -77,90 +84,40 @@ module Flipbook
 
       private
 
-      def seekable?(io)
-        io.respond_to?(:pos) && io.respond_to?(:seek)
-      rescue IOError, SystemCallError
-        false
-      end
-
-      def loop_count(value)
+      def plays(value)
         return 0 if value == true
         return 1 if value == false
-        return value if value.is_a?(Integer) && value.between?(0, 0xffff_ffff)
+        return value if value.is_a?(Integer) && value.between?(0, 0xFFFF_FFFF)
 
         raise ArgumentError, "loop must be true, false, or an integer from 0 to 4294967295"
       end
 
-      def write_header
-        @io << Tessel::SIGNATURE
-        write_chunk("IHDR", [@width, @height, 8, 6, 0, 0, 0].pack("N2C5"))
-        @actl_data_position = @io.pos + 8
-        write_chunk("acTL", [1, @loop].pack("N2"))
-      end
-
-      def write_frame(image, delay)
-        rectangle = if @frame_count.zero? || !@optimize
-          [0, 0, @width, @height]
-        else
-          Diff.bounds(@previous_image, image) || [0, 0, 1, 1]
-        end
-        x, y, width, height = rectangle
-        frame = rectangle == [0, 0, @width, @height] ? image : image.crop(x, y, width, height)
-        numerator, denominator = delay_fraction(delay)
-        alpha = frame.bytes.bytes.each_slice(4).any? { |_, _, _, channel| channel < 255 }
-        blend = @frame_count.zero? || alpha ? 0 : 1
-        control = [@sequence, width, height, x, y].pack("N5") + [numerator, denominator, 0, blend].pack("n2C2")
-        write_chunk("fcTL", control)
-        @sequence += 1
-
-        png = Tessel::PNG::Encoder.encode(frame)
-        idat = png_chunks(png).select { |type, _| type == "IDAT" }.map(&:last).join
-        if @frame_count.zero?
-          write_chunk("IDAT", idat)
-        else
-          write_chunk("fdAT", [@sequence].pack("N") + idat)
-          @sequence += 1
-        end
-      end
-
-      def delay_fraction(delay)
-        raise ArgumentError, "APNG frame delay cannot exceed 65535 seconds" if delay > 65_535
-
-        if delay.numerator <= 65_535 && delay.denominator <= 65_535
-          return [delay.numerator, delay.denominator]
-        end
-
-        denominator = [65_535, (65_535 / delay).floor].min
-        denominator = 65_535 if denominator < 1
-        numerator = (delay * denominator).round.clamp(1, 65_535)
-        [numerator, denominator]
+      def write_chunk(type, data)
+        Tessel::PNG::Chunk.write(@storage, type, data)
       end
 
-      def png_chunks(png)
-        chunks = []
-        offset = Tessel::SIGNATURE.bytesize
-        while offset < png.bytesize
-          length = png.unpack1("N", offset:)
-          type = png.byteslice(offset + 4, 4)
-          data = png.byteslice(offset + 8, length)
-          chunks << [type, data]
-          offset += length + 12
+      def idat_data(image)
+        png = Tessel::PNG.encode(image, color_type: :rgba, filter: @filter, level: @level, metadata: {})
+        output = "".b
+        cursor = Tessel::SIGNATURE.bytesize
+        while cursor + 12 <= png.bytesize
+          length = png.byteslice(cursor, 4).unpack1("N")
+          type = png.byteslice(cursor + 4, 4)
+          output << png.byteslice(cursor + 8, length) if type == "IDAT"
+          cursor += length + 12
           break if type == "IEND"
         end
-        chunks
-      end
+        raise Error, "Tessel produced a PNG without image data" if output.empty?
 
-      def write_chunk(type, data)
-        Tessel::PNG::Chunk.write(@io, type, data)
+        output
       end
 
-      def patch_animation_control
-        end_position = @io.pos
-        data = [@frame_count, @loop].pack("N2")
-        @io.seek(@actl_data_position)
-        @io.write(data)
-        @io.write([Zlib.crc32("acTL".b + data)].pack("N"))
-        @io.seek(end_position)
+      def finish_animation_control
+        control = [@frames, @loop].pack("N2")
+        ending = @storage.pos
+        @storage.seek(@animation_offset)
+        write_chunk("acTL", control)
+        @storage.seek(ending)
       end
     end
   end

data/lib/flipbook/diff.rb

@@ -4,38 +4,27 @@ module Flipbook
   module Diff
     module_function
 
-    # Returns the smallest changed rectangle, or nil when the images match.
     def bounds(previous, current)
-      unless previous.is_a?(Tessel::Image) && current.is_a?(Tessel::Image)
-        raise TypeError, "frames must be Tessel::Image values"
-      end
-      unless previous.width == current.width && previous.height == current.height
-        raise ArgumentError, "frame dimensions must match"
-      end
+      raise TypeError, "current must be a Tessel::Image" unless current.is_a?(Tessel::Image)
+      return [0, 0, current.width, current.height] unless previous
+      raise TypeError, "previous must be a Tessel::Image" unless previous.is_a?(Tessel::Image)
+      raise ArgumentError, "image dimensions must match" unless previous.width == current.width && previous.height == current.height
 
-      left = current.width
-      top = current.height
-      right = -1
-      bottom = -1
-      before = previous.bytes
-      after = current.bytes
-      current.height.times do |y|
-        current.width.times do |x|
-          offset = (y * current.width + x) * 4
-          next if before.byteslice(offset, 4) == after.byteslice(offset, 4)
+      old_bytes = previous.bytes
+      new_bytes = current.bytes
+      left, top, right, bottom = current.width, current.height, -1, -1
+      (0...(current.width * current.height)).each do |index|
+        offset = index * 4
+        next if old_bytes.byteslice(offset, 4) == new_bytes.byteslice(offset, 4)
 
-          left = x if x < left
-          top = y if y < top
-          right = x if x > right
-          bottom = y if y > bottom
-        end
+        x = index % current.width
+        y = index / current.width
+        left = x if x < left
+        top = y if y < top
+        right = x if x > right
+        bottom = y if y > bottom
       end
-      right.negative? ? nil : [left, top, right - left + 1, bottom - top + 1]
-    end
-
-    def crop(image, rectangle)
-      x, y, width, height = rectangle
-      image.crop(x, y, width, height)
+      right.negative? ? [0, 0, 1, 1] : [left, top, right - left + 1, bottom - top + 1]
     end
   end
 end

data/lib/flipbook/gif/lzw.rb

@@ -46,6 +46,72 @@ module Flipbook
         writer.sub_blocks
       end
 
+      def decode(bytes, minimum_code_size, expected_size: nil)
+        raise ArgumentError, "minimum code size must be between 2 and 8" unless minimum_code_size.is_a?(Integer) && minimum_code_size.between?(2, 8)
+
+        bytes = String(bytes).b
+        clear_code = 1 << minimum_code_size
+        end_code = clear_code + 1
+        dictionary = initial_dictionary(clear_code)
+        next_code = end_code + 1
+        code_width = minimum_code_size + 1
+        bit_offset = 0
+        previous = nil
+        output = "".b
+        ended = false
+        loop do
+          code = read_code(bytes, bit_offset, code_width)
+          break if code.nil?
+          bit_offset += code_width
+          if code == clear_code
+            dictionary = initial_dictionary(clear_code)
+            next_code = end_code + 1
+            code_width = minimum_code_size + 1
+            previous = nil
+            next
+          end
+          if code == end_code
+            ended = true
+            break
+          end
+
+          entry = if code < dictionary.length && dictionary[code]
+            dictionary[code]
+          elsif code == next_code && previous
+            previous + [previous.first]
+          else
+            raise Error, "invalid GIF LZW code"
+          end
+          output << entry.pack("C*")
+          raise Error, "GIF frame expands beyond its dimensions" if expected_size && output.bytesize > expected_size
+
+          if previous && next_code < 4096
+            dictionary[next_code] = previous + [entry.first]
+            next_code += 1
+            code_width += 1 if next_code == (1 << code_width) && code_width < 12
+          end
+          previous = entry
+        end
+        raise Error, "GIF LZW data is truncated" unless ended && (!expected_size || output.bytesize == expected_size)
+
+        output
+      end
+
+      def initial_dictionary(clear_code)
+        Array.new(clear_code) { |index| [index] } + [nil, nil]
+      end
+      private_class_method :initial_dictionary
+
+      def read_code(bytes, bit_offset, width)
+        return nil if bit_offset + width > bytes.bytesize * 8
+
+        value = 0
+        width.times do |bit|
+          value |= ((bytes.getbyte((bit_offset + bit) / 8) >> ((bit_offset + bit) % 8)) & 1) << bit
+        end
+        value
+      end
+      private_class_method :read_code
     end
   end
 end

data/lib/flipbook/gif/reader.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Flipbook
+  module GIF
+    class Reader
+      attr_reader :width, :height
+
+      def self.read(path)
+        new(File.binread(path)).frames
+      end
+
+      def initialize(data, max_pixels: 16_777_216, max_frames: 10_000, max_total_pixels: 67_108_864)
+        @data = String(data).b
+        @cursor = 0
+        @max_pixels = max_pixels
+        @max_frames = max_frames
+        @max_total_pixels = max_total_pixels
+        @decoded_pixels = 0
+        @frames = []
+        @delays = []
+        decode
+      end
+
+      def frames
+        @frames.map(&:dup).freeze
+      end
+
+      def delays
+        @delays.dup.freeze
+      end
+
+      def each(&block)
+        return enum_for(:each) unless block
+
+        @frames.each(&block)
+      end
+
+      private
+
+      def decode
+        raise Error, "invalid GIF signature" unless take(6).match?(/\AGIF8[79]a\z/)
+
+        @width, @height, packed, @background_index, = take(7).unpack("v2C3")
+        raise Error, "invalid GIF dimensions" unless @width.positive? && @height.positive?
+        raise Error, "GIF exceeds pixel limit" if @width * @height > @max_pixels
+
+        global = (packed & 0x80).zero? ? nil : read_palette(1 << ((packed & 7) + 1))
+        background = global && global[@background_index]
+        canvas = Tessel::Image.new(@width, @height)
+        @current_control = { disposal: 1, delay: 0, transparent: nil }
+        previous = nil
+        previous_disposal = 0
+        restore = nil
+        control = { disposal: 1, delay: 0, transparent: nil }
+
+        until @cursor >= @data.bytesize
+          marker = byte
+          case marker
+          when 0x3B then break
+          when 0x21 then read_extension(control)
+          when 0x2C
+            raise Error, "GIF exceeds frame limit" if @frames.length >= @max_frames
+            @current_control = control
+            frame = read_frame(global)
+            if previous
+              if previous_disposal == 2
+                color = control_background(global, background, previous[:control][:transparent])
+                canvas.fill_rect(previous[:left], previous[:top], previous[:width], previous[:height], color)
+              elsif previous_disposal == 3 && restore
+                canvas = restore.dup
+              end
+            elsif background && frame[:control][:transparent] != @background_index
+              canvas.clear([*background, 255])
+            end
+            restore = canvas.dup if frame[:control][:disposal] == 3
+            composite(canvas, frame)
+            @frames << canvas.dup
+            @delays << Rational(frame[:control][:delay], 100)
+            previous = frame
+            previous_disposal = frame[:control][:disposal]
+            control = { disposal: 1, delay: 0, transparent: nil }
+            @current_control = control
+          else
+            raise Error, "invalid GIF block marker"
+          end
+        end
+        raise Error, "GIF contains no frames" if @frames.empty?
+      end
+
+      def read_extension(control)
+        label = byte
+        if label == 0xF9
+          raise Error, "invalid GIF control extension" unless byte == 4
+          packed, delay, transparent = take(4).unpack("CvC")
+          raise Error, "invalid GIF control terminator" unless byte.zero?
+          control.replace(disposal: (packed >> 2) & 7, delay: delay, transparent: (packed & 1).zero? ? nil : transparent)
+        else
+          skip_sub_blocks
+        end
+      end
+
+      def read_frame(global)
+        left, top, width, height, packed = take(9).unpack("v4C")
+        raise Error, "invalid GIF frame dimensions" unless width.positive? && height.positive?
+        raise Error, "GIF frame exceeds pixel limit" if width * height > @max_pixels
+        raise Error, "GIF exceeds total decoded pixel limit" if @decoded_pixels + width * height > @max_total_pixels
+        raise Error, "GIF frame lies outside the logical screen" if left + width > @width || top + height > @height
+
+        local = (packed & 0x80).zero? ? nil : read_palette(1 << ((packed & 7) + 1))
+        palette = local || global
+        raise Error, "GIF frame has no color table" unless palette
+        minimum = byte
+        compressed = read_sub_blocks
+        indices = LZW.decode(compressed, minimum, expected_size: width * height)
+        indices = deinterlace(indices, width, height) unless (packed & 0x40).zero?
+        @decoded_pixels += width * height
+        { left:, top:, width:, height:, palette:, indices:, control: @current_control.dup }
+      end
+
+      def composite(canvas, frame)
+        frame[:height].times do |row|
+          frame[:width].times do |column|
+            index = frame[:indices].getbyte(row * frame[:width] + column)
+            next if index == frame[:control][:transparent]
+
+            color = frame[:palette][index]
+            raise Error, "GIF color index out of range" unless color
+            canvas[frame[:left] + column, frame[:top] + row] = [*color, 255]
+          end
+        end
+      end
+
+      def control_background(global, background, transparent)
+        return [0, 0, 0, 0] if transparent == @background_index
+        return [0, 0, 0, 0] unless global && background
+
+        [*background, 255]
+      end
+
+      def deinterlace(indices, width, height)
+        rows = [0, 4, 2, 1].flat_map do |start|
+          step = { 0 => 8, 4 => 8, 2 => 4, 1 => 2 }.fetch(start)
+          (start...height).step(step).to_a
+        end
+        output = "\0".b * indices.bytesize
+        rows.each_with_index do |row, source_row|
+          output[row * width, width] = indices.byteslice(source_row * width, width)
+        end
+        output
+      end
+
+      def read_palette(count)
+        take(count * 3).bytes.each_slice(3).map(&:freeze)
+      end
+
+      def skip_sub_blocks
+        read_sub_blocks
+      end
+
+      def read_sub_blocks
+        output = "".b
+        loop do
+          length = byte
+          break if length.zero?
+          raise Error, "GIF sub-block exceeds input" if @cursor + length > @data.bytesize
+
+          output << take(length)
+        end
+        output
+      end
+
+      def byte
+        raise Error, "truncated GIF" if @cursor >= @data.bytesize
+
+        value = @data.getbyte(@cursor)
+        @cursor += 1
+        value
+      end
+
+      def take(length)
+        raise Error, "truncated GIF" if length.negative? || @cursor + length > @data.bytesize
+
+        value = @data.byteslice(@cursor, length)
+        @cursor += length
+        value
+      end
+    end
+  end
+end

data/lib/flipbook/gif/writer.rb

@@ -20,20 +20,20 @@ module Flipbook
         raise
       end
 
-      def initialize(io, width:, height:, loop: true, palette: :per_frame, colors: 256, dither: :floyd_steinberg, transparent_index: nil, optimize: true)
+      def initialize(io, width:, height:, loop: true, palette: :per_frame, colors: 256, dither: :floyd_steinberg, optimize: true, transparent_index: nil, clear_background: false)
         @io = io
         @width = Integer(width)
         @height = Integer(height)
         raise ArgumentError, "GIF dimensions must be between 1 and 65535" unless @width.between?(1, 65_535) && @height.between?(1, 65_535)
         raise ArgumentError, "colors must be between 2 and 256" unless colors.is_a?(Integer) && colors.between?(2, 256)
         raise ArgumentError, "unknown dither: #{dither}" unless %i[none ordered floyd_steinberg].include?(dither)
-        raise TypeError, "optimize must be true or false" unless [true, false].include?(optimize)
 
         @loop = loop_value(loop)
         @colors = colors
         @dither = dither
-        @optimize = optimize
-        @previous_image = nil
+        @clear_background = clear_background
+        @optimize = optimize && !clear_background
+        @previous = nil
         @elapsed = Rational(0)
         @rounded_delay = 0
         @closed = false
@@ -41,11 +41,17 @@ module Flipbook
         @frame_count = 0
         @palette_mode = palette
         if palette == :per_frame
+          raise ArgumentError, "clear_background requires a global palette" if clear_background
           raise ArgumentError, "transparent_index is only valid with a global palette" unless transparent_index.nil?
           @global_palette = nil
         else
           raise TypeError, "palette must be :per_frame or an RGB array" unless palette.is_a?(Array)
           @global_palette = validate_palette(palette)
+          if (@optimize || clear_background) && transparent_index.nil?
+            raise ArgumentError, "global palettes need room for a transparent color when optimize is enabled" if @global_palette.length == 256
+            @global_palette = @global_palette + [[0, 0, 0]]
+            transparent_index = @global_palette.length - 1
+          end
           if transparent_index
             raise ArgumentError, "transparent_index must be the last palette entry" unless transparent_index == @global_palette.length - 1
             raise ArgumentError, "transparent_index is out of range" unless transparent_index.between?(0, @global_palette.length - 1)
@@ -67,32 +73,41 @@ module Flipbook
           @warned_short_delay = true
         end
         transparent_pixels = image.bytes.bytes.each_slice(4).any? { |_, _, _, alpha| alpha.zero? }
+        if @palette_mode == :per_frame && @frame_count.positive? && (@previous_transparency || transparent_pixels)
+          raise ArgumentError, "transparent multi-frame GIFs require a global palette"
+        end
         elapsed = @elapsed + seconds
         target_delay = (elapsed * 100).floor
         frame_delay = target_delay - @rounded_delay
         raise ArgumentError, "GIF frame delays cannot exceed 655.35 seconds" if frame_delay > 65_535
         palette, opaque_palette, transparent_index = frame_palette(image, transparent_pixels)
-        rectangle = if @optimize && @previous_image && !transparent_pixels
-          Diff.bounds(@previous_image, image) || [0, 0, 1, 1]
-        else
-          [0, 0, @width, @height]
-        end
-        left, top, width, height = rectangle
-        frame = rectangle == [0, 0, @width, @height] ? image : image.crop(left, top, width, height)
-        indices, = Tessel::Quantize.quantize(frame, palette: opaque_palette, dither: @dither)
+        indices, = Tessel::Quantize.quantize(image, palette: opaque_palette, dither: @dither)
         if transparent_pixels
           raise ArgumentError, "palette has no transparent entry" unless transparent_index
-          frame.bytes.bytes.each_slice(4).with_index do |(_, _, _, alpha), index|
+          image.bytes.bytes.each_slice(4).with_index do |(_, _, _, alpha), index|
             indices.setbyte(index, transparent_index) if alpha.zero?
           end
         end
 
+        left, top, width, height = @optimize ? Diff.bounds(@previous, image) : [0, 0, @width, @height]
+        if @previous && @optimize && transparent_index
+          image_bytes = image.bytes
+          old_bytes = @previous.bytes
+          (top...(top + height)).each do |y|
+            (left...(left + width)).each do |x|
+              offset = (y * @width + x) * 4
+              indices.setbyte(y * @width + x, transparent_index) if image_bytes.byteslice(offset, 4) == old_bytes.byteslice(offset, 4)
+            end
+          end
+        end
+        frame_indices = crop_indices(indices, left, top, width, height)
         write_control(frame_delay, transparent_index)
-        write_image(left, top, width, height, indices, palette)
+        write_image(left, top, width, height, frame_indices, palette)
         @elapsed = elapsed
         @rounded_delay = target_delay
         @frame_count += 1
-        @previous_image = image.dup
+        @previous_transparency = transparent_pixels
+        @previous = image.dup
         self
       end
 
@@ -133,7 +148,7 @@ module Flipbook
           return [@global_palette, opaque, @global_transparent_index]
         end
 
-        reserve = transparent_pixels
+        reserve = @optimize || transparent_pixels
         opaque_count = reserve ? [@colors - 1, 1].max : @colors
         opaque = Tessel::Quantize.palette_for(image, colors: [opaque_count, 2].max).first(opaque_count)
         palette = reserve ? opaque + [[0, 0, 0]] : opaque
@@ -144,7 +159,8 @@ module Flipbook
         @io << "GIF89a".b << [@width, @height].pack("v2")
         if @global_palette
           bits, size = table_size(@global_palette.length)
-          @io << [0x80 | 0x70 | (bits - 1), @global_transparent_index || 0, 0].pack("C3")
+          background = @clear_background ? @global_transparent_index : 0
+          @io << [0x80 | 0x70 | (bits - 1), background, 0].pack("C3")
           write_palette(@global_palette, size)
         else
           @io << "\0\0\0".b
@@ -155,7 +171,7 @@ module Flipbook
       end
 
       def write_control(delay, transparent_index)
-        packed = 0
+        packed = @clear_background ? 0x08 : (@optimize ? 0x04 : 0)
         packed |= 0x01 if transparent_index
         @io << "!\xF9\x04".b << [packed, delay, transparent_index || 0, 0].pack("CvCC")
       end
@@ -180,6 +196,13 @@ module Flipbook
         (size - palette.length).times { @io << "\0\0\0".b }
       end
 
+      def crop_indices(indices, left, top, width, height)
+        output = String.new(capacity: width * height, encoding: Encoding::BINARY)
+        height.times do |row|
+          output << indices.byteslice((top + row) * @width + left, width)
+        end
+        output
+      end
     end
   end
 end

data/lib/flipbook/timing.rb

@@ -4,7 +4,7 @@ module Flipbook
   module Timing
     module_function
 
-    def delays(count, fps: nil, delay: nil, warn_short: true)
+    def delays(count, fps: nil, delay: nil)
       raise ArgumentError, "frame count must be a positive integer" unless count.is_a?(Integer) && count.positive?
       raise ArgumentError, "provide fps or delay, not both" if !fps.nil? && !delay.nil?
       raise ArgumentError, "fps or delay is required" if fps.nil? && delay.nil?
@@ -19,7 +19,7 @@ module Flipbook
       else
         Array.new(count) { positive_delay(delay) }
       end
-      warn("Flipbook: delays below 1/50 second may be clamped by GIF viewers") if warn_short && values.any? { |value| value < Rational(1, 50) }
+      warn("Flipbook: delays below 1/50 second may be clamped by GIF viewers") if values.any? { |value| value < Rational(1, 50) }
       values
     end
 
@@ -39,6 +39,17 @@ module Flipbook
       end
     end
 
+    def apng_fraction(delay)
+      value = rational(delay)
+      raise ArgumentError, "APNG delays cannot exceed 65535 seconds" if value > 65_535
+      max_denominator = value > 1 ? (65_535 / value).floor : 65_535
+      denominator = [value.denominator, max_denominator, 65_535].min
+      denominator = 1 if denominator.zero?
+      numerator = [(value * denominator).round, 1].max
+      divisor = numerator.gcd(denominator)
+      [numerator / divisor, denominator / divisor]
+    end
+
     def rational(value)
       raise TypeError, "delay and fps must be numeric" unless value.is_a?(Numeric)
 

data/lib/flipbook/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Flipbook
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/flipbook.rb

@@ -1,43 +1,51 @@
 # frozen_string_literal: true
 
 require "tessel"
+require "zlib"
 
 require_relative "flipbook/version"
 require_relative "flipbook/timing"
+require_relative "flipbook/diff"
 require_relative "flipbook/gif/bit_writer"
 require_relative "flipbook/gif/lzw"
 require_relative "flipbook/gif/writer"
+require_relative "flipbook/gif/reader"
 require_relative "flipbook/apng/writer"
-require_relative "flipbook/diff"
 
 module Flipbook
   class Error < StandardError; end
 
   module_function
 
-  def write(path, frames, fps: nil, delay: nil, loop: true, colors: 256, palette: :global, dither: :floyd_steinberg, optimize: true)
+  def write(path, frames, fps: nil, delay: nil, loop: true, format: nil, colors: 256, palette: :global, dither: :floyd_steinberg, optimize: true, **options)
     raise TypeError, "frames must be an array of Tessel::Image values" unless frames.is_a?(Array) && frames.all? { |frame| frame.is_a?(Tessel::Image) }
     raise ArgumentError, "at least one frame is required" if frames.empty?
     raise ArgumentError, "frame dimensions must match" unless frames.all? { |frame| frame.width == frames.first.width && frame.height == frames.first.height }
 
-    extension = File.extname(String(path)).downcase
-    raise ArgumentError, "output path must end in .gif, .png, or .apng" unless %w[.gif .png .apng].include?(extension)
-
-    delays = Timing.delays(frames.length, fps:, delay:, warn_short: extension == ".gif")
-    if extension == ".gif"
+    delays = Timing.delays(frames.length, fps:, delay:)
+    extension = format&.to_s&.downcase || File.extname(String(path)).delete_prefix(".").downcase
+    case extension
+    when "gif"
       write_gif(path, frames, delays, loop:, colors:, palette:, dither:, optimize:)
-    else
-      APNG::Writer.open(path, width: frames.first.width, height: frames.first.height, loop:, optimize:) do |writer|
-        frames.zip(delays).each do |frame, frame_delay|
-          writer.add(frame, delay: frame_delay)
-        end
+    when "png", "apng"
+      APNG::Writer.open(path, width: frames.first.width, height: frames.first.height, loop:, optimize:, **options) do |writer|
+        frames.zip(delays).each { |frame, frame_delay| writer.add(frame, delay: frame_delay) }
       end
+    else
+      raise ArgumentError, "format must be GIF or APNG"
     end
   end
 
+  def read(path)
+    bytes = File.binread(path)
+    raise Error, "not a GIF file" unless bytes.start_with?("GIF87a", "GIF89a")
+
+    GIF::Reader.new(bytes).frames
+  end
+
   def write_gif(path, frames, delays, loop:, colors:, palette:, dither:, optimize:)
     has_transparency = frames.any? { |frame| frame.bytes.bytes.each_slice(4).any? { |_, _, _, alpha| alpha.zero? } }
-    transparent = has_transparency
+    transparent = optimize || has_transparency
     global_palette = if palette == :per_frame
       raise ArgumentError, "per-frame palettes cannot preserve transparency across frames" if has_transparency
       :per_frame
@@ -57,10 +65,9 @@ module Flipbook
     end
     transparent_index = global_palette.is_a?(Array) && transparent ? global_palette.length - 1 : nil
 
-    GIF::Writer.open(path, width: frames.first.width, height: frames.first.height, loop:, palette: global_palette, colors:, dither:, transparent_index:, optimize:) do |writer|
+    GIF::Writer.open(path, width: frames.first.width, height: frames.first.height, loop:, palette: global_palette, colors:, dither:, optimize:, transparent_index:, clear_background: has_transparency) do |writer|
       frames.zip(delays).each { |frame, frame_delay| writer.add(frame, delay: frame_delay) }
     end
   end
   private_class_method :write_gif
-
 end

data/sig/flipbook.rbs

@@ -1,22 +1,12 @@
 module Flipbook
   VERSION: String
 
-  def self.write: (String path, Array[Tessel::Image] frames, ?fps: Numeric?, ?delay: Numeric | Array[Numeric]?, ?loop: bool | Integer, ?colors: Integer, ?palette: Symbol | Array[[Integer, Integer, Integer]], ?dither: Symbol, ?optimize: bool) -> String
+  def self.write: (String path, Array[Tessel::Image] frames, ?fps: Numeric?, ?delay: Numeric | Array[Numeric]?, ?loop: bool | Integer, ?format: String?, ?colors: Integer, ?palette: Symbol | Array[[Integer, Integer, Integer]], ?dither: Symbol, ?optimize: bool, **untyped) -> String
+  def self.read: (String path) -> Array[Tessel::Image]
 
   module Timing
-    def self.delays: (Integer count, ?fps: Numeric?, ?delay: Numeric | Array[Numeric]?, ?warn_short: bool) -> Array[Rational]
+    def self.delays: (Integer count, ?fps: Numeric?, ?delay: Numeric | Array[Numeric]?) -> Array[Rational]
     def self.centiseconds: (Array[Numeric] delays) -> Array[Integer]
-  end
-
-  module APNG
-    class Writer
-      def self.open: (String path, width: Integer, height: Integer, ?loop: bool | Integer, ?optimize: bool) { (Writer) -> void } -> String
-      def add: (Tessel::Image image, delay: Numeric) -> Writer
-      def close: () -> Writer
-    end
-  end
-
-  module Diff
-    def self.bounds: (Tessel::Image previous, Tessel::Image current) -> [Integer, Integer, Integer, Integer]?
+    def self.apng_fraction: (Numeric delay) -> [Integer, Integer]
   end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flipbook
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Yudai Takada
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tessel
@@ -57,8 +58,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.6'
-description: Flipbook encodes optimized animated GIF and APNG files from Tessel RGBA
-  images.
+description: Flipbook encodes animated GIF and APNG files from Tessel RGBA images.
 email:
 - t.yudai92@gmail.com
 executables: []
@@ -70,12 +70,12 @@ files:
 - README.md
 - Rakefile
 - docs/verification.md
-- examples/generate.rb
 - lib/flipbook.rb
 - lib/flipbook/apng/writer.rb
 - lib/flipbook/diff.rb
 - lib/flipbook/gif/bit_writer.rb
 - lib/flipbook/gif/lzw.rb
+- lib/flipbook/gif/reader.rb
 - lib/flipbook/gif/writer.rb
 - lib/flipbook/timing.rb
 - lib/flipbook/version.rb
@@ -86,6 +86,7 @@ licenses:
 metadata:
   source_code_uri: https://github.com/rbgfx/flipbook
   changelog_uri: https://github.com/rbgfx/flipbook/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -100,7 +101,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
-summary: Write animated GIF and APNG files in Ruby
+summary: Write and read GIF and APNG animations in Ruby
 test_files: []

data/examples/generate.rb

@@ -1,49 +0,0 @@
-# frozen_string_literal: true
-
-require "fileutils"
-require "flipbook"
-
-output = ARGV.fetch(0, "examples/output")
-FileUtils.mkdir_p(output)
-
-frames = 24.times.map do |frame|
-  image = Tessel::Image.new(160, 120, fill: "#111827")
-  angle = frame * Math::PI / 12
-  cos = Math.cos(angle)
-  sin = Math.sin(angle)
-  (35...125).each do |y|
-    (55...105).each do |x|
-      dx = x - 80
-      dy = y - 60
-      next unless (dx * cos + dy * sin).abs <= 17 && (-dx * sin + dy * cos).abs <= 17
-
-      image[x, y] = [56, 189, 248, 255]
-    end
-  end
-  image
-end
-Flipbook.write(File.join(output, "spinning-square.gif"), frames, fps: 12)
-
-gradient = Tessel::Image.new(128, 32)
-gradient.height.times do |y|
-  gradient.width.times do |x|
-    gradient[x, y] = [x * 2, 100, 255 - x * 2, 255]
-  end
-end
-Flipbook.write(File.join(output, "gradient.gif"), [gradient], delay: 1)
-
-transparent = 16.times.map do |frame|
-  image = Tessel::Image.new(96, 96)
-  center_x = 48 + (25 * Math.cos(frame * Math::PI / 8)).round
-  center_y = 48 + (25 * Math.sin(frame * Math::PI / 8)).round
-  96.times do |y|
-    96.times do |x|
-      image[x, y] = [251, 113, 133, 255] if (x - center_x)**2 + (y - center_y)**2 <= 14**2
-    end
-  end
-  image
-end
-Flipbook.write(File.join(output, "transparent.gif"), transparent, fps: 8)
-Flipbook.write(File.join(output, "transparent.png"), transparent, fps: 8)
-
-puts "Wrote GIF and APNG examples to #{output}"