flipbook 0.3.0 → 0.4.0

data/lib/flipbook/gif/reader.rb

@@ -3,158 +3,148 @@
 module Flipbook
   module GIF
     class Reader
-      attr_reader :width, :height
-
-      def self.read(path)
-        new(File.binread(path)).frames
+      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(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
+      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 frames
-        @frames.map(&:dup).freeze
-      end
-
-      def delays
-        @delays.dup.freeze
-      end
+      def read
+        signature = take(6)
+        raise Error, "invalid GIF signature" unless %w[GIF87a GIF89a].include?(signature)
 
-      def each(&block)
-        return enum_for(:each) unless block
-
-        @frames.each(&block)
-      end
-
-      private
+        @width, @height, packed, background_index, = take(7).unpack("v2C3")
+        raise Error, "invalid GIF dimensions" if @width.zero? || @height.zero? || @width * @height > @max_pixels
 
-      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 }
+        @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 @cursor >= @data.bytesize
+        until @finished
           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"
+          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(control)
+      def read_extension
         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)
+        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_frame(global)
+      def read_image
         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
+        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
 
-        local = (packed & 0x80).zero? ? nil : read_palette(1 << ((packed & 7) + 1))
-        palette = local || global
+        palette = (packed & 0x80).positive? ? read_palette(1 << ((packed & 7) + 1)) : @global_palette
         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]
+        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
-      end
 
-      def control_background(global, background, transparent)
-        return [0, 0, 0, 0] if transparent == @background_index
-        return [0, 0, 0, 0] unless global && background
+        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
 
-        [*background, 255]
+          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 = [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)
+        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
-        output
+        rows.flatten
       end
 
       def read_palette(count)
-        take(count * 3).bytes.each_slice(3).map(&:freeze)
+        take(count * 3).unpack("C*").each_slice(3).map(&:freeze)
       end
 
-      def skip_sub_blocks
-        read_sub_blocks
+      def palette_color(palette, index)
+        color = palette&.[](index)
+        color || [0, 0, 0]
       end
 
       def read_sub_blocks
@@ -162,28 +152,117 @@ module Flipbook
         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
+      def skip_sub_blocks
+        loop do
+          length = byte
+          break if length.zero?
 
-        value = @data.getbyte(@cursor)
-        @cursor += 1
-        value
+          take(length)
+        end
       end
 
       def take(length)
-        raise Error, "truncated GIF" if length.negative? || @cursor + length > @data.bytesize
+        raise Error, "truncated GIF data" if length.negative? || @offset + length > @bytes.bytesize
 
-        value = @data.byteslice(@cursor, length)
-        @cursor += length
-        value
+        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

@@ -20,38 +20,35 @@ module Flipbook
         raise
       end
 
-      def initialize(io, width:, height:, loop: true, palette: :per_frame, colors: 256, dither: :floyd_steinberg, optimize: true, transparent_index: nil, clear_background: false)
+      def initialize(io, width:, height:, loop: true, palette: :per_frame, colors: 256, dither: :floyd_steinberg, transparent_index: nil, optimize: true)
         @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
-        @clear_background = clear_background
-        @optimize = optimize && !clear_background
-        @previous = nil
+        @optimize = optimize
+        @previous_image = nil
         @elapsed = Rational(0)
         @rounded_delay = 0
         @closed = false
         @warned_short_delay = false
         @frame_count = 0
+        @pending_frame = nil
+        @canvas_cleared = false
         @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
+          @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)
-          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)
@@ -73,41 +70,26 @@ 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"
+        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)
-        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
-
-        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
+        rectangle = if @optimize && @previous_image && !transparent_pixels && !@canvas_cleared
+          Diff.bounds(@previous_image, image) || [0, 0, 1, 1]
+        else
+          [0, 0, @width, @height]
         end
-        frame_indices = crop_indices(indices, left, top, width, height)
-        write_control(frame_delay, transparent_index)
-        write_image(left, top, width, height, frame_indices, palette)
+        @pending_frame = { image: image.dup, delay: frame_delay, rectangle:, transparent: transparent_pixels }
         @elapsed = elapsed
         @rounded_delay = target_delay
         @frame_count += 1
-        @previous_transparency = transparent_pixels
-        @previous = image.dup
+        @previous_image = image.dup
         self
       end
 
@@ -115,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?
@@ -148,30 +131,52 @@ module Flipbook
           return [@global_palette, opaque, @global_transparent_index]
         end
 
-        reserve = @optimize || 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
         @io << "GIF89a".b << [@width, @height].pack("v2")
         if @global_palette
           bits, size = table_size(@global_palette.length)
-          background = @clear_background ? @global_transparent_index : 0
-          @io << [0x80 | 0x70 | (bits - 1), background, 0].pack("C3")
+          @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 = @clear_background ? 0x08 : (@optimize ? 0x04 : 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
@@ -196,13 +201,6 @@ 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)
+    def delays(count, fps: nil, delay: nil, warn_short: true)
       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 values.any? { |value| value < Rational(1, 50) }
+      warn("Flipbook: delays below 1/50 second may be clamped by GIF viewers") if warn_short && values.any? { |value| value < Rational(1, 50) }
       values
     end
 
@@ -39,17 +39,6 @@ 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.3.0"
+  VERSION = "0.4.0"
 end