hexatess-code 0.1.0__tar.gz

hexatess_code-0.1.0/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 The Hexatess Code Authors
+
+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.
+
+----------------------------------------------------------------------
+Note on the specification:
+
+The format specification (SPECIFICATION.md) is additionally released under
+the Creative Commons Attribution 4.0 International license (CC-BY-4.0), so
+that anyone may implement compatible encoders/decoders in any language,
+under any license, without restriction. Provide attribution as:
+"Hexatess Code Specification v0.1, https://github.com/<you>/hexatess-code".

hexatess_code-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: hexatess-code
+Version: 0.1.0
+Summary: Hexatess Code - an experimental 2D barcode on a hexagonal grid with Reed-Solomon error correction
+Author: The Hexatess Code Authors
+License: MIT License
+        
+        Copyright (c) 2026 The Hexatess Code Authors
+        
+        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.
+        
+        ----------------------------------------------------------------------
+        Note on the specification:
+        
+        The format specification (SPECIFICATION.md) is additionally released under
+        the Creative Commons Attribution 4.0 International license (CC-BY-4.0), so
+        that anyone may implement compatible encoders/decoders in any language,
+        under any license, without restriction. Provide attribution as:
+        "Hexatess Code Specification v0.1, https://github.com/<you>/hexatess-code".
+        
+Project-URL: Homepage, https://github.com/lovro-abram/hexatess-code
+Project-URL: Specification, https://github.com/lovro-abram/hexatess-code/blob/main/SPECIFICATION.md
+Project-URL: Issues, https://github.com/lovro-abram/hexatess-code/issues
+Keywords: barcode,2d-barcode,qr-code,hexagonal,hexatess,reed-solomon,error-correction,aztec
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pillow>=9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# Hexatess Code 🐝
+
+**An experimental 2D barcode on a hexagonal grid** — with a hexagonal
+bullseye finder, spiral serialization and a continuously selectable
+Reed-Solomon error-correction budget of 5–90 %.
+
+![Hexatess Code example](docs/img/hexatess_primer.png)
+
+```python
+from hexatess import encode, decode, render
+
+grid, params = encode("Hello, Hexatess!", ec_pct=30)
+render(grid, "hello.png")
+text, stats = decode(grid)          # ('Hello, Hexatess!', {...})
+```
+
+## Symbol anatomy
+
+![Symbol anatomy](docs/img/hexatess_anatomy.png)
+
+* **A** — a real encoded symbol: hexagonal bullseye finder (rings 0–4),
+  orientation key (ring 5: two dark cells), data region (rings 6…)
+  filled in spiral order, and a quiet zone of at least 1 module;
+* **B** — finder close-up: light centre (v0.1 rule `bit = ring mod 2`),
+  alternating dark/light rings, and the key — the first two canonical
+  ring-5 cells set dark, breaking the 60-fold symmetry and marking the
+  spiral start direction;
+* **C** — spiral bit order across rings 6–7 (bit 0 at cell `(−6, +6)`),
+  rendered from the actual reference encoder output.
+
+## Why hexagons?
+
+* **+15.5 % packing density** over the square grid — hexagons tile the
+  plane with ~15.5 % more modules per area at equal module size, which
+  directly translates into more data per printed area.
+* **Rotational isotropy** — three axes of symmetry instead of two;
+  damage from any direction is statistically equivalent.
+* **Proven heritage** — MaxiCode (UPS, ISO/IEC 16023) already proved a
+  hexagonal 2D code works in the field; Hexatess Code generalizes the
+  idea to variable-size, high-capacity, Aztec-style symbols.
+* **Modern error control** — continuous EC budget from 5 % to 90 %
+  (not 7 discrete levels), independent RS blocks of ≤ 50 data bytes,
+  and a double-protected header.
+
+> **Status: experimental.** This is a young format: the symbol
+> specification and reference implementation are solid and heavily
+> tested (2,500+ tests, conformance vectors), but there is **no camera
+> decoder yet** — reading images assumes ideal upright sampling. See
+> the roadmap below. Adopting a young format is a deliberate bet; the
+> [full format specification](SPECIFICATION.md) is the insurance.
+
+## Installation
+
+```bash
+pip install hexatess-code            # from PyPI (once published)
+# or from a source checkout:
+pip install -e .
+```
+
+Requires Python ≥ 3.8 and Pillow (for rendering only).
+
+## Command line
+
+```bash
+hexatess "Hello world" -o koda.png --ec 30
+hexatess "Important URL https://example.org" -o url.png --ec 55
+hexatess-code --demo        # demo symbol + robustness statistics
+```
+
+## API
+
+| Function | Description |
+|---|---|
+| `encode(text, ec_pct=30, mask_id="auto", min_rings=None)` | UTF-8 text → `(grid, params)`; `grid` maps axial `(q, r)` to `0/1` |
+| `decode(grid)` | grid → `(text, stats)`; RS-corrects transparently |
+| `render(grid, path, size_px=18, ...)` | grid → PNG (pointy-top hexagons, quiet zone, supersampling) |
+| `sample_grid_from_image(path, rmax, ...)` | ideal re-sampling of a rendered PNG (self-test helper) |
+| `run_tests(...)` | noise/blob robustness statistics |
+
+`params` / `stats` contain `rmax` (radius in rings), `mask`, `ec`,
+`blocks` (list of `(data_bytes, ecc_bytes)`) and `data_len`.
+
+## Error-correction budget
+
+Choose any multiple of 5 between 5 and 90:
+
+| EC | Character |
+|---|---|
+| 5–15 | maximum capacity, clean environments |
+| 25–40 | general use (default 30) |
+| 50–70 | industrial / outdoor |
+| 80–90 | extreme damage tolerance |
+
+Physical behaviour (measured on the reference implementation): one
+flipped module is one RS *symbol* error, so uniform-noise tolerance is
+roughly `EC / 16` percent of modules, while clustered (smudge/blob)
+damage survives several times higher area fractions because flips
+concentrate inside whole bytes.
+
+## Implement it in your own language
+
+The format is deliberately **specification-first**: everything needed
+for an independent implementation is in
+[`SPECIFICATION.md`](SPECIFICATION.md), and
+[`test_vectors/vectors_v0.1.json`](test_vectors/vectors_v0.1.json)
+contains fixed inputs/outputs (grids, headers, damaged symbols, expected
+results) to verify conformance. If your Rust/Go/JS decoder passes the
+vectors, it speaks Hexatess Code.
+
+## Roadmap
+
+1. **v0.2 — camera decoding:** bullseye detection + perspective
+   correction (the critical ecosystem step).
+2. **v0.2 — erasure decoding:** declare blob-occluded modules as
+   erasures → doubles correctable symbol counts.
+3. **JavaScript/TypeScript SDK** + online playground (generate a code
+   in the browser in 10 seconds).
+4. Larger radii / capacity beyond 329 bytes (breaking header change).
+
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+* Code: [MIT](LICENSE)
+* Specification: CC-BY-4.0 — implement it anywhere, commercially, under
+  any license, no royalties, forever.
+
+---
+
+*Hexatess Code stands on the shoulders of giants: Aztec Code (bullseye +
+spiral), MaxiCode (hexagonal lattice), QR Code and Data Matrix
+(Reed-Solomon practice).*

