DEV Community: Xiao Ling

How to Generate a Boarding Pass Barcode in JavaScript (IATA BCBP)

Xiao Ling — Thu, 24 Sep 2026 06:35:15 +0000

The barcode on a boarding pass carries a payload defined by IATA Resolution 792 — an IATA Bar Coded Boarding Pass (BCBP). It is a fixed-order layout with mandatory and conditional sections, strictly sized fields, and two nested hexadecimal size fields that a reader has to follow to find where anything ends.

That structure is what makes a boarding pass worth generating rather than typing text into a generic QR generator. A payload is only useful as a test case if it is well formed — correct widths, correct padding, consistent size fields — and if you know what the scanner should return, so that a wrong or missing field stands out.

This article builds that generator: it composes a BCBP payload, signs the security section (items 25–30) with WebCrypto so an edited field can be caught later, renders the result as PDF417, Aztec Code, QR Code or Data Matrix on a printed or mobile pass preview, and prints the field-by-field result a conformant scanner should return.

What you'll build: a browser-side BCBP generator — the Resolution 792 encoder, the nested size fields, one-to-four flight legs, four symbologies, a security section that re-signs itself whenever a field changes, a canvas pass preview that marks what Randomise changed, and a self-check that parses the page's own output.

Online demo

Demo Video

Prerequisites

Node.js or any static file server for local development. The page itself has no build step.
A browser with an HTML5 canvas — the symbol and the preview are both drawn client-side.
bwip-js (BWIPP compiled to JavaScript), loaded from a CDN. It is the only third-party dependency.

Step 1: Lay out the BCBP field table

Start by writing down the layout, because every later step depends on these widths. The unique mandatory section is 23 characters:

Pos	Len	Item	Field
1	1	1	Format code, always `M`
2	1	5	Number of legs encoded (1–4)
3	20	11	Passenger name, `SURNAME/GIVEN NAME`, left-justified
23	1	253	Electronic ticket indicator, `E` or blank

Then a 35-character block that repeats for every leg:

Pos	Len	Item	Field
24	7	7	Operating carrier PNR
31	3	26	From airport (IATA)
34	3	38	To airport (IATA)
37	3	42	Operating carrier designator
40	5	43	Flight number, 4 digits + optional letter
45	3	46	Date of flight, Julian day of year
48	1	71	Compartment code
49	4	104	Seat number, 3-digit row + letter
53	5	107	Check-in sequence number
58	1	113	Passenger status

Positions 59–60 are item 6, the size field. Encode the fixed part first, with the padding rules spelled out:

function encodeMandatory(r, leg, index, variableSize) {
  var out = '';
  if (index === 0) {
    out += FORMAT_CODE;                                 // item 1
    out += String(r.legs.length);                       // item 5
    out += padRight(r.passengerName, SIZE.passengerName, ' '); // item 11
    out += r.electronicTicket ? 'E' : ' ';              // item 253
  }
  out += padRight(leg.pnr, 7, ' ');                     // item 7
  out += padRight(leg.from, 3, ' ');                    // item 26
  out += padRight(leg.to, 3, ' ');                      // item 38
  out += padRight(leg.carrier, 3, ' ');                 // item 42
  out += encodeFlightNumber(leg.flightNumber);          // item 43
  out += padLeft(leg.julianDate, 3, '0');               // item 46
  out += padRight(leg.compartment, 1, ' ');             // item 71
  out += encodeSeat(leg.seat);                          // item 104
  out += encodeSequence(leg.sequence);                  // item 107
  out += padRight(leg.passengerStatus, 1, ' ');         // item 113
  out += hex2(variableSize);                            // item 6
  return out;
}

The padding rules are the part that catches people out. Alphanumeric items are left-justified with trailing blanks; numeric items carry leading zeros. The seat and the sequence number look similar but pad differently:

function encodeSeat(value) {
  var v = upper(value).replace(/\s+/g, '');
  if (!v) return '    ';
  if (v === 'INF') return 'INF ';
  var m = /^(\d{1,3})([A-Z]{1,2})$/.exec(v);
  if (!m) {
    throw new Error('Seat "' + value
      + '" is not valid: use a row and a letter (18A), or INF for an infant on a separate pass.');
  }
  return m[1].padStart(3, '0') + m[2];
}

function encodeSequence(value) {
  var d = digitsOnly(value);
  if (!d) return '     ';
  if (d.length >= 5) return d.slice(0, 5);
  /* The IATA examples print four digits followed by a blank, so pad to four
     and leave the fifth position as the guide's trailing space. */
  return padRight(d.padStart(4, '0'), 5, ' ');
}

Seat 18A becomes 018A — leading zeros. Sequence 42 becomes 0042 — leading zeros and a trailing blank. The official Resolution 792 examples spell it that way (0025, 0027), and a scanner has to cope with that exact spelling, so the generator reproduces it rather than choosing the tidier-looking right-aligned form.

Step 2: Pack the conditional sections in fixed order

The variable field holds three things, one after another: the once-per-pass data, the once-per-leg data, and the carrier's own space. Both conditional blocks are a fixed sequence of slots with known widths, which is what lets a reader parse them without tags:

var UNIQUE_SLOTS = [
  { code: 'passengerDescription', label: 'Passenger description', item: 15, len: 1 },
  { code: 'checkinSource', label: 'Source of check-in', item: 12, len: 1 },
  // ... the rest, in the order listed below
];

var REPEATED_SLOTS = [
  { code: 'airlineNumericCode', label: 'Airline numeric code', item: 142, len: 3, numeric: true },
  // ... the rest, in the order listed below
];

The complete once-per-pass block (item 10):

Item	Len	Field
15	1	Passenger description
12	1	Source of check-in
14	1	Source of issuance
22	4	Date of issue — last digit of the year plus the Julian day
16	1	Document type
21	3	Airline designator of the issuer
23	13	Baggage tag; up to three, so up to 39 characters
31	13	Non-consecutive baggage tag
32	13	Second non-consecutive baggage tag

And the once-per-leg block (item 17):

Item	Len	Field
142	3	Airline numeric code
143	10	Document form / serial number
18	1	Selectee indicator
108	1	International documentation verification
19	3	Marketing carrier designator
20	3	Frequent flyer airline
236	16	Frequent flyer number
89	1	ID / AD indicator
118	3	Free baggage allowance
254	1	Fast track

Packing then means concatenating slots until the last non-empty one, and dropping only the trailing empties:

function packSlots(slots, values) {
  var last = -1;
  for (var i = 0; i < slots.length; i++) {
    if (str(values[slots[i].code]).trim() !== '') last = i;
  }
  if (last === -1) return '';
  var out = '';
  for (var j = 0; j <= last; j++) {
    var slot = slots[j];
    var value = str(values[slot.code]);
    out += slot.numeric ? padLeft(value, slot.len, '0') : padRight(value, slot.len, ' ');
  }
  return out;
}

Because the block is positional, a field can only be present if every field before it is present too. One consequence is worth surfacing in the UI: if a user fills in a later item and leaves an earlier one blank, that blank still gets packed, with its own padding character — data the user never entered. Writing a frequent flyer number therefore forces the free baggage allowance in front of it to appear as blanks.

The validator looks for that gap and reports it instead of silently inventing the filler:

    /* Interior gaps: the packed block will contain a filler the user did not
       type. Report it instead of silently inventing data. */
    var filled = firstInteriorGap(UNIQUE_SLOTS, {
      passengerDescription: r.passengerDescription,
      checkinSource: r.checkinSource,
      // ... one entry per slot, in the same order as UNIQUE_SLOTS
    });
    if (filled) {
      problems.push('The optional fields are written in a fixed order, so "' + filled
        + '" cannot be included while an earlier optional field is left out.');
    }

One block remains at the very end of the variable field: the security section, items 25–30. It is not typed into the form — it is signed — and Step 8 covers it.

Step 3: Write the size fields

This is the step that breaks generated passes. The variable field is not self-delimiting; it is measured by the field in front of it, and it contains two smaller size fields of its own.

Writing it is easiest if you assemble the bytes first and then take their length:

var blocks = r.legs.map(function (leg, index) {
  var repeated = encodeRepeated(leg);
  var airlineUse = leg.airlineUse;
  var body;
  if (index === 0) {
    /* A "version 0" pass predates the version marker. Item 6 is then 00 and
       nothing at all follows it — not even the item 17 size field. */
    if (r.version === '0') {
      body = '';
    } else {
      var unique = encodeUnique(r);
      body = '>' + r.version + hex2(unique.length) + unique
        + hex2(repeated.length) + repeated + airlineUse;
    }
  } else {
    body = hex2(repeated.length) + repeated + airlineUse;
  }
  /* item 6 counts everything that follows it, including the nested size
     fields: item 8 + item 9 (2), item 10's two hex digits (2) and item 17's
     two hex digits (2). Taking the length of the assembled block is the one
     definition that cannot drift out of step with the bytes. */
  return { size: body.length, body: body };
});

Reading the assembled block back makes the arithmetic self-evident:

> plus the version digit — 2 bytes (items 8 and 9)
the item 10 size field — 2 bytes
the unique conditional data
the item 17 size field — 2 bytes
the repeated conditional data
the airline's own data (item 4), which is whatever remains

For the official single-leg example with no conditional data, that gives item 6 = 06:

M1DESMARAIS/LUC       EABC123 YULFRAAC 0834 226F001A0025 106>60000
                                                              ^^ item 6 = 6 bytes
                                                                >60000  ->  '>', '6', item10='00', item17='00'

A later leg has no unique block, so its size field is just the repeated size plus the carrier data:

body = hex2(repeated.length) + repeated + airlineUse;

The page shows the assembled payload so you can count the bytes yourself:

Step 4: Support more than one leg

The mandatory block repeats per leg, but the 23-character header does not — the passenger name is written once. The PNR, however, sits inside the repeating block, so a two-leg pass can carry a different locator on each leg. The official Resolution 792 two-leg example does exactly that:

M2DESMARAIS/LUC       EAB12C3 YULFRAAC 0834 326J003A0027 167>5321WW1325BAC ... 4PCYLX58ZDEF456 FRAGVALH 3664 327C012C0002 12E2A0140987654321 ...
                     ^^^^^^ PNR on leg 1                                 ^^^^^^ PNR on leg 2

So the record keeps the PNR per leg, and the form propagates an edit to every leg that is still carrying the previous value:

els.pnr.addEventListener('input', function () {
  var previous = state.lastRecordPnr || '';
  var next = els.pnr.value;
  legEditors().forEach(function (editor) {
    var el = editor.querySelector('[data-field="pnr"]');
    if (el && (el.value === previous || el.value === '')) el.value = next;
  });
  state.lastRecordPnr = next;
  schedule();
});

One thing to watch: the free baggage allowance (item 118) is also per leg, so a second leg with no allowance omits it — while the PNR, in the same block, still appears. A two-leg pass is a good test of your size fields, because there are three of them to get wrong instead of one.

Step 5: Render the symbol with bwip-js

The payload is a plain string, so rendering is the easy part. Map each symbology to its BWIPP encoder name and a module size:

var FORMATS = {
  pdf417:     { bcid: 'pdf417',     label: 'PDF417',      scale: 5, rowHeight: 5, linear: true, minVersion: 1 },
  azteccode:  { bcid: 'azteccode',  label: 'Aztec Code',  scale: 7, minVersion: 7 },
  qrcode:     { bcid: 'qrcode',     label: 'QR Code',     scale: 7, minVersion: 7 },
  datamatrix: { bcid: 'datamatrix', label: 'Data Matrix', scale: 7, minVersion: 7 }
};

function renderSymbol(payload, formatId) {
  var format = FORMATS[formatId];
  var options = {
    bcid: format.bcid,
    text: payload,
    scale: format.scale,
    includetext: false,
    /* A quiet zone is part of the specification: a symbol that touches its
       own border is materially harder for a scanner to lock onto. */
    paddingwidth: 4,
    paddingheight: 4
  };
  if (format.linear) options.height = format.rowHeight;

  var canvas = document.createElement('canvas');
  return new Promise(function (resolve, reject) {
    var pending;
    try {
      pending = window.bwipjs.toCanvas(canvas, options);
    } catch (error) {
      reject(error);
      return;
    }
    if (pending && typeof pending.then === 'function') {
      pending.then(function () { resolve(canvas); }, reject);
    } else {
      resolve(canvas);
    }
  });
}

minVersion is not cosmetic. Aztec Code, QR Code and Data Matrix were only added to the standard for printed passes in version 7, so picking one of them silently sets the version field to 7. A payload that claims version 6 while travelling in a QR Code claims a combination the standard did not allow.

Also worth knowing: a symbol exported from a canvas is transparent by default. toCanvas leaves the background unset, so a PNG saved straight from it carries an alpha channel. Handed those pixels as RGBA, a reader treats (0,0,0,0) as black, which floods the quiet zone with ink and hides the symbol. Fill the canvas white first, or pass backgroundcolor: 'FFFFFF' to the encoder.

Step 6: Draw a pass preview

A preview that looks like a boarding pass is easier to sanity-check than a bare symbol: you can see at a glance that the name, route and seat are the ones you typed. The drawing is ordinary Canvas 2D; the parts worth calling out are the watermark and the symbol panel:

function drawSpecimen(ctx, x, y, size) {
  ctx.save();
  ctx.translate(x, y);
  ctx.rotate(-Math.PI / 10);
  ctx.font = 'bold ' + size + 'px ' + FONT;
  ctx.fillStyle = 'rgba(200, 16, 46, 0.09)';
  ctx.textAlign = 'center';
  ctx.textBaseline = 'middle';
  ctx.fillText('SPECIMEN', 0, 0);
  ctx.restore();
}

The symbol is drawn into a tinted panel and scaled to fit, which keeps it away from the pass border — the same quiet-zone reasoning as paddingwidth above:

var availW = panelW - inner * 2;
var availH = (panelBottom - panelTop) - labelH - inner;
var scale = Math.min(availW / symbol.width, availH / symbol.height, 1);
var drawW = Math.max(1, Math.round(symbol.width * scale));
var drawH = Math.max(1, Math.round(symbol.height * scale));
ctx.imageSmoothingEnabled = scale < 1;
ctx.drawImage(symbol,
  panelX + (panelW - drawW) / 2,
  panelTop + labelH + (availH - drawH) / 2,
  drawW, drawH);

The same payload also renders as a mobile wallet pass, which is the layout a phone would show:

Marking what Randomise changed

A button that rewrites a dozen controls at once is disorienting: nothing tells you which values moved, so a field you had set deliberately looks the same as one that was overwritten. Snapshotting the form before the rewrite and comparing after fixes that in a few lines:

function highlightChanges(before) {
  if (!before) return 0;
  var changed = 0;

  function mark(el, previous) {
    if (!el || previous === undefined) return;
    if (previous === el.value) {
      el.classList.remove('just-changed');
      return;
    }
    flash(el);
    changed++;
  }

  HIGHLIGHT_FIELDS.forEach(function (id) { mark(els[id], before[id]); });
  legEditors().forEach(function (editor, index) {
    HIGHLIGHT_LEG_FIELDS.forEach(function (name) {
      mark(editor.querySelector('[data-field="' + name + '"]'),
        before['leg' + index + '.' + name]);
    });
  });

  return changed;
}

function flash(el) {
  el.classList.remove('just-changed');
  /* Reading offsetWidth flushes the removal, so the animation replays even
     when the same control changes on two consecutive clicks. */
  void el.offsetWidth;
  el.classList.add('just-changed');
}

Two details are worth keeping:

The reflow. Removing and re-adding the class in the same frame does not restart a CSS animation — the browser coalesces the two mutations. Reading offsetWidth between them forces a style recalculation, which is the cheapest way to make the animation replay on every click.
The reduced-motion fallback. Skipping the animation entirely would remove the information, not just the motion, so the media query keeps a static colour instead:

@media (prefers-reduced-motion: reduce) {
    .form-control.just-changed {
        animation: none;
        background-color: #fff3e2;
        border-color: var(--dy-orange);
    }
}

The count of changed controls is worth reporting too — it turns "did that do anything?" into a number:

analytics.action('randomise', {
  style: state.style,
  format: state.format,
  legs: legs,
  changed: changed
});

Step 7: Prove the payload by parsing it back

Testing a scanner needs a generator you can verify. The most direct check is to parse your own output with the same code the scanner will use: write the decoder alongside the encoder, and treat the parse result as the test oracle rather than restating the form.

Because the two directions share one field table, the table above is read back from the bytes. That also makes a round-trip test possible: parse a payload, rebuild the record, re-encode, and require the bytes to come back identical.

function selfTest() {
  var results = SELF_TEST_VECTORS.map(function (vector) {
    var decoded = decode(vector.payload);
    var problems = [];
    if (!decoded.ok) {
      problems.push(decoded.error);
    } else {
      /* The round trip has to hold for the examples too: parse, rebuild the
         record, re-encode, and the bytes must come back identical. */
      try {
        var reencoded = encode(toRecord(decoded));
        if (reencoded !== vector.payload) {
          problems.push('re-encode differs from the original payload');
        }
      } catch (error) {
        problems.push('re-encode failed: ' + error.message);
      }
    }
    return { name: vector.name, passed: problems.length === 0, problems: problems };
  });
  return {
    passed: results.filter(function (r) { return r.passed; }).length,
    failed: results.filter(function (r) { return !r.passed; }).length,
    results: results
  };
}

Running that against the official Resolution 792 examples is what turns "it looks right" into a check. On page load the demo logs:

[boarding-pass] BCBP codec self-test: 4/4 IATA Resolution 792 examples round-trip

The four vectors cover the awkward cases rather than the happy path: a single leg with no conditional data (where item 6 is 00 and nothing follows it — not even the item 17 size field), a single leg with unique, repeated and security data, a two-leg pass with a different PNR per leg, and a version 6 pass whose size fields are present but zero.

The structural checks report the same thing to the user:

Step 8: Sign the security section automatically

The final block of the variable field is the security section — items 25–30, written once after the last leg. ^ marks the beginning (item 25), one character carries the type of security data (item 28), two hexadecimal characters carry the byte length of item 30 (item 29), and everything after that is the data itself:

...0025 106>60000^158iTRJaYu4CyZpYnRlKocV5gzDJEwsyeDmxpRo4d2gUl99ymfpHkIKySSyj8H1gv0RqVtBV5PzRhMP9XuYGILrZA==
                  ^ item 25: '^' marks the beginning of the security section
                   1 item 28: type of security data
                    58 item 29: two hex digits — 58 = 88 bytes of item 30
                      iTRJ… item 30: the signature itself, 88 base64 characters

Signing it raises one structural problem: item 30 is inside the payload it would sign, and a signature cannot cover itself. The fix is to sign everything up to the end of the last leg, then append items 25–30 afterwards — and for the verifier to strip that same section off before checking, so both sides always compare the same bytes. One helper does the trimming for both directions:

