qr_reader 0.0.1

data/lib/qr_reader/decoder/bitstream_parser.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+module QrReader
+  module Decoder
+    # Raised by BitstreamParser for data that violates the bit stream syntax.
+    # Decoder.decode turns it into a nil result.
+    class FormatError < Error; end
+
+    # Decoded data of one symbol, before it is wrapped into a Result (same
+    # meaning as the Result attributes of the same names).
+    Content = Data.define(:text, :raw_bytes, :segments, :eci, :fnc1, :structured_append, :symbology_identifier)
+
+    # Parses the data codewords of a symbol (ISO/IEC 18004 §7.4): a sequence
+    # of segments, each a 4-bit mode indicator followed by mode-specific data,
+    # ended by the terminator 0000 or by running out of bits (fewer than 4 left).
+    #
+    #   BitstreamParser.parse("\x40\x24\x86\x90\xec".b, 1).text  # => "Hi" (byte mode, 2 chars)
+    class BitstreamParser
+      TERMINATOR = 0x0
+      NUMERIC = 0x1
+      ALPHANUMERIC = 0x2
+      STRUCTURED_APPEND = 0x3
+      BYTE = 0x4
+      FNC1_FIRST = 0x5
+      ECI = 0x7
+      KANJI = 0x8
+      FNC1_SECOND = 0x9
+      HANZI = 0xD
+
+      # Character count indicator lengths for versions 1-9, 10-26 and 27-40.
+      COUNT_BITS = {
+        NUMERIC => [10, 12, 14], ALPHANUMERIC => [9, 11, 13], BYTE => [8, 16, 16],
+        KANJI => [8, 10, 12], HANZI => [8, 10, 12]
+      }.freeze
+
+      ALPHANUMERIC_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./:".b.freeze
+      # Decoded text for every valid 10-bit numeric group ("000".."999").
+      DIGIT_TRIPLES = ("000".."999").map(&:freeze).freeze
+      GB2312_SUBSET = 1
+      GROUP_SEPARATOR = "\x1D".b.freeze
+      ASCII = Encoding::US_ASCII
+
+      # Parses +data+ (binary String of data codewords) of a symbol of version
+      # +version+ (1..40). Returns a Content; raises FormatError.
+      def self.parse(data, version)
+        new(data, version).parse
+      end
+
+      def initialize(data, version)
+        raise ArgumentError, "version must be 1..40" unless version.is_a?(Integer) && version.between?(1, 40)
+
+        @data = data.b + "\0\0" # padding so a 24-bit window never reads past the end
+        @limit = data.bytesize * 8
+        @pos = 0
+        @size_class = if version <= 9 then 0
+                      elsif version <= 26 then 1
+                      else 2
+                      end
+      end
+
+      def parse
+        segments = [] # [mode, bytes, eci designator or nil]
+        eci = nil
+        first_eci = nil
+        fnc1 = nil
+        structured_append = nil
+        while @limit - @pos >= 4
+          mode = read_bits(4)
+          case mode
+          when TERMINATOR
+            break
+          when NUMERIC
+            segments << [:numeric, numeric(read_count(mode)), eci]
+          when ALPHANUMERIC
+            segments << [:alphanumeric, alphanumeric(read_count(mode), fnc1), eci]
+          when BYTE
+            segments << [:byte, byte(read_count(mode)), eci]
+          when KANJI
+            segments << [:kanji, kanji(read_count(mode)), eci]
+          when HANZI
+            subset = read_bits(4)
+            count = read_count(mode)
+            raise FormatError, "unsupported Hanzi subset #{subset}" unless subset == GB2312_SUBSET
+
+            segments << [:hanzi, hanzi(count), eci]
+          when ECI
+            eci = read_eci
+            first_eci ||= eci
+          when FNC1_FIRST
+            fnc1 = :first
+          when FNC1_SECOND
+            fnc1 = [:second, application_indicator]
+          when STRUCTURED_APPEND
+            sequence = read_bits(8)
+            structured_append = StructuredAppend.new(index: sequence >> 4, count: (sequence & 0x0F) + 1,
+                                                     parity: read_bits(8))
+          else
+            raise FormatError, format("invalid mode indicator %04b", mode)
+          end
+        end
+        build_content(segments, first_eci, fnc1, structured_append)
+      end
+
+      private
+
+      def available
+        @limit - @pos
+      end
+
+      # Next +count+ (<= 17) bits as an Integer, most significant first.
+      def read_bits(count)
+        pos = @pos
+        raise FormatError, "bit stream ends early" if pos + count > @limit
+
+        data = @data
+        index = pos >> 3
+        window = (data.getbyte(index) << 16) | (data.getbyte(index + 1) << 8) | data.getbyte(index + 2)
+        @pos = pos + count
+        (window >> (24 - (pos & 7) - count)) & ((1 << count) - 1)
+      end
+
+      def read_count(mode)
+        read_bits(COUNT_BITS[mode][@size_class])
+      end
+
+      def require_bits(count)
+        raise FormatError, "segment longer than the remaining data" if count > available
+      end
+
+      # 3 digits per 10 bits; a remainder of 2 digits takes 7 bits, 1 digit 4 bits.
+      def numeric(count)
+        require_bits(count / 3 * 10 + [0, 4, 7][count % 3])
+        out = "".b
+        while count >= 3
+          value = read_bits(10)
+          raise FormatError, "invalid numeric group #{value}" if value >= 1000
+
+          out << DIGIT_TRIPLES[value]
+          count -= 3
+        end
+        if count == 2
+          value = read_bits(7)
+          raise FormatError, "invalid numeric group #{value}" if value >= 100
+
+          out << DIGIT_TRIPLES[value].byteslice(1, 2)
+        elsif count == 1
+          value = read_bits(4)
+          raise FormatError, "invalid numeric digit #{value}" if value >= 10
+
+          out << DIGIT_TRIPLES[value].byteslice(2, 1)
+        end
+        out
+      end
+
+      # 2 characters per 11 bits, a final odd character in 6 bits. With FNC1
+      # in effect, "%%" stands for "%" and a lone "%" for the GS separator.
+      def alphanumeric(count, fnc1)
+        require_bits(count / 2 * 11 + (count.odd? ? 6 : 0))
+        out = "".b
+        while count >= 2
+          value = read_bits(11)
+          raise FormatError, "invalid alphanumeric pair #{value}" if value >= 2025
+
+          out << ALPHANUMERIC_CHARS.getbyte(value / 45) << ALPHANUMERIC_CHARS.getbyte(value % 45)
+          count -= 2
+        end
+        if count == 1
+          value = read_bits(6)
+          raise FormatError, "invalid alphanumeric character #{value}" if value >= 45
+
+          out << ALPHANUMERIC_CHARS.getbyte(value)
+        end
+        out = out.gsub(/%%?/n) { |m| m.bytesize == 2 ? "%" : GROUP_SEPARATOR } if fnc1 && out.include?("%")
+        out
+      end
+
+      def byte(count)
+        require_bits(count * 8)
+        start = @pos
+        shift = start & 7
+        @pos = start + count * 8
+        return @data.byteslice(start >> 3, count) if shift.zero?
+
+        # Unaligned: re-pack through a "0101..." string, at C speed.
+        [@data.byteslice(start >> 3, count + 1).unpack1("B*").byteslice(shift, count * 8)].pack("B*")
+      end
+
+      # 13 bits per character: the Shift_JIS code minus 0x8140 or 0xC140,
+      # high byte times 0xC0 plus low byte.
+      def kanji(count)
+        require_bits(count * 13)
+        out = "".b
+        while count.positive?
+          value = read_bits(13)
+          code = ((value / 0xC0) << 8) | (value % 0xC0)
+          code += code < 0x1F00 ? 0x8140 : 0xC140
+          out << (code >> 8) << (code & 0xFF)
+          count -= 1
+        end
+        out
+      end
+
+      # 13 bits per character: the GB 2312 code minus 0xA1A1 or 0xA6A1,
+      # high byte times 0x60 plus low byte.
+      def hanzi(count)
+        require_bits(count * 13)
+        out = "".b
+        while count.positive?
+          value = read_bits(13)
+          code = ((value / 0x60) << 8) | (value % 0x60)
+          code += code < 0x0A00 ? 0xA1A1 : 0xA6A1
+          out << ((code >> 8) & 0xFF) << (code & 0xFF)
+          count -= 1
+        end
+        out
+      end
+
+      # ECI designator in 1, 2 or 3 bytes (0xxxxxxx, 10xxxxxx +8, 110xxxxx +16).
+      def read_eci
+        first = read_bits(8)
+        value = if (first & 0x80).zero?
+                  first
+                elsif (first & 0xC0) == 0x80
+                  ((first & 0x3F) << 8) | read_bits(8)
+                elsif (first & 0xE0) == 0xC0
+                  ((first & 0x1F) << 16) | read_bits(16)
+                else
+                  raise FormatError, "invalid ECI designator"
+                end
+        raise FormatError, "ECI designator #{value} out of range" if value > 999_999
+
+        value
+      end
+
+      # FNC1 in second position is followed by an application indicator:
+      # two digits (00-99) or one letter (encoded as its ASCII value + 100).
+      def application_indicator
+        value = read_bits(8)
+        return format("%02d", value) if value < 100
+        return (value - 100).chr if value.between?(165, 190) || value.between?(197, 222)
+
+        raise FormatError, "invalid FNC1 application indicator #{value}"
+      end
+
+      def build_content(segments, first_eci, fnc1, structured_append)
+        guessed = guess_encoding(segments) unless first_eci
+        resolved = segments.map do |mode, bytes, eci|
+          [mode, bytes, eci, segment_encoding(mode, eci, first_eci, guessed)]
+        end
+        text = +""
+        bytes = "".b
+        segment_list = []
+        run_start = 0
+        resolved.each_with_index do |(mode, data, eci, encoding), i|
+          bytes << data
+          segment_list << Segment.new(mode: mode, text: CharacterSet.to_utf8(data, encoding), eci: eci)
+          next_encoding = resolved[i + 1]&.last
+          next if next_encoding == encoding
+
+          # Convert runs of segments in the same encoding together, so a
+          # character split across segments survives.
+          text << if run_start == i
+                    segment_list[i].text
+                  else
+                    CharacterSet.to_utf8(resolved[run_start..i].map { |s| s[1] }.join, encoding)
+                  end
+          run_start = i + 1
+        end
+        Content.new(text: text, raw_bytes: bytes, segments: segment_list.freeze, eci: first_eci, fnc1: fnc1,
+                    structured_append: structured_append,
+                    symbology_identifier: "]Q#{symbology_modifier(first_eci, fnc1)}")
+      end
+
+      # ISO/IEC 18004 Table F.1: 1 plain, 3 FNC1 first, 5 FNC1 second;
+      # one more when an ECI is present.
+      def symbology_modifier(eci, fnc1)
+        base = if fnc1 == :first then 3
+               elsif fnc1 then 5
+               else 1
+               end
+        eci ? base + 1 : base
+      end
+
+      # Without any ECI, all byte segments share one guessed encoding.
+      def guess_encoding(segments)
+        data = segments.filter_map { |mode, bytes, _| bytes if mode == :byte }
+        data.empty? ? nil : CharacterSet.guess(data.join)
+      end
+
+      def segment_encoding(mode, eci, first_eci, guessed)
+        case mode
+        when :numeric, :alphanumeric then ASCII
+        when :kanji then CharacterSet::SHIFT_JIS
+        when :hanzi then CharacterSet::GB18030
+        else
+          if eci
+            CharacterSet.for_eci(eci) || CharacterSet::ISO_8859_1
+          elsif first_eci
+            CharacterSet::ISO_8859_1 # default ECI 000003 before the first ECI
+          else
+            guessed
+          end
+        end
+      end
+    end
+  end
+end

