hexatess-code 0.1.0__tar.gz → 0.3.0__tar.gz

{hexatess_code-0.1.0 → hexatess_code-0.3.0}/LICENSE

@@ -27,4 +27,4 @@ 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 Specification v0.2, https://github.com/<you>/hexatess-code".

{hexatess_code-0.1.0 → hexatess_code-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexatess-code
-Version: 0.1.0
+Version: 0.3.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
@@ -32,7 +32,7 @@ License: MIT License
         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 Specification v0.2, 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
@@ -56,9 +56,18 @@ 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 🐝
+[![PyPI](https://img.shields.io/pypi/v/hexatess-code)](https://pypi.org/project/hexatess-code/) 
+
+[![Python](https://img.shields.io/pypi/pyversions/hexatess-code)](https://pypi.org/project/hexatess-code/) 
+
+[![CI](https://github.com/lovro-abram/hexatess-code/actions/workflows/ci.yml/badge.svg)](https://github.com/lovro-abram/hexatess-code/actions/workflows/ci.yml) 
 
 **An experimental 2D barcode on a hexagonal grid** — with a hexagonal
 bullseye finder, spiral serialization and a continuously selectable
@@ -81,7 +90,7 @@ text, stats = decode(grid)          # ('Hello, Hexatess!', {...})
 * **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`),
+* **B** — finder close-up: dark centre (rule `bit = 1 − 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;
@@ -104,27 +113,32 @@ 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 — printed labels, foil transparencies, tilted
+> and rotated shots.  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
 ```
 
 ## API
@@ -136,6 +150,7 @@ hexatess-code --demo        # demo symbol + robustness statistics
 | `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`.
@@ -162,16 +177,18 @@ 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.1.json`](test_vectors/vectors_v0.1.json)
+[`test_vectors/vectors_v0.2.json`](test_vectors/vectors_v0.2.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.
+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).

{hexatess_code-0.1.0 → hexatess_code-0.3.0}/README.md

@@ -1,4 +1,9 @@
 # Hexatess Code 🐝
+[![PyPI](https://img.shields.io/pypi/v/hexatess-code)](https://pypi.org/project/hexatess-code/) 
+
+[![Python](https://img.shields.io/pypi/pyversions/hexatess-code)](https://pypi.org/project/hexatess-code/) 
+
+[![CI](https://github.com/lovro-abram/hexatess-code/actions/workflows/ci.yml/badge.svg)](https://github.com/lovro-abram/hexatess-code/actions/workflows/ci.yml) 
 
 **An experimental 2D barcode on a hexagonal grid** — with a hexagonal
 bullseye finder, spiral serialization and a continuously selectable
@@ -21,7 +26,7 @@ text, stats = decode(grid)          # ('Hello, Hexatess!', {...})
 * **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`),
+* **B** — finder close-up: dark centre (rule `bit = 1 − 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;
@@ -44,27 +49,32 @@ 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 — printed labels, foil transparencies, tilted
+> and rotated shots.  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
 ```
 
 ## API
@@ -76,6 +86,7 @@ hexatess-code --demo        # demo symbol + robustness statistics
 | `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`.
@@ -102,16 +113,18 @@ 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.1.json`](test_vectors/vectors_v0.1.json)
+[`test_vectors/vectors_v0.2.json`](test_vectors/vectors_v0.2.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.
+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).

{hexatess_code-0.1.0 → hexatess_code-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hexatess-code"
-version = "0.1.0"
+version = "0.3.0"
 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.1.0 → hexatess_code-0.3.0}/src/hexatess/__init__.py

@@ -1,6 +1,6 @@
 """Hexatess Code - an experimental 2D barcode on a hexagonal grid.
 
-Reference implementation of specification v0.1.  The symbol is a
+Reference implementation of specification v0.2.  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
@@ -18,7 +18,7 @@ Quick start
 'Hello, Hexatess!'
 
 See SPECIFICATION.md in the repository for the full format
-specification, and test_vectors/vectors_v0.1.json for conformance
+specification, and test_vectors/vectors_v0.2.json for conformance
 data usable by independent implementations.
 """
 
@@ -57,8 +57,8 @@ 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"
+__version__ = "0.3.0"
+SPEC_VERSION = "0.2"
 
 __all__ = [
     # high-level API