/** The payload with its security section removed — the bytes that get signed. */
function securityBase(payload) {
  var text = str(payload);
  var parsed = decode(text);
  if (!parsed.ok || !parsed.security) return text;
  /* decoded.security.offset points at the type character (item 28); the '^'
     marking item 25 sits immediately before it. */
  return text.slice(0, parsed.security.offset - 1);
}

The second problem is encoding. ECDSA P-256 returns a raw 64-byte r‖s signature; hex-encoded that is 128 characters, and validate() puts a 100-character ceiling on item 30 — a hex signature is rejected before any key is involved. Base64 of the same bytes is 88 characters, comfortably inside the limit, so that is what item 30 carries. The signing itself is WebCrypto:

function signSecurityData(payload, privateKeyBase64) {
  var subtle = subtleCrypto();
  if (!subtle) return Promise.resolve(null);
  var data = new TextEncoder().encode(securityBase(payload));
  return importSigningKey('pkcs8', privateKeyBase64, ['sign'])
    .then(function (key) { return subtle.sign(SIGN_PARAMS, key, data); })
    .then(function (signature) { return base64FromBytes(new Uint8Array(signature)); })
    .catch(function () { return null; });
}

generate() then signs on every pass: encode the record with security: null, sign those bytes with the demo private key, and write the result back into the two security fields:

function autoSign(record) {
  var base;
  try {
    base = window.Bcbp.encode(Object.assign({}, record, { security: null }));
  } catch (error) {
    return Promise.resolve(null); /* renderPayload() reports the real error */
  }
  return window.Bcbp.signSecurityData(base, DEMO_PRIVATE_KEY).then(function (signature) {
    if (!signature) return null;
    els.security_type.value = SECURITY_TYPE;
    els.security_data.value = signature;
    return signature;
  });
}

The demo private key ships with the page, which is the one thing a production issuer must never do: that key belongs on the issuing server, only the signature travels, and readers get the public half — exactly what the companion scanner verifies against. WebCrypto also needs a secure context, so the page must be served from http://localhost or https; when it is not, the pass is left unsigned as typed and the hint under the field says so.

Because signing runs on every change, a keystroke in either security field would be overwritten immediately — so that keystroke latches manual mode instead: the value stays exactly as typed and nothing re-signs until Re-sign or Randomise is pressed.

/* Item 30 is machine-filled, so a keystroke in either security field is a
   deliberate hand edit: latch manual mode, keep the value as typed (even
   if it is empty) and stop re-signing until Re-sign or Randomise. */
function securityEdited() {
  state.securityManual = true;
  schedule();
}
els.security_type.addEventListener('input', securityEdited);
els.security_type.addEventListener('change', securityEdited);
els.security_data.addEventListener('input', securityEdited);
els.security_data.addEventListener('change', securityEdited);

After each render the page verifies its own output against the public key and reports the verdict in the hint: green for a signature that matches, red for one that does not (calling out the hand edit), plain when items 25–30 are absent. Re-signing without changing anything still produces a different value — ECDSA draws a fresh random nonce for every signature — but verification always strips back to the same base, so every one of those signatures checks out.

Source Code

Get the complete sample project source code on GitHub

How to Generate GS1 Barcodes in JavaScript for Scanner Testing

Xiao Ling — Fri, 18 Sep 2026 01:58:01 +0000

If you have written a GS1 parser, you need something to test it with.

What you'll build: a browser-side GS1 generator that composes a validated element string from application identifiers, calculates GTIN/SSCC check digits, recommends the symbology a real supply chain would use, renders a test label on an HTML5 canvas, and exports the PNG together with the table of values a scanner should report.

Online Demo

Demo Video

Step 1: Make the AI Table the Model

Everything else is derived from this table, so it is worth getting right first. Each entry needs four things: the code, a name, a length rule, and a way to produce a valid sample.

const AI_LIST = [
  { ai: '01', title: 'GTIN', kind: 'gtin', fixed: 14, group: 'Retail',
    sample: () => withCheckDigit('0' + DEMO_PREFIX + digits(5)) },

  { ai: '10', title: 'BATCH/LOT', kind: 'text', max: 20, group: 'Traceability',
    sample: () => 'LOT-' + digits(5) },

  { ai: '17', title: 'EXPIRATION DATE', kind: 'date', fixed: 6, group: 'Dates',
    sample: () => sampleDate(90, 700) }
];

The fixed/max distinction is not metadata — it is what tells the encoder whether a separator is needed after this element, and it is what lets a parser recover a payload whose separators were stripped.

The sample() function earns its place too. Every AI in the table can produce a value that passes its own validation, so "Randomize data" is always available and a half-built payload is never blocked on typing a plausible SSCC by hand.

One detail that matters more than it sounds: when Randomize data replaces the values, the fields that changed are marked for a moment.

Random sample values are all digit soup — 00950600403582 and 00950600786614 look equally arbitrary — so without the marker a click reads as "nothing happened", which is exactly the bug report this page got. The marker is a CSS animation on the row that fades out on its own and is removed from the DOM after 1.4 s, and it respects prefers-reduced-motion by dropping the animation while keeping the colour change, because the colour is the information.

Step 2: Calculate Check Digits, Don't Ask for Them

function checkDigit(data) {
  let sum = 0, weight = 3;
  for (let i = data.length - 1; i >= 0; i--) {
    sum += Number(data.charAt(i)) * weight;
    weight = weight === 3 ? 1 : 3;
  }
  return String((10 - (sum % 10)) % 10);
}

function withCheckDigit(dataWithoutCheck) {
  return dataWithoutCheck + checkDigit(dataWithoutCheck);
}

One routine covers GTIN, SSCC, GLN and GSRN, because they all use the same mod-10 scheme. Completing the digit automatically is what makes a generated image a fair test: a scanner that verifies check digits would correctly reject a hand-typed GTIN, and you would spend the afternoon debugging the scanner.

Step 3: Let the Payload Pick the Symbology

Twelve symbologies can carry GS1 data, and they are not interchangeable:

Symbology	Kind	What it can carry
GS1 DataBar Omnidirectional	1D	GTIN, full-height retail symbol
GS1 DataBar Truncated	1D	GTIN, shorter bars for small packaging
GS1 DataBar Stacked / Stacked Omnidirectional	1D	GTIN, split across two rows
GS1 DataBar Limited	1D	GTIN starting with 0 or 1, smallest DataBar
GS1 DataBar Expanded / Expanded Stacked	1D	GTIN plus up to 74 more characters
GS1 DataMatrix	2D	Any element string
GS1 QR Code	2D	Any element string, consumer readable
GS1-128	1D	Any element string, logistics default
ITF-14	1D	GTIN-14 only
EAN-13	1D	GTIN-13 only

The recommendation is a small decision function over the payload's AIs, and it is worth having because it encodes the field's own habits:

function decide(rows) {
  const ais = rows.map((row) => row.ai);
  const extra = ais.filter((ai) => ai !== '01');

  if (ais[0] === '00') {
    return { symbology: 'gs1_128',
      reason: 'An SSCC is 18 digits with no GTIN, so a linear GS1-128 is the carrier.' };
  }
  if (!extra.length) {
    return { symbology: /^\d{13}$/.test(rows[0].value) ? 'ean13' : 'databaromni',
      reason: 'A GTIN plus nothing else is exactly what DataBar Omnidirectional encodes.' };
  }
  if (ais.includes('3103') || ais.includes('3922') || ais.includes('30')) {
    return { symbology: 'databarexpandedstacked',
      reason: 'Weight and price make the element string too long for one row, so it stacks.' };
  }
  return { symbology: 'gs1datamatrix',
    reason: ais.length + ' elements is dense enough that a 2D symbol is the right choice.' };
}

Validation is then relative to the chosen symbol, which is the only way it can be meaningful: a GTIN plus a batch is perfectly encodable in DataBar Expanded and completely unencodable in DataBar Omnidirectional.

And every message that diagnoses a problem carries the change that resolves it. "A DataBar, ITF-14 or EAN-13 symbol carries the GTIN and nothing else" is followed by a Switch to GS1 DataMatrix button; a wrong check digit offers the corrected digit; a serial number with no trade item offers Add AI 01; a price in a currency with no quantity offers Add AI 30.

The payload model carries the remedies as data, so the UI never has to guess:

// A value longer than its AI allows, a bad check digit, a symbology that cannot
// carry the payload, a missing partner AI — each one ships the fix with the message.
{ level: 'error', ai: '01', message: 'Check digit should be 2.',
  fix: { kind: 'set-value', ai: '01', value: '09506000134352', label: 'Correct the check digit' } }

{ level: 'error', ai: null,
  message: 'A DataBar, ITF-14 or EAN-13 symbol carries the GTIN and nothing else. 3 extra elements cannot be encoded.',
  fix: { kind: 'set-symbology', symbology: 'gs1datamatrix', label: 'Switch to GS1 DataMatrix' } }

The pairing rules are worth stating outright, because the encoder's own message ("One of more requisite AIs for AI (21) are missing: 01 OR 03 OR 8006") arrives too late to be actionable:

AI	needs	why
`21` serial number	`01`, `03` or `8006`	a serial identifies a unit, so it needs the item it belongs to
`393x` price in a currency	`30`, or a `31nn`/`32nn`/`35nn`/`36nn` measure	a unit price needs the quantity it is a price of

Step 4: Feed the Encoder the AI Syntax

bwip-js is the encoder, and its GS1 symbologies accept the bracketed notation directly — the same string GS1 prints under a symbol as the human readable interpretation:

await bwipjs.toCanvas(canvas, {
  bcid: 'gs1datamatrix',
  text: '(01)00950600037152(17)270207(10)LOT-45727(21)SN96136133',
  scale: 6,
  includetext: false
});

BWIPP works out where the FNC1 bytes belong from the AI table: after 10, which has no fixed length, and not after 17, which does. That is a great deal of correctness to get for free, and it is the reason the payload model submits to the encoder as an AI list rather than as a hand-built byte string.

Two symbologies do not take AI syntax, and getting them wrong produces a silently different product:

function toEncoderInput(rows, symbologyId) {
  const gtin = (rows.find((row) => row.ai === '01') || {}).value || '';

  if (symbologyId === 'ean13') {
    // A GTIN-14 with packaging indicator 0 is a GTIN-13 with a leading zero.
    // Any other indicator has no GTIN-13 equivalent, and printing one anyway
    // would produce a symbol that decodes to a different product.
    if (gtin.length === 14 && gtin.charAt(0) !== '0') {
      return { error: 'EAN-13 carries a GTIN-13 only.' };
    }
    return { bcid: 'ean13', text: (gtin.length === 14 ? gtin.slice(1) : gtin).slice(0, 12) };
  }

  if (symbologyId === 'itf14') {
    // Hand over the GTIN as it stands. Trimming it to 13 digits would make the
    // encoder compute a *second* check digit over data that already contained
    // one, and the symbol would decode to a different number.
    return { bcid: 'itf14', text: gtin };
  }

  return { bcid: symbologyId, text: toHRI(rows) };   // the AI syntax form
}

That ITF-14 comment is a bug I shipped and then found. Passing 13 digits to an ITF-14 encoder looks reasonable and is wrong: the encoder appends a check digit, so a GTIN that already ended in one gets a second one computed over it. The generated label decoded cleanly to the wrong number, which is the worst kind of test fixture — it fails a scanner that is working perfectly.

Step 5: Render a Label a Camera Can Actually Read

A symbol floating on a white rectangle is not what a camera sees. Draw the thing that gets scanned: brand, product name, the identifiers in human-readable form, the symbol, and the HRI beneath it.

The layout detail that matters is the symbol band: it spans the full label width, because a logistic GS1-128 with five data elements is a lot of bars and squeezing it into a narrow column is how a test label ends up undecodable.

The size detail matters more. When a symbol is too wide for its frame, re-encode it at a smaller whole-number module size; do not scale the finished image:

function step(passesLeft) {
  return attempt().then((canvas) => {
    if (fits(canvas) || scale <= 1 || passesLeft <= 0) return canvas;
    const budget = Math.min(maxWidth / canvas.width, maxHeight / canvas.height);
    const next = Math.max(1, Math.floor(scale * budget));
    if (next >= scale) return canvas;
    scale = next;
    return step(passesLeft - 1);
  });
}

Scaling a linear symbol by a fraction blurs the module edges, and a symbol whose modules are no longer resolvable cannot be decoded however good the scanner is. Keeping the module size an integer number of pixels keeps every bar edge crisp. When even one pixel per module overflows the frame, the honest thing is to say so rather than hand out a weak image:

Rendered GS1-128 · symbol 1010 × 142 px · export 1200 × 800 px
· module size reduced to 2 px to fit the label

For a decoder test, the same page exports the bare symbol with its quiet zone and no label furniture at all.

Step 6: Print the Expected Result

This is the part that turns a picture into a test. For the payload that is on screen, the page states:

the element string a decoder should return, with | marking each position where an FNC1 byte has to appear;
the human readable interpretation;
every application identifier with the value the scanner should report, including the check-digit verdict;
and the GS1 Digital Link.

A | only appears where a variable-length element needs terminating. Drawing one after every element would be easier to read and wrong: a fixed-length element needs no terminator, and showing one invites the reader to think it does.

Source Code

Get the complete sample project source code on GitHub

How to Generate an AAMVA Driver's License Barcode in JavaScript for Scanner Testing

Xiao Ling — Fri, 11 Sep 2026 03:10:27 +0000

If you are building a driver's license scanner, the hardest part is finding documents to test it with. Real licenses are personal data, so you cannot put them in a test suite or commit them to a repository. And the sample images you can find online cover one or two jurisdictions on a single version of the AAMVA standard — out of 71 jurisdictions and three versions.

So the differences between cards go untested: a card from another jurisdiction has a different field set and jurisdiction code, a v9 card carries different mandated data elements than a v10 card, and an ID card uses a different subfile type than a DL card. One sample image is evidence for one combination out of hundreds, and the gaps only surface as missing or wrong fields once real cards arrive.

You can generate that test data yourself, because the AAMVA barcode is plaintext. It is a byte layout, not a signed blob, so a generator needs no keys, no cards and no special encoder: assemble the payload, encode it as a PDF417 symbol with bwip-js, and draw it on a canvas card. This article does that for all 71 jurisdictions AAMVA assigns an Issuer Identification Number to — 50 US states, the District of Columbia, 5 US territories, 13 Canadian provinces and territories, and 2 Mexican states — and then decodes the result with Dynamsoft Barcode Reader to prove the round trip works. The payoff is a card you can generate on demand, containing no personal information, for any of 71 jurisdictions × 3 versions of the standard × 2 document types — and re-create whenever a test starts failing.

What you'll build: a browser-side generator that takes a jurisdiction and a set of cardholder fields, assembles a specification-compliant AAMVA payload, renders it as a PDF417 symbol on a printable card face and back, and exports the whole sheet as a PNG. Then you'll feed that PNG back into a scanner to confirm the fields survive the trip.

Online Demo

The finished generator runs at codepool/demos/driver-license-generator — no install and no license key, and nothing you type leaves the browser. Read the cards it produces with the matching driver's license scanner demo, which also runs entirely in the browser.

Prerequisites

A browser with canvas support. The generator needs no SDK and no license key.
A Dynamsoft Capture Vision license if you want to decode the generated card yourself. Get a 30-day free trial license.

Step 1: Lay Out the AAMVA Payload

Everything rests on getting the byte layout right, so start from the specification rather than from a sample card. The header is fixed-width and position-dependent:

Field	Size	Example	Notes
Compliance indicator	1	`@`	Always `@`
Data element separator	1	`\n`	Terminates each data element
Record separator	1	`\x1e`
Segment terminator	1	`\r`	Ends each subfile
File type	5	`ANSI`	Note the trailing space
Issuer Identification Number	6	`636014`	California
AAMVA version number	2	`10`	v8 = 2013, v9 = 2016, v10 = 2020
Jurisdiction version number	2	`01`	Per-jurisdiction revision
Number of entries	2	`01`	Number of subfiles that follow

Each subfile designator is ten characters — the subfile type, then a four-digit offset and a four-digit length, both zero-padded. Build the payload only after you know the header length, because the offset depends on it:

var LF = '\n';
var RS = '\x1e';
var CR = '\r';

function pad(value, length) {
  var s = String(value);
  while (s.length < length) s = '0' + s;
  return s;
}

function buildPayload(sample, aamvaVersion, jurisdictionVersion) {
  var elements = [];
  function add(code, value) {
    if (value === undefined || value === null || value === '') return;
    elements.push(code + value);
  }

  add('DAQ', sample.licenceNumber);      // licence number
  add('DCS', sample.lastName);           // family name
  add('DDE', 'N');                       // family name truncation
  add('DAC', sample.firstName);          // first name
  add('DDF', 'N');
  add('DAD', sample.middleName);
  add('DDG', 'N');
  add('DCA', sample.vehicleClass);       // jurisdiction vehicle class
  add('DCB', sample.restrictions);
  add('DCD', sample.endorsements);
  add('DBD', mmddyyyy(sample.issueDate)); // issue date
  add('DBB', mmddyyyy(sample.birthDate)); // date of birth
  add('DBA', mmddyyyy(sample.expiryDate));// expiry date
  add('DBC', sample.sexCode);            // 1 = male, 2 = female
  add('DAU', sample.height);             // e.g. '068 in'
  add('DAY', sample.eyeColor);
  add('DAZ', sample.hairColor);
  add('DAG', sample.street);
  add('DAI', sample.city);
  add('DAJ', sample.jurisdictionCode);
  add('DAK', sample.postal);
  add('DCF', sample.documentDiscriminator);
  add('DCG', sample.countryCode);         // USA / CAN / MEX
  add('DDA', 'F');                        // compliance type
  add('DDB', mmddyyyy(sample.issueDate)); // card revision date
  add('DDD', '1');
  add('DAW', sample.weightLbs);

  var subfile = sample.cardType + elements.join(LF) + CR;   // 'DL' or 'ID'

  var entryCount = 1;
  var header = '@' + LF + RS + CR + 'ANSI '
    + sample.iin + aamvaVersion + jurisdictionVersion + pad(entryCount, 2);

  // The subfile starts after the header and all designators.
  var offset = header.length + 10 * entryCount;
  var designator = sample.cardType + pad(offset, 4) + pad(subfile.length, 4);

  return header + designator + subfile;
}

function mmddyyyy(date) {
  return pad(date.getMonth() + 1, 2) + pad(date.getDate(), 2) + date.getFullYear();
}

With a one-subfile payload the offset therefore always evaluates to 31, and subfile.length includes the leading DL and the trailing \r. Add an assertion while you develop — off-by-one errors here produce a payload that looks plausible but decodes to nothing.

Step 2: Cover Every AAMVA Jurisdiction