data/lib/qr_reader/decoder/character_set.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module QrReader
+  module Decoder
+    # Character sets: ECI designators to Ruby encodings, the encoding guess
+    # for byte segments without ECI, and conversion to valid UTF-8.
+    module CharacterSet
+      UTF_8 = Encoding::UTF_8
+      BINARY = Encoding::BINARY
+      ISO_8859_1 = Encoding::ISO_8859_1
+      SHIFT_JIS = Encoding::Shift_JIS
+      # Superset of Shift_JIS (NEC/IBM extensions); used when strict Shift_JIS
+      # cannot represent a character.
+      WINDOWS_31J = Encoding::Windows_31J
+      # Superset of GB 2312 (EUC-CN), used for Hanzi mode.
+      GB18030 = Encoding::GB18030
+
+      # ECI designator => Encoding (ISO/IEC 18004 / AIM ECI assignments as used
+      # by ZXing). 899 is "binary": the bytes are shown as ISO-8859-1.
+      ECI_ENCODINGS = {
+        0 => Encoding::IBM437, 2 => Encoding::IBM437,
+        1 => ISO_8859_1, 3 => ISO_8859_1,
+        4 => Encoding::ISO_8859_2, 5 => Encoding::ISO_8859_3, 6 => Encoding::ISO_8859_4,
+        7 => Encoding::ISO_8859_5, 8 => Encoding::ISO_8859_6, 9 => Encoding::ISO_8859_7,
+        10 => Encoding::ISO_8859_8, 11 => Encoding::ISO_8859_9, 12 => Encoding::ISO_8859_10,
+        13 => Encoding::ISO_8859_11, 15 => Encoding::ISO_8859_13, 16 => Encoding::ISO_8859_14,
+        17 => Encoding::ISO_8859_15, 18 => Encoding::ISO_8859_16,
+        20 => SHIFT_JIS,
+        21 => Encoding::Windows_1250, 22 => Encoding::Windows_1251,
+        23 => Encoding::Windows_1252, 24 => Encoding::Windows_1256,
+        25 => Encoding::UTF_16BE, 26 => UTF_8,
+        27 => Encoding::US_ASCII, 170 => Encoding::US_ASCII,
+        28 => Encoding::Big5, 29 => GB18030, 30 => Encoding::EUC_KR,
+        899 => BINARY
+      }.freeze
+
+      # Decodes one character that Shift_JIS cannot map, via Windows-31J.
+      WINDOWS_31J_FALLBACK = lambda do |char|
+        char.dup.force_encoding(WINDOWS_31J).encode(UTF_8, invalid: :replace, undef: :replace)
+      end
+
+      # GB 18030-2000 private-use code points (from the 2-byte codes A6D9..A6DF,
+      # A6EC, A6ED, A6F3 and A8BC) and their GB 18030-2005 replacements.
+      GB18030_PUA = "\uE78D\uE78E\uE78F\uE790\uE791\uE792\uE793\uE794\uE795\uE796\uE7C7"
+      GB18030_2005 = "\uFE10\uFE12\uFE11\uFE13\uFE14\uFE15\uFE16\uFE17\uFE18\uFE19\u1E3F"
+
+      module_function
+
+      # Encoding for an ECI designator, or nil if it names no known character set.
+      def for_eci(designator)
+        ECI_ENCODINGS[designator]
+      end
+
+      # Guesses the encoding of byte-mode data without ECI, following ZXing's
+      # StringUtils.guessCharset: UTF-16 with BOM; UTF-8 if the bytes are valid
+      # UTF-8 (strictly) containing multibyte characters; Shift_JIS if the bytes
+      # look like it (runs of 3+ double-byte or half-width katakana characters,
+      # or many Latin-1 symbols); else ISO-8859-1. Like zxing-cpp, control
+      # characters other than CR/LF mark the data as binary, not Shift_JIS,
+      # so that it decodes losslessly as ISO-8859-1.
+      def guess(bytes)
+        return ISO_8859_1 if bytes.ascii_only?
+
+        if bytes.bytesize > 2
+          b0 = bytes.getbyte(0)
+          b1 = bytes.getbyte(1)
+          return Encoding::UTF_16BE if b0 == 0xFE && b1 == 0xFF
+          return Encoding::UTF_16LE if b0 == 0xFF && b1 == 0xFE
+        end
+        return UTF_8 if bytes.dup.force_encoding(UTF_8).valid_encoding?
+
+        guess_latin1_or_shift_jis(bytes)
+      end
+
+      # Converts +bytes+ in +encoding+ to a valid UTF-8 String (invalid or
+      # unmappable sequences become U+FFFD).
+      def to_utf8(bytes, encoding)
+        return bytes.dup.force_encoding(UTF_8) if bytes.ascii_only? && encoding.ascii_compatible?
+
+        case encoding
+        when UTF_8
+          bytes.dup.force_encoding(UTF_8).scrub
+        when BINARY
+          bytes.encode(UTF_8, ISO_8859_1)
+        when SHIFT_JIS
+          # Characters Shift_JIS lacks (NEC/IBM extensions) are taken from
+          # Windows-31J one by one, so the rest keep their JIS X 0208 mapping.
+          # Ruby maps 0x815C to U+2014 EM DASH; ZXing and zxing-cpp (like
+          # Unicode's SHIFTJIS.TXT and Windows-31J) to U+2015 HORIZONTAL BAR.
+          bytes.encode(UTF_8, SHIFT_JIS, invalid: :replace, fallback: WINDOWS_31J_FALLBACK).tr("\u2014", "\u2015")
+        when GB18030
+          # Ruby uses the GB 18030-2000 private-use mappings for 11 GBK codes
+          # that GB 18030-2005 (and zxing-cpp) map to standard characters.
+          bytes.encode(UTF_8, GB18030, invalid: :replace, undef: :replace).tr(GB18030_PUA, GB18030_2005)
+        when Encoding::UTF_16BE, Encoding::UTF_16LE
+          text = bytes.encode(UTF_8, encoding, invalid: :replace, undef: :replace)
+          text.delete_prefix("\uFEFF")
+        else
+          bytes.encode(UTF_8, encoding, invalid: :replace, undef: :replace)
+        end
+      end
+
+      # ZXing's Latin-1 vs. Shift_JIS heuristics (bytes known not to be UTF-8).
+      def guess_latin1_or_shift_jis(bytes)
+        can_be_latin1 = true
+        can_be_sjis = true
+        sjis_bytes_left = 0
+        katakana_chars = 0
+        katakana_run = 0
+        double_byte_run = 0
+        max_katakana_run = 0
+        max_double_byte_run = 0
+        latin1_high_other = 0
+        bytes.each_byte do |v|
+          if can_be_latin1
+            if v > 0x7F && v < 0xA0
+              can_be_latin1 = false
+            elsif v > 0x9F && (v < 0xC0 || v == 0xD7 || v == 0xF7)
+              latin1_high_other += 1
+            end
+          end
+          if can_be_sjis
+            if sjis_bytes_left.positive?
+              if v < 0x40 || v == 0x7F || v > 0xFC
+                can_be_sjis = false
+              else
+                sjis_bytes_left -= 1
+              end
+            elsif v == 0x80 || v == 0xA0 || v > 0xEF || (v < 0x20 && v != 0x0A && v != 0x0D)
+              can_be_sjis = false
+            elsif v > 0xA0 && v < 0xE0
+              katakana_chars += 1
+              double_byte_run = 0
+              katakana_run += 1
+              max_katakana_run = katakana_run if katakana_run > max_katakana_run
+            elsif v > 0x7F
+              sjis_bytes_left += 1
+              katakana_run = 0
+              double_byte_run += 1
+              max_double_byte_run = double_byte_run if double_byte_run > max_double_byte_run
+            else
+              katakana_run = 0
+              double_byte_run = 0
+            end
+          end
+          break unless can_be_latin1 || can_be_sjis
+        end
+        can_be_sjis = false if sjis_bytes_left.positive?
+
+        return SHIFT_JIS if can_be_sjis && (max_katakana_run >= 3 || max_double_byte_run >= 3)
+
+        if can_be_latin1 && can_be_sjis
+          return SHIFT_JIS if (max_katakana_run == 2 && katakana_chars == 2) || latin1_high_other * 10 >= bytes.bytesize
+
+          return ISO_8859_1
+        end
+        return SHIFT_JIS if can_be_sjis && !can_be_latin1
+
+        ISO_8859_1
+      end
+    end
+  end
+end

