pharmacode-toolkit 0.2.1__py3-none-any.whl

pharmacode/__init__.py

@@ -0,0 +1,71 @@
+"""Toolkit for generating, detecting and decoding one-track Pharmacode."""
+
+from __future__ import annotations
+
+from pharmacode.decoding import decode_bars
+from pharmacode.detection import find_candidates
+from pharmacode.encoding import MAX_BARS, MAX_VALUE, MIN_BARS, MIN_VALUE, bars_to_value, encode
+from pharmacode.io import InputError, load_image, save_image
+from pharmacode.models import (
+    BarKind,
+    BarSequence,
+    BoundingBox,
+    DecodedPharmacode,
+    DecodeError,
+    DecoderConfig,
+    DecodeResult,
+    DetectionCandidate,
+    ErrorCode,
+    ImageInfo,
+)
+from pharmacode.pipeline import decode_image
+from pharmacode.rendering import (
+    NEGATIVE_KINDS,
+    Distortion,
+    RenderSpec,
+    compose_scene,
+    distort,
+    render_bars,
+    render_negative,
+    render_value,
+)
+from pharmacode.segmentation import extract_bars_from_upright
+from pharmacode.visualization import annotate
+
+__version__ = "0.2.1"
+
+__all__ = [
+    "MAX_BARS",
+    "MAX_VALUE",
+    "MIN_BARS",
+    "MIN_VALUE",
+    "BarKind",
+    "BarSequence",
+    "BoundingBox",
+    "DecodeError",
+    "DecodedPharmacode",
+    "DecodeResult",
+    "DecoderConfig",
+    "DetectionCandidate",
+    "Distortion",
+    "ErrorCode",
+    "ImageInfo",
+    "InputError",
+    "NEGATIVE_KINDS",
+    "RenderSpec",
+    "__version__",
+    "annotate",
+    "bars_to_value",
+    "compose_scene",
+    "decode_bars",
+    "decode_image",
+    "distort",
+    "encode",
+    "extract_bars_from_upright",
+    "find_candidates",
+    "load_image",
+    "render_bars",
+    "render_negative",
+    "render_value",
+    "save_image",
+]

pharmacode/__main__.py

@@ -0,0 +1,10 @@
+"""Allow ``python -m pharmacode``."""
+
+from __future__ import annotations
+
+import sys
+
+from pharmacode.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

pharmacode/benchmark.py

