hexatess-code 0.2.0__tar.gz → 0.3.1__tar.gz

{hexatess_code-0.2.0/src/hexatess_code.egg-info → hexatess_code-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexatess-code
-Version: 0.2.0
+Version: 0.3.1
 Summary: Hexatess Code - an experimental 2D barcode on a hexagonal grid with Reed-Solomon error correction
 Author: The Hexatess Code Authors
 License: MIT License
@@ -56,6 +56,10 @@ License-File: LICENSE
 Requires-Dist: pillow>=9.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: camera
+Requires-Dist: numpy>=1.24; extra == "camera"
+Requires-Dist: opencv-python>=4.8; extra == "camera"
+Requires-Dist: scipy>=1.10; extra == "camera"
 Dynamic: license-file
 
 # Hexatess Code 🐝
@@ -109,41 +113,73 @@ text, stats = decode(grid)          # ('Hello, Hexatess!', {...})
 
 > **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.
+> tested (2,500+ tests, conformance vectors).  A **camera decoder**
+> (`hexatess.camera`, optional `[camera]` extra) already reads symbols
+> from real photographs in about a second — printed labels, foil
+> transparencies, tilted and rotated shots.  Since spec v0.3 payload
+> text is zlib-compressed automatically, so long texts fit into
+> considerably smaller symbols.  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)
+pip install "hexatess-code[camera]"  # + photo decoding (numpy, opencv, scipy)
 # or from a source checkout:
 pip install -e .
 ```
 
-Requires Python ≥ 3.8 and Pillow (for rendering only).
+Requires Python ≥ 3.8; Pillow for rendering, numpy + OpenCV + SciPy
+for the optional camera decoder.
 
 ## 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
+hexatess --demo                       # demo symbol + robustness statistics
+hexatess decode-photo photo1.jpg photo2.jpg   # read symbols from photos
 ```
 
+Payload text is zlib-compressed automatically when that saves space
+(`--no-compress` disables it; the header flag keeps decoders fully
+backward compatible).
+
+## Payload compression (spec v0.3)
+
+One header bit marks the payload as a zlib stream. The encoder applies
+it only when it strictly helps, and decoders inflate transparently —
+symbols without the flag are byte-identical to v0.2. What that means
+in practice (EC 30 unless noted):
+
+| payload | raw | stored | symbol |
+|---|---|---|---|
+| 80 digits | 80 B | 21 B | rmax 17 → 11 |
+| `"X" × 250` | 250 B | 12 B | rmax 30 → 10 |
+| 849-byte Slovene paragraph | 849 B | 203 B | would not fit → rmax 28 |
+| short strings (≤ ~30 B) | — | unchanged | overhead wins |
+
+The maximum *stored* capacity is unchanged (329 bytes at EC 5), so
+incompressible data behaves exactly as before.
+
 ## 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 |
+| `encode(text, ec_pct=30, mask_id="auto", min_rings=None, compress="auto")` | UTF-8 text → `(grid, params)`; `grid` maps axial `(q, r)` to `0/1` |
+| `decode(grid)` | grid → `(text, stats)`; RS-corrects and inflates 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 |
+| `hexatess.camera.decode_photo(path)` | photograph → `(text, stats)`; finder detection, perspective handling, adaptive sampling (optional `[camera]` extra) |
 
 `params` / `stats` contain `rmax` (radius in rings), `mask`, `ec`,
-`blocks` (list of `(data_bytes, ecc_bytes)`) and `data_len`.
+`blocks` (list of `(data_bytes, ecc_bytes)`), `data_len` (stored
+length) and `compressed`; `stats` also reports `repair_bits` (the RS
+correction ledger) and, for camera decodes, `sector` and
+`finder_hits`.
 
 ## Error-correction budget
 
@@ -167,20 +203,27 @@ concentrate inside whole bytes.
 The format is deliberately **specification-first**: everything needed
 for an independent implementation is in
 [`SPECIFICATION.md`](SPECIFICATION.md), and
