stationery 0.10.0 → 0.11.0

data/lib/stationery/images/webp/lossless.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Images
+    class WebP
+      # A VP8L bitstream (WebP Lossless Bitstream Specification): the header
+      # is read on creation, `pixels` decodes the image to an Array of ARGB
+      # Integers, row by row from the top left.
+      class Lossless
+        SIGNATURE = 0x2F
+        HEADER_BYTES = 5
+        # What one image may decode to; the format itself allows 16384 a
+        # side, which no page needs and an Array of pixels cannot hold cheaply.
+        MAX_PIXELS = 1 << 25
+        PREDICTOR = 0
+        CROSS_COLOR = 1
+        SUBTRACT_GREEN = 2
+
+        attr_reader :width, :height
+
+        def initialize(data)
+          raise UnsupportedImage, "truncated WebP image" if data.bytesize < HEADER_BYTES
+
+          @reader = BitReader.new(data)
+          raise UnsupportedImage, "invalid WebP image: not a lossless bitstream" unless @reader.read(8) == SIGNATURE
+
+          @width = @reader.read(14) + 1
+          @height = @reader.read(14) + 1
+          @alpha = @reader.read(1) == 1
+          raise UnsupportedImage, "invalid WebP image: unknown lossless version" unless @reader.read(3).zero?
+          return if @width * @height <= MAX_PIXELS
+
+          raise UnsupportedImage, "WebP image too large: #{@width}x#{@height} pixels"
+        end
+
+        # Whether the alpha channel means anything; when not, every pixel is opaque.
+        def alpha? = @alpha
+
+        def pixels
+          transforms = read_transforms
+          argb = ImageStream.decode(@reader, @coded_width, @height, top: true)
+          raise UnsupportedImage, "truncated WebP image" if @reader.overrun?
+
+          transforms.reverse_each { |transform| argb = transform.call(argb) }
+          argb
+        rescue UnsupportedImage
+          raise unless @reader.overrun?
+
+          raise UnsupportedImage, "truncated WebP image"
+        end
+
+        private
+
+        # The transforms in the order they were applied, each as a callable
+        # that undoes it. A transform may appear once.
+        def read_transforms
+          @coded_width = @width
+          seen = []
+          transforms = []
+          while @reader.read(1) == 1
+            type = @reader.read(2)
+            raise UnsupportedImage, "invalid WebP image: transform used twice" if seen.include?(type)
+
+            seen << type
+            transforms << read_transform(type)
+          end
+          transforms
+        end
+
+        def read_transform(type)
+          width = @coded_width
+          case type
+          when PREDICTOR
+            bits, image = read_blocks(width)
+            ->(argb) { Predictor.inverse(argb, width, @height, bits, image) }
+          when CROSS_COLOR
+            bits, image = read_blocks(width)
+            ->(argb) { Transforms.cross_color(argb, width, @height, bits, image) }
+          when SUBTRACT_GREEN then Transforms.method(:add_green)
+          else read_color_indexing(width)
+          end
+        end
+
+        # An image of one value per block of 2**bits pixels a side.
+        def read_blocks(width)
+          bits = @reader.read(3) + 2
+          [bits, ImageStream.decode(@reader, ImageStream.subsample(width, bits),
+                                    ImageStream.subsample(@height, bits))]
+        end
+
+        def read_color_indexing(width)
+          size = @reader.read(8) + 1
+          table = Transforms.color_table(ImageStream.decode(@reader, size, 1))
+          bits = Transforms.bundling(size)
+          @coded_width = ImageStream.subsample(width, bits)
+          ->(argb) { Transforms.color_indexing(argb, width, @height, bits, table) }
+        end
+      end
+    end
+  end
+end

