Technisch artikel

UTF-8 in Data Matrix en PDF417: de ECI 26-marker

Een magazijnlabel slaat de ontvanger Müller GmbH, Köln als UTF-8 op in een Data Matrix-symbool, en elke handscanner op de vloer leest het terug als Müller GmbH, Köln. De PDFlibPas-property BarcodePayloadEncoding op bpeUTF8WithECI zetten plaatst een ECI 000026-marker vóór de data, waarmee Data Matrix- en PDF417-lezers wordt verteld dat ze de bytes als UTF-8 moeten decoderen

Waarom decodeert een UTF-8-payload als Müller?

Het symbool bevat geen tekensetdeclaratie, dus de lezer valt terug op de standaard-singlebyte tekenset van de symbologie, wat voor Data Matrix ISO-8859-1 is. Een UTF-8 ü bestaat uit de twee bytes C3 BC, die ISO-8859-1 vertaalt naar à en ¼; ö wordt op dezelfde manier ö. De bytes zelf zijn intact. Extended Channel Interpretation is de tekensetdeclaratie van de barcode-wereld. Het AIM ECI-register kent nummers toe aan tekensets, waaronder 000026 voor UTF-8, en een symbool dat opent met een ECI-designator vertelt een conforme lezer om alles wat erop volgt in die tekenset te decoderen. Voor het symbool is de designator gewone data. In beide hier besproken symbologieën kost hij twee codewoorden, telt hij mee voor de capaciteit en valt hij onder dezelfde Reed-Solomon-foutcorrectie voor 2D-barcodes als de payload erachter

Hoe identieke UTF-8-bytes op twee manieren decoderen in PDFlibPas-barcodes vanuit Delphi: geen ECI-marker betekent een ISO-8859-1-gok, ECI 000026 betekent UTF-8
het symbool slaat alleen bytes op, dus de ECI 000026-designator is wat de lezer vertelt dat de bytes UTF-8 zijn en geen ISO-8859-1-gok

ECI-codewoordposities in Data Matrix en PDF417

Elke symbologie heeft een vaste plek voor de marker. Zet u hem ergens anders neer, dan decodeert het symbool niet of met rommel vooraan:

Codewoordposities voor de ECI UTF-8-marker in PDFlibPas Data Matrix-, GS1 Data Matrix- en PDF417-symbolen vanuit Delphi, elk vast vóór de payload
elke symbologie spijkert de ECI-designator vast op een vaste eerste positie, en PDFlibPas schrijft hem voordat de positieafhankelijke encodations draaien
  • Data Matrix (ISO/IEC 16022): codewoord 241, daarna het ECI-nummer plus één in de single-codewordvorm voor waarden onder 127, dus 27 voor UTF-8. Hij opent de datastroom
  • GS1 Data Matrix: FNC1 (codewoord 232) moet op de eerste positie blijven, dus PDFlibPas zet de marker er direct achter als u er een vraagt; GS1-elementstrings komen echter uit een subset van ASCII en lezen zonder hem precies hetzelfde
  • PDF417 (ISO/IEC 15438): codewoord 0 is de symbollengte-descriptor en de marker volgt als codewoorden 927 en 26, vóór het eerste datacodewoord

Base 256 is het lastige geval. Die encodation, de compacte Data Matrix-modus voor willekeurige bytes, scrambelt elk codewoord met een pseudo-random waarde uit zijn absolute positie in het symbool, (149 × position mod 255) + 1. Plaats u de marker pas na het scrambelen, dan zat elke byte erachter bij het scrambelen op een positie twee eerder dan wat de lezer ziet en unscrambled de hele payload naar verkeerde waarden. EDIFACT-encodation heeft een mildere variant van dezelfde afhankelijkheid — de unlatch-positie schuift er twee op zodra de marker vooraan komt. PDFlibPas schrijft de marker in de codewoordstroom voordat een van die stappen draait, en de capaciteitscontrole die de symboolgrootte kiest rekent hem al mee. De labelcode voor beide symbologieën:

