pharmacode-toolkit 0.2.1__tar.gz

pharmacode_toolkit-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: build sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: python -m pip install --upgrade pip build twine && python -m build
+      - name: Check the archives and the README rendering
+        run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pharmacode-toolkit/
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Publish (trusted publishing, no token)
+        uses: pypa/gh-action-pypi-publish@release/v1

pharmacode_toolkit-0.2.1/.github/workflows/test.yml

@@ -0,0 +1,64 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: python -m pip install --upgrade pip && python -m pip install -e .[dev]
+      - name: Lint
+        run: ruff check . && ruff format --check .
+      - name: Tests
+        run: pytest
+      - name: Quick benchmark
+        run: pharmacode benchmark --seed 20260919 --output benchmark-output --quick
+      - name: Upload benchmark failures
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: benchmark-failures-${{ matrix.os }}-py${{ matrix.python }}
+          path: benchmark-output/failures
+          if-no-files-found: ignore
+
+  package:
+    name: build and install smoke test
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Build wheel
+        run: python -m pip install --upgrade pip build && python -m build
+      - name: Install wheel into a fresh environment and decode a generated code
+        shell: bash
+        run: |
+          python -m venv smoke
+          if [ -x smoke/bin/python ]; then PY=smoke/bin/python; else PY=smoke/Scripts/python.exe; fi
+          "$PY" -m pip install --quiet dist/*.whl
+          "$PY" -m pharmacode generate --value 12345 --dpi 300 --output smoke.png
+          "$PY" -m pharmacode decode smoke.png --dpi 300 --json smoke.json
+          "$PY" -c "import json; d = json.load(open('smoke.json')); assert d['detections'][0]['value'] == 12345, d"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheel-${{ matrix.os }}
+          path: dist/*.whl

pharmacode_toolkit-0.2.1/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+bench/
+benchmark-output*/
+tests/fixtures/generated/
+*.log
+.DS_Store
+Thumbs.db

pharmacode_toolkit-0.2.1/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 0.2.1 - 2026-09-20
+
+- Documentation describes the real-world sample check made before each release.
+- README renders on PyPI: absolute image and documentation links, `pip install pharmacode-toolkit`.
+- Releases are published to PyPI by a tag-triggered workflow using trusted publishing.
+- CI actions updated to their current major versions.
+
+## 0.2.0 - 2026-09-19
+
+Fixes and options that came out of checking the decoder on publicly available
+sample images.
+
+- Human-readable captions printed next to a code no longer break the bar-height check.
+- Codes that fill the frame keep their wide bars: the background kernel is sized from the strokes.
+- A thin rule crossing the bars is removed by a directional opening when nothing else is found.
+- `decode --allow-cropped-quiet-zone` downgrades a quiet zone cut by the image edge to a warning.
+- `decode --min-confidence` reports weak detections as `LOW_CONFIDENCE` errors.
+- The documentation states how the decoder was checked beyond the synthetic benchmark.
+
+## 0.1.0 - 2026-09-18
+
+First release.
+
+- Encoding and decoding of one-track Pharmacode values 3..131070 with both reading directions.
+- Synthetic renderer with Laetus standard and miniature dimensions, DPI, rotation, blur, noise,
+  JPEG, contrast, illumination, perspective, scaling, multi-code scenes and negative samples.
+- Detector and decoder for PNG, JPEG and TIFF: 0/90/180/270 degrees and small tilts,
+  quiet-zone and geometry validation, stable error codes, confidence.
+- `pharmacode generate`, `pharmacode decode` (JSON, annotated image, exit codes) and
+  `pharmacode benchmark` (condition matrix with failure artefacts); `python -m pharmacode ...`
+  is equivalent to the `pharmacode` console script.
+- Documentation: algorithm and threshold provenance, CLI, benchmark, limitations, provenance.
+- CI on Linux and Windows with a wheel install smoke test.

pharmacode_toolkit-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konstantin Dotsenko
+
+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.

