tessella 0.3.0

data/lib/tessella/canvas/block.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Tessella
+    class Canvas
+        # 2x2 sub-pixels per cell, packed into the Unicode quadrant
+        # block characters (Block Elements / Symbols for Legacy
+        # Computing): each of the four Unicode glyphs for a quadrant
+        # combination is the only character that means that exact
+        # combination, so this table is fixed by the Unicode names,
+        # not by any library.
+        class Block < Canvas
+            TOP_LEFT = 8
+            TOP_RIGHT = 4
+            BOTTOM_LEFT = 2
+            BOTTOM_RIGHT = 1
+
+            BITS = [
+                [TOP_LEFT, BOTTOM_LEFT],
+                [TOP_RIGHT, BOTTOM_RIGHT]
+            ].freeze
+
+            GLYPHS = [
+                " ", "▗", "▖", "▄", "▝", "▐", "▞", "▟",
+                "▘", "▚", "▌", "▙", "▀", "▜", "▛", "█"
+            ].freeze
+
+            private
+
+            def x_pixel_per_char = 2
+            def y_pixel_per_char = 2
+
+            def encode(code, sub_x, sub_y) = code | BITS[sub_x][sub_y]
+            def decode(code) = GLYPHS[code]
+        end
+
+        register(:block, Block)
+        # The image module's name for the same 2x2 quadrant glyphs.
+        register(:quadrant, Block)
+    end
+end

data/lib/tessella/canvas/braille.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Tessella
+    class Canvas
+        # 2x4 sub-pixels per cell, packed into the Unicode Braille
+        # Patterns block: dot n sets bit 2**(n-1) of the base U+2800,
+        # dots 1/2/3/7 in the left column (top to bottom), 4/5/6/8 in
+        # the right -- the Unicode standard's own dot layout, so this
+        # table is fixed by the codepoint scheme, not by any library.
+        class Braille < Canvas
+            BITS = [
+                [0x01, 0x02, 0x04, 0x40],
+                [0x08, 0x10, 0x20, 0x80]
+            ].freeze
+
+            private
+
+            def x_pixel_per_char = 2
+            def y_pixel_per_char = 4
+
+            def encode(code, sub_x, sub_y) = code | BITS[sub_x][sub_y]
+
+            def decode(code)
+                code.zero? ? " " : [0x2800 | code].pack("U")
+            end
+        end
+
+        register(:braille, Braille)
+    end
+end

data/lib/tessella/canvas/clip.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Tessella
+    class Canvas
+        # A segment far longer than the canvas (a spike past ylim:)
+        # steps only where it crosses the canvas: stepping it all, one
+        # rejected pixel at a time, took minutes for a value a million
+        # times the limits. Shorter segments keep the running sum, and
+        # so unicode_plot's exact pixels.
+        module Clip
+            private
+
+            def long?(steps) = steps > 2 * (pixel_width + pixel_height)
+
+            def clipped_line(from, inc, steps, color)
+                first, last = on_canvas(from, inc, steps)
+                first.upto(last) do |i|
+                    draw_pixel((from[0] + (inc[0] * i)).floor,
+                               (from[1] + (inc[1] * i)).floor, color)
+                end
+            end
+
+            # The steps [first, last] at which both coordinates are on
+            # the canvas, a pixel of margin either side.
+            def on_canvas(from, inc, steps)
+                x = span(from[0], inc[0], pixel_width)
+                y = span(from[1], inc[1], pixel_height)
+                within([x[0], y[0]].max, [x[1], y[1]].min, steps)
+            end
+
+            def within(first, last, steps)
+                [first.clamp(1, steps.ceil), last.clamp(0, steps.floor)]
+            end
+
+            def span(start, inc, size)
+                return flat_span(start, size) if inc.zero?
+
+                a, b = [(-1 - start) / inc, (size + 1 - start) / inc].minmax
+                [a.floor, b.ceil]
+            end
+
+            def flat_span(start, size)
+                start.between?(-1, size + 1) ? [0, Float::INFINITY] : [1, 0]
+            end
+        end
+
+        include Clip
+    end
+end