data/lib/stationery/images/webp/predictor.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Images
+    class WebP
+      # Reverses the predictor transform: every pixel is stored as its
+      # difference from a prediction made of its left (L), top (T), top-left
+      # (TL) and top-right (TR) neighbours, the mode chosen per block. All
+      # arithmetic is per channel, modulo 256, on packed ARGB Integers.
+      module Predictor
+        BLACK = 0xFF000000
+        ODD = 0xFF00FF00
+        EVEN = 0x00FF00FF
+        # Clears each channel's lowest bit, so halving cannot borrow from
+        # the channel above.
+        HALVES = 0xFEFEFEFE
+
+        module_function
+
+        def inverse(argb, width, height, bits, modes)
+          first_row(argb, width)
+          blocks_wide = ImageStream.subsample(width, bits)
+          (1...height).each do |y|
+            row = y * width
+            argb[row] = add(argb[row], argb[row - width])
+            column = 1
+            while column < width
+              mode = (modes[((y >> bits) * blocks_wide) + (column >> bits)] >> 8) & 0xF
+              stop = [((column >> bits) + 1) << bits, width].min
+              run(mode, argb, row + column, row + stop, width)
+              column = stop
+            end
+          end
+          argb
+        end
+
+        # The top-left pixel is predicted black, the rest of the row from the left.
+        def first_row(argb, width)
+          argb[0] = add(argb[0], BLACK)
+          (1...width).each { |x| argb[x] = add(argb[x], argb[x - 1]) }
+        end
+
+        def run(mode, argb, pos, stop, width)
+          while pos < stop
+            argb[pos] = add(argb[pos], predict(mode, argb, pos, width))
+            pos += 1
+          end
+        end
+
+        # rubocop:disable-next Metrics/AbcSize -- one branch per mode of the format, run per pixel
+        def predict(mode, argb, pos, width)
+          top = pos - width
+          case mode
+          when 1 then argb[pos - 1]
+          when 2 then argb[top]
+          when 3 then argb[top + 1]
+          when 4 then argb[top - 1]
+          when 5 then average(average(argb[pos - 1], argb[top + 1]), argb[top])
+          when 6 then average(argb[pos - 1], argb[top - 1])
+          when 7 then average(argb[pos - 1], argb[top])
+          when 8 then average(argb[top - 1], argb[top])
+          when 9 then average(argb[top], argb[top + 1])
+          when 10 then average(average(argb[pos - 1], argb[top - 1]), average(argb[top], argb[top + 1]))
+          when 11 then select(argb[pos - 1], argb[top], argb[top - 1])
+          when 12 then Gradient.full(argb[pos - 1], argb[top], argb[top - 1])
+          when 13 then Gradient.half(average(argb[pos - 1], argb[top]), argb[top - 1])
+          else BLACK # mode 0, and 14 and 15 which the format leaves unused
+          end
+        end
+
+        def add(a, b)
+          (((a & ODD) + (b & ODD)) & ODD) | (((a & EVEN) + (b & EVEN)) & EVEN)
+        end
+
+        def average(a, b)
+          (((a ^ b) & HALVES) >> 1) + (a & b)
+        end
+
+        # Left or top, whichever is nearer to the gradient L + T - TL.
+        def select(left, top, top_left)
+          distance(top, top_left) < distance(left, top_left) ? left : top
+        end
+
+        def distance(a, b)
+          ((a >> 24) - (b >> 24)).abs + (((a >> 16) & 0xFF) - ((b >> 16) & 0xFF)).abs +
+            (((a >> 8) & 0xFF) - ((b >> 8) & 0xFF)).abs + ((a & 0xFF) - (b & 0xFF)).abs
+        end
+
+        # Modes 12 and 13: the gradient of the neighbours, clamped per channel.
+        module Gradient
+          module_function
+
+          def full(left, top, top_left)
+            (clamp((left >> 24) + (top >> 24) - (top_left >> 24)) << 24) |
+              (clamp(((left >> 16) & 0xFF) + ((top >> 16) & 0xFF) - ((top_left >> 16) & 0xFF)) << 16) |
+              (clamp(((left >> 8) & 0xFF) + ((top >> 8) & 0xFF) - ((top_left >> 8) & 0xFF)) << 8) |
+              clamp((left & 0xFF) + (top & 0xFF) - (top_left & 0xFF))
+          end
+
+          def half(average, top_left)
+            (step(average >> 24, top_left >> 24) << 24) |
+              (step((average >> 16) & 0xFF, (top_left >> 16) & 0xFF) << 16) |
+              (step((average >> 8) & 0xFF, (top_left >> 8) & 0xFF) << 8) |
+              step(average & 0xFF, top_left & 0xFF)
+          end
+
+          # a + (a - b) / 2, the division rounding towards zero.
+          def step(a, b)
+            delta = a - b
+            clamp(a + (delta.negative? ? -(-delta >> 1) : delta >> 1))
+          end
+
+          def clamp(value) = value.clamp(0, 255)
+        end
+      end
+    end
+  end
+end