hexatess_code-0.1.0/README.md

@@ -0,0 +1,132 @@
+# Hexatess Code 🐝
+
+**An experimental 2D barcode on a hexagonal grid** — with a hexagonal
+bullseye finder, spiral serialization and a continuously selectable
+Reed-Solomon error-correction budget of 5–90 %.
+
+![Hexatess Code example](docs/img/hexatess_primer.png)
+
+```python
+from hexatess import encode, decode, render
+
+grid, params = encode("Hello, Hexatess!", ec_pct=30)
+render(grid, "hello.png")
+text, stats = decode(grid)          # ('Hello, Hexatess!', {...})
+```
+
+## Symbol anatomy
+
+![Symbol anatomy](docs/img/hexatess_anatomy.png)
+
+* **A** — a real encoded symbol: hexagonal bullseye finder (rings 0–4),
+  orientation key (ring 5: two dark cells), data region (rings 6…)
+  filled in spiral order, and a quiet zone of at least 1 module;
+* **B** — finder close-up: light centre (v0.1 rule `bit = ring mod 2`),
+  alternating dark/light rings, and the key — the first two canonical
+  ring-5 cells set dark, breaking the 60-fold symmetry and marking the
+  spiral start direction;
+* **C** — spiral bit order across rings 6–7 (bit 0 at cell `(−6, +6)`),
+  rendered from the actual reference encoder output.
+
+## Why hexagons?
+
+* **+15.5 % packing density** over the square grid — hexagons tile the
+  plane with ~15.5 % more modules per area at equal module size, which
+  directly translates into more data per printed area.
+* **Rotational isotropy** — three axes of symmetry instead of two;
+  damage from any direction is statistically equivalent.
+* **Proven heritage** — MaxiCode (UPS, ISO/IEC 16023) already proved a
+  hexagonal 2D code works in the field; Hexatess Code generalizes the
+  idea to variable-size, high-capacity, Aztec-style symbols.
+* **Modern error control** — continuous EC budget from 5 % to 90 %
+  (not 7 discrete levels), independent RS blocks of ≤ 50 data bytes,
+  and a double-protected header.
+
+> **Status: experimental.** This is a young format: the symbol
+> specification and reference implementation are solid and heavily
+> tested (2,500+ tests, conformance vectors), but there is **no camera
+> decoder yet** — reading images assumes ideal upright sampling. See
+> the roadmap below. Adopting a young format is a deliberate bet; the
+> [full format specification](SPECIFICATION.md) is the insurance.
+
+## Installation
+
+```bash
+pip install hexatess-code            # from PyPI (once published)
+# or from a source checkout:
+pip install -e .
+```
+
+Requires Python ≥ 3.8 and Pillow (for rendering only).
+
+## Command line
+
+```bash
+hexatess "Hello world" -o koda.png --ec 30
+hexatess "Important URL https://example.org" -o url.png --ec 55
+hexatess-code --demo        # demo symbol + robustness statistics
+```
+
+## API
+
+| Function | Description |
+|---|---|
+| `encode(text, ec_pct=30, mask_id="auto", min_rings=None)` | UTF-8 text → `(grid, params)`; `grid` maps axial `(q, r)` to `0/1` |
+| `decode(grid)` | grid → `(text, stats)`; RS-corrects transparently |
+| `render(grid, path, size_px=18, ...)` | grid → PNG (pointy-top hexagons, quiet zone, supersampling) |
+| `sample_grid_from_image(path, rmax, ...)` | ideal re-sampling of a rendered PNG (self-test helper) |
+| `run_tests(...)` | noise/blob robustness statistics |
+
+`params` / `stats` contain `rmax` (radius in rings), `mask`, `ec`,
+`blocks` (list of `(data_bytes, ecc_bytes)`) and `data_len`.
+
+## Error-correction budget
+
+Choose any multiple of 5 between 5 and 90:
+
+| EC | Character |
+|---|---|
+| 5–15 | maximum capacity, clean environments |
+| 25–40 | general use (default 30) |
+| 50–70 | industrial / outdoor |
+| 80–90 | extreme damage tolerance |
+
+Physical behaviour (measured on the reference implementation): one
+flipped module is one RS *symbol* error, so uniform-noise tolerance is
+roughly `EC / 16` percent of modules, while clustered (smudge/blob)
+damage survives several times higher area fractions because flips
+concentrate inside whole bytes.
+
+## Implement it in your own language
+
+The format is deliberately **specification-first**: everything needed
+for an independent implementation is in
+[`SPECIFICATION.md`](SPECIFICATION.md), and
+[`test_vectors/vectors_v0.1.json`](test_vectors/vectors_v0.1.json)
+contains fixed inputs/outputs (grids, headers, damaged symbols, expected
+results) to verify conformance. If your Rust/Go/JS decoder passes the
+vectors, it speaks Hexatess Code.
+
+## Roadmap
+
+1. **v0.2 — camera decoding:** bullseye detection + perspective
+   correction (the critical ecosystem step).
+2. **v0.2 — erasure decoding:** declare blob-occluded modules as
+   erasures → doubles correctable symbol counts.
+3. **JavaScript/TypeScript SDK** + online playground (generate a code
+   in the browser in 10 seconds).
+4. Larger radii / capacity beyond 329 bytes (breaking header change).
+
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+* Code: [MIT](LICENSE)
+* Specification: CC-BY-4.0 — implement it anywhere, commercially, under
+  any license, no royalties, forever.
+
+---
+
+*Hexatess Code stands on the shoulders of giants: Aztec Code (bullseye +
+spiral), MaxiCode (hexagonal lattice), QR Code and Data Matrix
+(Reed-Solomon practice).*

