wezen 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 371481b9c7234ab5048aeb49b4ee4413c71aee57c46331130c09b7ae3868250a
-  data.tar.gz: 1c37ec6416541d255d5714e168357d1a0aa5e750d7cf32aef48f20bdf6439814
+  metadata.gz: f7f7a2045f7c3c436e4d3baeb78b64195f9512c88a2727faa679ac53115d8f17
+  data.tar.gz: 5f92c2a5bb410f6805f7a976a6ba64b42b8b79a4227b9c12c65471f017dfb93f
 SHA512:
-  metadata.gz: 8efe1a7a8ef558760ebcdcd99c047863c1fbafdb59b97ddff81667a2ef081f3613795c6e01ad24b0a4b2e58f146ba8302f37986f3d6c2f9c02768eed9c6e7a22
-  data.tar.gz: 7f40b04e14c5ee213997189150c8b50c91b4b07bbf01f632850046b80064b212fe324bb8beab8f47a7f0fdfb382b1da05f81e5fdf9b419d84b079b0b61309987
+  metadata.gz: 3b2d904c4dfe01a254043657f021fa210b5c4b962e58b800f8bef577d882a68bd66ccc6b204ee0b4a854f1760962e4fdadd77a3de8282bcb72940c5a37b04d2f
+  data.tar.gz: 20d8675fc875ca2bfcb609688fe20d1acd528f43bdb0624d4628ba5d3b7ae73833be58701deed845b312a1d29554176b4ebb19364b40e904bfff8464bf0c4c39

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.1.1 - 2026-09-21
+
+- Optimize large GIF quantization and frame-difference encoding.
+
 ## 0.1.0 - 2026-09-20
 
 - Initial release.

data/README.md

@@ -1,25 +1,69 @@
-# Wezen
+<h1 align="center">Wezen</h1>
 
-Wezen is named for δ Canis Majoris, whose IAU name comes from the Arabic
-*al-wazn* (“the weight”). It is a dependency-free Ruby encoder for deterministic
-demo media.
+<p align="center">
+  <strong>Dependency-free Ruby encoders for deterministic APNG, GIF, PNG, and asciinema demo media.</strong>
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/wezen"><img src="https://img.shields.io/gem/v/wezen.svg?color=b7a66f" alt="Gem version"></a>
+  <a href="https://github.com/noxdea/wezen/actions/workflows/main.yml"><img src="https://github.com/noxdea/wezen/actions/workflows/main.yml/badge.svg" alt="CI status"></a>
+  <img src="https://img.shields.io/badge/Ruby-3.1%2B-cc342d" alt="Ruby 3.1 or newer">
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-4c8eda" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#output-formats">Output formats</a> ·
+  <a href="#development">Development</a>
+</p>
+
+---
+
+Wezen turns RGBA frames and terminal events into portable, reproducible demo
+assets. It is built for documentation, fixtures, and recording pipelines where
+the same input should produce the same bytes.
+
+The name comes from δ Canis Majoris: its IAU name derives from the Arabic
+*al-wazn*, meaning “the weight.”
 
 ## Features
 
-- Lossless APNG and PNG output with optional frame rectangles
-- GIF89a output with deterministic median-cut palettes and dithering
-- Pixel scaling, cropping, alpha blending, and change bounds
-- Asciinema v2 JSON Lines casts
+- Lossless APNG with optional changed-frame rectangles, plus PNG stills
+- GIF89a encoding with deterministic median-cut palettes and dithering
+- Frame coalescing, scaling, cropping, sampling, blending, and change bounds
+- Asciinema v2 JSON Lines output for terminal recordings
+- Byte-stable output for identical inputs
 - No runtime dependencies beyond Ruby's `zlib` and `json` standard libraries
 
 ## Installation
 
+Add Wezen to your Gemfile:
+
+```ruby
+gem "wezen"
+```
+
+Then install dependencies:
+
+```sh
+bundle install
+```
+
+Or install the gem directly:
+
 ```sh
 gem install wezen
 ```
 