data/lib/stationery/images/webp/prefix_code.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Images
+    class WebP
+      # Canonical prefix (Huffman) codes as lookup tables. A table is a flat
+      # Array indexed by the next ROOT_BITS bits of the stream: an entry is
+      # `length << 16 | symbol`; codes longer than ROOT_BITS share a LINK
+      # entry (`LINK | bits << 16 | offset`) to a second-level table appended
+      # after the root. A code with a single symbol takes no bits at all.
+      module PrefixCode
+        ROOT_BITS = 8
+        ROOT_SIZE = 1 << ROOT_BITS
+        ROOT_MASK = ROOT_SIZE - 1
+        LINK = 1 << 20
+        MAX_LENGTH = 15
+        # The order the lengths of the code-length code are stored in.
+        LENGTH_ORDER = [17, 18, 0, 1, 2, 3, 4, 5, 16, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15].freeze
+        # Extra bits and base of the repeat codes 16, 17 and 18.
+        REPEATS = [[2, 3], [3, 3], [7, 11]].freeze
+
+        module_function
+
+        # Reads one prefix code over `size` symbols and returns its table.
+        def read(reader, size)
+          build(reader.read(1) == 1 ? simple_lengths(reader, size) : coded_lengths(reader, size))
+        end
+
+        # One or two symbols stored as they are, the code being 0 or 1 bit.
+        def simple_lengths(reader, size)
+          count = reader.read(1) + 1
+          symbols = [reader.read(reader.read(1) == 1 ? 8 : 1)]
+          symbols << reader.read(8) if count == 2
+          raise UnsupportedImage, "invalid WebP image: prefix code symbol out of range" if symbols.max >= size
+
+          lengths = Array.new(size, 0)
+          symbols.each { |symbol| lengths[symbol] = 1 }
+          lengths
+        end
+
+        # Code lengths that are themselves prefix coded, with repeat codes.
+        def coded_lengths(reader, size)
+          code_lengths = Array.new(LENGTH_ORDER.size, 0)
+          (reader.read(4) + 4).times { |i| code_lengths[LENGTH_ORDER[i]] = reader.read(3) }
+          table = build(code_lengths)
+          remaining = reader.read(1) == 1 ? 2 + reader.read(2 + (2 * reader.read(3))) : size
+          raise UnsupportedImage, "invalid WebP image: too many code lengths" if remaining > size
+
+          expand(reader, table, size, remaining)
+        end
+
+        def expand(reader, table, size, remaining)
+          lengths = Array.new(size, 0)
+          previous = 8
+          symbol = 0
+          while symbol < size && remaining.positive?
+            remaining -= 1
+            length = reader.symbol(table)
+            if length < 16
+              lengths[symbol] = length
+              symbol += 1
+              previous = length unless length.zero?
+            else
+              symbol = repeat(reader, lengths, symbol, length, previous)
+            end
+          end
+          lengths
+        end
+
+        def repeat(reader, lengths, symbol, code, previous)
+          bits, base = REPEATS[code - 16]
+          count = reader.read(bits) + base
+          raise UnsupportedImage, "invalid WebP image: code lengths overflow" if symbol + count > lengths.size
+
+          lengths.fill(previous, symbol, count) if code == 16
+          symbol + count
+        end
+
+        # The lookup table of the canonical code with these lengths, which
+        # must be complete (every bit pattern decodes) or hold one symbol.
+        def build(lengths)
+          counts = Array.new(MAX_LENGTH + 1, 0)
+          lengths.each { |length| counts[length] += 1 }
+          used = lengths.size - counts[0]
+          counts[0] = 0
+          return Array.new(ROOT_SIZE, lengths.index(&:positive?)) if used == 1
+
+          space = (1..MAX_LENGTH).sum { |length| counts[length] << (MAX_LENGTH - length) }
+          raise UnsupportedImage, "invalid WebP image: incomplete prefix code" unless space == 1 << MAX_LENGTH
+
+          fill(lengths, counts)
+        end
+
+        def fill(lengths, counts)
+          codes = reversed_codes(lengths, counts)
+          table = Array.new(ROOT_SIZE, 0)
+          link(table, lengths, codes)
+          lengths.each_with_index do |length, symbol|
+            next if length.zero?
+
+            code = codes[symbol]
+            if length <= ROOT_BITS
+              spread(table, 0, ROOT_BITS, code, length, (length << 16) | symbol)
+            else
+              entry = table[code & ROOT_MASK]
+              spread(table, entry & 0xFFFF, (entry >> 16) & 0xF, code >> ROOT_BITS, length - ROOT_BITS,
+                     ((length - ROOT_BITS) << 16) | symbol)
+            end
+          end
+          table
+        end
+
+        # Every symbol's code with its bits reversed, since the stream is
+        # read least significant bit first.
+        def reversed_codes(lengths, counts)
+          code = 0
+          first = Array.new(MAX_LENGTH + 1, 0)
+          (1..MAX_LENGTH).each { |length| first[length] = code = (code + counts[length - 1]) << 1 }
+          lengths.map do |length|
+            next 0 if length.zero?
+
+            value = first[length]
+            first[length] += 1
+            reverse(value, length)
+          end
+        end
+
+        def reverse(value, length)
+          reversed = 0
+          length.times do
+            reversed = (reversed << 1) | (value & 1)
+            value >>= 1
+          end
+          reversed
+        end
+
+        # Appends a second-level table for every root entry that long codes
+        # share, sized for the longest of them.
+        def link(table, lengths, codes)
+          longest = {}
+          lengths.each_with_index do |length, symbol|
+            next unless length > ROOT_BITS
+
+            root = codes[symbol] & ROOT_MASK
+            longest[root] = length if length > longest.fetch(root, 0)
+          end
+          longest.each do |root, length|
+            bits = length - ROOT_BITS
+            table[root] = LINK | (bits << 16) | table.size
+            table.concat(Array.new(1 << bits, 0))
+          end
+        end
+
+        # Writes `entry` at every index of a `bits`-wide table whose low
+        # `length` bits are `code`.
+        def spread(table, offset, bits, code, length, entry)
+          index = code
+          size = 1 << bits
+          step = 1 << length
+          while index < size
+            table[offset + index] = entry
+            index += step
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stationery/images/webp/transforms.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Images
+    class WebP
+      # The subtract-green, cross-colour and colour-indexing transforms,
+      # reversed (the predictor has a file of its own). Each takes and
+      # returns the image as an Array of ARGB Integers.
+      module Transforms
+        module_function
+
+        # Green was subtracted from red and blue.
+        def add_green(argb)
+          argb.map! do |pixel|
+            green = (pixel >> 8) & 0xFF
+            (pixel & 0xFF00FF00) | (((pixel & 0x00FF00FF) + ((green << 16) | green)) & 0x00FF00FF)
+          end
+        end
+
+        # Red was predicted from green, blue from green and red, with
+        # signed 3.5 fixed-point multipliers stored per block.
+        def cross_color(argb, width, height, bits, elements)
+          blocks_wide = ImageStream.subsample(width, bits)
+          height.times do |y|
+            row = y * width
+            column = 0
+            while column < width
+              element = elements[((y >> bits) * blocks_wide) + (column >> bits)]
+              stop = [((column >> bits) + 1) << bits, width].min
+              recolor(argb, row + column, row + stop, element)
+              column = stop
+            end
+          end
+          argb
+        end
+
+        def recolor(argb, pos, stop, element)
+          green_to_red = signed(element & 0xFF)
+          green_to_blue = signed((element >> 8) & 0xFF)
+          red_to_blue = signed((element >> 16) & 0xFF)
+          while pos < stop
+            pixel = argb[pos]
+            green = signed((pixel >> 8) & 0xFF)
+            red = ((pixel >> 16) + ((green_to_red * green) >> 5)) & 0xFF
+            blue = (pixel + ((green_to_blue * green) >> 5) + ((red_to_blue * signed(red)) >> 5)) & 0xFF
+            argb[pos] = (pixel & 0xFF00FF00) | (red << 16) | blue
+            pos += 1
+          end
+        end
+
+        def signed(byte) = byte > 127 ? byte - 256 : byte
+
+        # The colour table as stored: every entry is the difference from the
+        # one before it. Padded to 256 entries so any index finds a colour
+        # (transparent black past the end of the table).
+        def color_table(deltas)
+          previous = 0
+          table = deltas.map { |delta| previous = Predictor.add(delta, previous) }
+          table.fill(0, table.size...256)
+        end
+
+        # Green holds an index into the colour table, or 2, 4 or 8 of them
+        # packed from the lowest bits up when the table is small.
+        def color_indexing(argb, width, height, bits, table)
+          return argb.map! { |pixel| table[(pixel >> 8) & 0xFF] } if bits.zero?
+
+          packed_width = ImageStream.subsample(width, bits)
+          depth = 8 >> bits
+          mask = (1 << depth) - 1
+          out = Array.new(width * height, 0)
+          height.times do |y|
+            source = y * packed_width
+            row = y * width
+            width.times do |x|
+              packed = (argb[source + (x >> bits)] >> 8) & 0xFF
+              out[row + x] = table[(packed >> ((x & ((1 << bits) - 1)) * depth)) & mask]
+            end
+          end
+          out
+        end
+
+        # How many indexes share a pixel for a table of `size` colours, as
+        # the power of two.
+        def bundling(size)
+          return 0 if size > 16
+          return 1 if size > 4
+
+          size > 2 ? 2 : 3
+        end
+      end
+    end
+  end
+end