data/lib/qr_reader/decoder/codewords.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module QrReader
+  module Decoder
+    # Codeword placement (ISO/IEC 18004 §7.7.3) and block structure.
+    #
+    # Everything that depends only on the version is computed once and cached
+    # in a Layout: the module indices of all data bits in zig-zag placement
+    # order, the data mask as one XOR value per codeword, and per EC level
+    # the raw codeword indices of every RS block. Reading a block is then a
+    # tight loop of getbyte calls on the module grid.
+    module Codewords
+      # Precomputed tables for one symbol version.
+      class Layout
+        # +order+: module indices of the data bits in placement order, 8 per
+        # codeword. +mirrored_order+: the same for a symbol stored transposed
+        # (mirrored), where module (x, y) lives at x * n + y.
+        attr_reader :version, :dimension, :order, :mirrored_order
+
+        def initialize(version)
+          @version = version
+          @dimension = version.dimension
+          @order, @mirrored_order = build_orders
+          @mask_codewords = Array.new(8)
+          @blocks = {}
+        end
+
+        # One Integer per codeword: the bits that data mask +mask+ flips,
+        # read from the mask's module grid like the data itself.
+        def mask_codewords(mask)
+          @mask_codewords[mask] ||= begin
+            count = @order.size / 8
+            Codewords.read_block(DataMask.grid(mask, @dimension), @order, Array.new(count, 0),
+                                 Array.new(count) { |k| k }).freeze
+          end
+        end
+
+        # RS blocks for EC level +level+ in block order: Array of
+        # [data_codeword_count, raw_codeword_indices] (data then EC codewords).
+        # Undoes the interleaving of §7.6: data codewords are taken from every
+        # block in turn (shorter blocks run out first), then EC codewords.
+        def blocks(level)
+          @blocks[level] ||= build_blocks(@version.ec_blocks(level))
+        end
+
+        private
+
+        # Undoes the interleaving of §7.6 (plain loops: runs once per level).
+        def build_blocks(ec_blocks)
+          data_counts = ec_blocks.data_codewords_per_block
+          count = data_counts.size
+          indices = Array.new(count) { [] }
+          raw = 0
+          longest = data_counts.max
+          i = 0
+          while i < longest
+            b = 0
+            while b < count
+              if i < data_counts[b]
+                indices[b] << raw
+                raw += 1
+              end
+              b += 1
+            end
+            i += 1
+          end
+          i = 0
+          while i < ec_blocks.ec_codewords_per_block
+            b = 0
+            while b < count
+              indices[b] << raw
+              raw += 1
+              b += 1
+            end
+            i += 1
+          end
+          blocks = []
+          b = 0
+          while b < count
+            blocks << [data_counts[b], indices[b].freeze].freeze
+            b += 1
+          end
+          blocks.freeze
+        end
+
+        # Zig-zag over column pairs from the right, alternately upwards and
+        # downwards, skipping the vertical timing column and function modules
+        # (same traversal as ZXing's BitMatrixParser#readCodewords). Returns
+        # the normal and the mirrored order; remainder bits are dropped.
+        def build_orders
+          n = @dimension
+          function = FunctionPatterns.for_version(@version.number)
+          order = []
+          mirrored = []
+          upward = true
+          x = n - 1
+          while x.positive?
+            x -= 1 if x == 6
+            count = 0
+            while count < n
+              y = upward ? n - 1 - count : count
+              index = y * n + x
+              if function.getbyte(index).zero?
+                order << index
+                mirrored << x * n + y
+              end
+              if function.getbyte(index - 1).zero?
+                order << index - 1
+                mirrored << (x - 1) * n + y
+              end
+              count += 1
+            end
+            upward = !upward
+            x -= 2
+          end
+          limit = @version.total_codewords * 8
+          [order.first(limit).freeze, mirrored.first(limit).freeze]
+        end
+      end
+
+      @layouts = Array.new(41)
+
+      class << self
+        # Layout for version +number+ (1..40), built on first use.
+        def layout(number)
+          @layouts[number] ||= Layout.new(SymbolVersion[number])
+        end
+
+        # Reads and unmasks the codewords with the given raw indices from
+        # +bits+ (a symbol's module String with only 0/1 bytes).
+        def read_block(bits, order, mask_codewords, indices)
+          count = indices.size
+          out = Array.new(count)
+          k = 0
+          while k < count
+            raw = indices[k]
+            i = raw << 3
+            out[k] = ((bits.getbyte(order[i]) << 7) | (bits.getbyte(order[i + 1]) << 6) |
+                      (bits.getbyte(order[i + 2]) << 5) | (bits.getbyte(order[i + 3]) << 4) |
+                      (bits.getbyte(order[i + 4]) << 3) | (bits.getbyte(order[i + 5]) << 2) |
+                      (bits.getbyte(order[i + 6]) << 1) | bits.getbyte(order[i + 7])) ^ mask_codewords[raw]
+            k += 1
+          end
+          out
+        end
+
+        # All codewords of a symbol in transmission (interleaved) order,
+        # unmasked. Mainly for tests and diagnostics; the decoder reads block
+        # by block so that garbage fails after the first block.
+        def read(bit_matrix, version, mask, mirrored: false)
+          layout = layout(version)
+          order = mirrored ? layout.mirrored_order : layout.order
+          mask_codewords = layout.mask_codewords(mask)
+          read_block(bit_matrix.bits, order, mask_codewords, (0...mask_codewords.size).to_a)
+        end
+
+        # Splits interleaved codewords into RS blocks (Arrays of Integers).
+        def deinterleave(codewords, version, level)
+          layout(version).blocks(level).map { |_, indices| codewords.values_at(*indices) }
+        end
+      end
+    end
+  end
+end

