RubyGems - flipbook - Versions diffs - 0.2.0 → 0.4.0 - Mend

flipbook 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +10 -0
data/README.md +11 -0
data/docs/assets/gradient.gif +0 -0
data/docs/assets/spinning-square.gif +0 -0
data/docs/assets/transparent.gif +0 -0
data/docs/assets/transparent.png +0 -0
data/docs/index.html +32 -0
data/docs/verification.md +4 -2
data/lib/flipbook/gif/reader.rb +268 -0
data/lib/flipbook/gif/writer.rb +42 -21
data/lib/flipbook/version.rb +1 -1
data/lib/flipbook.rb +5 -0
data/sig/flipbook.rbs +16 -0
data/sig/tessel.rbs +4 -0
metadata +16 -6

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21a1c656c9c85bbfdc6ace9cc7c09f3cbc8546c4f716d899d9bc72a1ec42e30b
-  data.tar.gz: fd9bda09b22c184e7f95933a9a795edfe4739e965eb1d0fc254d7eb35705a14b
+  metadata.gz: 9873e25f97a747f0f45e26e9eb9c503228d6b2daa975a8976f64480c1b3e0ba0
+  data.tar.gz: 90bfb6579e71d4fdea9035fe86561fcde8a4911acb56f9ce8414136d0004abd6
 SHA512:
-  metadata.gz: fdd1e8f6929f091b6dad1e8de5fc892ae6e17704d53ac564911962a2671c70e3f2864d751860ea66be5908b065a2276256b2a38e1ef6b4cb35db15fe68a6773c
-  data.tar.gz: cd3b12ca02ee239a641db540dede16bcc59647087e083a1cf78205d3b01ec2364c961d412dd9426ced032a839366d98c703f8d1b890b9a1e9d93338d02c5a91c
+  metadata.gz: eb493019ec22fce32d0f4741bd1db36dbc8403b1528b267f8abb94b99865de2ceed88f50e24efdf145f760de33ea1526ce5206d258b6739043135a87da2ead85
+  data.tar.gz: e9a8476651fbfbe0cf0ff3a8092b0a7c0d3b9ee80a50c95a9a3ae8e0394c8275c84f5be424ce7ed65bcfa722a1002546e98d2f57ae630dd5cd599608caedb937

data/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,15 @@
 # Changelog
+## [0.4.0] - 2026-09-25
+- Read composited GIF frames with configurable image, frame, and total-pixel limits.
+- Improve APNG writing and changed-region encoding.
+## [0.3.0] - 2026-09-25
+- Add GIF reading with LZW decoding, interlace handling, frame composition, and disposal methods.
+- Clear transparent GIF frames correctly and retain delta cropping for opaque animations.
 ## [0.2.0] - 2026-09-25
 - Add APNG writing with rational frame delays, alpha, and changed-region cropping.

data/README.md CHANGED Viewed

@@ -63,11 +63,20 @@ 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.
+Read GIFs as full-canvas `Tessel::Image` frames. The reader applies frame offsets, transparency, interlacing, and disposal before returning:
+~~~ruby
+frames = Flipbook.read("animation.gif")
+~~~
+`max_pixels:`, `max_frames:`, and `max_total_pixels:` can lower the decoder's resource limits for untrusted files.
 ### 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.read(path)` returns fully composited GIF frames and rejects malformed streams or files over its configured limits.
 - 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
@@ -78,6 +87,8 @@ Generate a rotating square, a color gradient, and transparent GIF/APNG samples:
 ruby examples/generate.rb
 ~~~
+![A blue square rotating in an animated GIF](docs/assets/spinning-square.gif)
 Pass an output directory as the first argument to choose where the files are written.
 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/assets/gradient.gif ADDED Viewed

Binary file

data/docs/assets/spinning-square.gif ADDED Viewed

Binary file

data/docs/assets/transparent.gif ADDED Viewed

Binary file

data/docs/assets/transparent.png ADDED Viewed

Binary file