@@ -0,0 +1,248 @@
+"""Synthetic benchmark: a matrix of conditions, never a single headline number."""
+
+from __future__ import annotations
+
+import json
+import platform
+import sys
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+import cv2
+import numpy as np
+
+from pharmacode import __version__
+from pharmacode.encoding import MAX_VALUE, MIN_VALUE
+from pharmacode.io import save_image
+from pharmacode.models import DecoderConfig
+from pharmacode.pipeline import decode_image
+from pharmacode.rendering import (
+    NEGATIVE_KINDS,
+    Distortion,
+    RenderSpec,
+    compose_scene,
+    distort,
+    render_negative,
+    render_value,
+)
+from pharmacode.visualization import annotate
+
+BOUNDARY_VALUES = [3, 4, 5, 6, 7, 8, 13, 25, 91, 100, 1234, 12345, 65535, 123456, 131070]
+
+
+@dataclass(frozen=True)
+class Condition:
+    name: str
+    group: str
+    dpi: float
+    distortion: Distortion = Distortion()
+    spec: RenderSpec | None = None
+    multi: bool = False
+    edge: bool = False
+    use_dpi: bool = True
+
+    def render_spec(self) -> RenderSpec:
+        return self.spec if self.spec is not None else RenderSpec(dpi=self.dpi)
+
+
+def build_conditions(quick: bool) -> list[Condition]:
+    conditions = [
+        Condition("clean-300", "clean", 300.0),
+        Condition("rotation-90", "rotation", 300.0, Distortion(rotation_deg=90)),
+        Condition("rotation-180", "rotation", 300.0, Distortion(rotation_deg=180)),
+        Condition("rotation-270", "rotation", 300.0, Distortion(rotation_deg=270)),
+        Condition("tilt-plus-3", "rotation", 300.0, Distortion(rotation_deg=3)),
+        Condition("tilt-minus-3", "rotation", 300.0, Distortion(rotation_deg=-3)),
+        Condition("dpi-150", "dpi", 150.0),
+        Condition("dpi-600", "dpi", 600.0),
+        Condition("blur-1", "blur", 300.0, Distortion(blur_sigma=1.0)),
+        Condition("blur-2", "blur", 300.0, Distortion(blur_sigma=2.0)),
+        Condition("noise-10", "noise", 300.0, Distortion(noise_sigma=10.0)),
+        Condition("noise-25", "noise", 300.0, Distortion(noise_sigma=25.0)),
+        Condition("jpeg-50", "jpeg", 300.0, Distortion(jpeg_quality=50)),
+        Condition("jpeg-30", "jpeg", 300.0, Distortion(jpeg_quality=30)),
+        Condition("contrast-0.4", "contrast", 300.0, Distortion(contrast=0.4)),
+        Condition("illumination-0.5", "illumination", 300.0, Distortion(illumination_gradient=0.5)),
+        Condition("perspective-3", "perspective", 300.0, Distortion(perspective_deg=3.0)),
+        Condition(
+            "scale-0.7x1.3", "scale", 300.0, Distortion(scale_x=0.7, scale_y=1.3), use_dpi=False
+        ),
+        Condition("edge-corner", "edge", 300.0, edge=True),
+        Condition("multi-3", "multi", 300.0, multi=True),
+        Condition("miniature-600", "tolerance", 600.0, spec=RenderSpec.miniature(dpi=600.0)),
+        Condition(
+            "tolerance-max-gap",
+            "tolerance",
+            300.0,
+            spec=RenderSpec(narrow_mm=0.7, wide_mm=2.5, gap_mm=2.5),
+        ),
+        Condition("dpi-150-blur-1", "blur", 150.0, Distortion(blur_sigma=1.0)),
+    ]
+    if quick:
+        # One condition per group (the first that appears), so a slice can't silently drop
+        # a whole group from CI coverage; rotation-180 is added on top for a second angle.
+        keep = {"clean", "rotation", "blur", "noise", "multi", "scale", "tolerance"}
+        selected: list[Condition] = []
+        seen: set[str] = set()
+        for c in conditions:
+            if c.group in keep and c.group not in seen:
+                selected.append(c)
+                seen.add(c.group)
+            if c.group == "rotation" and c.name == "rotation-180":
+                selected.append(c)
+        conditions = selected
+    return conditions
+
+
+def build_values(seed: int, quick: bool) -> list[int]:
+    rng = np.random.default_rng(seed)
+    count = 8 if quick else 40
+    random_values = sorted(int(v) for v in rng.integers(MIN_VALUE, MAX_VALUE + 1, count))
+    return (BOUNDARY_VALUES[:6] if quick else BOUNDARY_VALUES) + random_values
+
+
+def _make_image(condition: Condition, value: int, rng: np.random.Generator) -> np.ndarray:
+    spec = condition.render_spec()
+    code = render_value(value, spec)
+    if condition.multi:
+        others = [render_value(int(v), spec) for v in rng.integers(MIN_VALUE, MAX_VALUE + 1, 2)]
+        turned = distort(others[0], Distortion(rotation_deg=90))
+        canvas = (
+            code.shape[0] * 2 + turned.shape[0] + 200,
+            code.shape[1] + turned.shape[1] + others[1].shape[1] + 300,
+        )
+        code = compose_scene(
+            canvas,
+            [
+                (code, 50, 50),
+                (turned, code.shape[1] + 150, 60),
+                (others[1], 80, code.shape[0] + turned.shape[0] + 120),
+            ],
+        )
+    if condition.edge:
+        code = compose_scene((code.shape[0] + 150, code.shape[1] + 150), [(code, 0, 0)])
+    return (
+        distort(code, condition.distortion, rng) if condition.distortion != Distortion() else code
+    )
+
+
+def _environment() -> dict[str, str]:
+    return {
+        "toolkit": __version__,
+        "python": sys.version.split()[0],
+        "platform": platform.platform(),
+        "numpy": np.__version__,
+        "opencv": cv2.__version__,
+    }
+
+
+def run_benchmark(seed: int, output_dir: str | Path, quick: bool = False) -> dict[str, Any]:
+    """Render, decode and score every condition; write reports and failure images."""
+    output = Path(output_dir)
+    failures = output / "failures"
+    failures.mkdir(parents=True, exist_ok=True)
+    rng = np.random.default_rng(seed)
+    values = build_values(seed, quick)
+    report: dict[str, Any] = {
+        "seed": seed,
+        "quick": quick,
+        "environment": _environment(),
+        "config": asdict(DecoderConfig()),
+        "values": values,
+        "conditions": {},
+        "negatives": {},
+    }
+    for condition in build_conditions(quick):
+        detected = correct = 0
+        elapsed: list[float] = []
+        failed: list[dict[str, Any]] = []
+        config = DecoderConfig(dpi=condition.dpi if condition.use_dpi else None)
+        for value in values:
+            image = _make_image(condition, value, rng)
+            start = time.perf_counter()
+            result = decode_image(image, config)
+            elapsed.append((time.perf_counter() - start) * 1000.0)
+            found = bool(result.detections)
+            hit = any(value in (d.value, d.mirror_value) for d in result.detections)
+            detected += found
+            correct += hit
+            if not hit:
+                target = failures / condition.name
+                target.mkdir(parents=True, exist_ok=True)
+                save_image(target / f"{value}.png", annotate(image, result))
+                failed.append({"value": value, "errors": [e.to_dict() for e in result.errors]})
+        report["conditions"][condition.name] = {
+            "group": condition.group,
+            "images": len(values),
+            "detected": detected,
+            "detected_rate": detected / len(values),
+            "correct": correct,
+            "correct_rate": correct / len(values),
+            "mean_ms": float(np.mean(elapsed)),
+            "failures": failed,
+        }
+    negative_count = 40 if quick else 200
+    false_positives: list[dict[str, Any]] = []
+    for index in range(negative_count):
+        kind = NEGATIVE_KINDS[index % len(NEGATIVE_KINDS)]
+        image = render_negative(kind, rng)
+        result = decode_image(image, DecoderConfig())
+        if result.detections:
+            target = failures / "negatives"
+            target.mkdir(parents=True, exist_ok=True)
+            save_image(target / f"{kind}-{index}.png", annotate(image, result))
+            false_positives.append(
+                {"kind": kind, "index": index, "values": [d.value for d in result.detections]}
+            )
+    report["negatives"] = {
+        "images": negative_count,
+        "false_positives": len(false_positives),
+        "false_positive_rate": len(false_positives) / negative_count,
+        "cases": false_positives,
+    }
+    (output / "results.json").write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+    (output / "results.md").write_text(render_markdown(report), encoding="utf-8")
+    return report
+
+
+def gate(report: dict[str, Any], min_correct: float, max_false_positives: int) -> list[str]:
+    """Return one message per violated threshold; empty means the benchmark passed."""
+    violations: list[str] = []
+    for name, row in report["conditions"].items():
+        if row["correct_rate"] < min_correct:
+            violations.append(
+                f"{name}: correct rate {row['correct_rate']:.1%} below {min_correct:.1%}"
+            )
+    false_positives = report["negatives"]["false_positives"]
+    if false_positives > max_false_positives:
+        violations.append(
+            f"negatives: {false_positives} false positives, maximum {max_false_positives}"
+        )
+    return violations
+
+
+def render_markdown(report: dict[str, Any]) -> str:
+    env = report["environment"]
+    lines = [
+        f"# Benchmark (seed {report['seed']}, {'quick' if report['quick'] else 'full'})",
+        "",
+        f"Python {env['python']}, numpy {env['numpy']}, OpenCV {env['opencv']}, {env['platform']}",
+        "",
+        "| condition | group | images | detected | correct | mean ms |",
+        "|---|---|---|---|---|---|",
+    ]
+    for name, row in report["conditions"].items():
+        lines.append(
+            f"| {name} | {row['group']} | {row['images']} | {row['detected_rate']:.1%} | "
+            f"{row['correct_rate']:.1%} | {row['mean_ms']:.1f} |"
+        )
+    negatives = report["negatives"]
+    lines += [
+        "",
+        f"Negatives: {negatives['images']} images, {negatives['false_positives']} false positives "
+        f"({negatives['false_positive_rate']:.1%}).",
+        "",
+    ]
+    return "\n".join(lines)