data/lib/qr_reader/decoder/data_mask.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module QrReader
+  module Decoder
+    # The eight data mask patterns of ISO/IEC 18004 Table 10. Only used to
+    # precompute per-version tables, so clarity beats speed in masked?.
+    module DataMask
+      # Every pattern repeats after 12 rows and 12 columns (lcm of the 2-, 3-,
+      # 4- and 6-periodic conditions).
+      PERIOD = 12
+
+      module_function
+
+      # True if mask pattern +mask+ (0..7) inverts the module in column +x+,
+      # row +y+ (ISO's j and i).
+      def masked?(mask, x, y)
+        case mask
+        when 0 then (y + x).even?
+        when 1 then y.even?
+        when 2 then (x % 3).zero?
+        when 3 then ((y + x) % 3).zero?
+        when 4 then ((y / 2) + (x / 3)).even?
+        when 5 then ((y * x) % 6).zero?          # (ij mod 2) + (ij mod 3) == 0
+        when 6 then ((y * x) % 6) < 3            # ((ij mod 2) + (ij mod 3)) mod 2 == 0
+        when 7 then (((y + x) % 2) + ((y * x) % 3)).even?
+        else raise ArgumentError, "mask must be 0..7, got #{mask.inspect}"
+        end
+      end
+
+      # The whole pattern for an n x n symbol as a binary String of n * n
+      # bytes, row-major, "\x01" where the mask inverts the module. Built
+      # from the 12 distinct rows, so it costs O(n) String operations.
+      def grid(mask, n)
+        repeat = n / PERIOD + 1
+        rows = Array.new(PERIOD)
+        y = 0
+        while y < PERIOD
+          unit = "\0".b * PERIOD
+          x = 0
+          while x < PERIOD
+            unit.setbyte(x, 1) if masked?(mask, x, y)
+            x += 1
+          end
+          rows[y] = (unit * repeat).byteslice(0, n)
+          y += 1
+        end
+        out = "".b
+        y = 0
+        while y < n
+          out << rows[y % PERIOD]
+          y += 1
+        end
+        out
+      end
+    end
+  end
+end