A generator is only useful if it can produce the jurisdictions you need to test. AAMVA publishes the Issuer Identification Numbers it assigns, which makes the table finite and checkable: 71 entries covering the US, Canada and two Mexican states.

// code, name, iin, country, sample city, postal, licence-number pattern
var JURISDICTIONS = [
  ['CA', 'California', '636014', 'USA', 'Sacramento', '95814', 'A#######'],
  ['TX', 'Texas',    '636015', 'USA', 'Austin',     '78701', '########'],
  ['NY', 'New York', '636001', 'USA', 'Albany',     '12207', '#########'],
  ['ON', 'Ontario',  '636012', 'CAN', 'Toronto',    'M5H 2N1', 'A####-#####'],
  ['BC', 'British Columbia', '636028', 'CAN', 'Victoria', 'V8W 1A1', '########'],
  // ... 66 more
];

function randomFromPattern(pattern) {
  var out = '';
  for (var i = 0; i < pattern.length; i++) {
    var c = pattern[i];
    if (c === '#') out += Math.floor(Math.random() * 10);
    else if (c === 'A') out += String.fromCharCode(65 + Math.floor(Math.random() * 26));
    else out += c;
  }
  return out;
}

Each jurisdiction row carries what makes its cards distinguishable: the IIN that goes in the header, the two-letter code that goes in DAJ, a plausible sample city and postal code, and a licence-number pattern. Patterns are illustrative rather than authoritative — the point is to exercise a decoder, not to reproduce any particular issuing authority's formatting.

Step 3: Encode the Payload as PDF417

PDF417 is the symbology North American licenses use, and bwip-js renders it directly to a canvas:

await bwipjs.toCanvas(canvas, {
  bcid: 'pdf417',
  text: payload,
  scale: 8,          // pixels per module
  rowmult: 3,        // row height, in modules
  eclevel: 5,        // Reed-Solomon error correction level
  paddingwidth: 4,
  paddingheight: 4,
  backgroundcolor: 'FFFFFF',
  barcolor: '000000'
});

scale is the setting that decides whether the exported image is scannable. A payload of this size lands around 270–293 characters, which PDF417 lays out in roughly 12 columns; at scale: 8 every module is eight pixels wide, so the symbol survives being downscaled onto a card, exported to PNG and re-uploaded. Rendering at scale: 2 or 3 produces a symbol that looks fine on screen and fails to decode once it has been resized.

Step 4: Render a Card to Download

Draw the front and the back on one canvas so a single PNG carries both the human-readable fields and the barcode. Two details are worth copying: render the sheet at two device pixels per logical unit so the modules stay large, and stamp a SPECIMEN watermark so the output cannot be mistaken for a real document.

var DPR = 2;
canvas.width = SHEET_W * DPR;
canvas.height = SHEET_H * DPR;
var ctx = canvas.getContext('2d');
ctx.setTransform(DPR, 0, 0, DPR, 0, 0);   // then draw in logical units

function renderSheet(sample, barcodeCanvas) {
  ctx.fillStyle = '#f1f5f9';
  ctx.fillRect(0, 0, SHEET_W, SHEET_H);

  renderFront(ctx, sample);                 // header band, photo box, fields
  renderBack(ctx, sample, barcodeCanvas);   // PDF417 plus a magnetic stripe

  ctx.save();
  ctx.globalAlpha = 0.16;
  ctx.translate(SHEET_W / 2, SHEET_H / 2);
  ctx.rotate(-Math.PI / 6);
  ctx.fillStyle = '#c81e2b';
  ctx.font = 'bold 86px Arial';
  ctx.textAlign = 'center';
  ctx.fillText('SPECIMEN', 0, 0);
  ctx.restore();
}

Here is the whole flow in one pass — pick a jurisdiction, randomise the cardholder data, then scroll through what gets generated, front and back:

Step 5: Decode the Generated Card

Now close the loop. The interesting part is how you hand a still image to CaptureVisionRouter. capture() dispatches on the argument type, and the SDK's own image picker passes a DSImageData built from canvas pixels — not a Blob, HTMLImageElement or canvas. Only that shape decodes reliably:

function imageToDsImageData(img) {
  var width = img.naturalWidth;
  var height = img.naturalHeight;
  if (width > 4000) {                       // keep huge photos manageable
    height = Math.round(height * 4000 / width);
    width = 4000;
  }

  var canvas = document.createElement('canvas');
  canvas.width = width;
  canvas.height = height;
  var ctx = canvas.getContext('2d', { willReadFrequently: true });
  ctx.drawImage(img, 0, 0, width, height);

  var data = ctx.getImageData(0, 0, width, height);
  return {
    bytes: new Uint8Array(data.data.buffer, data.data.byteOffset, data.data.length),
    width: width,
    height: height,
    stride: 4 * width,
    format: 10                                // IPF_ABGR_8888 — canvas RGBA order
  };
}

var result = await cvRouter.capture(imageToDsImageData(img), 'ReadDenseBarcodes');

// capture() returns barcodes in `items`; only the streaming receiver uses
// `barcodeResultItems`.
var barcodes = (result.items || []).filter(function (item) {
  return item.type === Dynamsoft.Core.EnumCapturedResultItemType.CRIT_BARCODE;
});

var parsed = await parser.parse(barcodes[0].bytes);
console.log(JSON.parse(parsed.jsonString));

That items versus barcodeResultItems distinction is worth internalising: reading the wrong property makes capture() look broken, returning zero barcodes for every input, when it is working correctly. Log Object.keys(result) before concluding anything.

The quickest way to check a generated card is the driver's license scanner demo, which accepts drag & drop, a file picker and clipboard paste. Download the generated PNG, paste it into the demo with Ctrl+V, and the fields come back:

Source Code

Get the complete sample project source code on GitHub

To read the cards it produces, open the driver's license scanner demo — no install required — or build the same reader yourself with the driver's license PDF417 tutorial.

How to Build an Expo Barcode Scanner for Android and iOS

Xiao Ling — Fri, 04 Sep 2026 05:21:57 +0000

Scanning barcodes in an Expo app usually means installing a React Native plugin that wraps some native decoder. This sample takes a different route: the native bridge is written by hand inside the app as a local Expo module, so the app talks directly to the Dynamsoft Capture Vision native SDK on Android and iOS — no third-party scanning plugin in between.

What you'll build: An Expo SDK 57 app (expo-barcode-scanner) with a full-screen native camera scanner that decodes QR codes and other 1D/2D barcodes with the Dynamsoft Capture Vision template ReadBarcodes_Default, draws live overlays around every detected barcode, and returns a results list containing the decoded text, the barcode format, and the four corner points. A system photo-picker path decodes barcodes from existing images, and a scanFile method decodes from a local file path.

Demo Video: Expo Barcode Scanner in Action

Prerequisites

Before you start, make sure you have the following:

Node.js (LTS) and npm for the Expo toolchain
Android Studio (latest) with JDK 17 and a connected Android device or emulator
Xcode (latest, macOS only) with a connected iPhone and a signing team configured in Xcode → Settings → Accounts
A Dynamsoft license key — the sample embeds a time-limited trial key that requires a network connection on first use

Get a 30-day free trial license at dynamsoft.com/customer/license/trialLicense

How the Sample Project Is Organized

The complete app lives in the examples/expo-barcode-scanner folder of the sample repository:

expo-barcode-scanner/
├── app.json                          # App config: permissions, bundle IDs
├── App.tsx                           # Home + results list (React Native UI)
├── assets/                           # App icons
└── modules/
    └── expo-dynamsoft-barcode-scanner/  # Local Expo module (the native bridge)
        ├── expo-module.config.json   # Registers the module for apple + android
        ├── src/ExpoDynamsoftBarcodeScannerModule.ts   # TypeScript surface
        ├── android/                  # Kotlin module + ScannerActivity
        │   ├── build.gradle          # Dynamsoft capturevisionbundle dependency
        │   └── src/main/AndroidManifest.xml
        └── ios/                      # Swift module + BarcodeCameraScanViewController
            ├── ExpoDynamsoftBarcodeScanner.podspec
            ├── ExpoDynamsoftBarcodeScannerModule.swift
            └── SharedImagePicker.swift

Step 1: Scaffold the Expo App and the Local Module

Create the project with the blank TypeScript template and scaffold the module:

npx create-expo-app@latest expo-barcode-scanner --template blank-typescript
cd expo-barcode-scanner
npx create-expo-module@latest --local modules/expo-dynamsoft-barcode-scanner

If the scaffolder creates the module under modules/modules/, move it up one level and delete the empty wrapper. Restrict expo-module.config.json to the native platforms and align the module class names:

{
  "platforms": ["apple", "android"],
  "apple": {
    "modules": ["ExpoDynamsoftBarcodeScannerModule"]
  },
  "android": {
    "modules": ["expo.modules.dynamsoftbarcodescanner.ExpoDynamsoftBarcodeScannerModule"]
  }
}

Step 2: Add Camera and Photo Library Permissions

Declare the usage descriptions in app.json; the Android module manifest adds the CAMERA and photo-library permissions that are merged into the app manifest:

"ios": {
  "bundleIdentifier": "com.dynamsoft.expo.barcodescanner",
  "infoPlist": {
    "NSCameraUsageDescription": "Camera is used to scan barcodes.",
    "NSPhotoLibraryUsageDescription": "The app lets you pick a barcode image from your photo library to scan it."
  }
}

Step 3: Define the TypeScript API and the Result List UI

The module surface declares the bridge methods and the result type. The location of every decoded barcode is delivered as four corner points:

export type BarcodeResult = {
  text: string;                      // decoded payload
  formatString: string;              // e.g. QR_CODE, CODE_128
  points: Array<{ x: number; y: number }>; // 4 corners in frame coordinates
};

export type ScanResult = { results: BarcodeResult[] };

declare class ExpoDynamsoftBarcodeScannerModule extends NativeModule<{}> {
  initLicense(license?: string): Promise<InitLicenseResult>;
  startScan(): Promise<ScanResult>;        // full-screen camera scanner
  scanFromGallery(): Promise<ScanResult>;  // system photo picker
  scanFile(options: ScanFileOptions): Promise<ScanResult>;
}

The home screen in App.tsx offers a Camera / Image File toggle, runs the same license-and-scan flow for both sources, and renders each decoded barcode as a card with its format, text, and corners:

const scan = async () => {
  setBusy(true);
  setError(null);
  setResults([]);
  try {
    const license = await ExpoDynamsoftBarcodeScanner.initLicense();
    if (!license.success) {
      setError(`License failed: ${license.message}`);
      return;
    }
    const outcome = mode === 'camera'
      ? await ExpoDynamsoftBarcodeScanner.startScan()
      : await ExpoDynamsoftBarcodeScanner.scanFromGallery();
    setResults(outcome.results);
  } catch (e: any) {
    const message: string = e?.message ?? String(e);
    if (!/cancel/i.test(message)) {
      setError(message);   // user cancel: keep the home screen clean
    }
  } finally {
    setBusy(false);
  }
};

{results.map((r, i) => (
  <View key={`${r.text}-${i}`} style={styles.resultCard}>
    <Text style={styles.resultFormat}>{r.formatString}</Text>
    <Text style={styles.resultText}>{r.text}</Text>
    {r.points.length === 4 ? (
      <Text style={styles.resultPoints}>
        corners: {r.points.map((p) => `(${Math.round(p.x)}, ${Math.round(p.y)})`).join(' ')}
      </Text>
    ) : null}
  </View>
))}

Step 4: Implement the Android Native Module

The Android module adds the self-contained Dynamsoft Capture Vision bundle and appcompat (the scanner activity needs a LifecycleOwner for the camera):

dependencies {
  implementation 'androidx.appcompat:appcompat:1.7.0'
  implementation 'com.dynamsoft:capturevisionbundle:3.6.2000'
}

ScannerEngine.kt owns a single CaptureVisionRouter shared by the camera and file sources. The barcode preset template is used for both:

fun template(): String = EnumPresetTemplate.PT_READ_BARCODES

fun decodeBitmap(bitmap: Bitmap?): DecodedBarcodesResult {
  if (bitmap == null) throw ScannerException("Source bitmap is null")
  return unwrap(router.capture(bitmap, template()))
}

ScannerActivity.kt is the full-screen scanner. A CapturedResultReceiver receives every decoded frame, enables the Confirm button as soon as at least one barcode is found, and draws the result quads on the DBR drawing layer of the camera view:

// inside onDecodedBarcodesReceived -> refreshUi()
val count = latestItems.size
if (count == 0) {
  statusView.text = getString(R.string.status_scanning)
  captureButton.isEnabled = false
  clearOverlay()
  return
}
statusView.text = resources.getQuantityString(R.plurals.barcodes_found, count, count)
captureButton.isEnabled = true
drawOverlay()

private fun drawOverlay() {
  val layer = cameraView.getDrawingLayer(DrawingLayer.DBR_LAYER_ID) ?: return
  val items = ArrayList<DrawingItem<*>>()
  for (item in latestItems) {
    item.location?.let { items.add(QuadDrawingItem(it)) }
  }
  layer.setDrawingItems(items)
}

Confirming serializes the items (text, formatString, points) to a JSON array and returns it as the activity result. As in the MRZ sample, BridgeResultActivity hosts the startActivityForResult call on behalf of the module and resolves the parked promise with the parsed JSON; a cancel produces a canceled rejection.

Step 5: Implement the iOS Native Module

The podspec depends on the self-contained Dynamsoft framework (never combine it with separate core or license pods — duplicate Objective-C classes break the camera preview):

s.dependency 'ExpoModulesCore'
s.dependency 'DynamsoftCaptureVisionBundle', '3.6.2000'

ExpoDynamsoftBarcodeScannerModule.swift presents BarcodeCameraScanViewController on the main queue. The controller binds a CameraView + CameraEnhancer to a CaptureVisionRouter, loads the barcode templates shipped inside the framework, and applies the decoded items to a custom green drawing layer in its CapturedResultReceiver:

let bundleCandidates = Bundle.allFrameworks + Bundle.allBundles
if let templatePath = bundleCandidates.lazy
  .compactMap({ $0.path(forResource: "dbr-bundle-mobile-templates", ofType: "json") })
  .first {
  try? cvr.initSettingsFromFile(templatePath)
}

For the file data source the module runs a background decode with the same template and converts each item's location points (wrapped as NSValue) into plain {x, y} dictionaries:

let result = router.captureFromFile(url.path, templateName: Constants.templateName)
guard let items = result.decodedBarcodesResult?.items else { /* reject "No barcodes found" */ }
for item in items {
  var points: [[String: Any]] = []
  for value in item.location.points {
    let p = value.cgPointValue
    points.append(["x": p.x, "y": p.y])
  }
  array.append(["text": item.text ?? "", "formatString": item.formatString ?? "", "points": points])
}
promise.resolve(["results": array])

Step 6: Build and Run the App

npm install

# Android — builds and installs the debug app on the connected device/emulator
npx expo run:android

# iOS — builds and installs on a connected iPhone (Xcode signing required)
npx expo run:ios --device

Self-contained release builds are produced with:

cd android && ./gradlew :app:assembleRelease   # APK in app/build/outputs/apk/release/
# or: npx expo run:ios --configuration Release --device

Aim the camera at any barcode — the preview highlights every decoded barcode and the status bar shows the running count. Tap Confirm to open the results list with format, text, and corner coordinates:

Source Code

Get the complete sample project source code on GitHub

How to Benchmark Barcode Reading in C++ with ZXing-C++ and Dynamsoft Barcode Reader

Xiao Ling — Mon, 27 Jul 2026 08:01:20 +0000

An auditable C++ barcode benchmark must give every reader the same pixels, ground truth, format policy, and timing boundary. This project compares ZXing-C++ with Dynamsoft Barcode Reader on 7,894 unique images from the public BarBeR dataset and preserves every raw result for independent review.

What you'll build: A reproducible Windows C++ benchmark that builds ZXing-C++ from a Git submodule, runs both barcode readers on one RGB888 image buffer, validates BarBeR ground truth, and exports raw JSONL plus a complete JSON package.

Full BarBeR Benchmark Video

The video summarizes the complete dataset audit, the shared input method, and the measured results.

Prerequisites

Visual Studio 2022 with the C++ desktop workload
CMake 3.16 or later
Dynamsoft Barcode Reader SDK v11
ZXing-C++ 3.1.0 from the project submodule
Python 3 with Pillow for report media generation
A valid Dynamsoft license key. Get a 30-day free trial license.

Step 1: Build ZXing-C++ with the Benchmark

The root repository records ZXing-C++ as a Git submodule, and CMake builds its core reader target with the benchmark.