data/lib/stationery/images/webp.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+require_relative "webp/container"
+require_relative "webp/bit_reader"
+require_relative "webp/prefix_code"
+require_relative "webp/image_stream"
+require_relative "webp/predictor"
+require_relative "webp/transforms"
+require_relative "webp/lossless"
+
+module Stationery
+  module Images
+    # A lossless WebP (VP8L), decoded when it is loaded and embedded like a
+    # PNG with an alpha channel: RGB as a Flate stream, the alpha in a soft
+    # mask when any pixel is not opaque. Lossy and animated WebP are refused.
+    class WebP
+      attr_reader :width, :height
+
+      def initialize(data)
+        container = Container.new(data)
+        lossless = Lossless.new(container.bitstream)
+        @width = lossless.width
+        @height = lossless.height
+        if container.canvas && container.canvas != [@width, @height]
+          raise UnsupportedImage, "invalid WebP image: canvas and image sizes differ"
+        end
+
+        split(lossless.pixels, lossless.alpha?)
+      end
+
+      def inspect = "#<#{self.class} #{@width}x#{@height}>"
+
+      # This image scaled down to `width` pixels (a Resampled), memoised per
+      # width; the same instance is shared through the image cache.
+      def resample(width)
+        @resampled ||= {}
+        @resampled[width] ||= Resampled.new(pixels, width)
+      end
+
+      def build(writer)
+        dictionary = Images.xobject(@width, @height, :DeviceRGB, 8).merge(Filter: :FlateDecode)
+        if @alpha
+          mask = Images.xobject(@width, @height, :DeviceGray, 8).merge(Filter: :FlateDecode)
+          dictionary[:SMask] = writer.add(PDF::Stream.new(Zlib::Deflate.deflate(@alpha), mask))
+        end
+        writer.add(PDF::Stream.new(Zlib::Deflate.deflate(@color), dictionary))
+      end
+
+      private
+
+      # ARGB pixels as the bytes to embed: three per pixel of colour, and
+      # one of alpha unless the image is opaque.
+      def split(argb, alpha)
+        @color = String.new(capacity: argb.size * 3, encoding: Encoding::BINARY)
+        argb.each { |pixel| @color << ((pixel >> 16) & 0xFF) << ((pixel >> 8) & 0xFF) << (pixel & 0xFF) }
+        @alpha = argb.map { |pixel| pixel >> 24 }.pack("C*") if alpha && argb.any? { |pixel| pixel < 0xFF000000 }
+      end
+
+      def pixels
+        Pixels.new(width: @width, height: @height, channels: 3, color: rows(@color, @width * 3),
+                   alpha: @alpha && rows(@alpha, @width))
+      end
+
+      def rows(bytes, stride)
+        Array.new(@height) { |y| bytes.byteslice(y * stride, stride).bytes }
+      end
+    end
+  end
+end