data/docs/index.html ADDED Viewed

@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="theme-color" content="#101318">
+<meta name="description" content="Write optimized animated GIF and APNG files from Ruby images with Flipbook.">
+<title>Flipbook — animation from Ruby frames</title>
+<style>
+:root{color-scheme:dark;--bg:#101318;--panel:#181e27;--line:#2b3441;--text:#f1f4f8;--muted:#9ca9b8;--accent:#38bdf8;--mono:ui-monospace,SFMono-Regular,Menlo,monospace;--sans:Inter,ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif}
+*{box-sizing:border-box}body{margin:0;background:radial-gradient(ellipse at 75% -12%,#16384c,transparent 45%),var(--bg);color:var(--text);font:16px/1.65 var(--sans)}a{color:inherit;text-decoration:none}a:hover{color:var(--accent)}.wrap{width:min(1080px,calc(100% - 40px));margin:auto}.nav{height:76px;display:flex;align-items:center;justify-content:space-between;border-bottom:1px solid var(--line)}.brand{font-size:20px;font-weight:750;letter-spacing:-.04em}.brand span,.label{color:var(--accent)}.links{display:flex;gap:24px;color:var(--muted);font-size:14px}.hero{padding:84px 0 72px;display:grid;grid-template-columns:1fr .82fr;align-items:center;gap:56px}.label{font:12px var(--mono);text-transform:uppercase;letter-spacing:.14em}h1{font-size:clamp(48px,7vw,78px);line-height:.99;letter-spacing:-.075em;margin:18px 0}.hero p{font-size:18px;color:var(--muted);max-width:600px}.actions{display:flex;gap:12px;flex-wrap:wrap;margin:28px 0 22px}.button{padding:10px 16px;border:1px solid var(--line);border-radius:5px;font-weight:650}.primary{color:#061820;background:var(--accent);border-color:var(--accent)}.install{display:inline-flex;gap:16px;background:#090d12;border:1px solid var(--line);border-radius:6px;padding:12px 15px;font:14px var(--mono)}.install span{color:#6c7886}.visual{padding:20px;border:1px solid var(--line);border-radius:10px;background:linear-gradient(145deg,#1b2632,#11171e);box-shadow:0 24px 80px #0007;transform:rotate(1deg)}.window{height:34px;border-bottom:1px solid var(--line);margin:-2px 0 16px;display:flex;align-items:center;gap:7px}.dot{width:8px;height:8px;border-radius:50%;background:#566170}.filename{margin-left:8px;color:var(--muted);font:11px var(--mono)}.visual img{display:block;width:100%;border-radius:5px;image-rendering:auto}.caption{display:flex;justify-content:space-between;color:var(--muted);font:11px var(--mono);padding:12px 2px 0}.section{border-top:1px solid var(--line);padding:42px 0 66px}.section h2{font-size:28px;letter-spacing:-.04em;margin:8px 0}.section>p{color:var(--muted);max-width:650px}.formats{display:grid;grid-template-columns:1fr 1fr;gap:14px;margin-top:24px}.card{background:var(--panel);border:1px solid var(--line);border-radius:8px;overflow:hidden}.card img{display:block;width:100%;height:200px;object-fit:contain;background:#0b1016;padding:18px}.cardbody{padding:16px 18px}.card h3{margin:0;font-size:16px}.card p{color:var(--muted);font-size:14px;margin:5px 0 0}.code{background:#090d12;border:1px solid var(--line);border-radius:7px;padding:18px;overflow:auto;font:14px/1.8 var(--mono);color:#d5eaf5}.foot{border-top:1px solid var(--line);padding:24px 0 36px;display:flex;justify-content:space-between;gap:16px;color:var(--muted);font-size:13px}
+@media(max-width:740px){.hero{grid-template-columns:1fr;gap:32px;padding:66px 0 54px}.visual{max-width:500px}.links{gap:14px}.formats{grid-template-columns:1fr}.foot{flex-direction:column}}
+</style>
+</head>
+<body><div class="wrap">
+<nav class="nav" aria-label="Main navigation"><a class="brand" href="#top">flip<span>book</span></a><div class="links"><a href="#formats">Formats</a><a href="https://github.com/rbgfx/flipbook">GitHub</a><a href="https://rubygems.org/gems/flipbook">RubyGems</a></div></nav>
+<main id="top">
+<section class="hero"><div><div class="label">Animation from Ruby frames</div><h1>Every frame<br>in its place.</h1><p>Write optimized animated GIF and APNG files from Tessel images. Keep GIF palettes steady, preserve full-color alpha in APNG, and crop unchanged frame regions.</p><div class="actions"><a class="button primary" href="https://github.com/rbgfx/flipbook#api">Explore the API ↗</a><a class="button" href="https://github.com/rbgfx/flipbook/tree/main/examples">See examples</a></div><div class="install"><span>$</span> gem install flipbook</div></div><div class="visual"><div class="window"><i class="dot"></i><i class="dot"></i><i class="dot"></i><span class="filename">spinning-square.gif</span></div><img src="assets/spinning-square.gif" alt="A blue square rotating on a dark background"><div class="caption"><span>GIF · 12 FPS</span><span>24 frames</span></div></div></section>
+<section class="section" id="formats"><div class="label">Pick the right format</div><h2>Palette animation or full color</h2><p>Use GIF for compact, broadly supported animations; choose APNG when full RGBA color and partial transparency matter.</p><div class="formats"><article class="card"><img src="assets/gradient.gif" alt="A blue-to-red color gradient"><div class="cardbody"><h3>GIF · up to 256 palette colors</h3><p>Global palettes keep colors consistent. Per-frame palettes are available for streaming.</p></div></article><article class="card"><img src="assets/transparent.png" alt="An animated pink circle with transparent background"><div class="cardbody"><h3>APNG · full RGBA</h3><p>A standard PNG first frame, with full alpha and optimized animated updates.</p></div></article></div></section>
+<section class="section"><div class="label">Quick start</div><h2>Write from Tessel frames</h2><pre class="code"><code>require "flipbook"
+frames = 60.times.map do |index|
+  image = Tessel::Image.new(320, 240, fill: "#101827")
+  image.fill_rect(index * 4 % 320, 100, 32, 32, "#38bdf8")
+  image
+end
+Flipbook.write("animation.gif", frames, fps: 30, loop: true)
+Flipbook.write("animation.png", frames, fps: 30, loop: true)</code></pre></section>
+</main><footer class="foot"><span>Flipbook · Animated GIF and APNG for Ruby</span><span><a href="https://github.com/rbgfx/flipbook">Source</a> · MIT License</span></footer>
+</div></body>
+</html>

data/docs/verification.md CHANGED Viewed

@@ -1,14 +1,16 @@
 # 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, frame composition and disposal, resource limits, frame timing, transparent palette entries, cropped frame bounds, APNG sequence numbers, and PNG chunk CRCs.
-For an independent local check, install ImageMagick or gifsicle and inspect sample output:
+For an independent local check, install ImageMagick, FFmpeg, or gifsicle and inspect sample output:
 ~~~sh
 identify animation.gif
 magick animation.gif -coalesce /tmp/flipbook-gif-%02d.png
 gifsicle --info animation.gif
 magick identify animation.png
+ffprobe -v error -count_frames -select_streams v:0 \\
+  -show_entries stream=codec_name,nb_read_frames animation.png
 ~~~
 These tools are optional and are not runtime dependencies.

data/lib/flipbook/gif/reader.rb ADDED Viewed

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+module Flipbook
+  module GIF
+    class Reader
+      def self.read(path, max_pixels: 16_384 * 16_384, max_frames: 10_000, max_total_pixels: 100_000_000)
+        new(File.binread(path), max_pixels:, max_frames:, max_total_pixels:).read
+      end
+      def initialize(bytes, max_pixels: 16_384 * 16_384, max_frames: 10_000, max_total_pixels: 100_000_000)
+        @bytes = String(bytes).b
+        @offset = 0
+        @max_pixels = Integer(max_pixels)
+        @max_frames = Integer(max_frames)
+        @max_total_pixels = Integer(max_total_pixels)
+        raise ArgumentError, "limits must be positive" unless @max_pixels.positive? && @max_frames.positive? && @max_total_pixels.positive?
+      end
+      def read
+        signature = take(6)
+        raise Error, "invalid GIF signature" unless %w[GIF87a GIF89a].include?(signature)
+        @width, @height, packed, background_index, = take(7).unpack("v2C3")
+        raise Error, "invalid GIF dimensions" if @width.zero? || @height.zero? || @width * @height > @max_pixels
+        @global_palette = read_palette(1 << ((packed & 7) + 1)) if (packed & 0x80).positive?
+        @background_index = background_index
+        @background = palette_color(@global_palette, background_index)
+        @frames = []
+        @canvas = Tessel::Image.new(@width, @height, fill: @background)
+        @control = default_control
+        @previous_disposal = nil
+        @finished = false
+        until @finished
+          marker = byte
+          case marker
+          when 0x21 then read_extension
+          when 0x2c then read_image
+          when 0x3b then @finished = true
+          else raise Error, "invalid GIF block marker 0x#{marker.to_s(16)}"
+          end
+        end
+        raise Error, "GIF contains no frames" if @frames.empty?
+        @frames
+      end
+      private
+      def default_control
+        { delay: 0, disposal: 0, transparent: nil }
+      end
+      def read_extension
+        label = byte
+        case label
+        when 0xf9
+          size = byte
+          raise Error, "invalid GIF graphic control extension" unless size == 4
+          packed, delay, transparent_index = take(4).unpack("C v C")
+          raise Error, "invalid GIF graphic control terminator" unless byte.zero?
+          disposal = (packed >> 2) & 7
+          raise Error, "unsupported GIF disposal method" if disposal > 3
+          @control = { delay: delay, disposal:, transparent: (packed & 1).positive? ? transparent_index : nil }
+        when 0x01
+          skip_sub_blocks # fixed plain-text header and text data are both sub-blocks
+        else
+          skip_sub_blocks
+        end
+      end
+      def read_image
+        left, top, width, height, packed = take(9).unpack("v4C")
+        raise Error, "invalid GIF image dimensions" if width.zero? || height.zero?
+        raise Error, "GIF image rectangle is outside the canvas" if left + width > @width || top + height > @height
+        palette = (packed & 0x80).positive? ? read_palette(1 << ((packed & 7) + 1)) : @global_palette
+        raise Error, "GIF frame has no color table" unless palette
+        raise Error, "GIF transparent palette index is out of range" if @control[:transparent] && @control[:transparent] >= palette.length
+        minimum_code_size = byte
+        raise Error, "invalid GIF LZW code size" unless minimum_code_size.between?(2, 8)
+        indices = LZW.decode(read_sub_blocks, minimum_code_size, width * height)
+        indices = deinterlace(indices, width, height) if (packed & 0x40).positive?
+        draw_frame(indices, palette, left, top, width, height)
+      end
+      def draw_frame(indices, palette, left, top, width, height)
+        disposal = @control[:disposal]
+        if @previous_disposal
+          previous = @previous_disposal
+          case previous[:method]
+          when 2
+            @canvas.fill_rect(*previous[:rect], previous[:background])
+          when 3
+            @canvas = previous[:restore]
+          end
+        end
+        raise Error, "GIF frame limit exceeded" if @frames.length >= @max_frames
+        raise Error, "GIF total pixel limit exceeded" if (@frames.length + 1) * @width * @height > @max_total_pixels
+        restore = @canvas.dup if disposal == 3
+        transparent = @control[:transparent]
+        transparent_background = transparent && (!@global_palette || transparent == @background_index)
+        @canvas.clear([0, 0, 0, 0]) if @frames.empty? && transparent_background
+        indices.each_with_index do |palette_index, index|
+          next if palette_index == transparent
+          color = palette[palette_index]
+          raise Error, "GIF palette index is out of range" unless color
+          x = left + index % width
+          y = top + index / width
+          @canvas[x, y] = [*color, 255]
+        end
+        @frames << @canvas.dup
+        background = if transparent_background
+          [0, 0, 0, 0]
+        else
+          [*@background, 255]
+        end
+        @previous_disposal = { method: disposal, rect: [left, top, width, height], background:, restore: }
+        @control = default_control
+      end
+      def deinterlace(indices, width, height)
+        rows = Array.new(height)
+        offset = 0
+        [[0, 8], [4, 8], [2, 4], [1, 2]].each do |start, step|
+          (start...height).step(step) do |y|
+            rows[y] = indices.slice(offset, width)
+            offset += width
+          end
+        end
+        rows.flatten
+      end
+      def read_palette(count)
+        take(count * 3).unpack("C*").each_slice(3).map(&:freeze)
+      end
+      def palette_color(palette, index)
+        color = palette&.[](index)
+        color || [0, 0, 0]
+      end
+      def read_sub_blocks
+        output = "".b
+        loop do
+          length = byte
+          break if length.zero?
+          output << take(length)
+        end
+        output
+      end
+      def skip_sub_blocks
+        loop do
+          length = byte
+          break if length.zero?
+          take(length)
+        end
+      end
+      def take(length)
+        raise Error, "truncated GIF data" if length.negative? || @offset + length > @bytes.bytesize
+        result = @bytes.byteslice(@offset, length)
+        @offset += length
+        result
+      end
+      def byte
+        take(1).getbyte(0)
+      end
+    end
+    module LZW
+      module_function
+      def decode(bytes, minimum_code_size, expected_size)
+        clear = 1 << minimum_code_size
+        ending = clear + 1
+        prefix = Array.new(4096)
+        suffix = Array.new(4096)
+        clear.times { |index| suffix[index] = index }
+        next_code = ending + 1
+        width = minimum_code_size + 1
+        bit_offset = 0
+        previous = nil
+        first = nil
+        output = String.new(capacity: expected_size, encoding: Encoding::BINARY)
+        ended = false
+        loop do
+          code = read_code(bytes, bit_offset, width)
+          break unless code
+          bit_offset += width
+          if code == clear
+            clear.times { |index| suffix[index] = index }
+            next_code = ending + 1
+            width = minimum_code_size + 1
+            previous = nil
+            next
+          end
+          if code == ending
+            ended = true
+            break
+          end
+          if code < next_code && suffix[code]
+            entry, first = expand(code, clear, prefix, suffix)
+          elsif code == next_code && previous
+            entry, first = expand(previous, clear, prefix, suffix)
+            entry << first
+          else
+            raise Error, "invalid GIF LZW code"
+          end
+          output << entry.pack("C*")
+          raise Error, "GIF frame data exceeds its dimensions" if output.bytesize > expected_size
+          if previous && next_code < 4096
+            prefix[next_code] = previous
+            suffix[next_code] = first
+            next_code += 1
+            width += 1 if next_code == (1 << width) && width < 12
+          end
+          previous = code
+        end
+        raise Error, "truncated GIF LZW data" unless ended && output.bytesize == expected_size
+        output.bytes
+      end
+      def expand(code, clear, prefix, suffix)
+        stack = []
+        current = code
+        while current >= clear
+          raise Error, "invalid GIF LZW dictionary" unless current < 4096 && suffix[current] && prefix[current]
+          stack << suffix[current]
+          current = prefix[current]
+        end
+        stack << current
+        first = current
+        [stack.reverse, first]
+      end
+      private_class_method :expand
+      def read_code(bytes, bit_offset, width)
+        return nil if bit_offset + width > bytes.bytesize * 8
+        code = 0
+        width.times do |bit|
+          code |= ((bytes.getbyte((bit_offset + bit) / 8) >> ((bit_offset + bit) % 8)) & 1) << bit
+        end
+        code
+      end
+      private_class_method :read_code
+    end
+  end
+end

data/lib/flipbook/gif/writer.rb CHANGED Viewed

@@ -39,10 +39,13 @@ module Flipbook
         @closed = false
         @warned_short_delay = false
         @frame_count = 0
+        @pending_frame = nil
+        @canvas_cleared = false
         @palette_mode = palette
         if palette == :per_frame
           raise ArgumentError, "transparent_index is only valid with a global palette" unless transparent_index.nil?
           @global_palette = nil
+          @global_transparent_index = 0
         else
           raise TypeError, "palette must be :per_frame or an RGB array" unless palette.is_a?(Array)
           @global_palette = validate_palette(palette)
@@ -67,28 +70,22 @@ module Flipbook
           @warned_short_delay = true
         end
         transparent_pixels = image.bytes.bytes.each_slice(4).any? { |_, _, _, alpha| alpha.zero? }
+        if @pending_frame
+          disposal = (@pending_frame[:transparent] || transparent_pixels) ? 2 : 1
+          write_pending(disposal)
+          @canvas_cleared = disposal == 2
+        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
+        rectangle = if @optimize && @previous_image && !transparent_pixels && !@canvas_cleared
           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)
-        if transparent_pixels
-          raise ArgumentError, "palette has no transparent entry" unless transparent_index
-          frame.bytes.bytes.each_slice(4).with_index do |(_, _, _, alpha), index|
-            indices.setbyte(index, transparent_index) if alpha.zero?
-          end
-        end
-        write_control(frame_delay, transparent_index)
-        write_image(left, top, width, height, indices, palette)
+        @pending_frame = { image: image.dup, delay: frame_delay, rectangle:, transparent: transparent_pixels }
         @elapsed = elapsed
         @rounded_delay = target_delay
         @frame_count += 1
@@ -100,6 +97,7 @@ module Flipbook
         return if @closed
         raise Error, "GIF contains no frames" if @frame_count.zero?
+        write_pending(@pending_frame[:transparent] ? 2 : 1)
         @io << ";".b
         @closed = true
         @io.close if @owns_io && !@io.closed?
@@ -133,11 +131,33 @@ module Flipbook
           return [@global_palette, opaque, @global_transparent_index]
         end
-        reserve = transparent_pixels
-        opaque_count = reserve ? [@colors - 1, 1].max : @colors
+        opaque_count = [@colors - 1, 1].max
         opaque = Tessel::Quantize.palette_for(image, colors: [opaque_count, 2].max).first(opaque_count)
-        palette = reserve ? opaque + [[0, 0, 0]] : opaque
-        [palette, opaque, reserve ? opaque.length : nil]
+        [[[0, 0, 0]] + opaque, opaque, 0]
+      end
+      def write_pending(disposal)
+        pending = @pending_frame
+        image = pending[:image]
+        left, top, width, height = pending[:rectangle]
+        frame = if left.zero? && top.zero? && width == @width && height == @height
+          image
+        else
+          image.crop(left, top, width, height)
+        end
+        palette, opaque_palette, transparent_index = frame_palette(image, pending[:transparent])
+        indices, = Tessel::Quantize.quantize(frame, palette: opaque_palette, dither: @dither)
+        indices.each_byte.with_index { |index, offset| indices.setbyte(offset, index + 1) } if @palette_mode == :per_frame
+        if pending[:transparent]
+          raise ArgumentError, "palette has no transparent entry" unless transparent_index
+          frame.bytes.bytes.each_slice(4).with_index do |(_, _, _, alpha), index|
+            indices.setbyte(index, transparent_index) if alpha.zero?
+          end
+        end
+        write_control(pending[:delay], transparent_index, disposal:)
+        write_image(left, top, width, height, indices, palette)
+        @pending_frame = nil
       end
       def write_header
@@ -147,15 +167,16 @@ module Flipbook
           @io << [0x80 | 0x70 | (bits - 1), @global_transparent_index || 0, 0].pack("C3")
           write_palette(@global_palette, size)
         else
-          @io << "\0\0\0".b
+          @io << [0x80 | 0x70, 0, 0].pack("C3")
+          write_palette([[0, 0, 0]], 2)
         end
         if @loop
           @io << "!\xFF\x0BNETSCAPE2.0\x03\x01".b << [@loop].pack("v") << "\0".b
         end
       end
-      def write_control(delay, transparent_index)
-        packed = 0
+      def write_control(delay, transparent_index, disposal:)
+        packed = disposal << 2
         packed |= 0x01 if transparent_index
         @io << "!\xF9\x04".b << [packed, delay, transparent_index || 0, 0].pack("CvCC")
       end

data/lib/flipbook/version.rb CHANGED Viewed

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

data/lib/flipbook.rb CHANGED Viewed

@@ -6,6 +6,7 @@ require_relative "flipbook/version"
 require_relative "flipbook/timing"
 require_relative "flipbook/gif/bit_writer"
 require_relative "flipbook/gif/lzw"
+require_relative "flipbook/gif/reader"
 require_relative "flipbook/gif/writer"
 require_relative "flipbook/apng/writer"
 require_relative "flipbook/diff"
@@ -35,6 +36,10 @@ module Flipbook
     end
   end
+  def read(path, **options)
+    GIF::Reader.read(path, **options)
+  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

data/sig/flipbook.rbs CHANGED Viewed

@@ -2,6 +2,7 @@ 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.read: (String path, ?max_pixels: Integer, ?max_frames: Integer, ?max_total_pixels: Integer) -> Array[Tessel::Image]
   module Timing
     def self.delays: (Integer count, ?fps: Numeric?, ?delay: Numeric | Array[Numeric]?, ?warn_short: bool) -> Array[Rational]
@@ -16,6 +17,21 @@ module Flipbook
     end
   end
+  module GIF
+    class Writer
+      def self.open: (String path, width: Integer, height: Integer, ?loop: bool | Integer, ?palette: Symbol | Array[[Integer, Integer, Integer]], ?colors: Integer, ?dither: Symbol, ?transparent_index: Integer?, ?optimize: bool) { (Writer) -> void } -> String
+      def add: (Tessel::Image image, delay: Numeric) -> Writer
+      def close: () -> Writer
+    end
+    class Reader
+      def self.read: (String path, ?max_pixels: Integer, ?max_frames: Integer, ?max_total_pixels: Integer) -> Array[Tessel::Image]
+      def read: () -> Array[Tessel::Image]
+    end
+    def self.read: (String path, ?max_pixels: Integer, ?max_frames: Integer, ?max_total_pixels: Integer) -> Array[Tessel::Image]
+  end
   module Diff
     def self.bounds: (Tessel::Image previous, Tessel::Image current) -> [Integer, Integer, Integer, Integer]?
   end

data/sig/tessel.rbs ADDED Viewed

@@ -0,0 +1,4 @@
+module Tessel
+  class Image
+  end
+end

metadata CHANGED Viewed

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flipbook
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.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,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.6'
-description: Flipbook encodes optimized animated GIF and APNG files from Tessel RGBA
-  images.
+description: Flipbook encodes optimized GIF and APNG animations and reads composited
+  GIF frames from Tessel images.
 email:
 - t.yudai92@gmail.com
 executables: []
@@ -69,6 +70,11 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/assets/gradient.gif
+- docs/assets/spinning-square.gif
+- docs/assets/transparent.gif
+- docs/assets/transparent.png
+- docs/index.html
 - docs/verification.md
 - examples/generate.rb
 - lib/flipbook.rb
@@ -76,16 +82,19 @@ files:
 - 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
 - sig/flipbook.rbs
+- sig/tessel.rbs
 homepage: https://github.com/rbgfx/flipbook
 licenses:
 - MIT
 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 +109,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 animated GIF and APNG files in Ruby
 test_files: []