flipbook 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4c21569bdedb373e7209ca4931199bfaa3039c62e606e3a09c5f49b708d2f3da
+  data.tar.gz: f0f977372a0d76697924494e6b9fc63ebbf535d23a01a4b9e80858649855cf0a
+SHA512:
+  metadata.gz: b814f5fbb5d1a743bb406e409b82317ddc3506acf7a8abde3f6317d2ffbba5fc1f2f9721e183fa09fb94113915a98deff2c6915983880ccf31da3002d4bf99de
+  data.tar.gz: 32f5830b2b7a5584d8e2b21af6727a550717e888f4d8b57c0631738695a10d35feba4084a357878794b18ce4233055b8d68f118aa705b449cab7f4f78c123c40

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [0.1.0] - 2026-09-25
+
+Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+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,76 @@
+<h1 align="center">Flipbook</h1>
+
+<p align="center">Turn a sequence of RGBA images into animated GIF 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>
+  <a href="https://www.ruby-lang.org/"><img src="https://img.shields.io/badge/ruby-%3E%3D3.1-CC342D?logo=ruby&amp;logoColor=white" alt="Ruby version"></a>
+  <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) · [Development](#development)
+
+---
+
+Flipbook writes animated GIFs 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 |
+| --- | --- | --- | --- |
+| GIF | Up to 256 palette entries | One transparent palette index | GIF89a output with global or per-frame palettes |
+
+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.
+
+## Installation
+
+~~~ruby
+gem "flipbook"
+~~~
+
+Then run `bundle install`. Flipbook requires Ruby 3.1 or newer and Tessel 0.2 or newer.
+
+## API
+
+~~~ruby
+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)
+~~~
+
+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.
+
+For streaming GIF output, choose a per-frame palette:
+
+~~~ruby
+Flipbook::GIF::Writer.open("recording.gif", width: 320, height: 240, palette: :per_frame) do |writer|
+  writer.add(frame, delay: Rational(1, 30))
+end
+~~~
+
+### API contracts
+
+- `Flipbook.write(path, frames, fps: or delay:)` requires one or more same-sized `Tessel::Image` objects and a `.gif` output path.
+- `GIF::Writer#add` raises `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.
+
+GIF format acknowledgement: The Graphics Interchange Format© is the Copyright property of CompuServe Incorporated. GIF® is a Service Mark property of CompuServe Incorporated.
+
+## Development
+
+~~~sh
+bundle install
+bundle exec rake verify
+~~~
+
+Optional external checks for generated files are listed in [docs/verification.md](docs/verification.md).
+
+## License
+
+[MIT](LICENSE.txt)

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |task|
+  task.libs << "test"
+  task.pattern = "test/**/*_test.rb"
+end
+
+task verify: :test
+task default: :verify

data/docs/verification.md

@@ -0,0 +1,13 @@
+# File verification
+
+The test suite checks GIF LZW code-width growth and dictionary resets, frame timing, and transparent palette entries.
+
+For an independent local check, install ImageMagick or gifsicle and inspect sample output:
+
+~~~sh
+identify animation.gif
+magick animation.gif -coalesce /tmp/flipbook-gif-%02d.png
+gifsicle --info animation.gif
+~~~
+
+These tools are optional and are not runtime dependencies.

data/lib/flipbook/gif/bit_writer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Flipbook
+  module GIF
+    class BitWriter
+      def initialize
+        @bytes = "".b
+        @buffer = 0
+        @bits = 0
+      end
+
+      def write(code, width)
+        @buffer |= code << @bits
+        @bits += width
+        while @bits >= 8
+          @bytes << (@buffer & 255)
+          @buffer >>= 8
+          @bits -= 8
+        end
+      end
+
+      def sub_blocks
+        @bytes << (@buffer & 255) if @bits.positive?
+        output = "".b
+        @bytes.bytes.each_slice(255) { |slice| output << slice.length << slice.pack("C*") }
+        output << "\0".b
+      end
+    end
+  end
+end

data/lib/flipbook/gif/lzw.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Flipbook
+  module GIF
+    module LZW
+      module_function
+
+      def encode(indices, minimum_code_size)
+        minimum_code_size = Integer(minimum_code_size)
+        raise ArgumentError, "minimum code size must be between 2 and 8" unless minimum_code_size.between?(2, 8)
+
+        clear_code = 1 << minimum_code_size
+        end_code = clear_code + 1
+        next_code = end_code + 1
+        code_width = minimum_code_size + 1
+        dictionary = {}
+        writer = BitWriter.new
+        writer.write(clear_code, code_width)
+        bytes = String(indices).b
+        return writer.tap { |bits| bits.write(end_code, code_width) }.sub_blocks if bytes.empty?
+
+        prefix = bytes.getbyte(0)
+        bytes.byteslice(1..).to_s.each_byte do |byte|
+          key = (prefix << 8) | byte
+          if dictionary.key?(key)
+            prefix = dictionary[key]
+            next
+          end
+
+          writer.write(prefix, code_width)
+          if next_code < 4096
+            dictionary[key] = next_code
+            next_code += 1
+            code_width += 1 if next_code > (1 << code_width) && code_width < 12
+          else
+            writer.write(clear_code, code_width)
+            dictionary.clear
+            next_code = end_code + 1
+            code_width = minimum_code_size + 1
+          end
+          prefix = byte
+        end
+        writer.write(prefix, code_width)
+        code_width += 1 if next_code == (1 << code_width) && code_width < 12
+        writer.write(end_code, code_width)
+        writer.sub_blocks
+      end
+
+    end
+  end
+end

data/lib/flipbook/gif/writer.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Flipbook
+  module GIF
+    class Writer
+      def self.open(path, **options)
+        io = File.open(path, "wb")
+        writer = new(io, **options)
+        writer.instance_variable_set(:@owns_io, true)
+        return writer unless block_given?
+
+        begin
+          yield writer
+        ensure
+          writer.close
+        end
+        path
+      rescue StandardError
+        io&.close unless io&.closed?
+        raise
+      end
+
+      def initialize(io, width:, height:, loop: true, palette: :per_frame, colors: 256, dither: :floyd_steinberg, transparent_index: nil)
+        @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)
+
+        @loop = loop_value(loop)
+        @colors = colors
+        @dither = dither
+        @elapsed = Rational(0)
+        @rounded_delay = 0
+        @closed = false
+        @warned_short_delay = false
+        @frame_count = 0
+        @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
+        else
+          raise TypeError, "palette must be :per_frame or an RGB array" unless palette.is_a?(Array)
+          @global_palette = validate_palette(palette)
+          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)
+            raise ArgumentError, "global palette must include opaque and transparent colors" if @global_palette.length < 2
+          end
+          @global_transparent_index = transparent_index
+        end
+        write_header
+      end
+
+      def add(image, delay:)
+        raise IOError, "GIF 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 logical screen" unless image.width == @width && image.height == @height
+
+        seconds = Timing.duration(delay)
+        if seconds < Rational(1, 50) && !@warned_short_delay
+          warn("Flipbook: delays below 1/50 second may be clamped by GIF viewers")
+          @warned_short_delay = true
+        end
+        transparent_pixels = image.bytes.bytes.each_slice(4).any? { |_, _, _, alpha| alpha.zero? }
+        raise ArgumentError, "transparent frames require a global palette" if @palette_mode == :per_frame && transparent_pixels
+        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)
+        indices, = Tessel::Quantize.quantize(image, palette: opaque_palette, dither: @dither)
+        if transparent_pixels
+          raise ArgumentError, "palette has no transparent entry" unless transparent_index
+          image.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(0, 0, @width, @height, indices, palette)
+        @elapsed = elapsed
+        @rounded_delay = target_delay
+        @frame_count += 1
+        self
+      end
+
+      def close
+        return if @closed
+        raise Error, "GIF contains no frames" if @frame_count.zero?
+
+        @io << ";".b
+        @closed = true
+        @io.close if @owns_io && !@io.closed?
+        self
+      end
+
+      private
+
+      def loop_value(value)
+        return nil if value == false
+        return 0 if value == true
+        return value if value.is_a?(Integer) && value.between?(0, 65_535)
+
+        raise ArgumentError, "loop must be true, false, or an integer from 0 to 65535"
+      end
+
+      def validate_palette(palette)
+        raise ArgumentError, "palette must contain 1 to 256 colors" unless palette.length.between?(1, 256)
+        palette.map do |color|
+          unless color.is_a?(Array) && color.length == 3 && color.all? { |channel| channel.is_a?(Integer) && channel.between?(0, 255) }
+            raise TypeError, "palette colors must be RGB triples"
+          end
+          color.dup
+        end
+      end
+
+      def frame_palette(image, transparent_pixels)
+        if @global_palette
+          opaque = @global_transparent_index ? @global_palette[0...-1] : @global_palette
+          raise ArgumentError, "transparent pixels need a transparent palette entry" if transparent_pixels && !@global_transparent_index
+          return [@global_palette, opaque, @global_transparent_index]
+        end
+
+        reserve = 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
+        [palette, opaque, reserve ? opaque.length : nil]
+      end
+
+      def write_header
+        @io << "GIF89a".b << [@width, @height].pack("v2")
+        if @global_palette
+          bits, size = table_size(@global_palette.length)
+          @io << [0x80 | 0x70 | (bits - 1), 0, 0].pack("C3")
+          write_palette(@global_palette, size)
+        else
+          @io << "\0\0\0".b
+        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
+        packed |= 0x01 if transparent_index
+        @io << "!\xF9\x04".b << [packed, delay, transparent_index || 0, 0].pack("CvCC")
+      end
+
+      def write_image(left, top, width, height, indices, palette)
+        local = !@global_palette
+        bits, size = table_size(palette.length)
+        descriptor_flags = local ? 0x80 | (bits - 1) : 0
+        @io << ",".b << [left, top, width, height, descriptor_flags].pack("v4C")
+        write_palette(palette, size) if local
+        minimum = [bits, 2].max
+        @io << minimum.chr(Encoding::BINARY) << LZW.encode(indices, minimum)
+      end
+
+      def table_size(count)
+        bits = [[(count - 1).bit_length, 1].max, 8].min
+        [bits, 1 << bits]
+      end
+
+      def write_palette(palette, size)
+        palette.each { |rgb| @io << rgb.pack("C3") }
+        (size - palette.length).times { @io << "\0\0\0".b }
+      end
+
+    end
+  end
+end

data/lib/flipbook/timing.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Flipbook
+  module Timing
+    module_function
+
+    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?
+
+      values = if fps
+        rate = rational(fps)
+        raise ArgumentError, "fps must be positive" unless rate.positive?
+        Array.new(count, 1 / rate)
+      elsif delay.is_a?(Array)
+        raise ArgumentError, "delay count must match frame count" unless delay.length == count
+        delay.map { |value| positive_delay(value) }
+      else
+        Array.new(count) { positive_delay(delay) }
+      end
+      warn("Flipbook: delays below 1/50 second may be clamped by GIF viewers") if values.any? { |value| value < Rational(1, 50) }
+      values
+    end
+
+    def duration(value)
+      positive_delay(value)
+    end
+
+    def centiseconds(delays)
+      elapsed = Rational(0)
+      rounded = 0
+      delays.map do |delay|
+        elapsed += rational(delay)
+        target = (elapsed * 100).floor
+        current = target - rounded
+        rounded = target
+        current
+      end
+    end
+
+    def rational(value)
+      raise TypeError, "delay and fps must be numeric" unless value.is_a?(Numeric)
+
+      value.is_a?(Rational) ? value : Rational(value.to_s)
+    rescue ArgumentError, ZeroDivisionError
+      raise TypeError, "delay and fps must be numeric"
+    end
+    private_class_method :rational
+
+    def positive_delay(value)
+      result = rational(value)
+      raise ArgumentError, "delay must be positive" unless result.positive?
+      result
+    end
+    private_class_method :positive_delay
+  end
+end

data/lib/flipbook/version.rb

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

data/lib/flipbook.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "tessel"
+
+require_relative "flipbook/version"
+require_relative "flipbook/timing"
+require_relative "flipbook/gif/bit_writer"
+require_relative "flipbook/gif/lzw"
+require_relative "flipbook/gif/writer"
+
+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)
+    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 }
+
+    delays = Timing.delays(frames.length, fps:, delay:)
+    raise ArgumentError, "output path must end in .gif" unless File.extname(String(path)).casecmp?(".gif")
+
+    write_gif(path, frames, delays, loop:, colors:, palette:, dither:)
+  end
+
+  def write_gif(path, frames, delays, loop:, colors:, palette:, dither:)
+    has_transparency = frames.any? { |frame| frame.bytes.bytes.each_slice(4).any? { |_, _, _, alpha| alpha.zero? } }
+    transparent = has_transparency
+    global_palette = if palette == :per_frame
+      raise ArgumentError, "per-frame palettes cannot preserve transparency across frames" if has_transparency
+      :per_frame
+    elsif palette == :global
+      opaque_count = transparent ? [colors - 1, 1].max : colors
+      opaque = Tessel::Quantize.palette_for(frames, colors: [opaque_count, 2].max).first(opaque_count)
+      transparent ? opaque + [[0, 0, 0]] : opaque
+    elsif palette.is_a?(Array)
+      if transparent
+        raise ArgumentError, "palette needs one free entry for transparency" if palette.length >= 256
+        palette + [[0, 0, 0]]
+      else
+        palette
+      end
+    else
+      raise ArgumentError, "palette must be :global, :per_frame, or an RGB array"
+    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:) 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

@@ -0,0 +1,10 @@
+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) -> String
+
+  module Timing
+    def self.delays: (Integer count, ?fps: Numeric?, ?delay: Numeric | Array[Numeric]?) -> Array[Rational]
+    def self.centiseconds: (Array[Numeric] delays) -> Array[Integer]
+  end
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: flipbook
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: tessel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+description: Flipbook encodes animated GIF files from Tessel RGBA images.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/verification.md
+- lib/flipbook.rb
+- lib/flipbook/gif/bit_writer.rb
+- lib/flipbook/gif/lzw.rb
+- lib/flipbook/gif/writer.rb
+- lib/flipbook/timing.rb
+- lib/flipbook/version.rb
+- sig/flipbook.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
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Write animated GIFs in Ruby
+test_files: []