qr_reader 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8eabc5559f8483ccce0478d0910040e632a16c36f742eff00c8db2af43b69fad
+  data.tar.gz: b6c9afad43a6996e18791869703c23aa5730719dbede44e96099fbbc84967f80
+SHA512:
+  metadata.gz: f9f50d8bb7cfffa3ddd89b11898e458e4f346975816df4d7362470c4c1afa43fb79df92c751c4ae76a00e7cd150b8eef3036e5342e025f00f6f20b1c6ccf5717
+  data.tar.gz: 5c71745f5e75ac79d759f6f22364020a72e99c3b3350e1a1bf06849f14b344b0ac0a9143f73e0fc96dbd6b868406097f19576485a8a25dfe433a6c0cc9ab659d

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.0.1] - 2026-10-13
+
+- Initial release: pure-Ruby QR code reader (Model 2, versions 1–40; numeric,
+  alphanumeric, byte, Kanji, Hanzi, ECI, structured append, FNC1).
+- Input: PNG, JPEG (baseline/progressive), GIF, BMP, PNM, TIFF (incl. CCITT
+  G3/G4 fax, LZW, Deflate, PackBits, JPEG), PDF (embedded images: JPEG, CCITT,
+  JBIG2 generic regions, Flate, LZW, ...), raw pixel buffers.
+- Photos and scans: resolution pyramid for large pages, reduced-size JPEG
+  decoding, fax pixel-aspect correction, multi-page TIFF/PDF (`Result#page`).
+- API: `decode`, `decode!`, `decode_all`, `read`, `read_all`, `scan`;
+  `qr_reader` command-line tool.
+- Optional `qr_reader-native` gem: the same kernels compiled with Spinel.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andi Idogawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/NOTICE