hexatess_code-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hexatess-code"
+version = "0.1.0"
+description = "Hexatess Code - an experimental 2D barcode on a hexagonal grid with Reed-Solomon error correction"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { file = "LICENSE" }
+authors = [{ name = "The Hexatess Code Authors" }]
+keywords = [
+    "barcode", "2d-barcode", "qr-code", "hexagonal", "hexatess",
+    "reed-solomon", "error-correction", "aztec",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Multimedia :: Graphics",
+]
+dependencies = [
+    "pillow>=9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/lovro-abram/hexatess-code"
+Specification = "https://github.com/lovro-abram/hexatess-code/blob/main/SPECIFICATION.md"
+Issues = "https://github.com/lovro-abram/hexatess-code/issues"
+
+[project.scripts]
+hexatess = "hexatess.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

hexatess_code-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hexatess_code-0.1.0/src/hexatess/__init__.py

@@ -0,0 +1,83 @@
+"""Hexatess Code - an experimental 2D barcode on a hexagonal grid.
+
+Reference implementation of specification v0.1.  The symbol is a
+hexagonal lattice with a hexagonal bullseye finder, an
+orientation key ring, spiral serialization from the centre outwards,
+a Reed-Solomon protected header and a continuously selectable
+error-correction budget of 5-90 percent (Aztec-style).
+
+Quick start
+-----------
+>>> from hexatess import encode, decode, render
+>>> grid, params = encode("Hello, Hexatess!", ec_pct=30)
+>>> params["rmax"], params["mask"], params["data_len"]
+(11, 6, 16)
+>>> render(grid, "hello.png")
+'hello.png'
+>>> decode(grid)[0]
+'Hello, Hexatess!'
+
+See SPECIFICATION.md in the repository for the full format
+specification, and test_vectors/vectors_v0.1.json for conformance
+data usable by independent implementations.
+"""
+
+from __future__ import annotations
+
+from .decoder import decode
+from .encoder import encode
+from .geometry import (
+    DIRS,
+    hex_corner,
+    hex_distance,
+    hex_ring,
+    hex_to_pixel,
+    ring_capacity,
+)
+from .header import (
+    BULLSEYE_RINGS,
+    BLOCK_DATA_MAX,
+    DATA_RING0,
+    KEY_RING,
+    MAX_DATA_BYTES,
+    MAX_EC_PCT,
+    MAX_RINGS,
+    MIN_EC_PCT,
+    MODE_BITS,
+    MODE_BYTES,
+    MODE_ECC,
+    bits_to_bytes,
+    bytes_to_bits,
+    pack_mode,
+    plan_blocks,
+    unpack_mode,
+)
+from .masks import evaluate_mask, mask_bit, mask_payload, select_mask
+from .reedsolomon import rs_correct_msg, rs_encode_msg
+from .render import render, sample_grid_from_image
+from .resilience import add_blob_damage, add_random_noise, run_tests
+
+__version__ = "0.1.0"
+SPEC_VERSION = "0.1"
+
+__all__ = [
+    # high-level API
+    "encode", "decode", "render", "sample_grid_from_image",
+    "run_tests", "add_random_noise", "add_blob_damage",
+    # geometry
+    "DIRS", "hex_ring", "hex_distance", "hex_to_pixel", "hex_corner",
+    "ring_capacity",
+    # framing
+    "bytes_to_bits", "bits_to_bytes", "pack_mode", "unpack_mode",
+    "plan_blocks",
+    # masks
+    "mask_bit", "mask_payload", "evaluate_mask", "select_mask",
+    # error correction
+    "rs_encode_msg", "rs_correct_msg",
+    # constants
+    "BULLSEYE_RINGS", "KEY_RING", "DATA_RING0", "MAX_RINGS",
+    "BLOCK_DATA_MAX", "MODE_BYTES", "MODE_ECC", "MODE_BITS",
+    "MIN_EC_PCT", "MAX_EC_PCT", "MAX_DATA_BYTES",
+    # meta
+    "__version__", "SPEC_VERSION",
+]

hexatess_code-0.1.0/src/hexatess/cli.py

@@ -0,0 +1,65 @@
+"""Command-line interface for Hexatess Code.
+
+Examples
+--------
+Encode text to PNG::
+
+    hexatess-code "Hello world" -o koda.png --ec 30
+
+Render a demo symbol and run robustness tests::
+
+    hexatess-code --demo
+    hexatess-code --test
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from .decoder import decode
+from .encoder import encode
+from .render import render, sample_grid_from_image
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="hexatess",
+        description="Hexatess Code - hexagonal-grid 2D barcode "
+                    "(reference implementation, spec v0.1)")
+    ap.add_argument("text", nargs="?", help="text to encode (UTF-8)")
+    ap.add_argument("-o", "--output", default="hexatess.png",
+                    help="output PNG path (default: %(default)s)")
+    ap.add_argument("--ec", type=int, default=30,
+                    help="error-correction %% (5-90, step 5; default 30)")
+    ap.add_argument("--mask", type=int, default=None, metavar="0-7",
+                    help="force a mask instead of automatic selection")
+    ap.add_argument("--size", type=int, default=18,
+                    help="hex radius in pixels (default %(default)s)")
+    ap.add_argument("--test", action="store_true",
+                    help="run robustness tests")
+    ap.add_argument("--demo", action="store_true",
+                    help="render a demo symbol and run robustness tests")
+    args = ap.parse_args(argv)
+
+    if args.test or args.demo:
+        from .resilience import run_tests
+        run_tests()
+
+    if args.demo or args.text:
+        text = args.text or "Hexatess Code v0.1 - " * 6
+        grid, params = encode(text, ec_pct=args.ec, mask_id="auto"
+                              if args.mask is None else args.mask)
+        render(grid, args.output, size_px=args.size)
+        print("\nRendered: %s" % args.output)
+        print("  version (rings): %d, EC: %d%%, mask: %d, bytes: %d"
+              % (params["rmax"], params["ec"], params["mask"],
+                 params["data_len"]))
+        grid2 = sample_grid_from_image(args.output, params["rmax"],
+                                       size_px=args.size)
+        t, _st = decode(grid2)
+        print("  self-decode from image: %s"
+              % ("OK" if t == text else "FAILED"))
+
+
+if __name__ == "__main__":
+    main()

hexatess_code-0.1.0/src/hexatess/decoder.py

@@ -0,0 +1,75 @@
+"""Hexatess Code decoder (ideal-sampling reference).
+
+Accepts a module grid ``{(q, r): 0|1}`` (as produced by the encoder or
+sampled from an image) and returns the decoded UTF-8 text together with
+the header parameters.  Any symbol error correctable by Reed-Solomon is
+absorbed transparently.
+"""
+
+from __future__ import annotations
+
+from .geometry import hex_distance, hex_ring
+from .header import (
+    DATA_RING0,
+    MODE_BITS,
+    bits_to_bytes,
+    plan_blocks,
+    unpack_mode,
+)
+from .masks import mask_bit
+from .reedsolomon import rs_correct_msg
+
+
+def decode(grid, params=None):
+    """Decode a module grid into text.
+
+    Parameters
+    ----------
+    grid : dict
+        Mapping ``{(q, r): 0|1}``.
+    params : dict, optional
+        Ignored; kept for API symmetry with v0.1 of the prototype.
+
+    Returns
+    -------
+    (text, stats)
+        ``text`` is the decoded UTF-8 string; ``stats`` reports the
+        parameters read from the header (``rmax``, ``mask``, ``ec``,
+        ``blocks``, ``data_len``).
+    """
+    cells = sorted(grid.keys(), key=lambda c: hex_distance(*c))
+    rmax = max(hex_distance(*c) for c in cells)
+    data_cells = [c for k in range(DATA_RING0, rmax + 1)
+                  for c in hex_ring(k)]
+    bits = [grid[c] for c in data_cells]
+
+    # --- protected header
+    mode_bits = bits[:MODE_BITS]
+    mode = unpack_mode(bits_to_bytes(mode_bits))
+    rmax_m, mask_id, ec_pct, block_count, data_len = mode
+
+    # --- masked payload
+    payload_bits = bits[MODE_BITS:MODE_BITS + (data_len + sum(
+        e for _, e in plan_blocks(data_len, ec_pct))) * 8]
+    payload_bits = [b ^ mask_bit(i, mask_id)
+                    for i, b in enumerate(payload_bits)]
+    stream = bits_to_bytes(payload_bits)
+
+    # --- per-block Reed-Solomon correction
+    blocks = plan_blocks(data_len, ec_pct)
+    out = bytearray()
+    pos_d = 0
+    pos_e = 0
+    ecc_total = sum(e for _, e in blocks)
+    data_bytes = stream[:data_len]
+    ecc_bytes = stream[data_len:data_len + ecc_total]
+    for size, ecc in blocks:
+        cw = list(data_bytes[pos_d:pos_d + size]) + \
+             list(ecc_bytes[pos_e:pos_e + ecc])
+        out += bytes(rs_correct_msg(cw, ecc))
+        pos_d += size
+        pos_e += ecc
+    text = bytes(out).decode("utf-8")
+    stats = {"rmax": rmax_m, "mask": mask_id, "ec": ec_pct,
+             "blocks": block_count, "data_len": data_len}
+    return text, stats