set(ZXING_READERS ON CACHE BOOL "" FORCE)
set(ZXING_WRITERS OFF CACHE STRING "" FORCE)
set(ZXING_C_API OFF CACHE BOOL "" FORCE)
set(ZXING_EXAMPLES OFF CACHE BOOL "" FORCE)
set(ZXING_UNIT_TESTS OFF CACHE BOOL "" FORCE)
if(NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/zxing-cpp/CMakeLists.txt")
    message(FATAL_ERROR "ZXing-C++ submodule is missing. Run: git submodule update --init --recursive")
endif()
add_subdirectory(zxing-cpp EXCLUDE_FROM_ALL)

Initialize the submodule and build the executable.

git submodule update --init --recursive
cmake -S . -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release --target barcode_benchmark benchmark_tests
ctest --test-dir build -C Release --output-on-failure

Step 2: Give Both Readers the Same Pixels

The benchmark loads every image once into a shared three-channel RGB buffer. The buffer remains unchanged while both decoder adapters read it, so the comparison does not depend on separate image-loading paths.

ZXing-C++ receives an ImageView over that buffer.

const ZXing::ImageView view(image.rgb.data(), image.width, image.height,
                            ZXing::ImageFormat::RGB, image.stride);
const auto begin = std::chrono::steady_clock::now();
const auto barcodes = ZXing::ReadBarcodes(view, options_);
run.decode_time = std::chrono::steady_clock::now() - begin;

Dynamsoft Barcode Reader receives a CImageData object over the same bytes.

CImageData input(static_cast<int>(image.rgb.size()), image.rgb.data(), image.width, image.height,
                 image.stride, IPF_RGB_888);
const auto begin = std::chrono::steady_clock::now();
CCapturedResult* captured = router_->Capture(&input, template_name_.c_str());
run.decode_time = std::chrono::steady_clock::now() - begin;

Step 3: Audit BarBeR Ground Truth

The audit reads all 12 VGG JSON files from the public BarBeR dataset, validates payload structures, resolves overlapping annotations, and deduplicates image bytes by SHA-256.

build/Release/barcode_benchmark.exe audit `
  --images "D:/images/public-barcode-dataset/BarBeR - Dataset/dataset/images" `
  --annotations "D:/images/public-barcode-dataset/BarBeR - Dataset/Annotations/VIA" `
  --output manifests

The audited source contains 8,748 image records and 9,818 annotations. The benchmark manifest contains 7,894 unique images and 8,615 reliable barcode instances after exclusions.

Dataset stage	Count	How it relates to the run
Original image records	8,748	All image records referenced by the BarBeR VIA annotations
Original annotations	9,818	All barcode annotation regions before reliability filtering
Images without reliable ground truth	853	Removed because the payload was missing, generic, invalid, or not safely scorable
Exact duplicate images	1	Removed by SHA-256 byte identity
Final unique images	7,894	The image denominator used by each decoder
Final ground truth values	8,615	The accuracy denominator used for recall
Decoder records	15,788	7,894 images multiplied by two decoders and one measured run

This connection matters because the benchmark does not score every original BarBeR image. It scores only images with reliable payload ground truth, then verifies that image count, ground truth count, SHA-256 identity, and decoder record count agree before publishing the report.

Step 4: Run and Validate the Complete Dataset

The benchmark writes one resumable result record per image and decoder. results.jsonl is used for the append-only raw stream, which makes long runs easier to resume and validate one line at a time. The project also writes results.json, which packages the summary and the same raw records into one JSON document for consumers that expect a single JSON file.

build/Release/barcode_benchmark.exe run `
  --images "D:/images/public-barcode-dataset/BarBeR - Dataset/dataset/images" `
  --manifest manifests/benchmark_manifest.jsonl `
  --output results/full `
  --dbr-template ReadBarcodes_Default `
  --zxing-config configs/zxing_all_supported.json `
  --license-key-file "../../license-key.txt" `
  --repetitions 1

The validator checks record keys, image counts, ground truth consistency, repetitions, summary totals, and explicit decoder errors.

python tools/validate_results.py `
  --results results/full/results.jsonl `
  --summary results/full/summary.json `
  --expected-images 7894 `
  --expected-ground-truth 8615 `
  --expected-repetitions 1

Step 5: Inspect Accuracy and Decode Time

This benchmark ran each decoder once on every one of the 7,894 unique images. The accuracy denominator contains 8,615 ground truth barcode instances. The measured machine used Windows 11 Pro, an Intel Core i5-13400F, 31.8 GB of memory, a Release x64 build, and one thread per decoder task.

Recall and precision answer different questions. Recall measures how many known barcodes were found. Precision measures how many reported barcode results were correct.

Recall = correct ground truth matches / eligible ground truth instances
Precision = correct predictions / evaluated predictions
Evaluated predictions = correct + wrong_text + wrong_format + extra_result

In this benchmark, not_found and unsupported_format lower recall because they are missed ground truth instances. They do not lower precision because no decoded value was reported for those ground truth items. extra_result, wrong_text, and wrong_format lower precision because the decoder returned a result that did not match a ground truth barcode.

Decoder	Correct	Recall	Precision	Image all-read rate	Mean decode time	Median decode time	P95 decode time
Dynamsoft Barcode Reader 11.4.20.7177	7,444 / 8,615	86.41%	91.44%	86.57%	70.08 ms	44.99 ms	208.51 ms
ZXing-C++ 3.1.0	5,855 / 8,615	67.96%	93.17%	67.79%	74.09 ms	44.34 ms	250.22 ms

DBR produced 1,589 more correct ground truth matches and improved recall by 18.44 percentage points in this run. ZXing-C++ had 1.73 percentage points higher precision. DBR's mean decoder call was about 5.4% lower than ZXing-C++ in this run. These results show a recall, precision, and latency trade-off on this dataset rather than a universal ranking for every barcode workload.

The matcher normalizes UPC-A against the equivalent zero-prefixed EAN-13 payload before scoring. A full scan of the incorrect records found no remaining cases where a result was wrong only because one side had an extra leading zero. The canonical format normalizer also treats CODE39EXTENDED as CODE_39 when the decoded payload is the same.

This benchmark was implemented and published by Dynamsoft, the developer of Dynamsoft Barcode Reader. BarBeR is a public third-party dataset, and its standardized annotations were generated with assistance from proprietary Datalogic software. The source hashes, exclusions, configurations, raw records, and report are preserved so the comparison can be audited.

The static report embeds searchable per-image records and copies the complete JSONL, complete JSON package, summary, matching analysis, and source inventory into its download directory.

python tools/generate_html_report.py `
  --inventory manifests/barber_source_files.json `
  --environment configs/benchmark_environment.json `
  --results results/full/results.jsonl `
  --results-json results/full/results.json `
  --matching-analysis results/full/matching_analysis.json `
  --summary results/full/summary.json `
  --output report/index.html

Source Code

Get the complete sample project source code on GitHub

How to Build a Desktop Document Scanner with Python, PySide6, and Dynamsoft Capture Vision

Xiao Ling — Tue, 14 Jul 2026 09:08:46 +0000

Digitizing paper documents from a webcam usually means fighting with skewed angles, poor lighting, and manual cropping. This project is a production-style desktop scanner app that detects document boundaries in real time, corrects perspective distortion, and exports the results as PDFs, individual images, or stitched long images. The app is built with Python, PySide6, and the Dynamsoft Capture Vision SDK.

What you'll build: A PySide6 desktop document scanner that uses the Dynamsoft Capture Vision SDK to detect, normalize, filter, rotate, reorder, and export documents captured from a USB camera or imported image files.

Demo Video: Desktop Document Scanner in Action

Prerequisites

Dynamsoft Capture Vision Bundle >=3.0.0
Python 3.9+, PySide6 >=6.5.0, OpenCV >=4.8.0, Pillow, reportlab, numpy
A valid Dynamsoft license key. Get a 30-day free trial license.

Step 1: Install Dependencies and Initialize the SDK

Start by declaring the Python packages in requirements.txt and create a DCVScanner wrapper that initializes the license and CaptureVisionRouter.

# requirements.txt
dynamsoft-capture-vision-bundle>=3.0.0
PySide6>=6.5.0
opencv-python>=4.8.0
Pillow>=10.0.0
reportlab>=4.0.0
numpy>=1.24.0

# scanner.py
from dynamsoft_capture_vision_bundle import (
    CaptureVisionRouter,
    LicenseManager,
    EnumErrorCode,
)

DEFAULT_LICENSE_KEY = (
    "LICENSE-KEY"
)

DETECT_TEMPLATE = "DetectDocumentBoundaries_Default"
NORMALIZE_TEMPLATE = "NormalizeDocument_Default"

class DCVScanner:
    def __init__(self, license_key: str = DEFAULT_LICENSE_KEY):
        self.license_key = license_key
        self.cvr = None
        self._initialized = False

    def init(self):
        if self._initialized:
            return EnumErrorCode.EC_OK, "OK"
        ec, msg = LicenseManager.init_license(self.license_key)
        if ec != EnumErrorCode.EC_OK:
            return ec, msg
        self.cvr = CaptureVisionRouter()
        self._initialized = True
        return EnumErrorCode.EC_OK, "OK"

Step 2: Convert Between OpenCV Images and DCV ImageData

The SDK works with ImageData objects, while OpenCV and PySide6 use numpy arrays. Add helpers to move between the two formats without copying more data than necessary.

# scanner.py
import numpy as np
import cv2
from dynamsoft_capture_vision_bundle import (
    EnumImagePixelFormat,
    ImageData,
)

def np_to_image_data(image: np.ndarray) -> ImageData:
    if image.ndim == 2:
        h, w = image.shape
        stride = image.strides[0]
        return ImageData(image.tobytes(), w, h, stride, EnumImagePixelFormat.IPF_GRAYSCALED)
    if image.shape[2] == 3:
        h, w = image.shape[:2]
        stride = image.strides[0]
        return ImageData(image.tobytes(), w, h, stride, EnumImagePixelFormat.IPF_RGB_888)
    if image.shape[2] == 4:
        h, w = image.shape[:2]
        stride = image.strides[0]
        return ImageData(image.tobytes(), w, h, stride, EnumImagePixelFormat.IPF_ARGB_8888)
    rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
    h, w = rgb.shape[:2]
    stride = rgb.strides[0]
    return ImageData(rgb.tobytes(), w, h, stride, EnumImagePixelFormat.IPF_RGB_888)

def image_data_to_np(image_data: ImageData) -> np.ndarray:
    fmt = image_data.get_image_pixel_format()
    w = image_data.get_width()
    h = image_data.get_height()
    stride = image_data.get_stride()
    buf = image_data.get_bytes()
    if fmt == EnumImagePixelFormat.IPF_GRAYSCALED:
        arr = np.frombuffer(buf, dtype=np.uint8).reshape((h, stride))
        gray = arr[:, :w]
        return cv2.cvtColor(gray, cv2.COLOR_GRAY2RGB)
    if fmt == EnumImagePixelFormat.IPF_RGB_888:
        arr = np.frombuffer(buf, dtype=np.uint8).reshape((h, stride))
        arr = arr[:, :w * 3]
        return arr.reshape((h, w, 3))
    # ... additional format handling in the source file

Step 3: Detect and Normalize Document Boundaries

With the router initialized, call the detect template to find the best document quad, then pass that quad into the normalize template to deskew and crop the page.

# scanner.py
class DCVScanner:
    def detect_document(self, image: np.ndarray):
        if not self._initialized:
            self.init()
        img_data = np_to_image_data(image)
        result = self.cvr.capture(img_data, DETECT_TEMPLATE)
        if result.get_error_code() != EnumErrorCode.EC_OK:
            return None
        processed = result.get_processed_document_result()
        if not processed:
            return None
        quads = processed.get_detected_quad_result_items()
        if not quads:
            return None
        best = max(quads, key=lambda q: q.get_confidence_as_document_boundary())
        loc = best.get_location()
        return [QuadPoint(p.x, p.y) for p in loc.points]

    def normalize_document(self, image: np.ndarray, quad_points=None):
        if not self._initialized:
            self.init()
        img_data = np_to_image_data(image)
        template_name = NORMALIZE_TEMPLATE
        if quad_points and len(quad_points) == 4:
            ec, msg, settings = self.cvr.get_simplified_settings(template_name)
            if ec == EnumErrorCode.EC_OK:
                quad = Quadrilateral()
                quad.points = [Point(int(round(p.x)), int(round(p.y))) for p in quad_points]
                settings.roi = quad
                settings.roi_measured_in_percentage = 0
                ec2, msg2 = self.cvr.update_settings(template_name, settings)
                if ec2 != EnumErrorCode.EC_OK:
                    print(f"update_settings warning: {msg2}")
        result = self.cvr.capture(img_data, template_name)
        if result.get_error_code() != EnumErrorCode.EC_OK:
            return None
        processed = result.get_processed_document_result()
        if not processed:
            return None
        items = processed.get_enhanced_image_result_items()
        if not items:
            return None
        return image_data_to_np(items[0].get_image_data())

Step 4: Build the PySide6 UI and Camera Preview

The entry point creates a QApplication in Fusion style and shows the main window. The main window opens the default camera with OpenCV, converts each BGR frame to RGB, and displays it in a custom CameraWidget.

# main.py
import sys
from PySide6.QtWidgets import QApplication
from app import DocumentScannerApp

def main():
    app = QApplication(sys.argv)
    app.setStyle("Fusion")
    window = DocumentScannerApp()
    window.show()
    sys.exit(app.exec())

if __name__ == "__main__":
    main()

# app.py
class DocumentScannerApp(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Dynamsoft Document Scanner")
        self.setMinimumSize(900, 700)
        self.scanner = DCVScanner()
        self.thread_pool = QThreadPool()
        self.thread_pool.setMaxThreadCount(4)
        # ... UI setup and license screen

    def _init_camera(self):
        self.cap = cv2.VideoCapture(0)
        if self.cap and self.cap.isOpened():
            self.cap.set(cv2.CAP_PROP_FRAME_WIDTH, 1920)
            self.cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 1080)
        self.camera_timer.start(33)  # ~30 fps preview

    def _on_camera_frame(self):
        if not self.cap or not self.cap.isOpened():
            return
        ret, frame = self.cap.read()
        if not ret or frame is None:
            return
        rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
        self.latest_frame = rgb
        self.camera_widget.set_frame(rgb)

Step 5: Add Auto-Capture, Manual Capture, and File Import

Run detection on a downscaled frame in a background worker to keep the UI smooth. When the detected quad stays stable across several frames, the app auto-captures. A shutter button also triggers manual capture with a short timeout fallback.

# app.py
class DocumentScannerApp(QMainWindow):
    def _on_detection_tick(self):
        if not self.is_scanning or self.is_processing_frame or self.is_capture_in_progress:
            return
        if self.latest_frame is None:
            return
        self.is_processing_frame = True
        h, w = self.latest_frame.shape[:2]
        scale = min(1.0, 640 / w)
        if scale < 1.0:
            small = cv2.resize(self.latest_frame, (int(w * scale), int(h * scale)), interpolation=cv2.INTER_AREA)
        else:
            small = self.latest_frame.copy()
        worker = DetectWorker(self.scanner, small)
        worker.signals.result.connect(lambda quad: self._on_detection_result(quad, scale))
        worker.signals.error.connect(lambda msg: self._on_detection_result(None, scale))
        self.thread_pool.start(worker)

    def _on_detection_result(self, quad, scale):
        self.is_processing_frame = False
        if quad:
            full_quad = [QuadPoint(p.x / scale, p.y / scale) for p in quad] if scale < 1.0 else quad
            self.latest_detected_quad = full_quad
            self.camera_widget.set_overlay(full_quad)
            if self.manual_capture_pending:
                self.manual_capture_pending = False
                self._reset_stabilizer()
                self._perform_capture(False, full_quad)
                return
            if self.last_quad is None:
                self.last_quad = full_quad
                self.stable_counter = 1
            elif is_quad_stable(full_quad, self.last_quad, self.quad_stabilizer["iou_threshold"], self.quad_stabilizer["area_delta_threshold"]):
                self.stable_counter += 1
                self.last_quad = full_quad
            else:
                self.stable_counter = 0
                self.last_quad = full_quad
            if self.quad_stabilizer["enabled"] and self.stable_counter >= self.quad_stabilizer["stable_frame_count"]:
                self._reset_stabilizer()
                self._perform_capture(True, full_quad)
        else:
            self.camera_widget.set_overlay(None)
            self._reset_stabilizer()

Step 6: Filter, Rotate, Reorder, and Export Pages

After capture, each page is stored as a Page object. The app applies color, grayscale, or binary filters through DCV's ImageProcessor, rotates pages 90 degrees at a time, lets users drag to reorder, and exports to PDF, individual PNGs, or a stitched long image.

# scanner.py
from dynamsoft_capture_vision_bundle import ImageProcessor

def apply_filter(image: np.ndarray, mode: str) -> np.ndarray:
    if mode == "color":
        return image.copy()
    processor = ImageProcessor()
    img_data = np_to_image_data(image)
    if mode == "grayscale":
        result_data = processor.convert_to_gray(img_data)
        return image_data_to_np(result_data)
    if mode == "binary":
        result_data = processor.convert_to_binary_global(img_data, threshold=140, invert=True)
        return image_data_to_np(result_data)
    return image.copy()

def rotate_image_90(image: np.ndarray) -> np.ndarray:
    return cv2.rotate(image, cv2.ROTATE_90_CLOCKWISE)

# app.py
class DocumentScannerApp(QMainWindow):
    def _on_rotate(self):
        if not self.pages:
            return
        page = self.pages[self.current_page_index]
        page.base_image = rotate_image_90(page.base_image)
        self._render_result()
        self._update_thumbnail_bar()

    def _on_sort(self):
        if len(self.pages) < 2:
            self._show_toast("Need at least 2 pages to reorder.")
            return
        dialog = SortDialog(self.pages, self)
        if dialog.exec() == QDialog.Accepted:
            order = dialog.get_order()
            self.pages = [self.pages[i] for i in order]
            self.current_page_index = 0
            self._render_result()
            self._update_thumbnail_bar()

    def _on_export_pdf(self):
        if not self.pages:
            return
        path, _ = QFileDialog.getSaveFileName(self, "Save PDF", "documents.pdf", "PDF Files (*.pdf)")
        if not path:
            return
        pdf = pdf_canvas.Canvas(path, pagesize=A4)
        page_width, page_height = A4
        for i, page in enumerate(self.pages):
            if i > 0:
                pdf.showPage()
            img = apply_filter(page.base_image, page.filter_mode)
            h, w = img.shape[:2]
            ratio = min(page_width / w, page_height / h)
            draw_w = w * ratio
            draw_h = h * ratio
            x = (page_width - draw_w) / 2
            y = (page_height - draw_h) / 2
            temp_path = f"_temp_pdf_{i}.jpg"
            save_image(img, temp_path)
            pdf.drawImage(temp_path, x, y, width=draw_w, height=draw_h)
        pdf.save()
        for i in range(len(self.pages)):
            temp = f"_temp_pdf_{i}.jpg"
            if os.path.exists(temp):
                os.remove(temp)
        self._show_toast("PDF exported.")

Source Code

https://github.com/yushulx/python-document-scanner-sdk/tree/main/examples/official/multi-document-capture

How to Build a Most Accurate Barcode Reader for Low-Resolution, Low-Light, and Glare Images

Xiao Ling — Fri, 10 Jul 2026 06:47:09 +0000

Low-resolution barcode images, low-light warehouse photos, and glare from glossy labels are common causes of barcode scanning failures. The practical question is not only "which barcode reader is most accurate?", but also "when should I tune the DBR template, and when is the image too degraded to recover?"

This tutorial builds a reproducible Python benchmark using Dynamsoft Barcode Reader through the Dynamsoft Capture Vision bundle. It programmatically generates Code 128 and QR code images, degrades them with low resolution, low light, glare, blur, inverted polarity, and inverted low-light conditions, then compares the built-in PT_READ_BARCODES preset against a focused custom template.

What you'll build: A Python benchmark that creates difficult barcode and QR test images, runs Dynamsoft Barcode Reader with the default preset and a focused custom template, writes per-image JSON results, and produces an HTML report with bar charts for accuracy and speed.

Demo Video: Low-Resolution and Glare Benchmark

Prerequisites

Python 3.8 or later.
pillow, qrcode, python-barcode, opencv-python, and dynamsoft-capture-vision-bundle.
Get a 30-day free trial license for Dynamsoft Barcode Reader.

Install the dependencies:

pip install -r requirements.txt

Set your production license key before running the benchmark:

set DYNAMSOFT_LICENSE_KEY=YOUR-LICENSE-KEY

The sample also includes a public trial-key fallback for quick local testing.

Step 1: Generate Low-Resolution, Low-Light, and Glare Test Images

The sample project lives in samples/low-resolution-glare-barcode-reader/. Run the generator first:

python generate_test_images.py

The script creates a clean Code 128 inventory label and a QR warehouse bin label, then applies low-resolution scaling, low-light noise, glare, blur, inverted polarity, and inverted low-light conditions. The core degradation functions are real code from generate_test_images.py:

def low_resolution(img: Image.Image, factor=0.24) -> Image.Image:
    small = img.resize(
        (max(1, int(img.width * factor)), max(1, int(img.height * factor))),
        Image.Resampling.BILINEAR,
    )
    return small.resize(img.size, Image.Resampling.BILINEAR)


def low_light(img: Image.Image) -> Image.Image:
    arr = np.array(img).astype(np.float32)
    arr *= np.array([0.42, 0.43, 0.46], dtype=np.float32)
    noise = np.random.default_rng(7).normal(0, 10, arr.shape)
    arr = np.clip(arr + noise, 0, 255).astype(np.uint8)
    out = Image.fromarray(arr, "RGB")
    return ImageEnhance.Contrast(out).enhance(0.72)


def glare(img: Image.Image) -> Image.Image:
    base = img.convert("RGBA")
    overlay = Image.new("RGBA", img.size, (255, 255, 255, 0))
    draw = ImageDraw.Draw(overlay)
    w, h = img.size
    for i in range(42):
        alpha = max(0, 140 - i * 3)
        bbox = (
            int(w * 0.42) - i * 8,
            int(h * 0.22) - i * 5,
            int(w * 0.98) + i * 8,
            int(h * 0.58) + i * 5,
        )
        draw.ellipse(bbox, fill=(255, 255, 255, alpha))
    return Image.alpha_composite(base, overlay).convert("RGB")


def inverted(img: Image.Image) -> Image.Image:
    return ImageOps.invert(img.convert("RGB"))

The generator writes:

assets/images/*.png: 14 generated test images.
assets/ground_truth.json: expected barcode text for each image.

Step 2: Use the SDK Preset as the Default Baseline

The default baseline uses the SDK preset directly. It does not load a JSON file from the project:

run_profile("PT_READ_BARCODES preset", None, EnumPresetTemplate.PT_READ_BARCODES.value, image_paths, truth)

That matters for a fair comparison: "default" means the SDK's built-in PT_READ_BARCODES behavior, not a checked-in template file.

Step 3: Build a Fast Custom DBR Template

The fast custom template starts from the SDK preset settings, but only the custom template is saved as a project artifact. The sample uses a temporary file to read the SDK preset JSON, modifies two low-cost settings, and writes read-barcodes-fast-inverted.json.

def load_default_template() -> dict:
    router = CaptureVisionRouter()
    with tempfile.TemporaryDirectory() as temp_dir:
        temp_path = Path(temp_dir) / "preset-settings.json"
        err, msg = router.output_settings_to_file(EnumPresetTemplate.PT_READ_BARCODES.value, str(temp_path))
        if err != 0:
            raise RuntimeError(f"Failed to export default template: {msg}")
        return json.loads(temp_path.read_text(encoding="utf-8"))


def build_fast_inverted_template() -> Path:
    TEMPLATE_DIR.mkdir(parents=True, exist_ok=True)
    template = load_default_template()
    template["CaptureVisionTemplates"][0]["Name"] = "ReadBarcodes_FastInverted"

    task = template["BarcodeReaderTaskSettingOptions"][0]
    task["BarcodeFormatIds"] = ["BF_CODE_128", "BF_QR_CODE"]

    set_stage_modes(
        template,
        "SST_TRANSFORM_GRAYSCALE",
        "GrayscaleTransformationModes",
        [{"Mode": "GTM_ORIGINAL"}, {"Mode": "GTM_INVERTED"}],
    )

    fast_path = TEMPLATE_DIR / "read-barcodes-fast-inverted.json"
    fast_path.write_text(json.dumps(template, indent=2), encoding="utf-8")
    return fast_path

The custom template changes only two things. First, it adds GTM_INVERTED so the reader can handle light modules on a dark background. Second, it restricts barcode formats to the two known symbologies in the test set: Code 128 and QR Code. The generated template is saved as templates/read-barcodes-fast-inverted.json; no default template JSON is kept in the project.

Step 4: Compare Default and Custom Templates

Run the benchmark:

python benchmark_dbr_templates.py

The script loads each PNG image, decodes it with the selected profile, and compares returned text against ground_truth.json:

def run_profile(name: str, template_path: Path | None, template_name: str, image_paths: list[Path], truth: dict) -> dict:
    router = CaptureVisionRouter()
    if template_path:
        err, msg = router.init_settings_from_file(str(template_path))
        if err != 0:
            raise RuntimeError(f"Failed to load template {template_path}: {msg}")

    per_image = []
    correct = 0
    total_ms = 0.0
    for image_path in image_paths:
        start = time.perf_counter()
        items = decode_image(router, image_path, template_name)
        elapsed_ms = (time.perf_counter() - start) * 1000
        total_ms += elapsed_ms
        expected = set(truth.get(image_path.name, []))
        found = {item["text"] for item in items}
        ok = bool(expected and expected.issubset(found))
        if ok:
            correct += 1

On the generated dataset, the output was:

PT_READ_BARCODES preset: 10/14 (71.43%), avg 46.19 ms/image
Fast custom template: 14/14 (100.0%), avg 21.73 ms/image
Recovered by Fast custom template: 4
  - code128_inverted.png
  - code128_inverted_low_light.png
  - qr_inverted.png
  - qr_inverted_low_light.png

The default preset decoded every standard difficult-image variant: clean, low-resolution, low-light, glare, and blur for both Code 128 and QR. The focused custom template added value on a specific failure class, inverted polarity and inverted low-light images, without turning on expensive search paths.

Source Code

https://github.com/yushulx/python-barcode-qrcode-sdk/tree/main/examples/official/low-resolution-glare-barcode-reader

How to Build a Web Document Scanner with Google Drive Cloud Storage Upload

Xiao Ling — Thu, 25 Jun 2026 08:51:15 +0000

Capturing documents in the browser — from a physical scanner, a webcam, or an uploaded file — and then pushing them straight to cloud storage is a workflow many business apps need, but few SDKs support end-to-end. Dynamsoft Document Viewer (DDV) v4 handles the viewing, annotation, and export side, while Dynamic Web TWAIN handles physical scanner acquisition. Document edge detection is implemented with a pure-canvas algorithm (no external SDK required), and Google Identity Services provides the OAuth layer for cloud upload. This tutorial shows how to wire all of these together so scanned pages land in the cloud without ever touching a server.

What you'll build: A browser-based document annotation studio that captures pages from a webcam and TWAIN scanner, auto-detects document boundaries with a pure-canvas pipeline (Otsu thresholding plus orientation-aware quadrilateral fitting that handles rotated ID cards), lets users annotate and redact, and uploads the result to Google Drive as a PDF or PNG images — built with Dynamsoft Document Viewer v4 and TypeScript.

Demo Video: Document Capture and Cloud Storage Upload

Prerequisites

Dynamsoft Document Viewer v4 (npm install dynamsoft-document-viewer)
Dynamic Web TWAIN v19 for physical scanner support (loaded via CDN)
Node.js 18+ and an IDE (VS Code recommended)
A Google Cloud project with the Drive API enabled and an OAuth 2.0 Web Client ID for the upload feature
A valid Dynamsoft license key. Get a 30-day free trial license.

Step 1: Initialize the Document Viewer Engine

DDV's WASM engine must be initialized before any viewer is created. Set the license and engine resource path, then call DDV.Core.init(). The engine runs entirely in the browser via WebAssembly.

const ENGINE_RESOURCE_PATH =
  "https://cdn.jsdelivr.net/npm/dynamsoft-document-viewer@4.0.0/dist/engine";

async function initDDV(license: string): Promise<void> {
  DDV.Core.license = license;
  DDV.Core.engineResourcePath = ENGINE_RESOURCE_PATH;
  await DDV.Core.init();
  DDV.setProcessingHandler("imageFilter", new DDV.ImageFilter());
}

Once initialized, create an EditViewer with a custom UI configuration that exposes DDV's native annotation toolbar (shapes, ink, text, stamps, redaction) alongside page navigation, zoom, crop, and filter controls.

Step 2: Capture Photos from a Webcam

The camera capture system is split into two layers:

camera.ts — Opens a <dialog> element with a live camera stream, handles device switching, snapshots, thumbnail review, and returns an array of confirmed CapturedPhoto objects.
main.ts — Calls the camera dialog and inserts each confirmed photo into the DDV document via doc.loadSource().

Camera Dialog Entry Point

openCameraCapture() requests a MediaStream with getUserMedia, populates a device-select dropdown, and returns a Promise that resolves with the user's confirmed photos. Inside the promise, it wires up three button handlers — Capture, Add, and Close:

export async function openCameraCapture(): Promise<CapturedPhoto[]> {
  const photos: CapturedPhoto[] = [];

  // Request the camera (environment-facing, 1080p ideal)
  stream = await navigator.mediaDevices.getUserMedia({
    video: { facingMode: "environment", width: { ideal: 1920 }, height: { ideal: 1080 } },
    audio: false,
  });
  video.srcObject = stream;
  await video.play().catch(() => {});

  // Populate the camera device dropdown
  const devices = await navigator.mediaDevices.enumerateDevices();
  const videoDevices = devices.filter((d) => d.kind === "videoinput");
  videoDevices.forEach((d, i) => {
    deviceSelect.appendChild(new Option(d.label || `Camera ${i + 1}`, d.deviceId));
  });

  dialog.showModal();

  return new Promise<CapturedPhoto[]>((resolve) => {
    btnCapture.onclick = () => {
      captureFrame(video, (photo) => {
        photos.push(photo);
        renderThumbs(thumbStrip, photos, btnAdd);
      });
    };
    btnAdd.onclick = () => { stopStream(); dialog.close(); resolve(photos); };
    btnClose.onclick = () => { stopStream(); dialog.close(); resolve([]); };
    dialog.oncancel = () => { stopStream(); resolve([]); };
  });
}

Capturing a Single Frame

captureFrame() draws the current video frame to an off-screen canvas and converts it to a JPEG Blob via canvas.toBlob():

function captureFrame(
  video: HTMLVideoElement,
  cb: (photo: CapturedPhoto | null) => void
): void {
  const canvas = document.createElement("canvas");
  canvas.width = video.videoWidth;
  canvas.height = video.videoHeight;
  const ctx = canvas.getContext("2d")!;
  ctx.drawImage(video, 0, 0);
  canvas.toBlob(
    (blob) => {
      if (!blob) { cb(null); return; }
      cb({ blob, url: URL.createObjectURL(blob) });
    },
    "image/jpeg",
    0.92
  );
}

Switching the Active Camera

The device-select dropdown allows the user to switch between available cameras (e.g. front vs. rear on a phone). The handler stops the current stream and opens a new one with the selected device ID:

deviceSelect.onchange = async () => {
  stopStream();
  stream = await navigator.mediaDevices.getUserMedia({
    video: { deviceId: { exact: deviceSelect.value }, width: { ideal: 1920 }, height: { ideal: 1080 } },
    audio: false,
  });
  video.srcObject = stream;
  await video.play().catch(() => {});
};

Thumbnail Review with Per-Item Delete

Each captured frame is rendered as a 96 × 72 px thumbnail with a delete button. Clicking the delete button removes the photo from the array and re-renders the thumbnail strip:

function renderThumbs(
  container: HTMLElement,
  photos: CapturedPhoto[],
  btnAdd: HTMLButtonElement
): void {
  container.innerHTML = "";
  photos.forEach((photo, index) => {
    const wrapper = document.createElement("div");
    wrapper.className = "cam-thumb";

    const img = document.createElement("img");
    img.src = photo.url;
    img.alt = `Capture ${index + 1}`;

    const delBtn = document.createElement("button");
    delBtn.className = "cam-thumb-del";
    delBtn.innerHTML = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><path d="M18 6L6 18M6 6l12 12"/></svg>';
    delBtn.onclick = () => {
      URL.revokeObjectURL(photo.url);
      photos.splice(index, 1);
      renderThumbs(container, photos, btnAdd);
    };

    wrapper.appendChild(img);
    wrapper.appendChild(delBtn);
    container.appendChild(wrapper);
  });
}

Inserting Photos Into the DDV Document

Once the user clicks "Add", main.ts iterates over the confirmed photos and loads each Blob as a new page:

async function captureFromCamera(): Promise<void> {
  if (!viewerHandle) return;
  const photos = await openCameraCapture();
  if (photos.length === 0) return;

  for (let i = 0; i < photos.length; i++) {
    await appendImageBlob(viewerHandle, photos[i].blob, `camera photo ${i + 1}`);
    URL.revokeObjectURL(photos[i].url);
  }
  showToast(`Added ${photos.length} photo${photos.length > 1 ? "s" : ""} from camera.`, "success");
}

Each Blob is loaded via doc.loadSource({ fileData: blob }), which appends the image as a new page. The DDV viewer automatically updates the thumbnail rail and page count.

Step 3: Detect Document Edges and Normalize Perspective

Document edge detection uses a pure-canvas algorithm — no external SDK or license required. The image is downscaled to 500px on the longest side, converted to grayscale, and smoothed with a Gaussian blur. Otsu's thresholding algorithm automatically determines the optimal threshold to separate the document from its background.

Because a document can be either lighter or darker than its background (a white page on a dark desk, or a glossy ID card on light wood), a single brightness guess is unreliable. The pipeline instead segments with both polarities and keeps whichever yields the more document-like region. For each polarity it applies a morphological closing (dilate then erode) to fill gaps, extracts the largest connected component via BFS flood fill, and computes a convex hull from its boundary pixels.

The convex hull is then turned into a quadrilateral with an orientation-aware fit. The naive approach of picking corners by image-axis extremes (x + y, x − y) collapses to a degenerate triangle on rotated cards. Instead, the minimum-area enclosing rectangle (via rotating calipers) recovers the document's own rotation angle, and the four corners are located in that rotated frame — so rotated passports and ID cards are detected as cleanly as upright pages. Each candidate quad is scored by rectangularity (how completely the hull fills its minimum-area rectangle) and frame coverage. Blobs that fill more than ~90% of the frame are rejected as background, which is what stops the detector from selecting the whole image.

function detectDocumentQuad(img: HTMLImageElement): Quad | null {
  // Downscale for performance (max 500px on the long side)
  const scale = Math.min(500 / origW, 500 / origH, 1);

  // Grayscale + Gaussian blur to reduce noise
  const blurred = gaussianBlur(toGrayscale(imageData), w, h);
  const threshold = otsuThreshold(blurred);

  // Segment with BOTH polarities; keep the most document-like result.
  let best: { quad: Quad; score: number } | null = null;
  for (const docIsDark of [false, true]) {
    const binary = thresholdBinary(blurred, threshold, docIsDark);
    const closed = morphologicalClose(binary, w, h, 3);
    const boundary = findLargestComponent(closed, w, h, mask);
    if (!boundary) continue;

    const hull = convexHull(boundary);
    const fit = fitBestQuad(hull, w, h); // orientation-aware + scored
    if (fit && (!best || fit.score > best.score)) {
      best = { quad: orderQuadCorners(fit.quad), score: fit.score };
    }
  }
  return best ? scaleQuad(best.quad, 1 / scale) : null;
}

function fitBestQuad(hull: Pt[], w: number, h: number) {
  const rect = minAreaRect(hull);                 // document's orientation
  const oriented = fitQuadOriented(hull, rect.angle);

  // A real document is surrounded by background: reject blobs that fill
  // almost the whole frame — that is the background, not the document.
  const coverage = polygonArea(hull) / (w * h);
  if (coverage < 0.04 || coverage > 0.9) return null;

  const rectangularity = polygonArea(hull) / rect.area;
  // ...pick the tightest convex quad and combine the signals into a score
}

The entry point exports the current DDV page as a PNG Blob, runs detectDocumentQuad(), and opens a preview dialog. If auto-detection fails (low-contrast background, heavy shadow), a default inset quad is provided. In the dialog, the user sees the original image with the detected quadrilateral overlaid. They can drag the four corner handles to manually adjust the boundary.

export async function detectDocumentBoundary(
  handle: EditViewerHandle
): Promise<void> {
  const pageIndex = handle.viewer.getCurrentPageIndex();
  const originalBlob = await doc.saveToPng(pageIndex);

  const imgEl = await blobToImage(originalBlob);
  const detectedQuad = detectDocumentQuad(imgEl);

  // Fallback quad if detection fails
  const quad = detectedQuad ?? {
    tl: { x: imgWidth * 0.1, y: imgHeight * 0.1 },
    tr: { x: imgWidth * 0.9, y: imgHeight * 0.1 },
    br: { x: imgWidth * 0.9, y: imgHeight * 0.9 },
    bl: { x: imgWidth * 0.1, y: imgHeight * 0.9 },
  };

  const confirmed = await showDetectPreview(originalBlob, imgWidth, imgHeight, quad);
  // ... replace page with normalized result
}

When the user clicks "Confirm", the adjusted quad is used to compute a perspective-corrected image via a homography matrix — a pure pixel-level transform that runs on a temporary canvas without any library.

Step 4: Replace the Page with the Normalized Image

The normalized image replaces the original page using DDV's doc.updatePage() API, which accepts an UpdatedSource containing the new image Blob.

const pageUid = handle.viewer.indexToUid(pageIndex);
const normalizedBlob = await dataUrlToBlob(confirmed);
await doc.updatePage(pageUid, { fileData: normalizedBlob });

This preserves the document's page order and immediately reflects the change in the viewer canvas.

Step 5: Upload to Google Drive

Google Drive upload is handled entirely client-side. Google Identity Services provides the OAuth 2.0 token, and the Drive REST v3 multipart upload endpoint handles file creation.

First, load Google Identity Services and initialize the token client with the drive.file scope:

tokenClient = window.google.accounts.oauth2.initTokenClient({
  client_id: CLIENT_ID,
  scope: "https://www.googleapis.com/auth/drive.file",
  callback: (response: any) => {
    if (response.error) {
      reject(new Error(response.error_description || response.error));
      return;
    }
    accessToken = response.access_token;
    resolve();
  },
});
tokenClient.requestAccessToken({ prompt: "consent" });

For PDF upload, DDV's doc.saveToPdf() produces a flattened PDF Blob that is sent to Drive via a multipart/related request:

async function uploadAsPdf(doc: any): Promise<void> {
  const blob = await doc.saveToPdf({ saveAnnotation: "flatten" });
  const fileName = `${timestampedName()}.pdf`;
  const result = await uploadFile(blob, fileName, "application/pdf");
  openInDrive(result.id);
}

The multipart upload builds a boundary-delimited body containing JSON metadata and the file bytes:

const boundary = "-------dynamsoft_upload_" + Math.random().toString(36).slice(2);

const metadataBlob = new Blob([
  `--${boundary}\r\nContent-Type: application/json; charset=UTF-8\r\n\r\n`,
  JSON.stringify(metadata),
  `\r\n--${boundary}\r\nContent-Type: ${mimeType}\r\n\r\n`,
]);
const body = new Blob([metadataBlob, blob, new Blob([`\r\n--${boundary}--`])], {
  type: `multipart/related; boundary="${boundary}"`,
});

const res = await fetch(DRIVE_UPLOAD_URL, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": `multipart/related; boundary="${boundary}"`,
  },
  body,
});

For image upload, each page is exported as a PNG via doc.saveToPng(i) and uploaded individually. After a successful upload, the file is opened in a new tab via window.open().

Source Code

https://github.com/yushulx/web-twain-document-scan-management/tree/main/examples/pdf-image-annotation

How to Build a Browser Document Annotation Studio with PDF, Image, and Scanner Capture in TypeScript

Xiao Ling — Tue, 16 Jun 2026 06:11:51 +0000

Teams that work with contracts, invoices, forms, and evidence need more than a passive viewer. They need a browser app that can assemble pages from PDFs, image files, and scanners, annotate the result, remove pages, and export a finished document, all without uploading sensitive files to a server.

This tutorial builds that app with Dynamsoft Document Viewer (DDV) v4, Dynamic Web TWAIN (DWT), Vite, and TypeScript.

What you'll build: a client-side document annotation studio that opens PDFs and images, appends additional files instead of replacing the current document, captures pages from a scanner through Dynamic Web TWAIN, creates movable redaction marks and stamps, deletes unwanted pages, and exports to PDF, PNG, JPEG, or TIFF.

Demo: Assemble, Annotate, Redact, and PDF Export in the Browser

The video below shows the complete workflow in action: opening a PDF, appending images and scanned pages, adding a movable redaction mark and an approval stamp, deleting an unwanted page, and exporting the finished document as an editable PDF.

Prerequisites

Node.js 18+
dynamsoft-document-viewer@^4.0.0
A Dynamsoft Document Viewer license key for production Get a 30-day free trial license
Optional scanner capture:
- Dynamic Web TWAIN license key
- Dynamic Web TWAIN Service installed/running on the client machine
- A supported TWAIN/WIA/ICA/SANE/eSCL scanner

Optionally create .env.local to pre-fill the license input:

VITE_DDVR_LICENSE="your-document-viewer-license"
VITE_DWT_LICENSE="your-dynamic-web-twain-license"

Step 1: Scaffold the Vite + TypeScript Project

The project has one npm runtime dependency because DWT is loaded lazily from CDN in scanner.ts:

{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "dynamsoft-document-viewer": "^4.0.0"
  },
  "devDependencies": {
    "typescript": "^5.6.0",
    "vite": "^6.0.0"
  }
}

Run:

npm install
npm run dev

Then open http://localhost:5173/.

Step 2: License Screen, DDV Init, and the EditViewer

When the app opens, a license screen appears first. The user can paste their own DDV license key or click "Use Default License" to proceed with a built-in trial key. A link to the Dynamsoft trial license page is provided for those who need one. Once a license is chosen, the app hides the license screen and initializes the DDV engine.

import { DDV } from "dynamsoft-document-viewer";

const DEFAULT_LICENSE =
  "DLS2eyJ..."; // built-in trial key

const ENV_LICENSE: string | undefined =
  import.meta.env.VITE_DDVR_LICENSE;

const ENGINE_RESOURCE_PATH =
  "https://cdn.jsdelivr.net/npm/dynamsoft-document-viewer@4.0.0/dist/engine";

async function initDDV(license: string): Promise<void> {
  DDV.Core.license = license;
  DDV.Core.engineResourcePath = ENGINE_RESOURCE_PATH;
  await DDV.Core.init();
  DDV.setProcessingHandler("imageFilter", new DDV.ImageFilter());
}

The waitForLicense() function returns a Promise<string> that resolves when the user clicks Activate or Use Default License. The bootstrap sequence awaits it before showing the WASM loading overlay.

The EditViewer is configured with a built-in DDV toolbar and a left thumbnail rail:

const options: EditViewerConstructorOptions = {
  container,
  uiConfig: buildUiConfig(),
  thumbnailConfig: {
    visibility: "visible",
    position: "left",
    size: "204px",
    columns: 1,
    multiselectMode: false,
  },
};

const viewer = new EditViewer(options);

The app keeps file, scan, quick action, and export controls in its own header, while DDV owns the in-canvas editing toolbar. The text-search switch is omitted because it is not part of the required workflow.

Step 3: Append PDFs and Images Instead of Replacing the Document

The key change from a simple viewer is that opening another image should append pages to the active document. DDV supports this through doc.loadSource(source, index).

import { DDV, PdfSource, Source } from "dynamsoft-document-viewer";

async function loadIntoViewer(
  handle: EditViewerHandle,
  fileData: Blob,
  password?: string,
  fileName?: string
): Promise<void> {
  const { docManager, viewer } = handle;
  const existing = viewer.currentDocument;
  const doc = existing ?? docManager.createDocument();
  const insertAt = doc.pages.length;

  const isPdf =
    fileData.type === "application/pdf" ||
    fileData.type === "application/x-pdf" ||
    (fileData.type === "" && /\.(pdf)$/i.test(fileName ?? ""));

  if (isPdf) {
    // PDF: use PdfSource with convertMode, password, and renderOptions
    // for annotation round-trip support.
    const pdfSource: PdfSource = {
      fileData,
      convertMode: DDV.EnumConvertMode.CM_AUTO,
      password: password ?? "",
      renderOptions: {
        renderAnnotations: DDV.EnumAnnotationRenderMode.LOAD_ANNOTATIONS,
      },
    };
    await doc.loadSource(pdfSource, insertAt);
  } else {
    // Image (PNG/JPEG/TIFF/BMP): use plain Source — no convertMode needed.
    const imgSource: Source = { fileData };
    await doc.loadSource(imgSource, insertAt);
  }

  if (!existing) viewer.openDocument(doc.uid);
  viewer.goToPage(insertAt);
  document.dispatchEvent(new CustomEvent("app:document-opened"));
}

PDFs use a PdfSource with convertMode, password, and renderOptions for annotation round-trip support. Images use a plain Source object. Some browsers assign an empty Blob.type for certain PDFs, so the filename extension is checked as a fallback.

With this logic, selecting multiple image files creates a multi-page DDV document. Selecting more files later adds more pages to that same document.

Step 4: Delete the Current Page

Unwanted pages are removed with deletePages():

export function deleteCurrentPage(handle: EditViewerHandle): void {
  const doc = handle.getCurrentDoc();
  if (!doc) {
    showToast("Open a document first.", "error");
    return;
  }

  const index = handle.viewer.getCurrentPageIndex();
  if (index < 0) return;

  const ok = doc.deletePages([index]);
  if (!ok) {
    showToast("Could not delete the current page.", "error");
    return;
  }

  if (doc.pages.length === 0) {
    const uid = doc.uid;
    handle.viewer.closeDocument();
    try {
      handle.docManager.deleteDocuments([uid]);
    } catch {
      /* already deleted */
    }
    document.dispatchEvent(new CustomEvent("app:document-closed"));
    showToast("Removed the last page.", "success");
    return;
  }

  handle.viewer.goToPage(Math.min(index, doc.pages.length - 1));
  document.dispatchEvent(new CustomEvent("app:page-changed"));
  showToast("Page deleted.", "success");
}