data/lib/stationery/layout/columns/balancer.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    class Columns
+      # Finds the shortest column height at which a pour places everything,
+      # so the columns end at nearly the same height.
+      #
+      # The search runs between a height known to be too short and one known
+      # to fit. It starts at the single-column height divided by the column
+      # count (what perfectly divisible content needs) and, as the answer is
+      # rarely more than a line or two above that, climbs from there in
+      # doubling steps until a height fits, then halves the interval. A height
+      # that fits is lowered to the tallest column it produced, which is a
+      # real break position, so the result is never taller than its content.
+      # Fitting is not strictly monotonic in the height (keep_with_next,
+      # orphans and widows move content in steps), so the answer is the
+      # shortest height found, within TOLERANCE points of the shortest there
+      # is. The probe count is capped: the search ends whatever a split
+      # returns.
+      class Balancer
+        TOLERANCE = 0.5
+        MAX_PROBES = 40
+
+        # `limit` is the tallest a column may be; `fallback` is the pour at
+        # that height when the caller has it already.
+        def initialize(pour, limit: Float::INFINITY, fallback: nil)
+          @pour = pour
+          @limit = limit
+          @fallback = fallback
+        end
+
+        def call
+          high = [@limit, @pour.total].min
+          best = @fallback || @pour.call(high)
+          return best unless best.complete? && @pour.count > 1
+
+          search(best, [high, best.height(@pour.width)].min)
+        end
+
+        private
+
+        def search(best, high)
+          low = 0.0
+          probe = @pour.total / @pour.count
+          step = TOLERANCE
+          MAX_PROBES.times do
+            break if high - low <= TOLERANCE || probe >= high
+
+            poured = @pour.call(probe)
+            if poured.complete?
+              best = poured
+              high = [probe, poured.height(@pour.width)].min
+              step = nil
+            else
+              low = probe
+            end
+            step *= 2 if step
+            probe = [(low + high) / 2.0, step ? low + step : high].min
+          end
+          best
+        end
+      end
+    end
+  end
+end