uses
  SysUtils, PDFlibrary;

procedure PrintConsigneeLabel(const FileName: string);
var
  Pdf: TPDFlib;
begin
  Pdf := TPDFlib.Create;
  try
    Pdf.NewDocument;                                // maakt pagina 1 aan en selecteert die
    Pdf.SetPageSize('A4');
    Pdf.SetMeasurementUnits(1);                     // millimeters
    Pdf.SetOrigin(1);                               // Top wordt vanaf de bovenrand gemeten

    Pdf.BarcodePayloadEncoding := bpeUTF8WithECI;   // UTF-8-bytes + ECI 000026
    if Pdf.DrawDataMatrixSymbol(20, 20, 0.5, 'Müller GmbH, Köln',
      1,      // Encoding: 1 = ASCII-encodation
      0,      // SymbolSize: 0 = eerste maat in de tabel die past
      100) <> 1 then                                // normale orientatie, standaard 1-module quiet zone
      raise Exception.CreateFmt('Data Matrix failed (%d)', [Pdf.LastErrorCode]);

    if Pdf.DrawPDF417SymbolEx(20, 50, 'Zustellung: Müller GmbH, Köln',
      0, 0, 0,  // orientatie, kolommen, rijen: automatisch
      -1,       // error level automatisch
      0.3, 3.0) <> 1 then
      raise Exception.Create('PDF417 failed');

    // Een ECI-bewuste scanner zou voor beide symbolen de Duitse tekst moeten teruggeven
    Pdf.BarcodePayloadEncoding := bpeSystemANSI;    // terug naar de standaardwaarde
    Pdf.SaveToFile(FileName);
  finally
    Pdf.Free;
  end;
end;

NewDocument maakt pagina 1 al aan en selecteert die, dus de symbolen belanden op de eerste pagina zonder een NewPage-aanroep. SetOrigin(1) verplaatst de oorsprong naar de linkerbovenhoek, waardoor Top de afstand is van de bovenrand van het symbool tot de bovenkant van de pagina. Bij de standaard-oorsprong linksonder zet een Top van 10 mm die rand 10 mm boven de onderkant van het vel, en hangt een symbool van 11 mm eroverheen. DrawDataMatrixSymbol geeft 1 terug bij succes. Voor data die hij niet kan encoderen — een payload die na het meetellen van de marker niet meer in het grootste symbool past, of de vaste maat die u vroeg — geeft hij 0 terug, zet LastErrorCode op 302 en tekent niets, dus het voorbeeld behandelt alles anders dan 1 als fout

Moet elk label de ECI-marker meedragen?

Nee, en de standaardinstelling dekt dat. BarcodePayloadEncoding kent drie waarden, en elke waarde past bij een andere lezerspopulatie:

  • bpeSystemANSI (de standaard) converteert de tekst via de ANSI-codepagina van het systeem en schrijft geen marker, precies wat labelindelingen verwachten die met de PDFlibPas QR-, PDF417- en Data Matrix-functies zijn gebouwd
  • bpeUTF8 schrijft UTF-8-bytes zonder marker, voor gesloten systemen waarin uw eigen software de barcode leest en al van UTF-8 uitgaat
  • bpeUTF8WithECI schrijft UTF-8-bytes en voorziet ze van het label ECI 000026

De prijs voor het labelen van alles is lezersondersteuning. ECI-verwerking is een configuratieoptie op veel scanners, en afhankelijk van die instelling weigert een apparaat het symbool of geeft de designator als tekst door aan de host: de AIM-conventie is een backslash en zes cijfers, dus de applicatie ontvangt \000026Müller GmbH, Köln. Zet de marker per symbool aan, voor payloads met niet-ASCII-tekst, en rol die uit samen met de wijziging in het scannerprofiel. Een single-byte-payload blijft een prima keuze zolang elke naam in de codepagina past waar uw lezers van uitgaan. ü is byte FC in zowel Windows-1252 als ISO-8859-1, dus een Duits adres geschreven onder bpeSystemANSI op een West-Europees Windows-systeem decodeert correct op een Data Matrix-lezer die nog nooit van ECI heeft gehoord. Japanse tekst heeft zo'n fallback niet