When the last page is deleted, the document is closed and cleaned up via deleteDocuments() (wrapped in try/catch because DDV may have already disposed it). The header disables document-dependent actions through the app:document-closed event.

Step 5: Add Scanner Capture with Dynamic Web TWAIN

Browsers do not expose a standard scanner API, so scanner capture uses Dynamic Web TWAIN and its local service. The app loads DWT lazily only when the user refreshes scanners or starts scanning.

const DWT_VERSION = "19.4.1";
const DWT_CDN = `https://cdn.jsdelivr.net/npm/dwt@${DWT_VERSION}/dist`;
const DWT_SERVICE_INSTALLER_PATH = `https://unpkg.com/dwt@${DWT_VERSION}/dist/dist`;
const DWT_SCRIPT = `${DWT_CDN}/dynamsoft.webtwain.min.js`;
const DWT_LICENSE = import.meta.env.VITE_DWT_LICENSE ?? "";

The service installer path is important. The installers are under dist/dist. If you set:

Dynamsoft.DWT.ServiceInstallerLocation =
  "https://cdn.jsdelivr.net/npm/dwt@latest/dist";

DWT may try to download a wrong URL such as:

https://cdn.jsdelivr.net/npm/dwt@latest/dist/DynamicWebTWAINServiceSetup.msi