data/lib/stationery/layout/columns/pour.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    class Columns
+      # What one pour placed: a flow per column that took content, and the
+      # flow left over (nil when everything was placed).
+      Poured = Data.define(:columns, :rest) do
+        def complete? = rest.nil?
+        def height(width) = columns.map { |column| column.measure(width) }.max || 0
+      end
+
+      # Pours a flow into `count` columns of one width: column 1 takes what
+      # fits in the height, column 2 continues where it stopped, and so on. A
+      # column break is a page break with another height, so every column is
+      # cut by Flow#split. A column that places nothing ends the pour, which
+      # is what keeps a pour (and every search over pours) finite.
+      class Pour
+        attr_reader :width, :count
+
+        def initialize(flow, width, count)
+          @flow = flow
+          @width = width
+          @count = count
+        end
+
+        # The height of the flow in a single column.
+        def total = @flow.measure(@width)
+
+        # `fresh:` is true at the top of a page, where a column keeps a child
+        # too tall for it rather than placing nothing.
+        def call(height, fresh: false)
+          columns = []
+          rest = @flow.children.empty? ? nil : @flow
+          while rest && columns.size < @count
+            head, tail = rest.split(@width, height, fresh:)
+            break unless head
+
+            columns << head
+            rest = tail
+          end
+          Poured.new(columns:, rest:)
+        end
+      end
+    end
+  end
+end