pharmacode/cli.py

@@ -0,0 +1,214 @@
+"""Command line interface: ``pharmacode generate | decode | benchmark``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+import numpy as np
+
+from pharmacode import __version__
+from pharmacode.encoding import encode
+from pharmacode.io import InputError, load_image, save_image
+from pharmacode.models import DecoderConfig, DecodeResult, ErrorCode
+from pharmacode.pipeline import decode_image
+from pharmacode.rendering import Distortion, RenderSpec, distort, render_bars
+from pharmacode.visualization import annotate
+
+EXIT_OK = 0
+EXIT_USAGE = 2
+EXIT_INPUT = 3
+EXIT_NO_CANDIDATES = 4
+EXIT_VALIDATION_FAILED = 5
+EXIT_PARTIAL = 6
+EXIT_BENCHMARK_FAILED = 7
+
+
+def _fail(message: str, code: int) -> int:
+    print(f"error: {message}", file=sys.stderr)
+    return code
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pharmacode",
+        description="Generate, detect and decode one-track Pharmacode barcodes in images.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    generate = commands.add_parser("generate", help="render a synthetic Pharmacode image")
+    generate.add_argument("--value", type=int, required=True, help="integer 3..131070")
+    generate.add_argument("--output", required=True, help="PNG, JPEG or TIFF path")
+    generate.add_argument("--dpi", type=float, default=300.0)
+    generate.add_argument("--miniature", action="store_true", help="Laetus miniature dimensions")
+    generate.add_argument("--rotation", type=float, default=0.0, help="degrees counter-clockwise")
+    generate.add_argument("--scale-x", type=float, default=1.0)
+    generate.add_argument("--scale-y", type=float, default=1.0)
+    generate.add_argument("--perspective", type=float, default=0.0, help="tilt in degrees")
+    generate.add_argument("--blur", type=float, default=0.0, help="Gaussian sigma in pixels")
+    generate.add_argument("--noise", type=float, default=0.0, help="Gaussian noise sigma")
+    generate.add_argument("--contrast", type=float, default=1.0, help="1.0 = full contrast")
+    generate.add_argument("--illumination", type=float, default=0.0, help="0..1 brightness loss")
+    generate.add_argument("--jpeg", type=int, default=None, help="JPEG quality round trip")
+    generate.add_argument("--seed", type=int, default=0)
+    generate.set_defaults(handler=run_generate)
+
+    decode = commands.add_parser("decode", help="find and decode Pharmacode in an image")
+    decode.add_argument("input", help="PNG, JPEG or TIFF file")
+    decode.add_argument("--dpi", type=float, default=None, help="resolution for physical checks")
+    decode.add_argument("--json", default=None, help="write the result here instead of stdout")
+    decode.add_argument("--annotated", default=None, help="write an annotated image here")
+    decode.add_argument("--min-bars", type=int, default=2)
+    decode.add_argument("--max-bars", type=int, default=16)
+    decode.add_argument(
+        "--allow-cropped-quiet-zone",
+        action="store_true",
+        help="treat a quiet zone cut by the image edge as a warning instead of "
+        "QUIET_ZONE_VIOLATION",
+    )
+    decode.add_argument(
+        "--min-confidence",
+        type=float,
+        default=0.0,
+        help="reject detections below this confidence as LOW_CONFIDENCE errors (0.0..1.0)",
+    )
+    decode.set_defaults(handler=run_decode)
+
+    benchmark = commands.add_parser("benchmark", help="run the synthetic benchmark matrix")
+    benchmark.add_argument("--seed", type=int, default=20260919)
+    benchmark.add_argument("--output", default="benchmark-output")
+    benchmark.add_argument("--quick", action="store_true", help="small subset for CI")
+    benchmark.add_argument(
+        "--min-correct",
+        type=float,
+        default=1.0,
+        help="fail unless every condition reaches this correct rate",
+    )
+    benchmark.add_argument("--max-false-positives", type=int, default=0)
+    benchmark.set_defaults(handler=run_benchmark_command)
+    return parser
+
+
+def run_generate(args: argparse.Namespace) -> int:
+    try:
+        bars = encode(args.value)
+    except (TypeError, ValueError) as exc:
+        return _fail(str(exc), EXIT_USAGE)
+    if args.dpi <= 0:
+        return _fail("--dpi must be positive", EXIT_USAGE)
+    spec = RenderSpec.miniature(dpi=args.dpi) if args.miniature else RenderSpec(dpi=args.dpi)
+    image = render_bars(bars, spec)
+    try:
+        distortion = Distortion(
+            rotation_deg=args.rotation,
+            scale_x=args.scale_x,
+            scale_y=args.scale_y,
+            perspective_deg=args.perspective,
+            blur_sigma=args.blur,
+            noise_sigma=args.noise,
+            contrast=args.contrast,
+            illumination_gradient=args.illumination,
+            jpeg_quality=args.jpeg,
+        )
+    except ValueError as exc:
+        return _fail(str(exc), EXIT_USAGE)
+    if distortion != Distortion():
+        image = distort(image, distortion, np.random.default_rng(args.seed))
+    try:
+        save_image(args.output, image)
+    except InputError as exc:
+        return _fail(str(exc), EXIT_INPUT)
+    print(
+        json.dumps(
+            {
+                "value": args.value,
+                "bars": [bar.value for bar in bars],
+                "output": str(args.output),
+                "width": int(image.shape[1]),
+                "height": int(image.shape[0]),
+                "dpi": args.dpi,
+            }
+        )
+    )
+    return EXIT_OK
+
+
+def exit_code_for(result: DecodeResult) -> int:
+    """Map a result to the documented exit codes."""
+    if result.detections and not result.errors:
+        return EXIT_OK
+    if not result.detections:
+        if any(error.code is ErrorCode.NO_CANDIDATES for error in result.errors):
+            return EXIT_NO_CANDIDATES
+        return EXIT_VALIDATION_FAILED
+    return EXIT_PARTIAL
+
+
+def run_decode(args: argparse.Namespace) -> int:
+    if args.dpi is not None and args.dpi <= 0:
+        return _fail("--dpi must be positive", EXIT_USAGE)
+    if not 2 <= args.min_bars <= args.max_bars <= 16:
+        return _fail("--min-bars and --max-bars must satisfy 2 <= min <= max <= 16", EXIT_USAGE)
+    if not 0.0 <= args.min_confidence <= 1.0:
+        return _fail("--min-confidence must be between 0.0 and 1.0", EXIT_USAGE)
+    try:
+        image = load_image(args.input)
+    except InputError as exc:
+        return _fail(str(exc), EXIT_INPUT)
+    config = DecoderConfig(
+        dpi=args.dpi,
+        min_bars=args.min_bars,
+        max_bars=args.max_bars,
+        allow_truncated_quiet_zone=args.allow_cropped_quiet_zone,
+        min_confidence=args.min_confidence,
+    )
+    result = decode_image(image, config, path=str(args.input))
+    payload = json.dumps(result.to_dict(), indent=2)
+    if args.json:
+        try:
+            Path(args.json).write_text(payload + "\n", encoding="utf-8")
+        except OSError as exc:
+            return _fail(f"could not write JSON to {args.json}: {exc}", EXIT_INPUT)
+    else:
+        print(payload)
+    if args.annotated:
+        try:
+            save_image(args.annotated, annotate(image, result))
+        except InputError as exc:
+            return _fail(str(exc), EXIT_INPUT)
+    return exit_code_for(result)
+
+
+def run_benchmark_command(args: argparse.Namespace) -> int:
+    from pharmacode.benchmark import gate, render_markdown, run_benchmark
+
+    if not 0.0 <= args.min_correct <= 1.0:
+        return _fail("--min-correct must be between 0.0 and 1.0", EXIT_USAGE)
+    if args.max_false_positives < 0:
+        return _fail("--max-false-positives must be >= 0", EXIT_USAGE)
+    report = run_benchmark(seed=args.seed, output_dir=args.output, quick=args.quick)
+    print(render_markdown(report))
+    violations = gate(report, args.min_correct, args.max_false_positives)
+    if violations:
+        for violation in violations:
+            print(f"gate: {violation}", file=sys.stderr)
+        return EXIT_BENCHMARK_FAILED
+    print(
+        f"gate: passed (min correct {args.min_correct:.0%}, "
+        f"max false positives {args.max_false_positives})"
+    )
+    return EXIT_OK
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.handler(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pharmacode/decoding.py

@@ -0,0 +1,33 @@
+"""Turn a classified bar sequence into both reading directions."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from pharmacode.encoding import bars_to_value
+from pharmacode.models import BarKind, DecodeError, DecoderConfig, ErrorCode
+
+
+def decode_bars(kinds: Sequence[BarKind]) -> tuple[int, int]:
+    """Return ``(value, mirror_value)``.
+
+    ``value`` reads the sequence as given (most significant bar first);
+    ``mirror_value`` reads it reversed. Both are computed independently and no
+    heuristic prefers one over the other: the format itself does not encode
+    the reading direction.
+    """
+    sequence = tuple(kinds)
+    return bars_to_value(sequence), bars_to_value(tuple(reversed(sequence)))
+
+
+def check_bar_count(count: int, config: DecoderConfig) -> DecodeError | None:
+    """Return a ``DecodeError`` if ``count`` is outside the configured range."""
+    if count < config.min_bars:
+        return DecodeError(
+            ErrorCode.TOO_FEW_BARS, f"found {count} bars, minimum is {config.min_bars}"
+        )
+    if count > config.max_bars:
+        return DecodeError(
+            ErrorCode.TOO_MANY_BARS, f"found {count} bars, maximum is {config.max_bars}"
+        )
+    return None