data/lib/tessella/canvas/density.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Tessella
+    class Canvas
+        # 1x2 sub-pixels per cell; the glyph is chosen by hit count
+        # relative to the densest cell on the canvas, not by position
+        # (DESIGN.md, Canvas). ascii: true swaps the default shade
+        # ramp for an ASCII one (brief rules).
+        class Density < Canvas
+            SIGNS = [" ", "░", "▒", "▓", "█"].freeze
+            ASCII_SIGNS = [" ", ".", ":", "+", "#"].freeze
+
+            def initialize(width, height, xlim:, ylim:, ascii: false)
+                @signs = ascii ? ASCII_SIGNS : SIGNS
+                @max_density = 1
+                super(width, height, xlim: xlim, ylim: ylim)
+            end
+
+            private
+
+            def x_pixel_per_char = 1
+            def y_pixel_per_char = 2
+
+            # The oracle maps a pixel to its cell by floor(float
+            # round-trip), not exact integer division, and this can
+            # round a whole pixel short at some widths/heights (e.g.
+            # 13.fdiv(23) * 23 == 12.999999999999998, D1). Matched
+            # here verbatim for byte parity rather than "fixed", since
+            # the oracle's own output is what rendering must match.
+            def cell_index(px, py)
+                cx = (px.fdiv(pixel_width) * width).floor
+                cy = (py.fdiv(pixel_height) * height).floor
+                (cy * width) + cx
+            end
+
+            def encode(code, _sub_x, _sub_y)
+                count = code + 1
+                @max_density = count if count > @max_density
+                count
+            end
+
+            def decode(code)
+                return " " if code.zero?
+                scale = (@signs.size - 1).fdiv(@max_density)
+                @signs[(code * scale).round]
+            end
+        end
+
+        register(:density, Density)
+    end
+end

data/lib/tessella/canvas/dot.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Tessella
+    class Canvas
+        # 1x2 sub-pixels per cell: the top pixel alone draws a raised
+        # mark, the bottom alone a mark on the baseline, both a colon.
+        class Dot < Canvas
+            TOP = 2
+            BOTTOM = 1
+
+            GLYPHS = [" ", ".", "'", ":"].freeze
+
+            private
+
+            def x_pixel_per_char = 1
+            def y_pixel_per_char = 2
+
+            def encode(code, _sub_x, sub_y)
+                code | (sub_y.zero? ? TOP : BOTTOM)
+            end
+
+            def decode(code) = GLYPHS[code]
+        end
+
+        register(:dot, Dot)
+    end
+end

data/lib/tessella/canvas/eighths.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Tessella
+    class Canvas
+        # Eighth blocks, 1x8 sub-pixels per cell, for fills only (an
+        # area): a cell reads as filled from its bottom up to its
+        # highest pixel -- " ▁▂▃▄▅▆▇█" -- one pixel column per
+        # character, eight height steps. A pixel alone in a cell (a
+        # line, a dot) would read as a bar under it, so the charts take
+        # this canvas only where they fill.
+        class Eighths < Canvas
+            GLYPHS = " ▁▂▃▄▅▆▇█".chars.freeze
+
+            private
+
+            def x_pixel_per_char = 1
+            def y_pixel_per_char = 8
+
+            def encode(code, _sub_x, sub_y) = code | (1 << (7 - sub_y))
+
+            # The highest pixel set, as a height in eighths.
+            def decode(code) = GLYPHS[code.bit_length]
+        end
+
+        # Eighth blocks across, 8x1: a cell reads as filled from its
+        # left edge out to its rightmost pixel -- " ▏▎▍▌▋▊▉█" -- for an
+        # area filled sideways.
+        class EighthsWide < Canvas
+            GLYPHS = " ▏▎▍▌▋▊▉█".chars.freeze
+
+            private
+
+            def x_pixel_per_char = 8
+            def y_pixel_per_char = 1
+
+            def encode(code, sub_x, _sub_y) = code | (1 << sub_x)
+            def decode(code) = GLYPHS[code.bit_length]
+        end
+
+        register(:eighths, Eighths)
+        register(:eighths_wide, EighthsWide)
+    end
+end

