Most of the computer vision work that gets written about is inference-heavy: detectors, segmenters, depth. But a large share of the vision systems actually running in factories, warehouses and hospitals do something much less glamorous and much more load-bearing — they read a code off a thing and tie it to a record. Unit-level traceability, pharmaceutical serialisation, warehouse sortation, tool-crib check-out, medical device UDI: all of it comes down to a read.
It looks like a solved problem, which is why it is so often quoted at three days and delivered at three months. The failure is never "can OpenCV decode a QR code" — it obviously can. The failure is the 1.5% of units that don't read on a moving line, the operator who has no defined path when they don't, and the fact that nobody can prove afterwards which frame produced which code.
This tutorial builds the whole thing: which OpenCV 5 readers to use for which symbology, how to set up optics and exposure so decoding is possible at all, how to turn multiple frames into one defensible decision, and how to design the no-read path and audit trail that make the system auditable.
1. What ships in OpenCV 5, and what doesn't
Code reading lives in objdetect. Three things matter:
cv::barcode::BarcodeDetector— 1D linear symbologies: EAN-8/13, UPC-A/E, Code 128, Code 39, ITF. It graduated out ofcontriband is a normal part ofobjdetect; it does detection and decoding, and it will return several codes from one frame.cv::QRCodeDetectorAruco— the ArUco-based QR finder-pattern detector. It is generally faster and more robust on small or partially degraded QR codes than the classicQRCodeDetector, which is still present. Both support multi-code detection (detectAndDecodeMulti) and both handle Micro QR detection in recent builds.- DataMatrix — not in core OpenCV. This is the single most common surprise on industrial projects, because DataMatrix (ECC200) is the direct-part-marking symbology: it is what's laser-etched on surgical instruments, engine components and PCBs, and what pharma serialisation uses. OpenCV will happily help you find and rectify the mark; you decode it with
libdmtx(viapylibdmtx), ZXing-C++, or a commercial SDK. Plan for that dependency early — it has licence and packaging implications.
A pragmatic default stack for mixed-symbology work in 2026 is: OpenCV 5 for capture, preprocessing and ROI localisation; BarcodeDetector/QRCodeDetectorAruco for 1D and QR; ZXing-C++ or libdmtx as the decode fallback for DataMatrix, PDF417 and Aztec. Use one wrapper interface over all of them so the pipeline doesn't care which engine answered.
import cv2
bar = cv2.barcode.BarcodeDetector()
qr = cv2.QRCodeDetectorAruco()
def read_codes(gray):
"""Return a list of (symbology, payload, quad) from one frame."""
out = []
ok, infos, types, points = bar.detectAndDecodeWithType(gray)
if ok and infos is not None:
for text, kind, quad in zip(infos, types, points):
if text:
out.append((kind or "1D", text, quad))
ok, infos, points, _ = qr.detectAndDecodeMulti(gray)
if ok and infos is not None:
for text, quad in zip(infos, points):
if text:
out.append(("QR", text, quad))
return out
Note the API shape: these readers return quads, not axis-aligned boxes. Keep the quad. You need it for the audit trail, for rejecting reads outside the expected zone, and for measuring symbol size in pixels — which is the number that tells you whether your optics are adequate.
2. The read is won or lost before the software runs
Three physical numbers decide whether decoding is even possible. Get these on a spec sheet before writing pipeline code.
Pixels per module. A "module" is the smallest element of the code: one narrow bar, one QR/DataMatrix cell. Rules of thumb that hold up in practice:
- 1D barcodes: at least 2 pixels per narrow bar, 3 if the print quality is poor or the substrate is shiny.
- QR and DataMatrix: at least 3 pixels per module, 4–5 for laser-etched direct part marks where contrast is low.
Compute it, don't guess. If your DataMatrix is 8 mm square with 22 modules, that's 0.36 mm per module; at 3 px per module you need 0.12 mm per pixel, so a 100 mm field of view needs roughly 830 px across. A 1440-px sensor gives you headroom; a 640-px webcam does not, and no amount of upsampling or sharpening will invent the modules back.
Motion blur. Blur is line_speed × exposure_time, and the budget is less than one module. A conveyor at 0.5 m/s with a 2 ms exposure smears 1.0 mm — nearly three modules of the code above, i.e. an unreadable mark. Options, in order of preference: strobed illumination with a short pulse (200–500 µs), a global-shutter sensor at a short exposure with enough light to support it, or slowing the line (usually not negotiable). Rolling-shutter sensors also shear moving codes; global shutter is worth the money for anything above walking pace.
Illumination geometry. This is what separates people who have done this before from people who haven't. Diffuse dome or coaxial (on-axis) light for shiny, curved or laser-etched surfaces; low-angle dark-field for embossed or engraved marks with no contrast difference in colour; bar lights at a bounce angle for matte labels. A DataMatrix etched on brushed stainless is essentially invisible under a ring light and trivially readable under dark-field. Fix it with lighting, not with code.
Exposure and gain should be locked, not automatic. Auto-exposure hunting is a top cause of intermittent no-reads, because the frame in which the part is in position is the frame the AE loop decides to change.
3. Preprocessing that helps — and preprocessing that hurts
Modern readers are reasonably good at binarisation on their own. Resist the urge to pile on filters; each one is a place for a knob to drift. The short list of things that genuinely earn their keep:
import cv2
import numpy as np
def prepare(frame):
gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) if frame.ndim == 3 else frame
# 1) Undistort if the lens is wide or the code sits near the frame edge.
# (Use the intrinsics from a proper calibration - see the calibration tutorial.)
# gray = cv2.undistort(gray, K, dist)
# 2) Local contrast for uneven lighting across the field of view.
clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
gray = clahe.apply(gray)
# 3) Gentle upsampling ONLY when modules are marginal (<3 px), never as a fix for optics.
if needs_upsample:
gray = cv2.resize(gray, None, fx=2.0, fy=2.0, interpolation=cv2.INTER_CUBIC)
return gray
What hurts: aggressive unsharp masking (it creates phantom module edges), global cv2.threshold with a fixed value (fails the moment the substrate changes), and heavy denoising (it eats modules on small codes). If you must binarise for a legacy decoder, use cv2.adaptiveThreshold with a block size around 2–3× the module size, or Sauvola-style local thresholding.
For direct part marking, one extra step pays off: localise the mark first, then rectify it. Find candidate regions with a morphological closing along both axes plus contour filtering by area and squareness, take the quad, and warp it to a canonical square with cv2.warpPerspective before handing it to libdmtx. Decoders are much happier with a 200×200 upright mark than with a 30×34 skewed patch buried in a 5 MP frame — and it is far cheaper than running a full-frame search every frame.
4. One decision from many frames
A single frame is a sample, not a verdict. On a moving line you typically get 3–10 frames with the code in view, and the right architecture treats them as votes on one object, not as independent events.
from collections import Counter, defaultdict
class ReadAccumulator:
"""Accumulate votes for one part while it is in the read zone."""
def __init__(self, min_votes=2, zone=None):
self.votes = defaultdict(list) # payload -> list of (frame_idx, quad)
self.min_votes = min_votes
self.zone = zone # optional polygon: reject reads outside it
def add(self, frame_idx, symbology, payload, quad):
if self.zone is not None and not in_zone(quad, self.zone):
return
self.votes[(symbology, payload)].append((frame_idx, quad))
def verdict(self):
if not self.votes:
return ("NO_READ", None, 0)
(sym, payload), evidence = max(self.votes.items(), key=lambda kv: len(kv[1]))
if len(self.votes) > 1:
# Two different payloads in one read window: never guess.
return ("MULTI_READ", None, len(evidence))
if len(evidence) < self.min_votes:
return ("LOW_CONFIDENCE", payload, len(evidence))
return ("READ", payload, len(evidence))
Three rules worth hard-coding:
- Require agreement. Two frames decoding the same payload is dramatically stronger than one. Checksummed symbologies (EAN, Code 128, QR's Reed–Solomon) make a wrong decode rare, but truncated or partially occluded reads happen.
- Never resolve a conflict silently. Two payloads in one read window means two parts in frame, or a neighbouring label leaking into view. That's a fault condition, not a coin flip.
- Validate the payload against a schema, not just the checksum. GS1 Application Identifiers, your own serial format, a UDI structure, expected length, an expected prefix. A structurally valid code from the wrong product family should be rejected loudly. Parse GS1 element strings properly — don't regex the FNC1 separators.
5. Read-rate budget, and what happens on a no-read
This is the part clients care about and the part quotes usually omit. Two separate numbers:
- Read rate — fraction of presented parts that produce a valid read. This is the throughput number: 98% read rate at 60 parts/minute means about 72 manual interventions per hour.
- Misread rate — fraction that produce a wrong payload. This is the safety number, and for serialisation or medical traceability the target is effectively zero. Multi-frame agreement plus schema validation plus checksums is how you get there.
Be explicit that these trade off. Loosening thresholds to lift read rate raises misread risk; tightening for zero misreads means more no-reads. Decide which one the process can absorb, in writing, before commissioning.
Then design the no-read path, which is a process question with a software answer:
- Retry: trigger a second capture with a different exposure/illumination preset. A two-preset alternation (bright/diffuse and dark-field) recovers a surprising share of marginal marks at almost no cost.
- Divert: push the part to a reject or manual-verification lane. Requires a PLC handshake and a defined timeout — decide who wins if vision is late.
- Manual entry: operator keys or hand-scans the code, and the system records that it was manual. Never let a manual entry look like a machine read in the database.
And measure continuously. A read-rate trend line is the earliest warning of a dirty lens, a failing LED, a substrate change from a new label supplier, or a drifting print head. Read rate falling from 99.4% to 97% over two weeks is a maintenance ticket, not a mystery — the same monitoring discipline we describe in testing OpenCV 5 pipelines like software.
6. The audit trail
For serialisation and regulated traceability, "we read it" is not enough; you have to be able to show how. Log one structured record per part, not per frame:
{
"event_id": "01JD7Q...",
"station": "LINE3-READ1",
"trigger_ts": "2026-02-11T09:14:22.418Z",
"verdict": "READ",
"symbology": "DATAMATRIX",
"payload": "(01)09512345678907(21)A1B2C3D4",
"payload_schema": "gs1-ai-v1",
"votes": 4,
"frames_in_window": 6,
"quad_px": [[812,344],[913,349],[908,451],[806,446]],
"module_px": 4.1,
"exposure_us": 320,
"illumination_preset": "darkfield_a",
"decoder": "libdmtx-0.7.8",
"opencv": "5.0.0",
"pipeline_git_sha": "c1f9a4e",
"image_ref": "s3://line3-reads/2026/02/11/01JD7Q....jpg"
}
The fields that get asked for in an audit, every time: the payload, the timestamp, the image that produced it, and the version of the software that decoded it. Retain images for no-reads and misread investigations always; retain read images by sampling plus full retention for a rolling window if storage is a constraint. Note the privacy angle if people are ever in frame — codes on parts are boring, codes on wristbands in a clinic are personal data, and the redaction pipeline in our video anonymisation tutorial belongs in front of the archive.
One more thing: keep the decode idempotent and replayable. If you can re-run the archived frame through the current pipeline and get the same payload, you can answer questions about historical reads without hand-waving. That means pinned OpenCV and decoder versions, and preprocessing parameters recorded in the record rather than living in a config file that someone edited in March.
7. Performance, briefly
Code reading is cheap compared with deep inference, but full-frame multi-symbology search on 5 MP images at 30 fps still isn't free. In rough order of impact:
- Trigger, don't stream. A photo-eye or encoder trigger means you process 6 frames per part instead of 30 frames per second forever. It also fixes the part position, which shrinks the search.
- Search an ROI. If the code is always in the middle third, search the middle third.
cv2.UMator a GPU path is rarely necessary once the ROI is right. - Order your decoders. Try the expected symbology first and short-circuit on success; only fall through to the full battery on failure.
- Cap the retry budget. A per-part deadline (say 120 ms) with a defined verdict on timeout keeps the line deterministic. An unbounded retry loop turns a no-read into a stall, which is a much worse failure.
Budget the whole thing in the same frame-time terms as any other pipeline — the profiling approach in where your frame time actually goes applies unchanged.
Where this fits
Code reading is the least fashionable and most frequently under-scoped part of industrial vision. The library work is a day; the optics, the read-rate budget, the no-read handling and the audit trail are the project. Anyone quoting it without asking about line speed, mark type, substrate finish and what happens on a no-read has not done it before.
SentientSight's OpenCV consultants specify and build unit-level traceability stations — lighting and lens selection, mixed-symbology decode stacks, PLC handshakes, read-rate instrumentation and audit-ready logging — including rescues of stations that read fine in the lab and not on the line. If you have a mark you need read reliably, get in touch.