Use https://unpkg.com/dwt@19.4.1/dist/dist or self-host the SDK's service installers.

The scanner bridge creates a headless WebTwain object:

async function getDwtObject(): Promise<any> {
  await ensureDwtLoaded();

  const dwt = window.Dynamsoft?.DWT;
  dwt.ResourcesPath = DWT_CDN;
  dwt.ServiceInstallerLocation = DWT_SERVICE_INSTALLER_PATH;
  dwt.ProductKey = DWT_LICENSE;
  dwt.UseLocalService = true;

  return new Promise((resolve, reject) => {
    dwt.CreateDWTObjectEx(
      { WebTwainId: "scanBridge" },
      (object: any) => resolve(object),
      (error: any) => reject(error)
    );
  });
}

Listing and scanning use the modern async DWT APIs:

export async function listScanners(refresh = false): Promise<ScannerOption[]> {
  const dwt = await getDwtObject();
  devices = await dwt.GetDevicesAsync(undefined, refresh);
  return devices.map((device, index) => ({
    index,
    name: scannerName(device, index),
  }));
}

export async function scanFromDevice(deviceIndex: number): Promise<ScanResult | null> {
  const dwt = await getDwtObject();
  if (!devices.length) devices = await dwt.GetDevicesAsync(undefined, true);

  const device = devices[deviceIndex];
  if (!device) {
    showToast("Select a scanner first.", "error");
    return null;
  }

  const before = imageCount(dwt);
  setBusy(true, `Scanning from ${scannerName(device, deviceIndex)}\u2026`);

  try {
    await dwt.SelectDeviceAsync(device);
    await dwt.AcquireImageAsync({
      IfShowUI: false,
      IfCloseSourceAfterAcquire: true,
      IfFeederEnabled: true,
      IfDuplexEnabled: false,
      PixelType: window.Dynamsoft?.DWT?.EnumDWT_PixelType?.TWPT_RGB ?? 2,
      Resolution: 200,
    });

    const after = imageCount(dwt);
    if (after <= before) {
      showToast("No pages were scanned.", "info");
      return null;
    }

    const indices = Array.from({ length: after - before }, (_, i) => before + i);
    const blob = await convertToPdfBlob(dwt, indices);
    return { blob, pageCount: indices.length };
  } finally {
    setBusy(false);
  }
}

The scanned pages are converted to a PDF blob via ConvertToBlob() and appended with the same DDV loading path used for ordinary files. IfShowUI: false avoids showing the scanner vendor's TWAIN configuration dialog and makes the Scan button behave like a quick action. The before/after image count comparison handles scanners that already had images in the buffer.

Step 6: Create Movable Redaction Marks and Stamps

Programmatic annotations use PDF point units, and coordinates should come from pageData.mediaBox.

Quick Redact creates a redaction annotation and selects it, but does not immediately apply the redaction because users need to move or resize the region first.

export function quickRedact(handle: EditViewerHandle): void {
  const ctx = currentPageUid(handle);
  if (!ctx) {
    showToast("Open a page first.", "error");
    return;
  }

  const { pageUid, mediaBox } = ctx;
  const width = mediaBox.width * 0.5;
  const height = mediaBox.height * 0.12;
  const x = (mediaBox.width - width) / 2;
  const y = (mediaBox.height - height) / 2;

  const created = DDV.annotationManager.createAnnotation(pageUid, "redaction", {
    redactionType: "rectangle",
    background: "#000000",
    rects: [{ x, y, width, height }],
    overlayText: {
      text: "REDACTED",
      color: "#ffffff",
      textAlign: "center",
      fontSize: 10,
      repeatText: true,
      autoFontSize: true,
    },
  });

  handle.viewer.selectAnnotations([created.uid]);
  showToast(
    "Redaction mark added. Move or resize it, then apply it from the redaction toolbar.",
    "info"
  );
}

When the mark is correct, apply permanent redaction from DDV's redaction toolbar. Permanent redaction destroys underlying content, while a redaction annotation alone only marks the region.

The approval stamp uses a movable textBox annotation:

DDV.annotationManager.createAnnotation(pageUid, "textBox", {
  x,
  y,
  width,
  height,
  borderColor: "transparent",
  background: "rgba(255, 214, 0, 0.9)",
  textContents: [
    {
      content: stampText,
      color: "#1a1a1a",
      fontSize: 13,
      fontFamily: "Helvetica",
      fontWeight: "bold",
    },
  ],
});

Step 7: Export the Finished Document

DDV exports the current assembled document. The exported filename is generated from the current time, such as annotation-studio-20260615-143022.pdf, rather than from any imported file. This keeps exports predictable when the document was assembled from many files and scanned pages.

switch (format) {
  case "pdf-editable": {
    setBusy(true, "Exporting PDF (editable)\u2026");
    const blob = await doc.saveToPdf({ saveAnnotation: "annotation" });
    saveBlob(blob, `${base}.pdf`);
    break;
  }
  case "pdf-flatten": {
    setBusy(true, "Exporting PDF (flattened)\u2026");
    const blob = await doc.saveToPdf({ saveAnnotation: "flatten" });
    saveBlob(blob, `${base}.pdf`);
    break;
  }
  case "pdf-image": {
    setBusy(true, "Exporting PDF (as image)\u2026");
    const blob = await doc.saveToPdf({ saveAnnotation: "image" });
    saveBlob(blob, `${base}.pdf`);
    break;
  }
  case "png": {
    setBusy(true, "Exporting PNG\u2026");
    const count = doc.pages.length;
    for (let i = 0; i < count; i++) {
      const blob = await doc.saveToPng(i);
      saveBlob(blob, count > 1 ? `${base}_page${i + 1}.png` : `${base}.png`);
    }
    break;
  }
  case "jpeg": {
    setBusy(true, "Exporting JPEG\u2026");
    const count = doc.pages.length;
    for (let i = 0; i < count; i++) {
      const blob = await doc.saveToJpeg(i, { quality: 90 });
      saveBlob(blob, count > 1 ? `${base}_page${i + 1}.jpg` : `${base}.jpg`);
    }
    break;
  }
  case "tiff": {
    setBusy(true, "Exporting TIFF\u2026");
    const blob = await doc.saveToTiff({
      compression: DDV.EnumTIFFCompressionType.TIFF_AUTO,
    });
    saveBlob(blob, `${base}.tif`);
    break;
  }
}

The PDF annotation modes are:

"annotation": preserve editable PDF annotations.
"flatten": burn annotations into visible page content.
"image": rasterize each page.
"none": discard annotations.

JPEG export uses saveToJpeg(pageIndex, { quality: 90 }) for compressed output. TIFF export uses saveToTiff({ compression: TIFF_AUTO }) to produce a single multi-page TIFF archive. PNG and JPEG export one file per page, and multi-page documents get a _pageN suffix.

Source Code

https://github.com/yushulx/web-twain-document-scan-management/tree/main/examples/pdf-image-annotation

How to Build a Windows Desktop Document Scanner with OCR and Layout Analysis in Python

Xiao Ling — Fri, 12 Jun 2026 07:59:37 +0000

Paper documents still enter desktop workflows through scanners, but many sample apps stop at acquisition and never connect the pages to a practical OCR workflow. This project fills that gap with a Windows desktop application that scans documents through Dynamic Web TWAIN Service, runs local layout analysis, and lets users compare multiple OCR backends inside one PySide6 interface.

The current app supports three OCR options:

OneOCR for Windows-native OCR with text boxes.
PaddleOCR for fully local OCR with returned text coordinates.
Ollama (GLM-OCR) as an optional backend when you want to experiment with VLM-style OCR.

Ollama is intentionally optional here. On a CPU-only PC, it may be much slower than the other local OCR choices.

What you'll build: A Windows PySide6 desktop app that scans paper documents, visualizes layout regions, and runs full-page or region-level OCR with Dynamic Web TWAIN Service, PP-DocLayoutV3, OneOCR, PaddleOCR, and an optional Ollama backend.

Demo Video: Windows Document Scanner and OCR App

Prerequisites

Windows with Python 3.11 or later.
PySide6, Pillow, PyTorch, transformers, NumPy, and twain-wia-sane-scanner.
Dynamic Web TWAIN Service installed and reachable at http://127.0.0.1:18622.
A Dynamic Web TWAIN license key for scanner access.

Optional OCR backends:

OneOCR on Windows, plus its runtime files from Windows 11 Snipping Tool.
PaddleOCR with either paddle_static or transformers inference.
Ollama with glm-ocr:latest if you want to test an LLM OCR backend.

Get a 30-day free trial license

Step 1: Install Python Dependencies and Configure the OCR Environment

Install the same packages used by the sample project.

python -m pip install -r requirements.txt

If you want the PP-DocLayoutV3 layout model to run fully offline, download it once before launching the app:

huggingface-cli download PaddlePaddle/PP-DocLayoutV3_safetensors --local-dir D:\models\PP-DocLayoutV3_safetensors

$env:LAYOUT_MODEL_DIR="D:\models\PP-DocLayoutV3_safetensors"
$env:LAYOUT_LOCAL_ONLY="1"

The current dependency set is:

PySide6>=6.5
Pillow>=9.0
torch>=2.0
transformers>=4.0
numpy>=1.20
twain-wia-sane-scanner>=2.0.3
oneocr>=1.0.12; platform_system == "Windows"
paddleocr>=3.6.0

If you want to enable the optional Ollama backend as well:

ollama pull glm-ocr:latest

Step 2: Define OCR Engine Keys and Runtime Defaults

The Python app defines explicit OCR engine keys and lets the UI switch between them.

OCR_ENGINE_OLLAMA = "ollama"
OCR_ENGINE_ONEOCR = "oneocr"
OCR_ENGINE_PADDLEOCR = "paddleocr"
OCR_ENGINE_LABELS = {
    OCR_ENGINE_OLLAMA: "Ollama (GLM-OCR)",
    OCR_ENGINE_ONEOCR: "OneOCR",
    OCR_ENGINE_PADDLEOCR: "PaddleOCR",
}


def _default_paddleocr_engine() -> str:
    if importlib.util.find_spec("paddle") is not None:
        return "paddle_static"
    return "transformers"


