cnrocr

Container number detection and recognition — ISO 6346 end-to-end, ONNX only.

A region detector locates the number, ISO type code, owner code and serial on the container; an OCR recognizer reads each crop with a spec-constrained beam search. Fragments split across panels are merged back into a single number and validated against the ISO 6346 check digit.

No PyTorch required. The runtime is onnxruntime + numpy + pillow.

Install

pip install cnrocr             # CPU
pip install "cnrocr[gpu]"      # NVIDIA CUDA via onnxruntime-gpu
pip install "cnrocr[server]"   # local REST API + dashboard

Model weights (~113 MB) are not bundled in the wheel. They are downloaded on first use and cached locally:

cnrocr models download       # optional — happens automatically otherwise

Python API

from cnrocr import ContainerOCR

ocr = ContainerOCR()                      # weights resolved from cache
result = ocr.read("gate_cam.jpg")

for c in result.containers:
    print(c.number, c.iso_type, c.confidence, c.needs_review)
# TGHU8913889 22G1 0.9997 False

Multiple images

results = ocr.read_many(["a.jpg", "b.jpg", "c.jpg"], batch_size=8)

read_many treats the images as unrelated — N images in, N results out.

Multi-view fusion

When several cameras photograph the same container, fuse them into one answer instead of voting on strings:

mv = ocr.read_multiview(["cam1.jpg", "cam2.jpg", "cam3.jpg"])
print(mv.number, mv.agreement, mv.mode)

Beam-search candidates from every view are summed in log space, so a character that one view is unsure about can be settled by the others. If the views appear to be looking at different containers, they are not fused — mv.consensus becomes False rather than producing a confident wrong answer.

Review triage

A check digit alone is not enough. The constrained decoder only emits spec-conforming candidates, so when the true string is absent from the beam it will confidently output a plausible wrong number that still passes the check digit. needs_review combines the check digit, the spec flag and a confidence floor:

if c.needs_review:
    print(c.review_reason)     # "low confidence (0.612 < 0.7)"

Owner code registry (optional)

Real-world owner codes are registered with the BIC. Supplying the list filters out invented codes that would otherwise pass both the format check and the check digit:

from cnrocr import OwnerCodeRegistry
ocr = ContainerOCR(registry=OwnerCodeRegistry.from_file("bic_codes.txt"))

The list is not shipped with this package.

Command line

cnrocr read gate_cam.jpg
cnrocr read *.jpg --json --device cuda
cnrocr multiview cam1.jpg cam2.jpg cam3.jpg
cnrocr models status
cnrocr check                    # diagnose install, providers, cache

--fail-on-review makes the process exit with code 2 when any result needs human review, which is convenient in batch pipelines.

Local server

A REST API and a browser dashboard, both served from your own machine. Images never leave it.

pip install "cnrocr[server]"
cnrocr server start                  # http://127.0.0.1:8000
cnrocr server start --daemon         # background; `server stop` to end it

Open the address for the dashboard, or /docs for the interactive API. The models are loaded once at startup and shared by every request.

curl -X POST -F "file=@gate_cam.jpg" http://127.0.0.1:8000/api/read

{
  "detection_id": 41,
  "device": "cuda",
  "containers": [{"number": "TGHU8913889", "iso_type": "22G1",
                  "confidence": 0.9997, "needs_review": false}],
  "elapsed_ms": 38.4
}

Review queue

Results below --review-confidence (default 0.7) are flagged and collected for a human instead of being silently trusted. In practice that is a small fraction of traffic — on our validation set every misread scored below 0.7 while correct reads sat near 1.0, so the threshold catches the errors and sends only a few percent of good reads along with them.

The dashboard shows each flagged result next to its photo, with the number in an editable field. Confirming stores the corrected value, which is the only record of which misreadings repeat.

Access from a phone

The dashboard is built for a phone first: the camera button photographs a container and uploads it directly, which is enough to work the queue at the gate.

cnrocr server start --host 0.0.0.0 --token "$(python -c 'import secrets;print(secrets.token_urlsafe(24))')"

Binding to 0.0.0.0 exposes the server to everyone who can reach the host, so set a token when you do. The server says so at startup if you forget; it does not refuse to start, because a closed network is a legitimate setup.

Configuration

Flags, a YAML file, or the environment — later wins, and flags win over all.

cnrocr server start --config server.yaml --port 9000 --device cuda

server:
  host: 127.0.0.1
  port: 8000
  api_token: ""            # required in practice once host is not loopback
models:
  device: auto             # auto | cpu | cuda
  workers: 4
  review_confidence: 0.7
storage:
  save_images: true        # the review screen needs the photo
  max_history: 5000

Every setting also reads from CNROCR_SERVER_<NAME>. An unknown key in the YAML is an error rather than a silent no-op — a typo in api_token must not quietly leave authentication off.

cnrocr server status        # is it up, on what device, since when
cnrocr server list          # every instance this machine knows about
cnrocr server logs -f       # follow
cnrocr server read img.jpg  # send a file to a running instance
cnrocr server stop

Evaluation limit

Without a licence, cnrocr processes 30 images per day. The counter is per image, not per call, and resets at 00:00 UTC. It is shared by the library, the CLI and the server — they all draw on the same daily budget.

cnrocr license      # licence status and today's usage

When the quota runs out the process exits with code 3 and prints how to ask for a licence. Nothing is processed on a call that would exceed the quota — it is all or nothing, so a refused call costs no quota.

To request an unrestricted licence, email vislab2026@gmail.com with your name, organisation and intended use. You will receive a key:

# Windows
setx CNROCR_LICENSE "eyJlbWFpbCI6..."

# macOS / Linux
export CNROCR_LICENSE='eyJlbWFpbCI6...'

The key may also be saved to a file named license in the cache directory (cnrocr models path shows where). Verify with cnrocr check.

Weights and caching

Every file is verified against a SHA-256 recorded in the wheel. Released assets are immutable: a new model set ships under a new tag and a new library version, so upgrading never invalidates an existing install.

The weights are encrypted and are decrypted into memory when a session is built. The cache holds ciphertext only; no plaintext model is written to disk.

Environment overrides:

License

Proprietary. Evaluation and non-commercial research use only — see LICENSE. Contact the copyright holder for commercial licensing.