GS1-128 з точністю 0,1 mm із JSON

Якщо ви відправляєте фізичні товари, рано чи пізно доведеться друкувати GS1-128, який зчитає реальний ручний scanner у реальному складі. Це виглядає як дрібниця, але в PDF generation саме тут часто з’являються дорогі відмови.

Ця стаття пояснює, що означає точність “0,1 mm” для GS1-128, чому HTML/CSS renderer її легко втрачає, і які правила допомагають пройти сканери DHL, FedEx, USPS та Amazon inbound.

Що означає точність barcode

GS1-128 (раніше UCC/EAN-128) кодує дані через ширини штрихів і проміжків у строгих пропорціях. Базова одиниця — X-dimension, ширина найвужчого штриха або проміжку. Решта ширин кратні X.

Scanner вимірює відносні ширини. У production найчастіше ламаються дві речі:

1. Непослідовна X-dimension у символі: renderer по-різному округлює сусідні штрихи на sub-pixel рівні.
2. Неправильна загальна довжина або scaling: символ renderиться, а потім масштабується, і X-dimension падає нижче мінімуму GS1, зазвичай 0,495 mm при 1,0×.

Один sample може читатися, але партія матиме відмови 1 із 30. Dev scanner часто більш терпимий, ніж складський.

Правило 0,1 mm

Важлива загальна довжина barcode у межах 0,1 mm від цілі специфікації. Це не означає, що кожен штрих має 0,1 mm; зазвичай він 0,495 mm або ширший.

Для типового GS1-128 з 18 цифрами:

• Символ має близько 120 штрихів і проміжків
• Загальна довжина при 1,0× близько 58 mm
• 0,1 mm tolerance — це ~0,17% по всій довжині
• На один штрих лишається близько 0,001 mm

Тому штрих, який мав бути 7,4 px, а став 7 px, може зірвати читання. Sub-pixel помилка накопичується по всьому символу.

Чому HTML/CSS складний

Типовий шлях: створити SVG, вставити в HTML, а потім зробити PDF через Puppeteer або Prince. Кожен етап може змістити геометрію.

1. Browser округлює під час растеризація

Навіть SVG у HTML проходить через painter браузера. Потрібні shape-rendering="crispEdges", межі на цілих пікселях і чиста відповідність DPI до ширини штриха.

2. CSS може непомітно масштабувати

Старий transform: scale(0.95) для іншого layout викривляє всі barcode на сторінці. PDF виглядає нормально; scanner бачить інше.

3. PDF emitter квантує координати

Деякі рушії прив’язують координати до внутрішньої сітки при записі PDF. Результат майже правильний, але помилка накопичується.

4. Code 128 font ще ризикованіший

Font є vector, але font hinting зміщує малі ширини для людського ока. Scanner потребує протилежного.

Структурований rendering

gPdf обчислює pattern штрихів і проміжків зі специфікації GS1-128 та напряму пише PDF vector primitives: без HTML, без SVG translation, без font hinting.

{
  "pages": [{
    "size": "label_100_150",
    "elements": [
      {
        "type": "barcode",
        "format": "gs1128",
        "content": "(00)123456789012345678",
        "x": 4,
        "y": 8,
        "width": 58.0,
        "height": 18.0,
        "barcode_text": { "enabled": true, "position": "bottom" }
      }
    ]
  }]
}

В елементі barcode поле width — це загальна довжина символу в mm, яку можна виміряти штангенциркулем на надрукованій етикетці. width: 58.0 означає:

• Renderer рахує X-dimension із цільової довжини та кількості штрихів.
• Кожен штрих малюється з тією самою X-dimension.
• Ширини записуються в PDF як floating-point coordinates.
• Немає CSS pixel rounding, layout scaling чи font hinting.

Якщо printer не додає власного scaling, довжина лишається в межах 0,1 mm від цілі.

Що друкувати на практиці

Правило 1: задавайте загальну довжину

width — правильний параметр, бо його можна виміряти. Якщо задавати лише X-dimension, довжина символу залежатиме від encoded data.

• Shipping label 4×6 in: ширина 100 mm, GS1-128 зазвичай ~58–72 mm
• Compliance label 4×4 in: ~45–58 mm
• Carton label 2×1 in (Amazon UPC): це не GS1-128; використовуйте UPC-A

Правило 2: quiet zones завжди

GS1-128 потребує quiet zones ≥ 10X з обох боків. При 1,0× (X = 0,495 mm) це мінімум 4,95 mm чистого білого поля. Barcode у x: 0 може позбавити scanner стартової межі. gPdf резервує ці зони автоматично.

Правило 3: тестуйте на цільовому scanner

Камера телефона пробачає більше, ніж промислові Honeywell або Zebra. Надрукуйте 50 етикеток на production-принтері, у production-швидкості, і перевірте реальним scanner. Read rate нижче 99% — перший сигнал дивитися X-dimension.

Реальність багатьох форматів

Етикетка рідко має лише GS1-128:

Symbol	Використання	Джерело специфікації
GS1-128	Логістичні одиниці, GTIN + serial + lot	GS1 General Specifications
QR with FNC1	Ecommerce, що сканується mobile	ISO/IEC 18004
Data Matrix	Фармацевтика (DSCSA / EU FMD)	ISO/IEC 16022
PDF417	Водійські посвідчення, boarding passes	ISO/IEC 15438
Aztec	Транспортні квитки	ISO/IEC 24778
MaxiCode	Спеціально UPS	ISO/IEC 16023

Renderer лише для GS1-128 згодом змусить додати другий інструмент. У logistics зазвичай потрібні щонайменше два формати.

Діагностика відхилення сканером у production

1. Візьміть реальні failed labels.
2. Виміряйте штангенциркулем загальну довжину і X-dimension.
3. Перевірте human-readable text під символом.
4. Виміряйте quiet zones.
5. Спробуйте іншу модель scanner.
6. Порівняйте з known-good reference label.

TL;DR

Точність GS1-128 — не про те, наскільки тонкий штрих можна надрукувати. Вона про стабільну X-dimension по всьому символу. HTML/CSS додає sub-pixel drift на кількох етапах; прямі PDF vector primitives прибирають ці джерела.

Якщо поточний PDF stack має 1–5% відхилення сканером, почніть тут. Playground може render GS1-128 з width точно за вашою специфікацією; надрукуйте і виміряйте.