tessella 0.3.0

data/lib/tessella/image.rb

@@ -0,0 +1,454 @@
+# frozen_string_literal: true
+
+module Tessella
+    # A picture as text (DESIGN.md, "Images"): tone ramps, shade
+    # blocks, half/quadrant/sextant/braille pixels, or Sobel edges,
+    # with error-diffusion or ordered dithering. Ported from the
+    # ascii-art skill's scripts/img2art.rb; Tessella.image is the
+    # entry point, at the bottom of this file. Its --pad is dropped:
+    # composition pads a block itself (DESIGN.md, "Blocks and
+    # composition"), and a blank braille cell is U+0020, never
+    # U+2800, so every other house rule (no trailing blank, ASCII
+    # from the first byte) falls out of Block on its own.
+    module Image
+        RAMPS = { ramp: " .:-=+*#%@", blocks: " ░▒▓█" }.freeze
+        QUAD = " ▘▝▀▖▌▞▛▗▚▐▜▄▙▟█"
+        BRAILLE_BITS = [[0x01, 0x08], [0x02, 0x10], [0x04, 0x20],
+                        [0x40, 0x80]].freeze
+        # U+1FB00.. enumerates the 6-bit sextant subsets in binary
+        # order (UL=1 UR=2 ML=4 MR=8 LL=16 LR=32), skipping empty/full
+        # and the two half-blocks, which live in U+2580-259F.
+        SEXTANT = (0..63).map do |v|
+            case v
+            when 0  then " "
+            when 21 then "▌"
+            when 42 then "▐"
+            when 63 then "█"
+            else [0x1FB00 + v - 1 - (v > 21 ? 1 : 0) - (v > 42 ? 1 : 0)]
+                .pack("U")
+            end
+        end.freeze
+        STYLES = %i[ramp blocks half quadrant sextant braille octant
+                    petscii edges].freeze
+        DITHERS = %i[none fs atkinson bayer].freeze
+        SUBCELL = { ramp: [1, 1], blocks: [1, 1], half: [1, 2],
+                    quadrant: [2, 2], sextant: [2, 3], braille: [2, 4],
+                    octant: [2, 4], petscii: [4, 8],
+                    edges: [1, 1] }.freeze
+        DEFAULTS = { style: :ramp, width: 78, ramp: nil, gamma: 1.0,
+                     threshold: 0.5, dither: :fs, invert: false,
+                     edge_threshold: 0.3, ascii: false }.freeze
+
+        # A picture whose every cell is blank (edges on a flat image, a
+        # threshold above every tone) is refused as Blank, naming the
+        # options to move, rather than returned as an empty figure.
+        class Blank < ArgumentError; end
+
+        def self.build(source, opts)
+            raster = Source.raster(source)
+            resolved = Options.resolve(DEFAULTS.merge(ascii: Target.ascii?,
+                                                      **opts))
+            rows = Renderer.rows(raster, resolved)
+            if rows.all? { it.strip.empty? }
+                raise Blank, blank_message(resolved)
+            end
+
+            Block.new(rows)
+        end
+
+        def self.blank_message(opts)
+            knob = opts[:style] == :edges ? "edge_threshold" : "threshold"
+            "the picture renders blank at style #{opts[:style]}: lower " \
+                "#{knob}, or try invert or another style"
+        end
+    end
+
+    # Validates Tessella.image's keyword options and resolves the
+    # tone ramp, exactly as img2art.rb's OptionParser does, plus the
+    # ASCII rule this library adds: ascii: true allows only
+    # style: :ramp with an ASCII ramp (DESIGN.md).
+    module Image
+        class Options
+            def self.resolve(opts)
+                new(opts).resolve
+            end
+
+            def initialize(opts)
+                @opts = opts
+            end
+
+            def resolve
+                check_style!
+                check_dither!
+                Check.positive_integer!(@opts[:width], "width")
+                check_numeric!
+                chars = resolve_ramp
+                check_ascii!(chars)
+                @opts.merge(chars: chars)
+            end
+
+            private
+
+            def check_style!
+                return if Image::STYLES.include?(@opts[:style])
+
+                raise ArgumentError, "unknown style: #{@opts[:style].inspect}"
+            end
+
+            def check_dither!
+                return if Image::DITHERS.include?(@opts[:dither])
+
+                raise ArgumentError,
+                      "unknown dither: #{@opts[:dither].inspect}"
+            end
+
+            def check_numeric!
+                Check.finite!([@opts[:gamma]], "gamma")
+                Check.finite!([@opts[:threshold]], "threshold")
+                Check.finite!([@opts[:edge_threshold]], "edge_threshold")
+                Check.positive!(@opts[:gamma], "gamma")
+            end
+
+            # A ramp named in the glyph registry (ramp, blocks, long,
+            # hatch), else the glyphs given; a name wins.
+            def resolve_ramp
+                ramp = @opts[:ramp]
+                named = ramp && Tessella::Glyphs::RAMPS[Borders.name(ramp)]
+                return named if named
+                return check_custom_ramp!(ramp) if ramp
+
+                Image::RAMPS.fetch(@opts[:style], Image::RAMPS[:ramp])
+            end
+
+            # Glyphs of one's own: a String. A Symbol is a ramp's name,
+            # and one the registry lacks is refused, not drawn with.
+            def check_custom_ramp!(ramp)
+                unless ramp.is_a?(String)
+                    names = Tessella::Glyphs::RAMPS.keys.join(", ")
+                    raise ArgumentError, "unknown ramp: #{ramp.inspect} " \
+                                         "(#{names}, or glyphs)"
+                end
+                raise ArgumentError, "ramp must not be empty" if ramp.empty?
+
+                ramp
+            end
+
+            def check_ascii!(chars)
+                return unless @opts[:ascii]
+
+                check_ascii_style!
+                return if chars.ascii_only?
+
+                raise ArgumentError,
+                      "ascii: true needs an ASCII ramp: #{chars.inspect}"
+            end
+
+            def check_ascii_style!
+                return if @opts[:style] == :ramp
+
+                raise ArgumentError,
+                      "ascii: true allows only style: :ramp, not " \
+                      "#{@opts[:style].inspect}"
+            end
+        end
+    end
+
+    # Tessella.image's source: a Raster already decoded, an IO to
+    # read as image bytes (Raster.read), or a String of image bytes
+    # (Raster.decode).
+    module Image
+        module Source
+            def self.raster(source)
+                return source if source.is_a?(Raster)
+                return Raster.read(source) if source.respond_to?(:read)
+                return Raster.decode(source) if source.is_a?(String)
+
+                raise ArgumentError,
+                      "source must be a Raster, IO, or String: " \
+                      "#{source.inspect}"
+            end
+        end
+    end
+
+    # Floyd-Steinberg / Atkinson error diffusion, or a 4x4 Bayer
+    # threshold matrix, turning a sampled luma grid into on/off
+    # cells before a style's glyph table reads it. Ported from
+    # img2art.rb's Dither, byte for byte but for dither: as a Symbol.
+    module Image
+        class Dither
+            KERNELS = {
+                fs: [[1, 0, 7], [-1, 1, 3], [0, 1, 5], [1, 1, 1]]
+                    .map { |x, y, w| [x, y, w / 16.0] },
+                atkinson: [[1, 0], [2, 0], [-1, 1], [0, 1], [1, 1], [0, 2]]
+                          .map { |x, y| [x, y, 1 / 8.0] }
+            }.freeze
+
+            BAYER4 = [[0, 8, 2, 10], [12, 4, 14, 6], [3, 11, 1, 9],
+                      [15, 7, 13, 5]].freeze
+
+            def self.apply(grid, pw, ph, thr, mode)
+                new(grid, pw, ph, thr).run(mode)
+            end
+
+            def initialize(grid, pw, ph, thr)
+                @grid = grid
+                @pw = pw
+                @ph = ph
+                @thr = thr
+            end
+
+            def run(mode)
+                return bayer if mode == :bayer
+
+                diffuse(KERNELS[mode])
+            end
+
+            private
+
+            def bayer
+                @grid.each_with_index.map do |v, i|
+                    cell = BAYER4[(i / @pw) % 4][i % @pw % 4]
+                    v > @thr + ((cell + 0.5) / 16.0) - 0.5
+                end
+            end
+
+            def diffuse(kernel)
+                return @grid.map { |v| v > @thr } unless kernel
+
+                out = Array.new(@grid.size)
+                (0...@ph).each { |y| row(out, y, kernel) }
+                out
+            end
+
+            def row(out, y, kernel)
+                (0...@pw).each do |x|
+                    i = (y * @pw) + x
+                    on = @grid[i] > @thr
+                    out[i] = on
+                    spread(x, y, @grid[i] - (on ? 1.0 : 0.0), kernel)
+                end
+            end
+
+            def spread(x, y, err, kernel)
+                kernel.each do |dx, dy, w|
+                    nx = x + dx
+                    ny = y + dy
+                    next if nx.negative? || nx >= @pw || ny >= @ph
+
+                    @grid[(ny * @pw) + nx] += err * w
+                end
+            end
+        end
+    end
+
+    # Samples a Raster's luma into one float per output pixel (box
+    # filter, gamma and polarity applied), then dithers it into
+    # on/off cells for every style but ramp/blocks/edges, which read
+    # the float tone directly. Ported from img2art.rb's
+    # Renderer#sample, #box_mean, #value and #bits.
+    module Image
+        class Field
+            def initialize(raster, cols, rows, opts)
+                @raster = raster
+                @cols = cols
+                @rows = rows
+                @sw, @sh = SUBCELL[opts[:style]]
+                @pw = cols * @sw
+                @ph = rows * @sh
+                @gamma = opts[:gamma]
+                @invert = opts[:invert]
+                @thr = opts[:threshold]
+                @dither = opts[:dither]
+            end
+
+            def tone(cx, cy) = sample(cx, cy, 1, 1)
+
+            # A subcell's tone, undithered: what petscii matches.
+            def level(x, y) = sample(x, y, @sw, @sh)
+
+            def on?(x, y) = bits[(y * @pw) + x]
+
+            private
+
+            def bits
+                @bits ||= begin
+                    grid = Array.new(@pw * @ph) do |i|
+                        sample(i % @pw, i / @pw, @sw, @sh)
+                    end
+                    Dither.apply(grid, @pw, @ph, @thr, @dither)
+                end
+            end
+
+            def sample(sx, sy, sw, sh)
+                x0, x1 = span(sx, sw, @cols, @raster.width)
+                y0, y1 = span(sy, sh, @rows, @raster.height)
+                value(box_mean(x0, x1, y0, y1))
+            end
+
+            # One axis of a sample window: the source pixels an
+            # output subcell at s (of cells subcells wide) covers,
+            # at least one pixel even when size < cells * sub.
+            def span(s, sub, cells, size)
+                g = cells * sub
+                a = s * size / g
+                [a, [(s + 1) * size / g, a + 1].max]
+            end
+
+            def box_mean(x0, x1, y0, y1)
+                sum = 0.0
+                (y0...y1).each do |y|
+                    (x0...x1).each do |x|
+                        sum += @raster.luma[(y * @raster.width) + x]
+                    end
+                end
+                sum / ((x1 - x0) * (y1 - y0))
+            end
+
+            def value(v)
+                v = 1.0 - v if @invert
+                v**@gamma
+            end
+        end
+    end
+
+    # One character per output cell, from a Field's on/off pixels or
+    # tone, for every style. Ported from img2art.rb's Renderer#glyph
+    # and its per-style methods.
+    module Image
+        class Glyphs
+            include OctantGlyph
+            include PetsciiGlyph
+
+            SOBEL_X = [[-1, -1, -1], [-1, 0, -2], [-1, 1, -1],
+                       [1, -1, 1], [1, 0, 2], [1, 1, 1]].freeze
+            SOBEL_Y = [[-1, -1, -1], [0, -1, -2], [1, -1, -1],
+                       [-1, 1, 1], [0, 1, 2], [1, 1, 1]].freeze
+
+            def initialize(field, opts, cols, rows)
+                @field = field
+                @style = opts[:style]
+                @chars = opts[:chars]
+                @cols = cols
+                @rows = rows
+                @edge_thr = opts[:edge_threshold]
+            end
+
+            # The style's own glyph method; the ramps' is tone.
+            GLYPH = { half: :half, quadrant: :quadrant, sextant: :sextant,
+                      braille: :braille, octant: :octant,
+                      petscii: :petscii, edges: :edge }.freeze
+
+            def glyph(cx, cy) = send(GLYPH.fetch(@style, :tone), cx, cy)
+
+            private
+
+            def tone(cx, cy)
+                v = @field.tone(cx, cy)
+                @chars[(v * (@chars.length - 1)).round]
+            end
+
+            def half(cx, cy)
+                top = @field.on?(cx, cy * 2)
+                bot = @field.on?(cx, (cy * 2) + 1)
+                [" ", "▀", "▄", "█"][(top ? 1 : 0) | (bot ? 2 : 0)]
+            end
+
+            def quadrant(cx, cy)
+                bits = 0
+                [[0, 0, 1], [1, 0, 2], [0, 1, 4], [1, 1, 8]]
+                    .each do |dx, dy, bit|
+                        bits |= bit if @field.on?((cx * 2) + dx, (cy * 2) + dy)
+                    end
+                QUAD[bits]
+            end
+
+            def sextant(cx, cy)
+                bits = 0
+                (0...3).each do |dy|
+                    (0...2).each do |dx|
+                        bits |= 1 << ((dy * 2) + dx) if
+                            @field.on?((cx * 2) + dx, (cy * 3) + dy)
+                    end
+                end
+                SEXTANT[bits]
+            end
+
+            def braille(cx, cy)
+                bits = 0
+                (0...4).each do |dy|
+                    (0...2).each do |dx|
+                        bits |= BRAILLE_BITS[dy][dx] if
+                            @field.on?((cx * 2) + dx, (cy * 4) + dy)
+                    end
+                end
+                bits.zero? ? " " : [0x2800 | bits].pack("U")
+            end
+
+            def cell(cx, cy)
+                @field.tone(cx.clamp(0, @cols - 1), cy.clamp(0, @rows - 1))
+            end
+
+            def edge(cx, cy)
+                gx = SOBEL_X.sum { |dx, dy, w| w * cell(cx + dx, cy + dy) }
+                gy = SOBEL_Y.sum { |dx, dy, w| w * cell(cx + dx, cy + dy) }
+                return " " if Math.hypot(gx, gy) / 4.0 < @edge_thr
+
+                stroke(gx, gy)
+            end
+
+            def stroke(gx, gy)
+                deg = ((Math.atan2(gy, gx) * 180 / Math::PI) + 90) % 180
+                return "─" if deg < 22.5 || deg >= 157.5
+                return "╲" if deg < 67.5
+                return "│" if deg < 112.5
+
+                "╱"
+            end
+        end
+    end
+
+    # The finished grid of lines, one call per output cell through
+    # Glyphs. img2art.rb joined rows with "\n" and trimmed each row's
+    # own trailing blanks (--pad kept them); Block.new on the raw
+    # rows does both instead (DESIGN.md), after the ASCII rule has
+    # already run (Options).
+    module Image
+        class Renderer
+            def self.rows(raster, opts)
+                new(raster, opts).rows
+            end
+
+            def initialize(raster, opts)
+                @cols = opts[:width]
+                @rows = fit_rows(raster, @cols)
+                field = Field.new(raster, @cols, @rows, opts)
+                @glyphs = Glyphs.new(field, opts, @cols, @rows)
+            end
+
+            def rows = (0...@rows).map { |cy| row(cy) }
+
+            private
+
+            # Output rows follow the source aspect; a single row at
+            # least, however wide the source or narrow the width.
+            def fit_rows(raster, cols)
+                [(raster.height * cols / (2.0 * raster.width)).round,
+                 1].max
+            end
+
+            def row(cy)
+                (0...@cols).map { |cx| @glyphs.glyph(cx, cy) }.join
+            end
+        end
+    end
+
+    # style: :ramp, width: 78, ramp: nil, gamma: 1.0, threshold: 0.5,
+    # dither: :fs, invert: false, edge_threshold: 0.3, ascii: false
+    # (Image::DEFAULTS) are every keyword's default; **opts keeps this
+    # within the house parameter-count limit (as Chart#initialize
+    # does), not a looser contract -- an unknown keyword is ignored,
+    # exactly as a missing one falls back to its default.
+    def self.image(source, **opts)
+        Image.build(source, opts)
+    end
+end