@@ -0,0 +1,14 @@
+qr_reader
+Copyright (c) 2026 Andi Idogawa (MIT License, see LICENSE.txt)
+
+Test material derived from the ZXing project (https://github.com/zxing/zxing):
+some fixtures under test/fixtures/jpeg and test/decoder/fixtures were made from
+images of the ZXing blackbox QR code test corpus, which is licensed under the
+Apache License, Version 2.0 (https://www.apache.org/licenses/LICENSE-2.0).
+The corpus itself is not part of this repository or the gem; `rake
+corpus:fetch` downloads it into test/corpus/zxing.
+
+The qr_reader-native gem (native/) contains C code generated by Spinel and the
+Spinel runtime (MIT, Copyright (c) 2024- Yukihiro Matsumoto), parts of which
+derive from mruby (MIT, Copyright (c) 2010- mruby developers); see
+native/LICENSE-spinel.txt and native/LICENSE-mruby.txt.

data/README.md

@@ -0,0 +1,222 @@
+# qr_reader
+
+A fast, accurate QR code reader in pure Ruby. No native extensions, no
+ImageMagick, no zbar — just Ruby (and its standard library). Reads photos and
+scanned documents: PNG, JPEG, GIF, BMP, PNM, TIFF (including CCITT G3/G4 fax
+compression) and the images inside scanned PDFs.
+
+```ruby
+require "qr_reader"
+
+QrReader.decode("ticket.jpg")          # => "https://example.com/t/8F2K" (or nil)
+QrReader.decode_all("invoice.pdf")     # => ["SPC\n0200\n1\nCH44...", ...]
+
+code = QrReader.read("label.png")
+code.text            # => "https://example.com"
+code.version         # => 3
+code.ec_level        # => :m
+code.points          # => [[x, y], ...] corners: top-left, top-right, bottom-right, bottom-left
+
+QrReader.scan("scans.tiff") do |code|  # lazily, page by page
+  puts "page #{code.page}: #{code.text}"
+end
+```
+
+## Installation
+
+```bash
+bundle add qr_reader
+```
+
+Requires Ruby 3.2 or newer and nothing else: no C compiler, no ImageMagick,
+no native libraries — it also runs on Rubies without C extensions. Enable YJIT
+for the best speed (`RUBY_YJIT_ENABLE=1`, `ruby --yjit`, or
+`RubyVM::YJIT.enable` at boot).
+
+### Optional: native kernels (qr_reader-native)
+
+The hot loops (image decoding, binarization, pattern scanning) are written as
+plain-Ruby "kernels" that the [Spinel](https://github.com/matz/spinel) AOT
+compiler can turn into C. The separate gem `qr_reader-native` contains exactly
+those kernels compiled; with it installed, qr_reader uses them automatically:
+
+```ruby
+gem "qr_reader"
+gem "qr_reader-native"   # optional, needs a C compiler at install time
+```
+
+`QrReader.native?` tells whether they are in use. It mainly pays off on Rubies
+running without YJIT (see "Accuracy and speed"); results are identical, and
+without the gem — or with `QR_READER_NATIVE=0` — the same code runs as Ruby.
+
+## Usage
+
+| method | returns |
+|---|---|
+| `QrReader.decode(input)` | text of the first code, or `nil` |
+| `QrReader.decode!(input)` | text of the first code, or raises `QrReader::NotFoundError` |
+| `QrReader.decode_all(input)` | texts of all codes (all pages) |
+| `QrReader.read(input)` | first code as a `QrReader::Result`, or `nil` |
+| `QrReader.read_all(input)` | all codes as `QrReader::Result`s |
+| `QrReader.scan(input) { \|result\| }` | yields codes as they are found; an `Enumerator` without a block |
+
+`input` can be a file path (`String` or `Pathname`), an `IO`, a binary
+`String` with the encoded image, a `QrReader::Image`, or any object with
+`width`, `height` and `pixels` (e.g. a `ChunkyPNG::Image`). Raw pixel buffers
+can be wrapped with `QrReader::Image.from_pixels(width, height, bytes, :rgba)`
+(also `:rgb`, `:bgr`, `:bgra`, `:gray`, ...).
+
+Options (for every method, and `QrReader::Reader.new` for reuse):
+
+- `try_harder: true` — when the fast strategies find nothing, keep trying
+  slower ones. `false` gives up early (faster on images without a code).
+- `inverted: :auto` — also look for light-on-dark codes; `true` only those,
+  `false` never.
+
+A `QrReader::Result` is an immutable `Data` object:
+
+| attribute | |
+|---|---|
+| `text` | decoded content as a UTF-8 `String` (`to_s` returns it too) |
+| `raw_bytes` | the payload bytes before character-set decoding (binary `String`) |
+| `version`, `ec_level`, `mask` | symbol version (1–40), error correction level (`:l`, `:m`, `:q`, `:h`), mask |
+| `points` | corners in image pixels: top-left, top-right, bottom-right, bottom-left |
+| `page` | page/image index for multi-page TIFF and PDF input, else `nil` |
+| `mirrored?`, `errors_corrected` | read mirrored? / number of repaired codewords |
+| `eci`, `segments`, `structured_append`, `fnc1`, `symbology_identifier` | encoding details |
+
+Errors: `QrReader::ImageError` (unreadable image data),
+`QrReader::UnsupportedImageError` (e.g. WebP, HEIC, encrypted PDF),
+`Errno::ENOENT` for missing files.
+
+### Command line
+
+```bash
+qr_reader photo.jpg                 # prints the text of the first code
+qr_reader --all --json scan.pdf     # every code, with metadata, as JSON lines
+```
+
+### Large images
+
+There is no need to shrink photos or page scans before reading them: large
+images are searched through a resolution pyramid (coarse levels first) and
+large JPEGs are first decoded at reduced size, so a big code is found quickly
+while a small code on a 300/600 DPI scan is still read at full resolution.
+Shrinking beforehand can make small codes unreadable — a 12 mm code on a
+300 DPI A4 scan is lost when the page is reduced to 1000 px.
+
+What does help with big inputs:
+
+- Run with YJIT (see above).
+- Pass `try_harder: false` when most images contain a code and you prefer a
+  quick "no" over a thorough search (images without a code are the slowest
+  case, since every strategy runs to the end).
+- If you already use ImageMagick or libvips, letting it *decode* big PNG/TIFF
+  files can be faster than the pure-Ruby decoders. Keep at least ~2500 px on
+  the long side for scans:
+
+  ```ruby
+  require "open3"
+
+  def read_with_imagemagick(path)
+    out, = Open3.capture2("magick", path, "-resize", "2500x2500>", "-colorspace", "Gray", "-depth", "8",
+                          "-format", "%w %h\n", "-write", "info:-", "gray:-", binmode: true)
+    header, pixels = out.split("\n", 2)
+    width, height = header.split.map(&:to_i)
+    QrReader.read(QrReader::Image.new(width, height, pixels))
+  end
+  ```
+
+## What it handles
+
+- QR Code Model 2, versions 1–40, all error correction levels and masks;
+  numeric, alphanumeric, byte, Kanji and Hanzi (GB2312) segments, ECI
+  character sets, structured append, FNC1 (GS1); mirrored symbols;
+  light-on-dark codes.
+- Photos: perspective, rotation, uneven lighting, blur, noise, JPEG artifacts.
+- Scans: small codes on large pages (searched through a resolution pyramid),
+  150–600 DPI, fax pages (CCITT G3/G4, non-square 204x98 dpi pixels),
+  B&W/dithered scanner modes, multi-page TIFF and PDF, Swiss QR-bills (the
+  cross in the middle is just damage the error correction repairs).
+- Scanned PDFs: images compressed with JPEG, CCITT fax, JBIG2 (generic
+  regions), Flate, LZW, run-length; xref and object streams; PDFs encrypted
+  with an empty user password.
+- Multiple codes per image (`decode_all` / `read_all`).
+
+Vector-drawn QR codes in digitally created PDFs are not rendered — only raster
+images embedded in the PDF are scanned. JPEG 2000 images in PDFs are skipped.
+Images larger than 67 megapixels (JPEG) or 134 megapixels (other formats) are
+rejected rather than risking huge memory use.
+
+## Accuracy and speed
+
+On the ZXing blackbox QR corpus (179 real-world photos, each also rotated by
+90°, 180° and 270°) qr_reader decodes **688 of 716** cases, more than
+zxing-cpp (664) and ZXing Java (~619), and every case zxing-cpp decodes.
+
+On a corpus of 259 simulated scanned documents (`rake scans:generate`; A4
+letters, invoices, Swiss QR-bills, receipts, labels, fax pages; 150–600 DPI;
+skew, blur, noise, dot gain, fading, dithering, JPEG/TIFF/PDF output) it reads
+**233 of 259** — all 109 "common" office-scanner cases, 91 of 97 "hard" and 33
+of 53 "extreme" ones — against 226 for zxing-cpp, and never returns a wrong
+text. A scanned page takes about 0.7 s on average (YJIT).
+
+Time per reading (warm, one process; i7-10750H, Ruby 4.0), with and without
+YJIT, and with the optional qr_reader-native kernels:
+
+| input | YJIT | YJIT + native | no YJIT | no YJIT + native | peak RAM |
+|---|---|---|---|---|---|
+| small photo (ZXing corpus PNG) | 23 ms | 21 ms | 29 ms | 14 ms | 2 MB |
+| 12 MP phone photo (JPEG) | 506 ms | 491 ms | 2.2 s | 1.8 s | 24 MB |
+| A4 300 dpi scan (JPEG) | 199 ms | 165 ms | 712 ms | 555 ms | 13 MB |
+| A4 300 dpi scan (PDF with JPEG) | 202 ms | 180 ms | 676 ms | 541 ms | 14 MB |
+| A4 300 dpi scan (1-bit TIFF G4) | 121 ms | 97 ms | 444 ms | 72 ms | 28 MB |
+| A4 300 dpi scan (gray PNG) | 567 ms | 545 ms | 2.6 s | 857 ms | 63 MB |
+| A4 page without a code | 953 ms | 507 ms | 3.9 s | 853 ms | 63 MB |
+| 12 MP photo without a code | 1.9 s | 1.1 s | 7.7 s | 2.3 s | 89 MB |
+
+Images without a code are the slowest case: every strategy runs to the end
+(`try_harder: false` stops early). The library itself needs about 10 MB.
+
+Benchmarks: `bundle exec ruby bench/reading.rb` (time and memory per reading),
+`bench/corpus.rb` (ZXing corpus), `bench/scans/run.rb` (scanned documents),
+`bench/synthetic.rb` (distortion stress test).
+
+## Development
+
+```bash
+bundle install
+bundle exec rake corpus:fetch   # ZXing test images (Apache-2.0), used by some tests
+bundle exec rake test
+```
+
+### Native kernels
+
+Hot loops live in `lib/qr_reader/kernels/` and must stay within the Ruby
+subset Spinel compiles (see DESIGN.md, "Kernels"). After changing them,
+regenerate the qr_reader-native sources with a Spinel checkout:
+
+```bash
+SPINEL_HOME=~/workspace/spinel bundle exec rake native:generate
+bundle exec rake native:compile native:test
+```
+
+CI fails when the generated sources are out of date.
+
+### Releasing
+
+Releases are published from GitHub Actions with RubyGems
+[trusted publishing](https://guides.rubygems.org/trusted-publishing/) — no API
+key is stored anywhere. One tag releases both gems, qr_reader and
+qr_reader-native, at the same version. Bump `QrReader::VERSION`, update
+`CHANGELOG.md`, then:
+
+```bash
+git tag v0.0.1
+git push origin v0.0.1
+```
+
+## License
+
+MIT. The ZXing test images fetched by `rake corpus:fetch` are Apache-2.0 and
+are not part of the gem.

data/exe/qr_reader

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require_relative "../lib/qr_reader"
+
+options = { all: false, format: :text, try_harder: true, inverted: :auto }
+parser = OptionParser.new do |o|
+  o.banner = "Usage: qr_reader [options] IMAGE...\n" \
+             "Decodes QR codes in PNG, JPEG, GIF, BMP and PNM images (use - for stdin)."
+  o.on("-a", "--all", "Print every code found (default: first code only)") { options[:all] = true }
+  o.on("-j", "--json", "Print results as JSON lines with metadata") { options[:format] = :json }
+  o.on("-v", "--verbose", "Print metadata (version, EC level, position) after the text") { options[:format] = :verbose }
+  o.on("--fast", "Skip the slower fallback strategies") { options[:try_harder] = false }
+  o.on("--[no-]inverted", "Only / never look for light-on-dark codes (default: both)") { |v| options[:inverted] = v }
+  o.on("--version", "Print version") { puts QrReader::VERSION; exit }
+end
+
+begin
+  files = parser.parse(ARGV)
+rescue OptionParser::ParseError => e
+  warn e.message, parser.help
+  exit 2
+end
+if files.empty?
+  warn parser.help
+  exit 2
+end
+
+status = 0
+reader = QrReader::Reader.new(try_harder: options[:try_harder], inverted: options[:inverted])
+files.each do |file|
+  input = file == "-" ? $stdin.binmode.read : file
+  results = begin
+    options[:all] ? reader.read_all(input) : [reader.read(input)].compact
+  rescue QrReader::Error, SystemCallError => e
+    warn "#{file}: #{e.message}"
+    status = 2
+    next
+  end
+  if results.empty?
+    warn "#{file}: no QR code found"
+    status = 1 if status.zero?
+    next
+  end
+
+  results.each do |r|
+    case options[:format]
+    when :json
+      puts JSON.generate(file: file, text: r.text, version: r.version, ec_level: r.ec_level, mask: r.mask,
+                         points: r.points&.map { |pt| pt.map { |c| c.round(1) } }, mirrored: r.mirrored,
+                         errors_corrected: r.errors_corrected, eci: r.eci,
+                         symbology_identifier: r.symbology_identifier)
+    when :verbose
+      puts r.text
+      corners = r.points&.map { |x, y| "(#{x.round},#{y.round})" }&.join(" ")
+      warn "  #{file}: version #{r.version}, EC #{r.ec_level}, mask #{r.mask}, " \
+           "#{r.errors_corrected} codewords corrected#{r.mirrored ? ', mirrored' : ''}" \
+           "#{corners ? ", corners #{corners}" : ''}"
+    else
+      puts files.size > 1 ? "#{file}: #{r.text}" : r.text
+    end
+  end
+end
+exit status

data/lib/qr_reader/binarizer.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "kernels/binarizer"
+
+module QrReader
+  # Converts a grayscale Image into a BitMatrix (1 = dark, one cell per pixel).
+  #
+  # * hybrid           - local thresholds as in zxing-cpp's HybridBinarizer:
+  #                      copes with shadows, gradients, glare and low
+  #                      contrast; the default.
+  # * local_mean       - local thresholds as in ZXing (Java)'s
+  #                      HybridBinarizer (block means; flat blocks pushed
+  #                      towards white).
+  # * global_histogram - one threshold for the whole image from the valley
+  #                      of the luminance histogram (ZXing's
+  #                      GlobalHistogramBinarizer); the local methods use it
+  #                      for images smaller than 40 pixels.
+  # * threshold        - fixed threshold.
+  #
+  # All methods return a BitMatrix of the image's size and never fail: an
+  # image without usable contrast simply binarizes to all light.
+  #
+  # The per-pixel work of the local methods lives in kernels/binarizer.rb
+  # (QrReaderKernels, optionally compiled to C by qr_reader-native).
+  module Binarizer
+    # Blocks with a luminance range up to this are treated as flat.
+    MIN_DYNAMIC_RANGE = QrReaderKernels::BIN_MIN_RANGE
+    # The local methods need 5x5 blocks of 8x8 pixels.
+    MINIMUM_DIMENSION = 40
+    # Histogram resolution of global_histogram: 32 buckets of 8 grey levels.
+    LUMINANCE_SHIFT = 3
+    LUMINANCE_BUCKETS = 256 >> LUMINANCE_SHIFT
+
+    # String#tr source listing all 256 byte values (escaped for tr).
+    TR_ALL_BYTES = Image::INVERT_FROM
+    # tr targets for level t: bytes < t become "\x01", all others "\x00".
+    TR_TARGETS = Array.new(257) { |t| ("\x01" * t + "\x00" * (256 - t)).b.freeze }.freeze
+    private_constant :TR_ALL_BYTES, :TR_TARGETS
+
+    class << self
+      # Local-threshold binarization. The image is divided into blocks of
+      # 8x8 pixels. A block with contrast gets the threshold
+      # (min + max) / 2, a flat block none - unless an edge runs exactly
+      # along its border: two neighbouring flat blocks whose luminance
+      # ranges lie more than MIN_DYNAMIC_RANGE apart both get the threshold
+      # halfway between them (crisp generated images whose module size is a
+      # multiple of 8 have no edge inside any block). Each block's threshold
+      # is then the mean over the 5x5 blocks around it that have one, and
+      # blocks in large flat areas take the nearest threshold in scan
+      # order. Pixels at or below their block's threshold become dark.
+      # Unlike local_mean, a flat area (quiet zone, large modules) does not
+      # drag its neighbours' thresholds down, which matters for low-contrast
+      # symbols.
+      def hybrid(image)
+        local_threshold(image, :hybrid)
+      end
+
+      # ZXing's HybridBinarizer: each 8x8 block's black point is its mean
+      # luminance, or for flat blocks half its darkest value unless its
+      # neighbours suggest it lies inside a dark area; black points are
+      # averaged over 5x5 blocks.
+      def local_mean(image)
+        local_threshold(image, :local_mean)
+      end
+
+      # Global threshold at the histogram valley between the dark and the
+      # light peak. Low contrast images become all light.
+      def global_histogram(image)
+        black_point = global_black_point(image)
+        black_point ? threshold(image, black_point) : BitMatrix.new(image.width, image.height)
+      end
+
+      # Pixels with luminance < +level+ become dark (C speed via String#tr).
+      def threshold(image, level)
+        BitMatrix.new(image.width, image.height, image.data.tr(TR_ALL_BYTES, TR_TARGETS[level.clamp(0, 256)]))
+      end
+
+      # The threshold global_histogram uses, or nil when the image has too
+      # little contrast.
+      def global_black_point(image)
+        estimate_black_point(histogram(image))
+      end
+
+      private
+
+      # Shared driver of the block-threshold methods (the per-pixel work is
+      # done by QrReaderKernels.binarize_*, see kernels/binarizer.rb).
+      def local_threshold(image, method)
+        width = image.width
+        height = image.height
+        return global_histogram(image) if width < MINIMUM_DIMENSION || height < MINIMUM_DIMENSION
+
+        bits = if method == :hybrid
+                 QrReaderKernels.binarize_hybrid(image.data, width, height)
+               else
+                 QrReaderKernels.binarize_local_mean(image.data, width, height)
+               end
+        BitMatrix.new(width, height, bits)
+      end
+
+      # 32-bucket luminance histogram of the central 3/5 of up to 16 rows
+      # spread evenly over the image (all rows of small images).
+      def histogram(image)
+        width = image.width
+        height = image.height
+        data = image.data
+        buckets = Array.new(LUMINANCE_BUCKETS, 0)
+        left = width / 5
+        right = width * 4 / 5
+        left, right = 0, width if right - left < 8
+        rows = height < 64 ? height : 16
+        k = 0
+        while k < rows
+          y = rows == height ? k : height * (k + 1) / (rows + 1)
+          i = y * width + left
+          stop = y * width + right
+          while i < stop
+            buckets[data.getbyte(i) >> LUMINANCE_SHIFT] += 1
+            i += 1
+          end
+          k += 1
+        end
+        buckets
+      end
+
+      # ZXing's valley search: the tallest peak, a second peak weighted by
+      # squared distance, then the deepest valley between them, biased
+      # towards the light peak. nil if the peaks are too close together.
+      def estimate_black_point(buckets)
+        n = buckets.size
+        max_count = 0
+        first_peak = 0
+        n.times do |x|
+          if buckets[x] > max_count
+            first_peak = x
+            max_count = buckets[x]
+          end
+        end
+        second_peak = 0
+        second_score = 0
+        n.times do |x|
+          d = x - first_peak
+          score = buckets[x] * d * d
+          if score > second_score
+            second_peak = x
+            second_score = score
+          end
+        end
+        return nil if buckets[second_peak].zero?
+
+        first_peak, second_peak = second_peak, first_peak if first_peak > second_peak
+        return nil if second_peak - first_peak <= n / 16
+
+        best_valley = second_peak - 1
+        best_score = -1
+        x = second_peak - 1
+        while x > first_peak
+          from_first = x - first_peak
+          score = from_first * from_first * (second_peak - x) * (max_count - buckets[x])
+          if score > best_score
+            best_valley = x
+            best_score = score
+          end
+          x -= 1
+        end
+        best_valley << LUMINANCE_SHIFT
+      end
+    end
+  end
+end

data/lib/qr_reader/bit_matrix.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module QrReader
+  # A 2D grid of dark/light cells. Used both for binarized images (one cell
+  # per pixel) and for sampled QR symbols (one cell per module).
+  #
+  # Storage is a binary String with one byte per cell, row-major:
+  # "\x01" = dark (black), "\x00" = light (white). The byte representation is
+  # deliberate: String#getbyte/#setbyte are fast (and YJIT-inlined), and runs
+  # can be found at C speed with String#index("\x01", pos) / ("\x00", pos).
+  class BitMatrix
+    DARK = "\x01".b.freeze
+    LIGHT = "\x00".b.freeze
+
+    attr_reader :width, :height, :bits
+
+    def initialize(width, height = width, bits = nil)
+      @width = width
+      @height = height
+      if bits
+        raise ArgumentError, "expected #{width * height} cells, got #{bits.bytesize}" if bits.bytesize != width * height
+
+        @bits = bits.encoding == Encoding::BINARY ? bits : bits.b
+      else
+        @bits = "\0".b * (width * height)
+      end
+    end
+
+    # Builds a matrix from rows given as Arrays of booleans/integers or as
+    # Strings where '#', 'X', '1' or 'x' mark dark cells.
+    def self.from_rows(rows)
+      h = rows.size
+      w = rows.first.size
+      m = new(w, h)
+      rows.each_with_index do |row, y|
+        cells = row.is_a?(String) ? row.chars.map { |c| "#X1x".include?(c) } : row
+        cells.each_with_index { |v, x| m.set(x, y) if v && v != 0 }
+      end
+      m
+    end
+
+    # 1 if dark, 0 if light.
+    def get(x, y)
+      @bits.getbyte(y * @width + x)
+    end
+
+    def dark?(x, y)
+      @bits.getbyte(y * @width + x) == 1
+    end
+    alias [] dark?
+
+    def set(x, y, value = 1)
+      @bits.setbyte(y * @width + x, value == true || value == 1 ? 1 : 0)
+    end
+
+    def unset(x, y)
+      @bits.setbyte(y * @width + x, 0)
+    end
+
+    def flip(x, y)
+      i = y * @width + x
+      @bits.setbyte(i, @bits.getbyte(i) ^ 1)
+    end
+
+    # Cells of row y as a binary String of "\x00"/"\x01" bytes.
+    def row(y)
+      @bits.byteslice(y * @width, @width)
+    end
+
+    def dark_count
+      @bits.count(DARK)
+    end
+
+    def dup
+      BitMatrix.new(@width, @height, @bits.dup)
+    end
+
+    # Matrix with all cells inverted (dark <-> light).
+    def invert
+      BitMatrix.new(@width, @height, @bits.tr("\x00\x01", "\x01\x00"))
+    end
+
+    # Mirror along the main diagonal (x <-> y).
+    def transpose
+      w = @width
+      h = @height
+      src = @bits
+      out = "\0".b * (w * h)
+      y = 0
+      while y < h
+        x = 0
+        off = y * w
+        while x < w
+          out.setbyte(x * h + y, src.getbyte(off + x))
+          x += 1
+        end
+        y += 1
+      end
+      BitMatrix.new(h, w, out)
+    end
+
+    def ==(other)
+      other.is_a?(BitMatrix) && other.width == @width && other.height == @height && other.bits == @bits
+    end
+    alias eql? ==
+
+    def hash
+      [@width, @height, @bits].hash
+    end
+
+    # ASCII rendering for debugging ("##" = dark, "  " = light).
+    def to_s(dark: "##", light: "  ")
+      (0...@height).map { |y| row(y).bytes.map { |b| b == 1 ? dark : light }.join }.join("\n")
+    end
+
+    def inspect
+      "#<QrReader::BitMatrix #{@width}x#{@height}>"
+    end
+  end
+end