data/lib/tessella/canvas/half.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Tessella
+    class Canvas
+        # Half blocks, 1x2 sub-pixels per cell: the upper half, the
+        # lower, or both -- "▀", "▄", "█" -- one pixel column per
+        # character, two rows. A column chart's columns rise by half a
+        # cell; an area fills by halves.
+        class Half < Canvas
+            TOP = 1
+            BOTTOM = 2
+
+            GLYPHS = [" ", "▀", "▄", "█"].freeze
+
+            private
+
+            def x_pixel_per_char = 1
+            def y_pixel_per_char = 2
+
+            def encode(code, _sub_x, sub_y)
+                code | (sub_y.zero? ? TOP : BOTTOM)
+            end
+
+            def decode(code) = GLYPHS[code]
+        end
+
+        # Half blocks across, 2x1 sub-pixels per cell: the left half,
+        # the right, or both -- "▌", "▐", "█" -- so a horizontal bar
+        # grows by half a cell, one bar per text row.
+        class HalfWide < Canvas
+            LEFT = 1
+            RIGHT = 2
+
+            GLYPHS = [" ", "▌", "▐", "█"].freeze
+
+            private
+
+            def x_pixel_per_char = 2
+            def y_pixel_per_char = 1
+
+            def encode(code, sub_x, _sub_y)
+                code | (sub_x.zero? ? LEFT : RIGHT)
+            end
+
+            def decode(code) = GLYPHS[code]
+        end
+
+        register(:half, Half)
+        register(:half_wide, HalfWide)
+    end
+end

data/lib/tessella/canvas/sextant.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Tessella
+    class Canvas
+        # Teletext sextants, 2x3 sub-pixels per cell, solid where
+        # braille is dotted: Unicode 13's Symbols for Legacy Computing
+        # (U+1FB00..1FB3B, with ▌ ▐ █ for the halves and the whole),
+        # Image::SEXTANT's table. Bit (row * 2 + column), top left 1.
+        class Sextant < Canvas
+            private
+
+            def x_pixel_per_char = 2
+            def y_pixel_per_char = 3
+
+            def encode(code, sub_x, sub_y) = code | (1 << ((sub_y * 2) + sub_x))
+            def decode(code) = Image::SEXTANT[code]
+        end
+
+        # Octants, 2x4 sub-pixels per cell: braille's resolution,
+        # solid -- Unicode 16 (U+1CD00..1CDE5 and older glyphs for the
+        # patterns that had one), Image::OCTANT's table, so only the
+        # newest terminals draw them.
+        class Octant < Canvas
+            private
+
+            def x_pixel_per_char = 2
+            def y_pixel_per_char = 4
+
+            def encode(code, sub_x, sub_y) = code | (1 << ((sub_y * 2) + sub_x))
+            def decode(code) = Image::OCTANT[code]
+        end
+
+        register(:sextant, Sextant)
+        register(:octant, Octant)
+    end
+end