-[`test_vectors/vectors_v0.2.json`](test_vectors/vectors_v0.2.json)
+[`test_vectors/vectors_v0.3.json`](test_vectors/vectors_v0.3.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
+1. ~~v0.2/0.3 — camera decoding~~ **done (v0.3.0):** `hexatess.camera`
+   reads symbols from photographs — bullseye detection, homography +
+   correction-field warp handling, adaptive sampling; validated on
+   printed foil with curl and glare.  **v0.3.1:** ≈10× faster
+   (a typical 12 MP photo now takes about a second) plus stable
+   outer-ring sampling and mis-decode-proof pose selection.
+2. ~~v0.3 — payload compression~~ **done (v0.3.1):** zlib flag bit in
+   the header, applied automatically when it helps.
+3. **Erasure decoding:** declare blob-occluded modules as
    erasures → doubles correctable symbol counts.
-3. **JavaScript/TypeScript SDK** + online playground (generate a code
+4. **JavaScript/TypeScript SDK** + online playground (generate a code
    in the browser in 10 seconds).
-4. Larger radii / capacity beyond 329 bytes (breaking header change).
+5. Larger radii / capacity beyond 329 stored bytes (breaking header
+   change).
 
 Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
 

{hexatess_code-0.2.0 → hexatess_code-0.3.1}/README.md

@@ -49,41 +49,73 @@ text, stats = decode(grid)          # ('Hello, Hexatess!', {...})
 
 > **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.
+> tested (2,500+ tests, conformance vectors).  A **camera decoder**
+> (`hexatess.camera`, optional `[camera]` extra) already reads symbols
+> from real photographs in about a second — printed labels, foil
+> transparencies, tilted and rotated shots.  Since spec v0.3 payload
+> text is zlib-compressed automatically, so long texts fit into
+> considerably smaller symbols.  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)
+pip install "hexatess-code[camera]"  # + photo decoding (numpy, opencv, scipy)
 # or from a source checkout:
 pip install -e .
 ```
 
-Requires Python ≥ 3.8 and Pillow (for rendering only).
+Requires Python ≥ 3.8; Pillow for rendering, numpy + OpenCV + SciPy
+for the optional camera decoder.
 
 ## 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
+hexatess --demo                       # demo symbol + robustness statistics
+hexatess decode-photo photo1.jpg photo2.jpg   # read symbols from photos
 ```
 
+Payload text is zlib-compressed automatically when that saves space
+(`--no-compress` disables it; the header flag keeps decoders fully
+backward compatible).
+
+## Payload compression (spec v0.3)
+
+One header bit marks the payload as a zlib stream. The encoder applies
+it only when it strictly helps, and decoders inflate transparently —
+symbols without the flag are byte-identical to v0.2. What that means
+in practice (EC 30 unless noted):
+
+| payload | raw | stored | symbol |
+|---|---|---|---|
+| 80 digits | 80 B | 21 B | rmax 17 → 11 |
+| `"X" × 250` | 250 B | 12 B | rmax 30 → 10 |
+| 849-byte Slovene paragraph | 849 B | 203 B | would not fit → rmax 28 |
+| short strings (≤ ~30 B) | — | unchanged | overhead wins |
+
+The maximum *stored* capacity is unchanged (329 bytes at EC 5), so
+incompressible data behaves exactly as before.
+
 ## 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 |
+| `encode(text, ec_pct=30, mask_id="auto", min_rings=None, compress="auto")` | UTF-8 text → `(grid, params)`; `grid` maps axial `(q, r)` to `0/1` |
+| `decode(grid)` | grid → `(text, stats)`; RS-corrects and inflates 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 |
+| `hexatess.camera.decode_photo(path)` | photograph → `(text, stats)`; finder detection, perspective handling, adaptive sampling (optional `[camera]` extra) |
 
 `params` / `stats` contain `rmax` (radius in rings), `mask`, `ec`,
-`blocks` (list of `(data_bytes, ecc_bytes)`) and `data_len`.
+`blocks` (list of `(data_bytes, ecc_bytes)`), `data_len` (stored
+length) and `compressed`; `stats` also reports `repair_bits` (the RS
+correction ledger) and, for camera decodes, `sector` and
+`finder_hits`.
 
 ## Error-correction budget
 
@@ -107,20 +139,27 @@ concentrate inside whole bytes.
 The format is deliberately **specification-first**: everything needed
 for an independent implementation is in
 [`SPECIFICATION.md`](SPECIFICATION.md), and
-[`test_vectors/vectors_v0.2.json`](test_vectors/vectors_v0.2.json)
+[`test_vectors/vectors_v0.3.json`](test_vectors/vectors_v0.3.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
+1. ~~v0.2/0.3 — camera decoding~~ **done (v0.3.0):** `hexatess.camera`
+   reads symbols from photographs — bullseye detection, homography +
+   correction-field warp handling, adaptive sampling; validated on
+   printed foil with curl and glare.  **v0.3.1:** ≈10× faster
+   (a typical 12 MP photo now takes about a second) plus stable
+   outer-ring sampling and mis-decode-proof pose selection.
+2. ~~v0.3 — payload compression~~ **done (v0.3.1):** zlib flag bit in
+   the header, applied automatically when it helps.
+3. **Erasure decoding:** declare blob-occluded modules as
    erasures → doubles correctable symbol counts.
-3. **JavaScript/TypeScript SDK** + online playground (generate a code
+4. **JavaScript/TypeScript SDK** + online playground (generate a code
    in the browser in 10 seconds).
-4. Larger radii / capacity beyond 329 bytes (breaking header change).
+5. Larger radii / capacity beyond 329 stored bytes (breaking header
+   change).
 
 Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
 

{hexatess_code-0.2.0 → hexatess_code-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hexatess-code"
-version = "0.2.0"
+version = "0.3.1"
 description = "Hexatess Code - an experimental 2D barcode on a hexagonal grid with Reed-Solomon error correction"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -36,6 +36,11 @@ dependencies = [
 dev = [
     "pytest>=7.0",
 ]
+camera = [
+    "numpy>=1.24",
+    "opencv-python>=4.8",
+    "scipy>=1.10",
+]
 
 [project.urls]
 Homepage = "https://github.com/lovro-abram/hexatess-code"

{hexatess_code-0.2.0 → hexatess_code-0.3.1}/src/hexatess/__init__.py

@@ -1,10 +1,12 @@
 """Hexatess Code - an experimental 2D barcode on a hexagonal grid.
 
-Reference implementation of specification v0.2.  The symbol is a
+Reference implementation of specification v0.3.  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).
+error-correction budget of 5-90 percent (Aztec-style).  Since spec
+v0.3 the payload can optionally be zlib-compressed (one header flag
+bit; applied automatically whenever it saves space).
 
 Quick start
 -----------
@@ -18,13 +20,13 @@ Quick start
 'Hello, Hexatess!'
 
 See SPECIFICATION.md in the repository for the full format
-specification, and test_vectors/vectors_v0.2.json for conformance
+specification, and test_vectors/vectors_v0.3.json for conformance
 data usable by independent implementations.
 """
 
 from __future__ import annotations
 
-from .decoder import decode
+from .decoder import decode, payload_to_text
 from .encoder import encode
 from .geometry import (
     DIRS,
@@ -37,6 +39,7 @@ from .geometry import (
 from .header import (
     BULLSEYE_RINGS,
     BLOCK_DATA_MAX,
+    COMPRESSED_FLAG,
     DATA_RING0,
     KEY_RING,
     MAX_DATA_BYTES,
@@ -51,14 +54,15 @@ from .header import (
     pack_mode,
     plan_blocks,
     unpack_mode,
+    unpack_mode_ex,
 )
 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.2.0"
-SPEC_VERSION = "0.2"
+__version__ = "0.3.1"
+SPEC_VERSION = "0.3"
 
 __all__ = [
     # high-level API
@@ -69,7 +73,7 @@ __all__ = [
     "ring_capacity",
     # framing
     "bytes_to_bits", "bits_to_bytes", "pack_mode", "unpack_mode",
-    "plan_blocks",
+    "unpack_mode_ex", "plan_blocks", "payload_to_text",
     # masks
     "mask_bit", "mask_payload", "evaluate_mask", "select_mask",
     # error correction
@@ -77,7 +81,7 @@ __all__ = [
     # 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",
+    "MIN_EC_PCT", "MAX_EC_PCT", "MAX_DATA_BYTES", "COMPRESSED_FLAG",
     # meta
     "__version__", "SPEC_VERSION",
 ]