data/lib/tessella/image_octant.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Tessella
+    # Octants for Tessella.image (style: :octant): 2x4 pixels per cell,
+    # as braille, but solid -- Unicode 16's Symbols for Legacy
+    # Computing Supplement, U+1CD00..1CDE5, so only the newest
+    # terminals (Ghostty-class) draw them yet. A pattern's bits are its
+    # cells row by row, left then right, top first. The block holds 230
+    # patterns in that bit order; the other 26 are glyphs that already
+    # existed, listed in EXISTING.
+    module Image
+        OCTANT_EXISTING = {
+            0 => " ", 1 => "\u{1CEA8}", 2 => "\u{1CEAB}", 3 => "\u{1FB82}",
+            5 => "▘", 10 => "▝", 15 => "▀", 20 => "\u{1FBE6}",
+            40 => "\u{1FBE7}", 63 => "\u{1FB85}", 64 => "\u{1CEA3}",
+            80 => "▖", 85 => "▌", 90 => "▞", 95 => "▛", 128 => "\u{1CEA0}",
+            160 => "▗", 165 => "▚", 170 => "▐", 175 => "▜", 192 => "▂",
+            240 => "▄", 245 => "▙", 250 => "▟", 252 => "▆", 255 => "█"
+        }.freeze
+
+        OCTANT = begin
+            code = 0x1CD00
+            (0..255).map do |bits|
+                OCTANT_EXISTING.fetch(bits) do
+                    [code].pack("U").tap { code += 1 }
+                end
+            end.freeze
+        end
+
+        # Glyphs#octant: the cell's eight pixels, bit 0 the top left.
+        module OctantGlyph
+            private
+
+            def octant(cx, cy)
+                bits = 0
+                (0...4).each do |dy|
+                    (0...2).each do |dx|
+                        bits |= 1 << ((dy * 2) + dx) if
+                            @field.on?((cx * 2) + dx, (cy * 4) + dy)
+                    end
+                end
+                OCTANT[bits]
+            end
+        end
+    end
+end

