flipbook 0.3.0 → 0.4.0

data/lib/flipbook.rb

@@ -1,51 +1,48 @@
 # 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/gif/writer"
 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, format: nil, colors: 256, palette: :global, dither: :floyd_steinberg, optimize: true, **options)
+  def write(path, frames, fps: nil, delay: nil, loop: true, colors: 256, palette: :global, dither: :floyd_steinberg, optimize: true)
     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:)
-    extension = format&.to_s&.downcase || File.extname(String(path)).delete_prefix(".").downcase
-    case extension
-    when "gif"
+    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"
       write_gif(path, frames, delays, loop:, colors:, palette:, dither:, optimize:)
-    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"
+      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
+      end
     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
+  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 = optimize || has_transparency
+    transparent = has_transparency
     global_palette = if palette == :per_frame
       raise ArgumentError, "per-frame palettes cannot preserve transparency across frames" if has_transparency
       :per_frame
@@ -65,9 +62,10 @@ 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:, optimize:, transparent_index:, clear_background: has_transparency) do |writer|
+    GIF::Writer.open(path, width: frames.first.width, height: frames.first.height, loop:, palette: global_palette, colors:, dither:, transparent_index:, optimize:) 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,12 +1,38 @@
 module Flipbook
   VERSION: 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]
+  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]?) -> Array[Rational]
+    def self.delays: (Integer count, ?fps: Numeric?, ?delay: Numeric | Array[Numeric]?, ?warn_short: bool) -> Array[Rational]
     def self.centiseconds: (Array[Numeric] delays) -> Array[Integer]
-    def self.apng_fraction: (Numeric delay) -> [Integer, 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 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
 end

data/sig/tessel.rbs

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flipbook
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -58,7 +58,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.6'
-description: Flipbook encodes 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,7 +70,13 @@ 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
 - lib/flipbook/apng/writer.rb
 - lib/flipbook/diff.rb
@@ -80,6 +87,7 @@ files:
 - lib/flipbook/timing.rb
 - lib/flipbook/version.rb
 - sig/flipbook.rbs
+- sig/tessel.rbs
 homepage: https://github.com/rbgfx/flipbook
 licenses:
 - MIT
@@ -104,5 +112,5 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: Write and read GIF and APNG animations in Ruby
+summary: Write and read animated GIF and APNG files in Ruby
 test_files: []