PADDLEOCR_ENGINE = os.environ.get("PADDLEOCR_ENGINE", _default_paddleocr_engine())
PADDLEOCR_DEVICE = os.environ.get(
    "PADDLEOCR_DEVICE",
    "gpu" if torch.cuda.is_available() else "cpu",
)
PADDLEOCR_DET_MODEL = os.environ.get("PADDLEOCR_DET_MODEL", "PP-OCRv5_mobile_det")
PADDLEOCR_REC_MODEL = os.environ.get("PADDLEOCR_REC_MODEL", "PP-OCRv5_mobile_rec")
LAYOUT_MODEL_DIR = os.environ.get("LAYOUT_MODEL_DIR", "").strip()
LAYOUT_LOCAL_ONLY = os.environ.get("LAYOUT_LOCAL_ONLY", "").strip().lower() in {
    "1", "true", "yes", "on"
}

This keeps desktop defaults practical. In particular, PaddleOCR now prefers the lighter PP-OCRv5 mobile detection and recognition models, which are much more suitable than heavier defaults on a typical PC.

For layout analysis, the same idea applies: you can either let transformers resolve PaddlePaddle/PP-DocLayoutV3_safetensors through the default endpoint or mirror you provide, or you can point the app at a pre-downloaded local directory and run without network access.

Step 3: Build a Toolbar with Separate Layout and OCR Actions

The current UI makes layout analysis a first-class action. That keeps the workflow explicit and avoids surprising users when OCR silently changes the overlay.

self.layout_action = QAction("Layout Analysis", self)
self.layout_action.setIcon(QIcon.fromTheme("insert-object"))
self.layout_action.triggered.connect(self._on_layout_clicked)
self.layout_action.setEnabled(False)
toolbar.addAction(self.layout_action)

self.ocr_action = QAction("Run OCR", self)
self.ocr_action.setIcon(QIcon.fromTheme("find"))
self.ocr_action.triggered.connect(self._on_ocr_clicked)
self.ocr_action.setEnabled(False)
toolbar.addAction(self.ocr_action)

self.ocr_engine_combo = QComboBox()
self.ocr_engine_combo.currentIndexChanged.connect(self._on_ocr_engine_changed)
toolbar.addWidget(self.ocr_engine_combo)

self.ocr_mode_label = QLabel("Mode:")
toolbar.addWidget(self.ocr_mode_label)

self.ocr_mode_combo = QComboBox()
self.ocr_mode_combo.addItems([
    "Text Recognition", "Table Recognition", "Figure Recognition",
])
toolbar.addWidget(self.ocr_mode_combo)

The Mode control is only relevant to Ollama (GLM-OCR), so the app hides it for the other engines instead of pretending every OCR backend shares the same prompt model.

Step 4: Run Layout Analysis Independently Before OCR

Layout Analysis runs PP-DocLayoutV3 by itself and draws an overlay of document regions without triggering any OCR pass.

class LayoutAnalysisWorker(QThread):
    layout_ready = Signal(LayoutResult)
    progress = Signal(str)
    error = Signal(str)

    def __init__(self, image_path: str, parent=None):
        super().__init__(parent)
        self.image_path = image_path

    def run(self):
        self.progress.emit("Running layout analysis...")
        OcrWorker.ensure_model_loaded()
        img = Image.open(self.image_path).convert('RGB')
        inputs = OcrWorker._processor(images=[img], return_tensors='pt')
        inputs = {key: value.to(OcrWorker._device) for key, value in inputs.items()}
        target_sizes = torch.tensor([img.size[::-1]], device=OcrWorker._device)

        with torch.no_grad():
            outputs = OcrWorker._model(**inputs)

        raw_results = OcrWorker._processor.post_process_object_detection(
            outputs, threshold=LAYOUT_THRESHOLD, target_sizes=target_sizes
        )[0]

Internally, the shared layout loader supports both cached and explicit local-directory loading:

model_source = LAYOUT_MODEL_DIR or LAYOUT_MODEL_ID
load_kwargs: Dict[str, Any] = {}
if LAYOUT_LOCAL_ONLY or LAYOUT_MODEL_DIR:
    load_kwargs["local_files_only"] = True

cls._processor = PPDocLayoutV3ImageProcessor.from_pretrained(model_source, **load_kwargs)
cls._model = PPDocLayoutV3ForObjectDetection.from_pretrained(model_source, **load_kwargs)

You can choose your own download source when preparing the model, or skip the network entirely by shipping the model folder with your deployment.

The overlay preserves more than just text targets. Text, table, and formula regions remain interactive, while non-text categories such as image stay visible with their own coloring and labels.

This matters because PP-DocLayoutV3 can tell you that a region is broadly an image block, but it does not distinguish whether that image is a portrait, logo, illustration, or seal. If you want portrait detection, you need an extra classifier or detector on top of the layout model.

Step 5: Let Coordinate-Aware OCR Replace the Layout Overlay

Some OCR engines can return text coordinates directly. In that case, the app uses OCR-native boxes instead of leaving the earlier layout overlay on screen.

def _engine_returns_text_coordinates(engine_key: str) -> bool:
    return engine_key in {OCR_ENGINE_ONEOCR, OCR_ENGINE_PADDLEOCR}

When the user clicks Run OCR, the app clears any existing layout result for coordinate-aware engines so the overlay gets rebuilt from OCR output:

def _on_ocr_clicked(self):
    if self.selected_item is None or self.worker is not None or self.layout_worker is not None:
        return

    self._set_busy(True)
    self.ocr_result = None
    self.result_text.clear()

    if self.selected_item is not None:
        self.selected_item.ocr_result = None
        if _engine_returns_text_coordinates(self.selected_ocr_engine):
            self.selected_item.layout_result = None

    self.worker = OcrWorker(
        self.selected_item.file_path,
        mode=self.ocr_mode_combo.currentText(),
        engine_key=self.selected_ocr_engine,
    )

That design gives users a predictable workflow:

Layout Analysis shows document structure.
Run OCR returns text.
OneOCR and PaddleOCR can replace the overlay with text boxes.
OCR engines without coordinates do not destroy the existing layout overlay.

Step 6: Use OneOCR and PaddleOCR as Coordinate-Aware Backends

OneOCR is Windows-only, but it returns OCR line boxes directly. The app converts those boxes into the same normalized overlay format used elsewhere.

if self.engine_key == OCR_ENGINE_ONEOCR:
    self.progress.emit("Running OneOCR...")
    engine = _ensure_oneocr_engine_loaded()
    raw_result = engine.recognize_pil(img)
    layout_result = _build_oneocr_layout_result(raw_result, img.size[0], img.size[1])
    if layout_result.has_coordinates:
        self.layout_ready.emit(layout_result)
    full_text = _clean_content(_extract_oneocr_text(raw_result))
    self.ocr_done.emit(OcrResult(
        text=full_text,
        line_count=layout_result.region_count,
        has_coordinates=layout_result.has_coordinates,
        raw_response=full_text,
    ))
    return

PaddleOCR can do the same thing. In this project, its result payload exposes rec_polys, rec_boxes, and dt_polys, so the app can build overlay boxes directly from OCR output.

if self.engine_key == OCR_ENGINE_PADDLEOCR:
    self.progress.emit("Running PaddleOCR...")
    engine = _ensure_paddleocr_engine_loaded()
    raw_result = _predict_with_paddleocr(engine, image_path=self.image_path)
    layout_result = _build_paddleocr_layout_result(raw_result, img.size[0], img.size[1])
    if layout_result.has_coordinates:
        self.layout_ready.emit(layout_result)
    full_text = _clean_content(_extract_paddleocr_text(raw_result))
    self.ocr_done.emit(OcrResult(
        text=full_text,
        line_count=layout_result.region_count,
        has_coordinates=layout_result.has_coordinates,
        raw_response=full_text,
    ))
    return

That means both engines can behave like coordinate-aware desktop OCR, not just plain text extractors.

Step 7: Keep Ollama as an Optional LLM OCR Backend

The app still supports Ollama (GLM-OCR), but it is now treated as optional. On a machine without GPU acceleration, it can be much slower than OneOCR or PaddleOCR, so it should not define the title or the main architecture.

The integration is still useful when you want prompt-controlled OCR modes such as text, table, or formula recognition.

def _backend_supports_prompt_modes(engine_key: str) -> bool:
    return engine_key == OCR_ENGINE_OLLAMA


def _ocr_generate_b64_list(image_payloads: List[bytes], prompt: str,
                           model: str = OLLAMA_MODEL) -> str:
    payload = _ollama_generate_request(prompt=prompt, image_payloads=image_payloads, model=model)
    return payload.get("response", "") or ""

If you do not need it, you can simply use OneOCR or PaddleOCR and ignore the Ollama setup entirely.

Step 8: OCR Individual Layout Regions on Demand

Instead of OCRing every region immediately, the app lets users click a single highlighted block and OCR only that crop.

class RegionOcrWorker(QThread):
    region_ocr_done = Signal(int, str)
    error = Signal(str)

    def run(self):
        try:
            cropped_image = _prepare_region_image(self.image_path, self.bbox_2d)
            content = _ocr_with_engine(
                self.engine_key,
                pil_image=cropped_image,
                task_type=self.task_type,
            )
            display_text = _clean_content(content)
            self.region_ocr_done.emit(self.region_index, display_text)
        except Exception as e:
            import traceback
            self.error.emit(f"Region OCR failed: {e}\n\n{traceback.format_exc()}")

The preview widget distinguishes between interactive OCR targets and non-text layout regions.

def _is_clickable_region(line: OcrLine) -> bool:
    return line.task_type in {"text", "table", "formula"}

Step 9: Scan Pages Through Dynamic Web TWAIN Service

On the scanner side, the project uses twain-wia-sane-scanner to talk to Dynamic Web TWAIN Service. It enumerates TWAIN and WIA devices, creates a job, streams pages, and saves them as images for the same OCR workflow.

class ScanWorker(QThread):
    page_scanned = Signal(str)
    scan_done = Signal(int)
    error = Signal(str)
    progress = Signal(str)

    def run(self):
        controller = ScannerController(timeout=120, raise_errors=True)
        job_id = ""
        page_count = 0
        job = controller.createJob(self.host, {
            "license": self.license_key,
            "device": self.device,
            "autoRun": False,
            "jobTimeout": 180,
            "scannerFailureTimeout": 90,
            "config": DWT_SCAN_CONFIG,
        })
        job_id = job.get("jobuid", "")
        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")

        while True:
            image_bytes = controller.getImageStream(self.host, job_id, imageType="image/png")
            if image_bytes is None:
                break

            page_count += 1
            image_path = self.output_dir / f"scan_{timestamp}_{page_count:03d}.png"
            image_path.write_bytes(image_bytes)
            self.page_scanned.emit(str(image_path))

The scan configuration passed to createJob disables the native scanner UI and enables the document feeder so multi-page scans flow unattended:

DWT_SCAN_CONFIG = {
    "IfShowUI": False,
    "PixelType": 2,
    "Resolution": 200,
    "IfFeederEnabled": True,
    "IfDuplexEnabled": False,
}

Step 10: Keep the UI Responsive While OCR and Scanning Run

The project also guards against a common desktop pitfall: destroying worker threads while a blocking OCR or scan request is still active.

def _has_running_worker(self) -> bool:
    return any(
        worker is not None and worker.isRunning()
        for worker in (
            self.worker,
            self.layout_worker,
            self.region_worker,
            self.scan_worker,
            self.preload_worker,
        )
    )

When the user tries to close the window, closeEvent checks this helper and shows a message box instead of letting Qt destroy live threads.

Source Code

https://github.com/yushulx/python-twain-wia-sane-scanner/tree/main/example/pyside6-ocr

How to Choose a Barcode Reader for Retail Checkout Systems

Xiao Ling — Tue, 09 Jun 2026 07:08:01 +0000

Retail checkout is unforgiving: a scanner that misreads a UPC, chokes on a wrinkled GS1-128 logistics label, or stalls on a loyalty QR code slows every lane in the store. Choosing the right barcode reader means matching the symbologies, platform, and decode reliability that a point-of-sale (POS) terminal actually needs. This tutorial walks through those decision criteria and then proves them out with a desktop Python scanner built with PySide6 and the Dynamsoft Barcode Reader SDK.

What you'll build: A desktop POS-style scanner app in Python and PySide6 that reads every retail symbology — EAN-13, UPC-A, EAN-8, Code 128, GS1-128, and QR — from a live camera or an image file, drawing live overlays and building a deduplicated receipt with the Dynamsoft Barcode Reader Bundle.

Demo Video: Scanning a Self-Checkout Frame

Open a saved checkout frame or point a webcam at the shelf — the app boxes every barcode and lists each decoded item in a receipt panel:

How to Choose a Barcode Reader for Retail Checkout

Before writing code, evaluate a reader against four checkout-specific criteria.

Symbology Coverage

Retail product codes are almost always EAN-13, UPC-A, EAN-8, or UPC-E. Beyond the till, you also meet GS1 DataBar (produce, coupons, pharmacy), Code 128 / GS1-128 (cases, weight/batch data), and increasingly QR codes for mobile loyalty and digital coupons. A reader that only handles QR — or only handles 1D codes — will fail somewhere in the store.

Platform Fit

POS terminals and self-checkout kiosks run on desktop operating systems, so the decoding engine has to be a native desktop/server SDK rather than a mobile-only component. Dynamsoft ships the same engine across Python, C++, .NET, Java, and JavaScript, so a PySide6 prototype on desktop maps cleanly to a production C++ or .NET till.

Multi-Code Decoding

Self-checkout cameras and "scan-as-you-bag" stations capture several items at once. The reader must return every barcode in a frame — with its location — not just the first one it finds.

Decode Reliability

Real labels are wrinkled, glare-lit, rotated, and partially occluded. Production-grade engines apply localization, deblurring, and grayscale enhancement automatically — features a hand-rolled or open-source decoder rarely matches.

The app below satisfies all four with the Dynamsoft Barcode Reader Bundle.

Prerequisites

Python 3.8+
Dynamsoft Barcode Reader Bundle 11.2.5000 (pip install dynamsoft-barcode-reader-bundle)
PySide6, opencv-python, and numpy for the desktop UI and camera
python-barcode, qrcode, and Pillow to synthesize the sample image set
A Dynamsoft license key

Get a 30-day free trial license at dynamsoft.com/customer/license/trialLicense

Install everything:

pip install dynamsoft-barcode-reader-bundle==11.2.5000 PySide6 opencv-python numpy python-barcode qrcode Pillow

Step 1: Generate a Realistic Retail Image Set

To test without a physical scanner, the project synthesizes product "packages" — a colored card with a name band and a barcode panel — and scatters them on a conveyor-belt background, the way an overhead self-checkout camera sees them. The catalog mixes every symbology a checkout meets:

# (filename, product label, symbology, value, card color)
CATALOG = [
    ("cereal_box", "Morning Oat Cereal 500g", "ean13", "4006381333931", (255, 214, 102)),
    ("soda_can", "Cola Classic 330ml", "upca", "036000291452", (214, 69, 65)),
    ("gum_pack", "Mint Gum", "ean8", "96385074", (120, 200, 160)),
    ("milk_carton", "Whole Milk 1L", "ean13", "5012345678900", (235, 238, 245)),
    ("shipping_label", "Backroom Carton", "code128", "SKU-7741-CASE24", (206, 178, 140)),
    ("weighed_produce", "Bananas (GS1-128)", "gs1_128", "0109501101530003", (245, 224, 120)),
]