Symboolgrootte: automatische keuze, vaste templates en rechthoeken

De twee codewoorden van de marker werken zelden alleen. In ASCII-encodation bevat de ontvangerregel onder bpeSystemANSI ü en ö als single bytes boven 127, twee codewoorden per stuk, en de hele regel kost 19 codewoorden, wat past in een 20×20-symbool met zijn 22 datacodewoorden. Als UTF-8 worden die twee letters vier high bytes en kost de regel 23. De marker brengt het op 25. Dat vraagt 22×22, en die stap komt van de UTF-8-bytes alleen, want 23 overschrijdt 20×20 al. Een template dat SymbolSize op 9 (20×20) vastzet, krijgt 0 en fout 302 van DrawDataMatrixSymbol zodra de encoding verandert, en er wordt niets getekend op de barcodeplek

Automatische grootte kan de vorm veranderen. Met SymbolSize op 0 loopt PDFlibPas de maattabel van ISO/IEC 16022 in volgorde af en pakt de eerste entry waarvan de datacapaciteit de stroom herbergt. De zes rechthoekige maten staan in die lijst tussen de vierkanten door. Een payload die in een 26×26-symbool paste (44 datacodewoorden) heeft met de marker 46 nodig, en de eerstvolgende entry die 46 herbergt is 16×48 met 49, vóór 32×32 met 62. Bij 0,5 mm per module wordt een vierkant van 13 mm een strook van 8 × 24 mm. Een volle 22×22 doet hetzelfde: 30 codewoorden plus twee belanden in 16×36. Kleine payloads blijven vierkant — drie codewoorden die 10×10 vulden worden er vijf en passen in 12×12, dat vóór 8×18 in de lijst staat. Reserveert het label een vierkante plek, zet dan SymbolSize vast op het vierkant dat u kunt missen (16 voor 32×32) en laat fout 302 u vertellen wanneer een naam te lang wordt; automatische grootte past bij indelingen die beide vormen aan kunnen

PDF417 groeit volgens een andere regel. Met ErrorLevel op -1 plant de encoder de foutcorrectie volgens de aanbevolen minimumniveaus uit ISO/IEC 15438, die op 41, 161 en 321 codewoorden een stap omhoog gaan, lengte-descriptor meegerekend. Een stroom van 39 codewoorden wordt met de marker 41, het minimumniveau schuift van 2 naar 3, en het foutcorrectieblok waarvoor hij plant groeit van 8 naar 16 codewoorden. Dat zijn tien extra codewoorden. Met automatische kolommen en rijen legt de encoder de rechthoek uit op basis van dat grotere totaal, dus een payload die net onder een stap zit wint meer oppervlak dan zijn twee marker-codewoorden doen vermoeden

Welke encodation houdt een UTF-8 Data Matrix klein?

Vergelijk de twee kosten direct. ASCII-encodation propt een cijferpaar in één codewoord en gewone ASCII tegen één per teken, maar elke byte boven 127 kost er twee: een Upper Shift (235) en de byte minus 127. Base 256 betaalt eenmalig een latch en een lengteveld — één lengtecodewoord tot 249 bytes, daarboven twee — en daarna één codewoord per byte, zonder cijferpacking. Voor tekst zonder cijferreeksen wint Base 256 zodra een payload drie high bytes bevat. De Müller-regel doet dat al, met 21 codewoorden tegen 23. Lange numerieke reeksen schuiven de balans terug richting ASCII, want elk cijferpaar scheelt daar een codewoord. De helper hieronder telt beide kosten en tekent met de goedkopere modus; pure ASCII krijgt helemaal geen marker, want die leest onder elke tekenset identiek:

// Teken een Data Matrix voor Unicode-tekst met de goedkopere encodation
function DrawUnicodeDataMatrix(Pdf: TPDFlib; Left, Top, ModuleSize: Double;
  const Text: WideString): Integer;
var
  Bytes: UTF8String;
  I, HighBytes, AsciiCost, Base256Cost, Mode: Integer;
  Saved: TPDFlibBarcodePayloadEncoding;
begin
  Bytes := UTF8Encode(Text);
  HighBytes := 0;
  AsciiCost := 0;
  I := 1;
  while I <= Length(Bytes) do
  begin
    if (I < Length(Bytes)) and (Bytes[I] >= '0') and (Bytes[I] <= '9') and
       (Bytes[I + 1] >= '0') and (Bytes[I + 1] <= '9') then
    begin
      Inc(AsciiCost);                    // cijferpaar: één codewoord
      Inc(I, 2);
      Continue;
    end;
    if Ord(Bytes[I]) > 127 then
    begin
      Inc(HighBytes);
      Inc(AsciiCost, 2);                 // Upper Shift + (byte - 127)
    end
    else
      Inc(AsciiCost);
    Inc(I);
  end;
  if Length(Bytes) <= 249 then
    Base256Cost := Length(Bytes) + 2     // latch + één lengtecodewoord
  else
    Base256Cost := Length(Bytes) + 3;    // latch + twee lengtecodewoorden

  Saved := Pdf.BarcodePayloadEncoding;
  try
    if HighBytes = 0 then
    begin
      Pdf.BarcodePayloadEncoding := bpeSystemANSI;  // pure ASCII: geen marker
      Mode := 1;
    end
    else
    begin
      Pdf.BarcodePayloadEncoding := bpeUTF8WithECI;
      if Base256Cost < AsciiCost then
        Mode := 3                        // Base 256
      else
        Mode := 1;                       // ASCII
    end;
    Result := Pdf.DrawDataMatrixSymbol(Left, Top, ModuleSize, Text, Mode, 0, 100);
  finally
    Pdf.BarcodePayloadEncoding := Saved;
  end;
end;

Voor 東京都千代田区 is de UTF-8-vorm 21 bytes, allemaal boven 127. Met de marker heeft Base 256 25 datacodewoorden nodig en ASCII-encodation 44, wat volgens de capaciteitstabel een 22×22-symbool is tegen een 26×26 bij dezelfde modulegrootte. Die 26×26 zit vol. Eén codewoord meer en hij springt naar 16×48. GS1-payloads (modus 7) blijven buiten de helper, omdat hun elementstrings ASCII zijn. QR-codes geven hun data-modus mee via het EncodeOptions-argument van DrawQRCode, en Aztec-symbolen die PDFlibPas tekent dragen automatisch een ECI 26-vlag zodra de payload-bytes geldige UTF-8 zijn met minstens één niet-ASCII-teken

ASCII versus Base 256-encodationkosten voor PDFlibPas Data Matrix-barcodes in Delphi, met uitgewerkte codewoordtotalen en de modus die de helper kiest
base 256 wint zodra drie of meer high bytes opduiken, terwijl cijferrijke payloads de kosten weer richting ASCII-encodation terugschuiven

Voor de Müller-regel kost de marker twee codewoorden, terwijl de sprong van 20×20 naar 22×22 — 10 mm naar 11 mm bij 0,5 mm-modules — door de UTF-8-bytes komt. Heeft uw labelplek die extra millimeter, zet dan BarcodePayloadEncoding op bpeUTF8WithECI op de TPDFlib-instantie van de PDFlibPas Delphi PDF Library net voordat het ontvangersymbool wordt getekend, en zet hem terug op bpeSystemANSI voor de legacy-symbolen op dezelfde pagina