data/lib/tessella/canvas.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Tessella
+    # Glyphs written over a canvas's cells, whatever those cells draw:
+    # text (annotate) and point marks (mark). Kept apart from Canvas so
+    # Canvas's own class body stays under budget.
+    module Overlay
+        # char in the cell holding (x, y), over whatever that cell
+        # draws; outside the limits, nothing.
+        def mark(x, y, char, color: nil)
+            return unless x.between?(@xlo, @xhi) && y.between?(@ylo, @yhi)
+
+            px, py = to_pixel(x, y).map(&:floor)
+            px = clip(px, pixel_width)
+            py = clip(py, pixel_height)
+            @overlay[cell_index(px, py)] =
+                Cell.new(char: char, color: cell_color(color, px, py))
+        end
+
+        def annotate(col, row, text, color: nil)
+            text.each_char.with_index do |ch, i|
+                next unless (col + i).between?(0, width - 1) &&
+                            row.between?(0, height - 1)
+                @overlay[(row * width) + col + i] =
+                    Cell.new(char: ch, color: color)
+            end
+        end
+    end
+
+    # A grid of character cells a chart draws data into: data
+    # coordinates map onto pixels, pixel (0, 0) is the bottom-left, and
+    # sub-pixels pack into one Cell per character (DESIGN.md, Canvas).
+    # Concrete sub-pixel layouts live in canvas/*.rb, each registering
+    # itself under its type with Canvas.register.
+    class Canvas
+        include Overlay
+
+        def self.types = (@types ||= {})
+        def self.register(type, klass) = (types[type] = klass)
+
+        # type, width:, height:, xlim:, ylim: and a type's own extras
+        # (density's ascii:). A missing required keyword raises
+        # ArgumentError naming it, as Ruby's own "missing keyword:
+        # :width" does, rather than failing deeper in a subclass.
+        def self.build(type, **opts)
+            klass = types.fetch(type) do
+                raise Error, "unknown canvas type: #{type.inspect}"
+            end
+            missing = %i[width height xlim ylim] - opts.keys
+            unless missing.empty?
+                s = missing.size > 1 ? "s" : ""
+                names = missing.map { ":#{it}" }.join(", ")
+                raise ArgumentError, "missing keyword#{s}: #{names}"
+            end
+            klass.new(opts.delete(:width), opts.delete(:height), **opts)
+        end
+
+        attr_reader :width, :height, :pixel_width, :pixel_height
+
+        def initialize(width, height, xlim:, ylim:)
+            @width = width
+            @height = height
+            @pixel_width = width * x_pixel_per_char
+            @pixel_height = height * y_pixel_per_char
+            @xlo, @xhi = xlim
+            @ylo, @yhi = ylim
+            @grid = Array.new(width * height, blank_code)
+            @colors = Array.new(width * height)
+            @overlay = Array.new(width * height)
+        end
+
+        def point(x, y, color: nil)
+            return unless x.between?(@xlo, @xhi) && y.between?(@ylo, @yhi)
+            draw_pixel(*to_pixel(x, y).map(&:floor), color)
+        end
+
+        def points(xs, ys, color: nil)
+            xs.zip(ys).each { |x, y| point(x, y, color: color) }
+        end
+
+        def line(x0, y0, x1, y1, color: nil)
+            return if out?(x0, x1, @xlo, @xhi) || out?(y0, y1, @ylo, @yhi)
+            draw_line(x0, y0, x1, y1, color)
+        end
+
+        def lines(xs, ys, color: nil)
+            (0...(xs.size - 1)).each do |i|
+                line(xs[i], ys[i], xs[i + 1], ys[i + 1], color: color)
+            end
+        end
+
+        def rows
+            Array.new(height) { |r| Array.new(width) { |c| cell_at(r, c) } }
+        end
+
+        private
+
+        def blank_code = 0
+
+        def out?(a, b, lo, hi) = (a < lo && b < lo) || (a > hi && b > hi)
+
+        def to_pixel(x, y)
+            fx = (x - @xlo).fdiv(@xhi - @xlo) * pixel_width
+            fy = pixel_height - ((y - @ylo).fdiv(@yhi - @ylo) * pixel_height)
+            [fx, fy]
+        end
+
+        def draw_line(x0, y0, x1, y1, color)
+            from = to_pixel(x0, y0)
+            to = to_pixel(x1, y1)
+            draw_pixel(from[0].floor, from[1].floor, color)
+            dda(from, to, color)
+        end
+
+        def dda(from, to, color)
+            dx = to[0] - from[0]
+            dy = to[1] - from[1]
+            steps = [dx.abs, dy.abs].max
+            return if steps.zero?
+
+            inc = [dx.fdiv(steps), dy.fdiv(steps)]
+            line = long?(steps) ? :clipped_line : :step_line
+            send(line, from, inc, steps, color)
+        end
+
+        # A running sum, as unicode_plot (from + inc * i rounds apart).
+        def step_line(from, inc, steps, color)
+            x, y = from
+            1.upto(steps) do
+                draw_pixel((x += inc[0]).floor, (y += inc[1]).floor, color)
+            end
+        end
+
+        # color: a name, or a callable of the cell's row and column.
+        def draw_pixel(px, py, color)
+            return unless px.between?(0, pixel_width) &&
+                          py.between?(0, pixel_height)
+            x = clip(px, pixel_width)
+            y = clip(py, pixel_height)
+            set_sub_pixel(x, y, cell_color(color, x, y))
+        end
+
+        def cell_color(color, px, py)
+            return color unless color.respond_to?(:call) && color.arity == 2
+
+            color.call(py / y_pixel_per_char, px / x_pixel_per_char)
+        end
+
+        def clip(v, max) = v == max ? v - 1 : v
+
+        def set_sub_pixel(px, py, color)
+            i = cell_index(px, py)
+            @grid[i] = encode(@grid[i], px % x_pixel_per_char,
+                              py % y_pixel_per_char)
+            @colors[i] = color unless color.nil?
+        end
+
+        # Overridden by density.rb, D1.
+        def cell_index(px, py)
+            ((py / y_pixel_per_char) * width) + (px / x_pixel_per_char)
+        end
+
+        def cell_at(row, col)
+            i = (row * width) + col
+            @overlay[i] || Cell.new(char: decode(@grid[i]), color: @colors[i])
+        end
+    end
+end

data/lib/tessella/cell.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Tessella
+    # One character cell of a chart body: its glyph, and the colour name
+    # it is drawn in (nil: none). Canvases produce rows of these; the
+    # frame renders them (DESIGN.md).
+    Cell = Data.define(:char, :color) do
+        def self.blank = new(char: " ", color: nil)
+    end
+end