Run it to produce images/products/*.png and images/checkout-belt.png:

python generate_retail_images.py

Step 2: Configure the SDK for Retail Symbologies

The decoding engine lives in a small RetailBarcodeEngine class. It initializes the license once, then restricts decoding to retail formats so the reader skips irrelevant work and avoids false reads. Setting expected_barcodes_count = 0 tells it to return every code in a frame:

RETAIL_FORMATS = (
    EnumBarcodeFormat.BF_ONED
    | EnumBarcodeFormat.BF_GS1_DATABAR
    | EnumBarcodeFormat.BF_QR_CODE
)

class RetailBarcodeEngine:
    """Wraps a CaptureVisionRouter configured for retail symbologies."""

    def __init__(self, license_key):
        err_code, err_str = LicenseManager.init_license(license_key)
        if err_code != EnumErrorCode.EC_OK and err_code != EnumErrorCode.EC_LICENSE_WARNING:
            raise RuntimeError(f"License initialization failed: {err_str}")
        self.cvr = CaptureVisionRouter()
        err_code, err_str, settings = self.cvr.get_simplified_settings(
            EnumPresetTemplate.PT_READ_BARCODES)
        settings.barcode_settings.barcode_format_ids = RETAIL_FORMATS
        settings.barcode_settings.expected_barcodes_count = 0
        self.cvr.update_settings(EnumPresetTemplate.PT_READ_BARCODES, settings)

Step 3: Decode a Frame and Capture Barcode Locations

A POS UI needs both the text and the position of every code so it can draw overlays. decode_bgr accepts an OpenCV frame, wraps it in an ImageData, and returns the format, text, and corner points for each barcode:

def decode_bgr(self, frame):
    """Decode a BGR numpy frame; return a list of {format, text, points}."""
    frame = np.ascontiguousarray(frame)
    image_data = ImageData(
        frame.tobytes(), frame.shape[1], frame.shape[0],
        frame.strides[0], EnumImagePixelFormat.IPF_RGB_888,
    )
    result = self.cvr.capture(image_data, EnumPresetTemplate.PT_READ_BARCODES)
    barcode_result = result.get_decoded_barcodes_result()
    items = []
    if barcode_result is not None:
        for item in barcode_result.get_items():
            location = item.get_location()
            points = [(p.x, p.y) for p in location.points]
            items.append({
                "format": item.get_format_string(),
                "text": item.get_text(),
                "points": points,
            })
    return items

The same decode_bgr powers both the image-file mode and the live camera, so there is a single decode path to maintain.

Step 4: Draw Live Overlays Over Each Barcode

With the corner points in hand, drawing a bounding box and a symbology label is a few lines of OpenCV:

def draw_overlays(frame, items):
    """Draw green quadrilaterals and labels over each decoded barcode."""
    annotated = frame.copy()
    for item in items:
        pts = np.array(item["points"], dtype=np.int32)
        cv2.polylines(annotated, [pts], True, (0, 200, 0), 3)
        x, y = pts[0]
        cv2.putText(annotated, item["format"], (int(x), int(y) - 10),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 200, 0), 2)
    return annotated

Step 5: Stream the Camera on a Background Thread

Decoding every frame on the UI thread would freeze the window, so a QThread grabs frames, decodes them, and emits the annotated image plus the results back to the GUI:

class CameraWorker(QThread):
    """Grabs camera frames, decodes each one, and emits annotated results."""

    frame_ready = Signal(QImage, list)

    def __init__(self, engine, cam_index=0):
        super().__init__()
        self.engine = engine
        self.cam_index = cam_index
        self._running = False

    def run(self):
        cap = cv2.VideoCapture(self.cam_index)
        if not cap.isOpened():
            return
        self._running = True
        while self._running:
            ok, frame = cap.read()
            if not ok:
                break
            items = self.engine.decode_bgr(frame)
            annotated = draw_overlays(frame, items)
            self.frame_ready.emit(bgr_to_qimage(annotated), items)
        cap.release()

    def stop(self):
        self._running = False
        self.wait()

Step 6: Build the POS Receipt and Wire Up the UI

The main window shows the live preview on the left and an accumulating, deduplicated "receipt" table on the right. Both Open Image and Start Camera feed the same add_to_receipt method:

def add_to_receipt(self, item):
    key = (item["format"], item["text"])
    if key in self.seen:
        return
    self.seen.add(key)
    row = self.table.rowCount()
    self.table.insertRow(row)
    fmt_item = QTableWidgetItem(item["format"])
    fmt_item.setForeground(QColor("#1d8a4a"))
    self.table.setItem(row, 0, fmt_item)
    self.table.setItem(row, 1, QTableWidgetItem(item["text"]))
    self.count_label.setText(f"{len(self.seen)} unique items")

Run the app:

python retail_scanner_gui.py

Click Open Image and choose images/checkout-belt.png to decode all seven barcodes in one frame, or click Start Camera to scan real products live. Each unique code lands in the receipt exactly once.

Source Code

https://github.com/yushulx/python-barcode-qrcode-sdk/tree/main/examples/official/retail-checkout

How to Share a TWAIN Scanner Securely Over a LAN with Python FastAPI and Dynamic Web TWAIN

Xiao Ling — Tue, 02 Jun 2026 07:01:33 +0000

Shared TWAIN scanners are awkward to expose on a local network because direct LAN access does not solve identity, concurrency, or auditability. This tutorial shows how to share a TWAIN scanner securely with a Python FastAPI gateway and the Dynamic Web TWAIN Service REST API, so registered users can sign in, see shared scanner availability, and capture pages from a browser without direct access to the scanner host.

What you'll build: A Python FastAPI gateway that authenticates users, leases a shared TWAIN scanner to one operator at a time, and returns scanned pages to the browser with Dynamic Web TWAIN.

Demo Video: Secure Gateway Sign-In, Scanner Locking, and Page Preview

Prerequisites

Python 3.10 or later
Dynamic Web TWAIN Service installed on the gateway machine
A Dynamic Web TWAIN license with REST API access
FastAPI, Uvicorn, PyJWT, and python-multipart from the sample requirements
A current Dynamic Web TWAIN Service build. The repo does not pin a service version, so validate compatibility with the service once it is installed.

Get a 30-day free trial license for testing the gateway with Dynamic Web TWAIN.

Step 1: Install and Configure the Gateway

The sample keeps the web stack intentionally small, then reads the scanner host, JWT secret, admin bootstrap, and lock TTL from environment variables.

fastapi==0.115.12
uvicorn[standard]==0.30.6
PyJWT==2.9.0
python-multipart==0.0.9
twain-wia-sane-scanner==2.0.3

DWT_LICENSE_KEY=
DWT_SERVICE_HOST=http://127.0.0.1:18622
REMOTE_SCAN_JWT_SECRET=replace-with-a-long-random-secret
ACCESS_TOKEN_TTL_MINUTES=120
SCANNER_LOCK_TTL_SECONDS=600
REMOTE_SCAN_SCANNER_TYPES=0x50
DWT_SERVICE_VERIFY=true
# Optional: pre-create an admin account at startup
REMOTE_SCAN_ADMIN_USERNAME=
REMOTE_SCAN_ADMIN_PASSWORD=
REMOTE_SCAN_ADMIN_FULL_NAME=

Step 2: Store Users, Admin Roles, and Scanner Leases in SQLite

The gateway creates a WAL-mode SQLite database with an is_admin column on users, auto-promotes the earliest account when no admin exists, and enforces lock leases for scanner contention.

def init_database() -> None:
    DATABASE_PATH.parent.mkdir(parents=True, exist_ok=True)
    with get_connection() as connection:
        connection.execute('PRAGMA journal_mode=WAL')
        connection.execute(
            '''
            CREATE TABLE IF NOT EXISTS users (
                id INTEGER PRIMARY KEY AUTOINCREMENT,
                username TEXT NOT NULL UNIQUE,
                full_name TEXT NOT NULL,
                password_hash TEXT NOT NULL,
                created_at TEXT NOT NULL
            )
            '''
        )
        user_columns = {
            row['name']
            for row in connection.execute('PRAGMA table_info(users)').fetchall()
        }
        if 'is_admin' not in user_columns:
            connection.execute('ALTER TABLE users ADD COLUMN is_admin INTEGER NOT NULL DEFAULT 0')
        connection.execute(
            '''
            UPDATE users
            SET is_admin = 1
            WHERE id = (
                SELECT id
                FROM users
                ORDER BY created_at ASC, id ASC
                LIMIT 1
            )
            AND NOT EXISTS (
                SELECT 1
                FROM users
                WHERE is_admin = 1
            )
            '''
        )
        connection.execute(
            '''
            CREATE TABLE IF NOT EXISTS scanner_locks (
                scanner_id TEXT PRIMARY KEY,
                scanner_name TEXT NOT NULL,
                owner_username TEXT NOT NULL,
                lock_token TEXT NOT NULL,
                status TEXT NOT NULL,
                job_uid TEXT,
                acquired_at TEXT NOT NULL,
                expires_at TEXT NOT NULL
            )
            '''
        )
        connection.execute(
            '''
            CREATE TABLE IF NOT EXISTS audit_log (
                id INTEGER PRIMARY KEY AUTOINCREMENT,
                username TEXT NOT NULL,
                action TEXT NOT NULL,
                scanner_id TEXT,
                detail TEXT,
                created_at TEXT NOT NULL
            )
            '''
        )

Step 3: Register Users and Issue JWT Access Tokens

Registration stores a PBKDF2 hash in SQLite, auto-assigns the first registrant as administrator, and the login flow returns a short-lived bearer token that every protected route validates.

class RegistrationRequest(BaseModel):
    username: str = Field(min_length=3, max_length=50)
    full_name: str = Field(min_length=1, max_length=80)
    password: str = Field(min_length=8, max_length=128)


def create_user_account(payload: RegistrationRequest) -> Dict[str, Any]:
    username = payload.username.strip().lower()
    full_name = payload.full_name.strip()
    if not is_valid_username(username):
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail='Usernames may only include letters, numbers, dots, dashes, and underscores.',
        )

    with DB_LOCK:
        with get_connection() as connection:
            existing_user = connection.execute(
                'SELECT username FROM users WHERE username = ?',
                (username,),
            ).fetchone()
            if existing_user:
                raise HTTPException(
                    status_code=status.HTTP_409_CONFLICT,
                    detail='That username is already registered.',
                )

            created_at = utcnow_string()
            admin_exists = connection.execute(
                'SELECT 1 FROM users WHERE is_admin = 1 LIMIT 1'
            ).fetchone()
            is_admin = 0 if admin_exists else 1
            connection.execute(
                'INSERT INTO users (username, full_name, password_hash, created_at, is_admin) VALUES (?, ?, ?, ?, ?)',
                (username, full_name, hash_password(payload.password), created_at, is_admin),
            )

    write_audit_log(username, 'auth.registered')
    return {
        'username': username,
        'full_name': full_name,
        'created_at': created_at,
        'is_admin': bool(is_admin),
    }

The login endpoint validates credentials and returns a signed JWT. The token carries the username in the sub claim and an exp claim set to the configured TTL.

def create_access_token(username: str) -> TokenResponse:
    expires_at = utcnow() + timedelta(minutes=ACCESS_TOKEN_TTL_MINUTES)
    access_token = jwt.encode({'sub': username, 'exp': expires_at}, JWT_SECRET, algorithm=JWT_ALGORITHM)
    return TokenResponse(
        access_token=access_token,
        expires_in=ACCESS_TOKEN_TTL_MINUTES * 60,
    )

Every protected route extracts the token from the Authorization: Bearer header, decodes it with the shared secret, and looks up the user in SQLite. If the token is missing, expired, or maps to a deleted account, the gateway returns HTTP 401.

def get_current_user(token: str = Depends(oauth2_scheme)) -> Dict[str, Any]:
    authentication_error = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail='Could not validate credentials.',
        headers={'WWW-Authenticate': 'Bearer'},
    )
    try:
        payload = jwt.decode(token, JWT_SECRET, algorithms=[JWT_ALGORITHM])
    except jwt.InvalidTokenError:
        raise authentication_error

    username = payload.get('sub')
    if not username:
        raise authentication_error

    user_record = get_user_record(username)
    if not user_record:
        raise authentication_error

    return {
        'username': user_record['username'],
        'full_name': user_record['full_name'],
        'created_at': user_record['created_at'],
        'is_admin': bool(user_record['is_admin']),
    }

Step 4: Lock Each Shared Scanner Before Starting a Job

The gateway never starts a scan until it has written a lease record for the selected scanner, which is what lets other users see status without stealing the device mid-job.

def acquire_lock(scanner_id: str, scanner_name: str, username: str) -> Optional[Dict[str, Any]]:
    with DB_LOCK:
        with get_connection() as connection:
            prune_expired_locks(connection)
            existing_lock = connection.execute(
                'SELECT scanner_id, scanner_name, owner_username, status, job_uid, acquired_at, expires_at FROM scanner_locks WHERE scanner_id = ?',
                (scanner_id,),
            ).fetchone()
            if existing_lock and existing_lock['owner_username'] != username:
                return {
                    'scanner_id': existing_lock['scanner_id'],
                    'scanner_name': existing_lock['scanner_name'],
                    'owner_username': existing_lock['owner_username'],
                    'status': existing_lock['status'],
                    'job_uid': existing_lock['job_uid'],
                    'acquired_at': existing_lock['acquired_at'],
                    'expires_at': existing_lock['expires_at'],
                }

            now = utcnow_string()
            expires_at = (utcnow() + timedelta(seconds=SCANNER_LOCK_TTL_SECONDS)).strftime('%Y-%m-%dT%H:%M:%SZ')
            connection.execute(
                '''
                INSERT INTO scanner_locks (
                    scanner_id, scanner_name, owner_username, lock_token, status, job_uid, acquired_at, expires_at
                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
                ON CONFLICT(scanner_id) DO UPDATE SET
                    scanner_name = excluded.scanner_name,
                    owner_username = excluded.owner_username,
                    lock_token = excluded.lock_token,
                    status = excluded.status,
                    job_uid = excluded.job_uid,
                    acquired_at = excluded.acquired_at,
                    expires_at = excluded.expires_at
                ''',
                (scanner_id, scanner_name, username, uuid.uuid4().hex, 'pending', '', now, expires_at),
            )
    return None

conflicting_lock = acquire_lock(scanner_id, scanner.get('name', 'Unknown scanner'), current_user['username'])
if conflicting_lock:
    raise HTTPException(
        status_code=status.HTTP_423_LOCKED,
        detail={
            'message': 'Scanner is currently locked by another user.',
            'locked_by': conflicting_lock['owner_username'],
            'status': conflicting_lock['status'],
            'expires_at': conflicting_lock['expires_at'],
        },
    )

job = scanner_controller.createJob(
    SERVICE_HOST,
    {
        'license': LICENSE_KEY,
        'device': scanner['device'],
        'autoRun': False,
        'jobTimeout': payload.job_timeout,
        'scannerFailureTimeout': payload.scanner_failure_timeout,
        'requestFocusForScanningUI': False,
        'checkFeederLoaded': payload.feeder_enabled,
        'config': {
            'IfShowUI': payload.show_ui,
            'PixelType': payload.pixel_type,
            'Resolution': payload.resolution,
            'IfFeederEnabled': payload.feeder_enabled,
            'IfDuplexEnabled': payload.duplex_enabled,
            'IfCloseSourceAfterAcquire': True,
        },
    },
)
job_uid = job.get('jobuid', '')
if not job_uid:
    raise HTTPException(
        status_code=status.HTTP_502_BAD_GATEWAY,
        detail=job or scanner_controller.last_error or {'message': 'Failed to create scan job.'},
    )

update_lock(scanner_id, current_user['username'], 'pending', job_uid=job_uid)

start_result = scanner_controller.updateJob(SERVICE_HOST, job_uid, {'status': JobStatus.RUNNING})
if start_result.get('status') not in (JobStatus.RUNNING, JobStatus.COMPLETED):
    raise HTTPException(
        status_code=status.HTTP_502_BAD_GATEWAY,
        detail=start_result or scanner_controller.last_error or {'message': 'Failed to start scan job.'},
    )

update_lock(scanner_id, current_user['username'], 'scanning', job_uid=job_uid)

Step 5: Stream Scanned Pages Back to the Browser Dashboard

Once the lock is held and the job is running, the backend drains the scan job into base64 strings and the frontend renders them as data URLs.

images = scanner_controller.getImageStreams(SERVICE_HOST, job_uid, imageType=payload.image_type)
job_info = scanner_controller.checkJob(SERVICE_HOST, job_uid)
if job_info.get('status') == JobStatus.FAULTED:
    raise HTTPException(status_code=status.HTTP_502_BAD_GATEWAY, detail=job_info)

encoded_images = [base64.b64encode(image).decode('utf-8') for image in images]
write_audit_log(
    current_user['username'],
    'scan.completed',
    scanner_id=scanner_id,
    detail='{count} page(s)'.format(count=len(encoded_images)),
)
return {
    'scanner': {'id': scanner_id, 'name': scanner['name']},
    'page_count': len(encoded_images),
    'image_type': payload.image_type,
    'job_status': job_info.get('status', JobStatus.COMPLETED),
    'images': encoded_images,
}

Step 6: Build the Browser Dashboard for Scanner Selection and Live Status

The frontend stores the bearer token in sessionStorage, polls scanner status every five seconds, and disables the scan button when another user owns the lease.

async function api(path, options = {}) {
  const headers = new Headers(options.headers || {});
  if (state.token) {
    headers.set("Authorization", `Bearer ${state.token}`);
  }
  if (options.json) {
    headers.set("Content-Type", "application/json");
  }

  const response = await fetch(path, {
    method: options.method || "GET",
    headers,
    body: options.json ? JSON.stringify(options.json) : options.body,
  });

  const contentType = response.headers.get("content-type") || "";
  const payload = contentType.includes("application/json")
    ? await response.json()
    : await response.text();

  if (!response.ok) {
    throw payload;
  }
  return payload;
}

function renderScanners(scanners) {
  state.scanners = scanners;
  syncSelectedScanner(scanners);

  if (!scanners.length) {
    scannerSelect.innerHTML = '<option value="">No scanners available</option>';
    scannerSelect.disabled = true;
    renderSelectedScanner();
    return;
  }

  scannerSelect.disabled = false;
  scannerSelect.innerHTML = scanners.map((scanner) => {
    const selected = scanner.id === state.selectedScannerId ? " selected" : "";
    const lockLabel = scanner.locked ? ` (${scanner.locked_by || "locked"})` : "";
    return `<option value="${scanner.id}"${selected}>${scanner.name}${lockLabel}</option>`;
  }).join("");
  renderSelectedScanner();
}

function renderSelectedScanner() {
  const scanner = getSelectedScanner();
  if (!scanner) {
    scannerDetail.innerHTML = '<div class="empty-state">No shared TWAIN scanners are available right now.</div>';
    scanSelectedButton.disabled = true;
    return;
  }

  const isLockedByOther = scanner.locked && scanner.locked_by !== state.currentUser.username;
  const availabilityClass = scanner.locked ? "locked" : "free";
  const stateClass = scanner.lock_status || "idle";
  const ownerLine = scanner.locked
    ? `Locked by <strong>${scanner.locked_by}</strong> until ${scanner.lock_expires_at}`
    : "Available for the next authenticated user.";

  scannerDetail.innerHTML = `
    <article class="scanner-summary-card">
      <div class="scanner-card-header">
        <div>
          <h3>${scanner.name}</h3>
          <p class="scanner-meta">ID: ${scanner.id}</p>
        </div>
        <span class="lock-chip ${availabilityClass}">${scanner.locked ? "Locked" : "Ready"}</span>
      </div>
      <p class="scanner-meta">${ownerLine}</p>
      <div class="scanner-card-footer">
        <span class="state-chip ${stateClass}">${scanner.lock_status}</span>
        <span class="scanner-meta">Selected scanner</span>
      </div>
    </article>
  `;
  scanSelectedButton.disabled = isLockedByOther;
  scanSelectedButton.textContent = isLockedByOther
    ? `Locked by ${scanner.locked_by}`
    : "Scan Selected Scanner";
}

async function runScan(scannerId, scannerName) {
  const payload = {
    resolution: Number(document.getElementById("resolutionInput").value),
    pixel_type: Number(document.getElementById("pixelTypeInput").value),
    image_type: document.getElementById("imageTypeInput").value,
    feeder_enabled: document.getElementById("feederInput").checked,
    duplex_enabled: document.getElementById("duplexInput").checked,
    show_ui: document.getElementById("showUiInput").checked,
  };

  try {
    setBanner(`Locking ${scannerName} and waiting for scanned pages...`);
    const result = await api(`/api/scanners/${scannerId}/scan`, {
      method: "POST",
      json: payload,
    });
    renderResults(result);
    setBanner(`Completed ${result.page_count} page(s) on ${scannerName}.`, "success");
  } catch (error) {
    setBanner(formatError(error), "error");
  } finally {
    await loadScanners().catch(() => {});
  }
}

Step 7: Add an Administrator Workspace for User Management

Administrator accounts see a dedicated User Management panel instead of scanner controls. They can delete accounts, toggle admin roles, and the first registered user is automatically granted admin rights.

function setSignedInState(user) {
  state.currentUser = user;
  sessionState.innerHTML = `<span class="status-dot"></span><span>Signed in as ${user.username}</span>`;
  workspaceRolePill.textContent = user.is_admin ? "Administrator Workspace" : "Operator Workspace";

  // Role-appropriate sections
  scanControlsSection.hidden = user.is_admin;
  scannerStatusSection.hidden = user.is_admin;
  usersPanel.hidden = !user.is_admin;
  resultPanel.hidden = user.is_admin;
  workspaceSection.classList.toggle("admin-view", user.is_admin);

  // Switch panel title
  workspaceTitle.textContent = user.is_admin ? "User Management" : "Scanner Operations";
  workspaceCopy.textContent = user.is_admin
    ? "Delete accounts or change a user's administrator permissions."
    : "Controls and status change based on your account role.";

  // Admin badge is redundant — "Signed in as ..." already shows username
  userBadge.hidden = user.is_admin;

  setAuthMode("hidden");
  syncLayout();
}

Source Code

https://github.com/yushulx/python-twain-wia-sane-scanner/tree/main/webexample