+Wezen requires Ruby 3.1 or newer.
+
 ## Quick start
 
+Create a two-frame animation and write lossless APNG and compatible GIF
+versions:
+
 ```ruby
 require "wezen"
 
@@ -31,22 +75,115 @@ Wezen::APNG.write("demo.apng", animation)
 Wezen::GIF.write("demo.gif", animation, dither: :bayer)
 ```
 
-`Animation` accepts RGBA strings in row-major order. Repeated frames are
-coalesced and their delays are added. Encoding the same animation twice yields
-the same bytes.
+Frames are packed RGBA strings in row-major order. `Animation#add` merges
+identical consecutive frames and adds their delays automatically.
+
+## Output formats
+
+| Format | Use case | Behavior |
+|---|---|---|
+| APNG | Lossless animation | Preserves RGBA pixels and stores changed rectangles when possible |
+| GIF89a | Broad compatibility | Uses a deterministic global palette with optional dithering |
+| PNG | Still frames | Writes a single lossless RGBA image |
+| Asciinema v2 | Terminal sessions | Writes chronological output, input, and resize events as JSON Lines |
+
+### APNG
+
+APNG is the preferred animation format when color and alpha fidelity matter:
+
+```ruby
+bytes = Wezen::APNG.encode(animation, compression: 9, diff: true)
+File.binwrite("demo.apng", bytes)
+```
+
+### GIF
+
+Control palette size, palette strategy, dithering, and frame differences:
+
+```ruby
+Wezen::GIF.write(
+  "demo.gif",
+  animation,
+  colors: 128,
+  palette: :global,
+  dither: :floyd_steinberg,
+  diff: true
+)
+```
+
+Provide a `Wezen::Palette` when the recording needs a fixed application palette.
+Supported dithering modes are `:floyd_steinberg`, `:bayer`, and `:none`.
+
+### PNG
+
+Write a single packed RGBA frame:
+
+```ruby
+frame = animation.each.first
+Wezen::PNG.write("frame.png", animation.width, animation.height, frame.rgba)
+```
+
+### Asciinema casts
+
+Create an asciinema v2 recording from chronological terminal events:
+
+```ruby
+events = [
+  Wezen::Cast::Event.new(0.0, :output, "$ bundle exec rake\r\n"),
+  Wezen::Cast::Event.new(0.4, :output, "12 examples, 0 failures\r\n")
+]
+
+Wezen::Cast.write(
+  "demo.cast",
+  width: 80,
+  height: 24,
+  title: "Test run",
+  events: events
+)
+```
+
+Event kinds are `:output`, `:input`, and `:resize`.
+
+## Transform animations
+
+Every transformation returns a new `Wezen::Animation`:
+
+```ruby
+animation = animation.coalesce(tolerance: 2)
+animation = animation.scale(to_width: 640, to_height: 360)
+animation = animation.crop([0, 0, 320, 180])
+animation = animation.drop_to(fps: 12)
+```
+
+Use `Wezen::Image` directly for lower-level scaling, cropping, alpha blending,
+and changed-pixel bounds.
+
+## Design decisions
+
+Wezen deliberately ships encoders without runtime decoders. This keeps the gem
+small, portable, and focused while round-trip tests validate generated media.
+
+The architecture records explain the durable format choices:
+
+- [Encode-only scope](docs/adr/001-encode-only.md)
+- [Deterministic global palette](docs/adr/002-global-palette.md)
+- [APNG as the default animation format](docs/adr/003-apng-default.md)
 
 ## Development
 
 ```sh
 bundle install
 bundle exec rake
+bundle exec rake bench
 bundle exec rbs -I sig validate
 gem build --strict wezen.gemspec
 ```
 