data/lib/tessella/image_petscii.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Tessella
+    # PETSCII-style pictures for Tessella.image (style: :petscii): each
+    # cell is sampled as 4x8 tones and drawn with the glyph whose shape
+    # fits them best (least squared error), from a set in the spirit of
+    # the Commodore character ROM -- blocks, halves and quadrants,
+    # quarter and three-quarter blocks on every side (the upper and
+    # right ones from Symbols for Legacy Computing), eighth-lines,
+    # diagonal triangles and lines, shades, line pieces, discs. The
+    # shape a glyph draws is a function of the cell's x and y (0..1, y
+    # down), so the set is one table. Threshold and dither do
+    # not apply: the match reads tones, not on/off pixels.
+    module Image
+        HLINE = ->(_x, y) { (y - 0.5).abs < 0.13 }
+        VLINE = ->(x, _y) { (x - 0.5).abs < 0.26 }
+
+        PETSCII_SHAPES = {
+            " " => ->(_x, _y) { false }, "█" => ->(_x, _y) { true },
+            "▀" => ->(_x, y) { y < 0.5 }, "▄" => ->(_x, y) { y >= 0.5 },
+            "▌" => ->(x, _y) { x < 0.5 }, "▐" => ->(x, _y) { x >= 0.5 },
+            "▘" => ->(x, y) { x < 0.5 && y < 0.5 },
+            "▝" => ->(x, y) { x >= 0.5 && y < 0.5 },
+            "▖" => ->(x, y) { x < 0.5 && y >= 0.5 },
+            "▗" => ->(x, y) { x >= 0.5 && y >= 0.5 },
+            "▚" => ->(x, y) { (x < 0.5) == (y < 0.5) },
+            "▞" => ->(x, y) { (x < 0.5) != (y < 0.5) },
+            "▙" => ->(x, y) { x < 0.5 || y >= 0.5 },
+            "▛" => ->(x, y) { x < 0.5 || y < 0.5 },
+            "▜" => ->(x, y) { x >= 0.5 || y < 0.5 },
+            "▟" => ->(x, y) { x >= 0.5 || y >= 0.5 },
+            "▏" => ->(x, _y) { x < 0.25 }, "▕" => ->(x, _y) { x >= 0.75 },
+            "▔" => ->(_x, y) { y < 0.125 }, "▁" => ->(_x, y) { y >= 0.875 },
+            "▊" => ->(x, _y) { x < 0.75 },
+            "\u{1FB8A}" => ->(x, _y) { x >= 0.25 },
+            "▂" => ->(_x, y) { y >= 0.75 }, "▆" => ->(_x, y) { y >= 0.25 },
+            "\u{1FB82}" => ->(_x, y) { y < 0.25 },
+            "\u{1FB85}" => ->(_x, y) { y < 0.75 },
+            "◢" => ->(x, y) { x + y >= 1 }, "◣" => ->(x, y) { y >= x },
+            "◤" => ->(x, y) { x + y < 1 }, "◥" => ->(x, y) { x > y },
+            "╱" => ->(x, y) { (x + y - 1).abs < 0.22 },
+            "╲" => ->(x, y) { (x - y).abs < 0.22 },
+            "╳" => ->(x, y) { (x + y - 1).abs < 0.22 || (x - y).abs < 0.22 },
+            "─" => HLINE, "│" => VLINE,
+            "┼" => ->(x, y) { HLINE.call(x, y) || VLINE.call(x, y) },
+            "┌" => ->(x, y) { corner(x, y, x >= 0.375, y >= 0.4375) },
+            "┐" => ->(x, y) { corner(x, y, x < 0.625, y >= 0.4375) },
+            "└" => ->(x, y) { corner(x, y, x >= 0.375, y < 0.5625) },
+            "┘" => ->(x, y) { corner(x, y, x < 0.625, y < 0.5625) },
+            "├" => lambda { |x, y|
+                VLINE.call(x, y) || (HLINE.call(x, y) && x >= 0.375)
+            },
+            "┤" => lambda { |x, y|
+                VLINE.call(x, y) || (HLINE.call(x, y) && x < 0.625)
+            },
+            "┬" => lambda { |x, y|
+                HLINE.call(x, y) || (VLINE.call(x, y) && y >= 0.4375)
+            },
+            "┴" => lambda { |x, y|
+                HLINE.call(x, y) || (VLINE.call(x, y) && y < 0.5625)
+            },
+            "●" => ->(x, y) { disc(x, y) < 0.42 },
+            "○" => ->(x, y) { disc(x, y).between?(0.25, 0.45) }
+        }.freeze
+
+        # A corner piece: the horizontal run on one side, the vertical
+        # on the other.
+        def self.corner(x, y, across, down)
+            (HLINE.call(x, y) && across) || (VLINE.call(x, y) && down)
+        end
+
+        # Distance from the cell's centre, x counted half as much: the
+        # cell is twice as tall as wide, so this is a round disc.
+        def self.disc(x, y) = Math.hypot((x - 0.5) * 0.5, y - 0.5)
+
+        PETSCII_SUB = [4, 8].freeze
+
+        # Each glyph's shape as 4x8 ink (1.0) or paper (0.0), row by
+        # row, plus the shades as flat tones.
+        PETSCII = begin
+            sw, sh = PETSCII_SUB
+            shapes = PETSCII_SHAPES.transform_values do |shape|
+                (0...sh).flat_map do |y|
+                    (0...sw).map do |x|
+                        shape.call((x + 0.5) / sw, (y + 0.5) / sh) ? 1.0 : 0.0
+                    end
+                end
+            end
+            shades = { "░" => 0.25, "▒" => 0.5, "▓" => 0.75 }
+                     .transform_values { Array.new(sw * sh, it) }
+            shapes.merge(shades).freeze
+        end
+
+        # Glyphs#petscii: the glyph of least squared error over the
+        # cell's 4x8 tones.
+        module PetsciiGlyph
+            private
+
+            def petscii(cx, cy)
+                tones = petscii_tones(cx, cy)
+                PETSCII.min_by do |_, ink|
+                    ink.each_with_index.sum { |v, i| (v - tones[i])**2 }
+                end.first
+            end
+
+            def petscii_tones(cx, cy)
+                sw, sh = PETSCII_SUB
+                (0...sh).flat_map do |y|
+                    (0...sw).map do |x|
+                        @field.level((cx * sw) + x, (cy * sh) + y)
+                    end
+                end
+            end
+        end
+    end
+end