pharmacode_toolkit-0.2.1/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.5
+Name: pharmacode-toolkit
+Version: 0.2.1
+Summary: Generate, detect and decode one-track Pharmacode barcodes in images
+Project-URL: Homepage, https://github.com/Dotsen/pharmacode-toolkit
+Project-URL: Repository, https://github.com/Dotsen/pharmacode-toolkit
+Project-URL: Issues, https://github.com/Dotsen/pharmacode-toolkit/issues
+Project-URL: Changelog, https://github.com/Dotsen/pharmacode-toolkit/blob/main/CHANGELOG.md
+Project-URL: Author, https://www.linkedin.com/in/dotsen/
+Author-email: Konstantin Dotsenko <konstantin@dotsenko.pro>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: barcode,computer-vision,laetus,opencv,pharmacode
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26
+Requires-Dist: opencv-python-headless>=4.8
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pharmacode-toolkit
+
+Generate, detect and decode one-track [Pharmacode](https://en.wikipedia.org/wiki/Pharmacode)
+barcodes in PNG, JPEG and TIFF images. Pure Python on numpy and OpenCV.
+
+![Three codes found and annotated](https://raw.githubusercontent.com/Dotsen/pharmacode-toolkit/main/examples/annotated/three_codes_scanned.jpg)
+
+```json
+{
+  "detections": [
+    {"bbox": {"x": 45, "y": 63, "width": 149, "height": 94}, "orientation_deg": 0.0,
+     "bars": ["narrow", "wide", "wide", "wide", "narrow", "narrow"],
+     "bar_widths_px": [3, 9, 9, 9, 3, 3],
+     "value": 91, "mirror_value": 77, "confidence": 1.0, "warnings": []}
+  ],
+  "errors": []
+}
+```
+
+## What it does
+
+- Encodes any value from 3 to 131070 into the 2..16 narrow/wide bars of the format.
+- Renders synthetic codes with the Laetus physical dimensions at any DPI, with
+  optional rotation, blur, noise, JPEG artefacts, contrast loss, uneven lighting,
+  perspective and scaling, all seeded and reproducible.
+- Finds one or more codes in an image at 0, 90, 180 and 270 degrees and small tilts.
+- Classifies bars, checks quiet zones and geometry, and reports **both** reading
+  directions, because the format has no start or stop pattern.
+- Writes a JSON result with stable error codes and an annotated image.
+- Ships a benchmark that reports a matrix of conditions, not one number.
+
+## Install
+
+```bash
+pip install pharmacode-toolkit
+```
+
+From a clone of the repository: `pip install .` (or `pip install -e .[dev]` for
+development). Requires Python 3.10 or newer. Runtime dependencies: numpy,
+opencv-python-headless.
+
+## Quick start
+
+```bash
+pharmacode generate --value 12345 --dpi 300 --output sample.png
+pharmacode decode sample.png --dpi 300
+pharmacode decode sample.png --dpi 300 --json result.json --annotated result.png
+pharmacode decode sample.png --dpi 300 --min-confidence 0.8
+```
+
+`python -m pharmacode ...` works the same as the `pharmacode` command above,
+for environments where installing a console script is inconvenient.
+
+From Python:
+
+```python
+from pharmacode import DecoderConfig, decode_image, load_image
+
+result = decode_image(load_image("sample.png"), DecoderConfig(dpi=300))
+for code in result.detections:
+    print(code.value, code.mirror_value, code.confidence)
+```
+
+## Supported input
+
+8-bit grayscale or colour PNG, JPEG and TIFF; dark bars on a light background;
+codes upright, rotated by multiples of 90 degrees, or tilted a few degrees.
+Pass `--dpi` whenever you know the resolution: it enables physical checks and
+reliable classification of codes that use a single bar width.
+
+## Limitations
+
+See [docs/limitations.md](https://github.com/Dotsen/pharmacode-toolkit/blob/main/docs/limitations.md). In short: no inverted codes, no
+two-track or colour Pharmacode, no DPI from file metadata. Thresholds come from the
+specification and a synthetic benchmark; on top of that the decoder is checked
+against real-world sample images (codes as they appear in the wild: with captions,
+tightly cropped, with a rule drawn across the bars, inside a chart of symbologies).
+
+## Documentation
+
+- [Algorithm and threshold provenance](https://github.com/Dotsen/pharmacode-toolkit/blob/main/docs/algorithm.md)
+- [Command line and exit codes](https://github.com/Dotsen/pharmacode-toolkit/blob/main/docs/cli.md)
+- [Benchmark](https://github.com/Dotsen/pharmacode-toolkit/blob/main/docs/benchmark.md)
+- [Provenance](https://github.com/Dotsen/pharmacode-toolkit/blob/main/docs/provenance.md)
+- [Changelog](https://github.com/Dotsen/pharmacode-toolkit/blob/main/CHANGELOG.md)
+
+## Disclaimer
+
+This project is an independent implementation from public descriptions of the
+format. It is **not validated** for regulated pharmaceutical packaging control and
+must not be used as the sole check in such a process.
+
+## Author
+
+Konstantin Dotsenko ([LinkedIn](https://www.linkedin.com/in/dotsen/)).
+
+## License
+
+MIT, see [LICENSE](https://github.com/Dotsen/pharmacode-toolkit/blob/main/LICENSE).

pharmacode_toolkit-0.2.1/README.md

@@ -0,0 +1,99 @@
+# pharmacode-toolkit
+
+Generate, detect and decode one-track [Pharmacode](https://en.wikipedia.org/wiki/Pharmacode)
+barcodes in PNG, JPEG and TIFF images. Pure Python on numpy and OpenCV.
+
+![Three codes found and annotated](https://raw.githubusercontent.com/Dotsen/pharmacode-toolkit/main/examples/annotated/three_codes_scanned.jpg)
+
+```json
+{
+  "detections": [
+    {"bbox": {"x": 45, "y": 63, "width": 149, "height": 94}, "orientation_deg": 0.0,
+     "bars": ["narrow", "wide", "wide", "wide", "narrow", "narrow"],
+     "bar_widths_px": [3, 9, 9, 9, 3, 3],
+     "value": 91, "mirror_value": 77, "confidence": 1.0, "warnings": []}
+  ],
+  "errors": []
+}
+```
+
+## What it does
+
+- Encodes any value from 3 to 131070 into the 2..16 narrow/wide bars of the format.
+- Renders synthetic codes with the Laetus physical dimensions at any DPI, with
+  optional rotation, blur, noise, JPEG artefacts, contrast loss, uneven lighting,
+  perspective and scaling, all seeded and reproducible.
+- Finds one or more codes in an image at 0, 90, 180 and 270 degrees and small tilts.
+- Classifies bars, checks quiet zones and geometry, and reports **both** reading
+  directions, because the format has no start or stop pattern.
+- Writes a JSON result with stable error codes and an annotated image.
+- Ships a benchmark that reports a matrix of conditions, not one number.
+
+## Install
+
+```bash
+pip install pharmacode-toolkit
+```
+
+From a clone of the repository: `pip install .` (or `pip install -e .[dev]` for
+development). Requires Python 3.10 or newer. Runtime dependencies: numpy,
+opencv-python-headless.
+
+## Quick start
+
+```bash
+pharmacode generate --value 12345 --dpi 300 --output sample.png
+pharmacode decode sample.png --dpi 300
+pharmacode decode sample.png --dpi 300 --json result.json --annotated result.png
+pharmacode decode sample.png --dpi 300 --min-confidence 0.8
+```
+
+`python -m pharmacode ...` works the same as the `pharmacode` command above,
+for environments where installing a console script is inconvenient.
+
+From Python:
+
+```python
+from pharmacode import DecoderConfig, decode_image, load_image
+
+result = decode_image(load_image("sample.png"), DecoderConfig(dpi=300))
+for code in result.detections:
+    print(code.value, code.mirror_value, code.confidence)
+```
+
+## Supported input
+
+8-bit grayscale or colour PNG, JPEG and TIFF; dark bars on a light background;
+codes upright, rotated by multiples of 90 degrees, or tilted a few degrees.
+Pass `--dpi` whenever you know the resolution: it enables physical checks and
+reliable classification of codes that use a single bar width.
+
+## Limitations
+
+See [docs/limitations.md](https://github.com/Dotsen/pharmacode-toolkit/blob/main/docs/limitations.md). In short: no inverted codes, no
+two-track or colour Pharmacode, no DPI from file metadata. Thresholds come from the
+specification and a synthetic benchmark; on top of that the decoder is checked
+against real-world sample images (codes as they appear in the wild: with captions,
+tightly cropped, with a rule drawn across the bars, inside a chart of symbologies).
+
+## Documentation
+
+- [Algorithm and threshold provenance](https://github.com/Dotsen/pharmacode-toolkit/blob/main/docs/algorithm.md)
+- [Command line and exit codes](https://github.com/Dotsen/pharmacode-toolkit/blob/main/docs/cli.md)
+- [Benchmark](https://github.com/Dotsen/pharmacode-toolkit/blob/main/docs/benchmark.md)
+- [Provenance](https://github.com/Dotsen/pharmacode-toolkit/blob/main/docs/provenance.md)
+- [Changelog](https://github.com/Dotsen/pharmacode-toolkit/blob/main/CHANGELOG.md)
+
+## Disclaimer
+
+This project is an independent implementation from public descriptions of the
+format. It is **not validated** for regulated pharmaceutical packaging control and
+must not be used as the sole check in such a process.
+
+## Author
+
+Konstantin Dotsenko ([LinkedIn](https://www.linkedin.com/in/dotsen/)).
+
+## License
+
+MIT, see [LICENSE](https://github.com/Dotsen/pharmacode-toolkit/blob/main/LICENSE).