-The runtime gem intentionally contains encoders only; decoder helpers belong in
-tests so the package stays small and dependency-free.
+## Contributing
+
+Bug reports and pull requests are welcome in the
+[GitHub repository](https://github.com/noxdea/wezen).
 
 ## License
 
-MIT. See [LICENSE.txt](LICENSE.txt).
+Wezen is available under the [MIT License](LICENSE.txt).

data/lib/wezen/gif.rb

@@ -24,18 +24,25 @@ module Wezen
 
       previous = nil
       animation.each.with_index do |frame, index|
-        indices = Quantize.apply_with_size(frame.rgba, source_palette, width: animation.width, height: animation.height, dither: dither)
-        rect, patch = if index.zero? || !diff || previous.nil?
-          [[0, 0, animation.width, animation.height], indices]
+        rect, patch_rgba = if index.zero? || !diff || previous.nil?
+          [[0, 0, animation.width, animation.height], frame.rgba]
         else
           bounds = Image.diff_bounds(previous, frame.rgba, animation.width, animation.height)
           if bounds
-            [bounds, indexed_crop(indices, animation.width, bounds)]
+            [bounds, Image.crop(frame.rgba, animation.width, animation.height, bounds)]
           else
-            [[0, 0, 1, 1], source_palette.transparent_index.chr]
+            [[0, 0, 1, 1], nil]
           end
         end
-        transparent = source_palette.transparent_index && frame.rgba.bytes.each_slice(4).any? { |pixel| pixel[3] < 128 }
+        patch = if patch_rgba
+          width = rect[2]
+          height = rect[3]
+          transparent = source_palette.transparent_index && patch_rgba.bytes.each_slice(4).any? { |pixel| pixel[3] < 128 }
+          Quantize.apply_with_size(patch_rgba, source_palette, width: width, height: height, dither: dither)
+        else
+          transparent = source_palette.transparent_index
+          patch_rgba
+        end
         output << graphic_control(frame.delay_ms, transparent ? source_palette.transparent_index : nil)
         output << image_descriptor(rect, bits)
         output << sub_blocks(lzw(patch, [bits, 2].max), [bits, 2].max)
@@ -69,13 +76,6 @@ module Wezen
       [44, x, y, width, height, 0].pack("CvvvvC")
     end
 
-    def indexed_crop(indices, width, rect)
-      x, y, crop_width, crop_height = rect
-      output = String.new(capacity: crop_width * crop_height, encoding: Encoding::BINARY)
-      crop_height.times { |row| output << indices.byteslice((y + row) * width + x, crop_width) }
-      output
-    end
-
     def sub_blocks(bytes, minimum_code_size)
       output = minimum_code_size.chr
       bytes.bytes.each_slice(255) { |slice| output << slice.length.chr << slice.pack("C*") }
@@ -105,7 +105,7 @@ module Wezen
         if next_code < 4096
           dictionary[key] = next_code
           next_code += 1
-          code_size += 1 if next_code == (1 << code_size) && code_size < 12
+          code_size += 1 if next_code > (1 << code_size) && code_size < 12
         else
           writer.write(clear, code_size)
           dictionary.clear
@@ -143,6 +143,6 @@ module Wezen
     end
 
     private_class_method :reserve_transparency, :loop_extension, :graphic_control, :image_descriptor,
-      :indexed_crop, :sub_blocks, :lzw
+      :sub_blocks, :lzw
   end
 end

data/lib/wezen/image.rb

@@ -81,10 +81,21 @@ module Wezen
     def diff_bounds(previous, current, width, height)
       validate!(previous, width, height); validate!(current, width, height)
       min_x = width; min_y = height; max_x = -1; max_y = -1
-      (0...(width * height)).each do |index|
-        next if previous.byteslice(index * 4, 4) == current.byteslice(index * 4, 4)
-        x = index % width; y = index / width
-        min_x = x if x < min_x; min_y = y if y < min_y; max_x = x if x > max_x; max_y = y if y > max_y
+      row_bytes = width * 4
+      height.times do |y|
+        row_offset = y * row_bytes
+        next if previous.byteslice(row_offset, row_bytes) == current.byteslice(row_offset, row_bytes)
+
+        width.times do |x|
+          offset = row_offset + x * 4
+          different = previous.getbyte(offset) != current.getbyte(offset) ||
+            previous.getbyte(offset + 1) != current.getbyte(offset + 1) ||
+            previous.getbyte(offset + 2) != current.getbyte(offset + 2) ||
+            previous.getbyte(offset + 3) != current.getbyte(offset + 3)
+          if different
+            min_x = x if x < min_x; min_y = y if y < min_y; max_x = x if x > max_x; max_y = y if y > max_y
+          end
+        end
       end
       max_x.negative? ? nil : [min_x, min_y, max_x - min_x + 1, max_y - min_y + 1]
     end

data/lib/wezen/quantize.rb

@@ -4,13 +4,20 @@ module Wezen
   module Quantize
     module_function
 
+    MAX_PALETTE_SAMPLES = 32_768
+
     def palette(animation, colors:, method: :median_cut)
       raise ArgumentError, "unsupported quantizer: #{method}" unless %i[median_cut octree].include?(method)
       limit = Integer(colors)
       raise ArgumentError, "colors must be between 2 and 256" unless limit.between?(2, 256)
-      pixels = animation.each.flat_map { |frame| frame.rgba.bytes.each_slice(4).reject { |pixel| pixel[3] < 128 }.map { |pixel| pixel[0, 3] } }
+      total_pixels = animation.width * animation.height * animation.size
+      pixels, transparent = if total_pixels <= MAX_PALETTE_SAMPLES
+        [animation.each.flat_map { |frame| frame.rgba.bytes.each_slice(4).reject { |pixel| pixel[3] < 128 }.map { |pixel| pixel[0, 3] } },
+          animation.each.any? { |frame| frame.rgba.bytes.each_slice(4).any? { |pixel| pixel[3] < 128 } }]
+      else
+        sample_pixels(animation, total_pixels)
+      end
       pixels = [[0, 0, 0]] if pixels.empty?
-      transparent = animation.each.any? { |frame| frame.rgba.bytes.each_slice(4).any? { |pixel| pixel[3] < 128 } }
       opaque_limit = transparent ? limit - 1 : limit
       colors_out = median_cut(pixels, opaque_limit)
       if transparent
@@ -21,6 +28,30 @@ module Wezen
       end
     end
 
+    def sample_pixels(animation, total_pixels)
+      # ponytail: cap median-cut input at 32K samples; replace with a weighted histogram if palette fidelity matters.
+      step = (total_pixels.fdiv(MAX_PALETTE_SAMPLES)).ceil
+      pixels = []
+      transparent = false
+      pixel_index = 0
+      next_sample = 0
+      animation.each do |frame|
+        rgba = frame.rgba
+        offset = 0
+        while offset < rgba.bytesize
+          alpha = rgba.getbyte(offset + 3)
+          transparent ||= alpha < 128
+          if pixel_index == next_sample
+            pixels << [rgba.getbyte(offset), rgba.getbyte(offset + 1), rgba.getbyte(offset + 2)] if alpha >= 128
+            next_sample += step
+          end
+          pixel_index += 1
+          offset += 4
+        end
+      end
+      [pixels, transparent]
+    end
+
     def apply(rgba, palette, width: nil, height: nil, dither: :floyd_steinberg)
       raise ArgumentError, "unknown dither: #{dither}" unless %i[none bayer floyd_steinberg].include?(dither)
       raise ArgumentError, "palette must be a Wezen::Palette" unless palette.respond_to?(:colors)
@@ -30,7 +61,11 @@ module Wezen
     end
 
     def apply_with_size(rgba, palette, width:, height:, dither: :floyd_steinberg)
-      raise ArgumentError, "invalid RGBA pixels" unless rgba.bytesize == Integer(width) * Integer(height) * 4
+      width = Integer(width)
+      height = Integer(height)
+      raise ArgumentError, "invalid RGBA pixels" unless rgba.bytesize == width * height * 4
+      return apply_without_error(rgba, palette, width, height, dither) unless dither == :floyd_steinberg
+
       colors = palette.colors
       output = String.new(capacity: width * height, encoding: Encoding::BINARY)
       errors = Array.new(width * 3, 0.0)
@@ -65,6 +100,48 @@ module Wezen
       output
     end
 
+    def apply_without_error(rgba, palette, width, height, dither)
+      colors = palette.colors
+      transparent_index = palette.transparent_index
+      output = String.new(capacity: width * height, encoding: Encoding::BINARY)
+      cache = {}
+      offset = 0
+      x = 0
+      y = 0
+      while offset < rgba.bytesize
+        alpha = rgba.getbyte(offset + 3)
+        if alpha < 128 && transparent_index
+          output << transparent_index
+        else
+          red = rgba.getbyte(offset)
+          green = rgba.getbyte(offset + 1)
+          blue = rgba.getbyte(offset + 2)
+          if dither == :bayer
+            adjustment = (bayer(x, y) * 16 - 8).to_i
+            red = red + adjustment
+            green = green + adjustment
+            blue = blue + adjustment
+            red = 0 if red < 0
+            green = 0 if green < 0
+            blue = 0 if blue < 0
+            red = 255 if red > 255
+            green = 255 if green > 255
+            blue = 255 if blue > 255
+          end
+          key = (red << 16) | (green << 8) | blue
+          cache[key] ||= nearest_rgb(red, green, blue, colors, transparent_index)
+          output << cache[key]
+        end
+        offset += 4
+        x += 1
+        if x == width
+          x = 0
+          y += 1
+        end
+      end
+      output
+    end
+
     def median_cut(pixels, limit)
       boxes = [pixels.sort_by { |pixel| pixel[0] * 65_536 + pixel[1] * 256 + pixel[2] }]
       while boxes.length < limit
@@ -87,9 +164,22 @@ module Wezen
     end
 
     def nearest(pixel, colors, transparent_index)
-      colors.each_with_index.reject { |_color, index| index == transparent_index }.min_by do |color, index|
-        [pixel.each_with_index.sum { |value, channel| (value - color[channel])**2 }, index]
-      end.last
+      nearest_rgb(pixel[0], pixel[1], pixel[2], colors, transparent_index)
+    end
+
+    def nearest_rgb(red, green, blue, colors, transparent_index)
+      best_index = nil
+      best_distance = nil
+      colors.each_with_index do |color, index|
+        next if index == transparent_index
+
+        distance = (red - color[0])**2 + (green - color[1])**2 + (blue - color[2])**2
+        if best_distance.nil? || distance < best_distance
+          best_distance = distance
+          best_index = index
+        end
+      end
+      best_index
     end
 
     def bayer(x, y)
@@ -103,6 +193,6 @@ module Wezen
       add.call(next_errors, x, 5.0 / 16)
       add.call(next_errors, x + 1, 1.0 / 16)
     end
-    private_class_method :median_cut, :nearest, :bayer, :distribute
+    private_class_method :sample_pixels, :median_cut, :nearest, :nearest_rgb, :apply_without_error, :bayer, :distribute
   end
 end

data/lib/wezen/version.rb

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

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wezen
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Yudai Takada
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-20 00:00:00.000000000 Z
 dependencies: []
 description: Pure Ruby encoders and pixel primitives for deterministic demo recordings.
 email:
@@ -44,6 +45,7 @@ metadata:
   source_code_uri: https://github.com/noxdea/wezen/tree/main
   changelog_uri: https://github.com/noxdea/wezen/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -58,7 +60,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: Deterministic GIF, APNG, PNG, and asciinema encoders for Ruby
 test_files: []