Artículo técnico

UTF-8 en Data Matrix y PDF417: el marcador ECI 26

Una etiqueta de almacén guarda el destinatario Müller GmbH, Köln como UTF-8 en un símbolo Data Matrix, y todos los escáneres de mano de la nave se lo devuelven como Müller GmbH, Köln. Poner la propiedad BarcodePayloadEncoding de PDFlibPas en bpeUTF8WithECI antepone un marcador ECI 000026 a los datos, que indica a los lectores Data Matrix y PDF417 que decodifiquen los bytes como UTF-8

¿Por qué un payload UTF-8 se decodifica como Müller?

El símbolo no lleva ninguna declaración de juego de caracteres, así que el lector recurre al juego de un solo byte por defecto de la simbología, que en Data Matrix es ISO-8859-1. Una ü en UTF-8 son los dos bytes C3 BC, que ISO-8859-1 mapea como à y ¼; ö acaba en ö por el mismo camino. Los bytes en sí están intactos. Extended Channel Interpretation es la declaración de juego de caracteres del mundo de los códigos de barras. El registro ECI del AIM asigna números a los juegos de caracteres —000026 entre ellos, para UTF-8—, y un símbolo que arranca con un designador ECI indica al lector conforme que decodifique todo lo que venga después en ese juego de caracteres. Para el símbolo el designador son datos corrientes. Ocupa dos palabras de código en las dos simbologías que tratamos aquí, cuenta para la capacidad y queda protegido por la misma corrección de errores Reed-Solomon para códigos 2D que el payload que lleva detrás

Cómo unos mismos bytes UTF-8 se decodifican de dos maneras en códigos de barras PDFlibPas desde Delphi: sin marcador ECI hay una conjetura ISO-8859-1, y ECI 000026 significa UTF-8
el símbolo solo guarda bytes, así que el designador ECI 000026 es lo que dice al lector que los bytes son UTF-8 y no una conjetura ISO-8859-1

Posiciones de la palabra de código ECI en Data Matrix y PDF417

Cada simbología tiene una ranura fija para el marcador. Ponlo en cualquier otro sitio y el símbolo deja de decodificarse o se decodifica con basura delante:

Ranuras de palabra de código para el marcador ECI UTF-8 en símbolos Data Matrix, GS1 Data Matrix y PDF417 de PDFlibPas desde Delphi, cada una fija delante del payload
cada simbología fija el designador ECI en una ranura inicial concreta, y PDFlibPas lo escribe antes de que se ejecuten las codificaciones dependientes de la posición
  • Data Matrix (ISO/IEC 16022): la palabra de código 241 y después el número ECI más uno en la forma de una sola palabra de código que se usa para valores por debajo de 127, o sea 27 para UTF-8. Abre el flujo de datos
  • GS1 Data Matrix: el FNC1 (palabra de código 232) tiene que seguir en la primera posición, así que PDFlibPas coloca el marcador justo detrás si se pide uno; eso sí, las cadenas de elementos GS1 salen de un subconjunto de ASCII y se leen igual sin él
  • PDF417 (ISO/IEC 15438): la palabra de código 0 es el descriptor de longitud del símbolo, y detrás vienen el marcador como palabras de código 927 y 26, delante de la primera palabra de código de datos

Base 256 es el caso difícil. Esa codificación, el modo Data Matrix compacto para bytes arbitrarios, revuelve cada palabra de código con un valor pseudoaleatorio derivado de su posición absoluta en el símbolo, (149 × position mod 255) + 1. Anteponer el marcador una vez hecho el revuelto deja cada byte detrás de él revuelto para una posición dos puestos anterior a la que ve el lector, así que el payload entero se deshace en valores equivocados. La codificación EDIFACT tiene una versión más leve de la misma dependencia: su posición de unlatch se desplaza dos puestos cuando el marcador va delante. PDFlibPas escribe el marcador en el flujo de palabras de código antes de que se ejecute cualquiera de los dos pasos, y la comprobación de capacidad que elige el tamaño del símbolo ya lo incluye. El código de la etiqueta para las dos simbologías:

uses
  SysUtils, PDFlibrary;

procedure PrintConsigneeLabel(const FileName: string);
var
  Pdf: TPDFlib;
begin
  Pdf := TPDFlib.Create;
  try
    Pdf.NewDocument;                                // crea y selecciona la página 1
    Pdf.SetPageSize('A4');
    Pdf.SetMeasurementUnits(1);                     // milímetros
    Pdf.SetOrigin(1);                               // Top se mide desde el borde superior

    Pdf.BarcodePayloadEncoding := bpeUTF8WithECI;   // bytes UTF-8 + ECI 000026
    if Pdf.DrawDataMatrixSymbol(20, 20, 0.5, 'Müller GmbH, Köln',
      1,      // Encoding: 1 = codificación ASCII
      0,      // SymbolSize: 0 = primer tamaño de la tabla que cabe
      100) <> 1 then                                // orientación normal, zona silenciosa de 1 módulo por defecto
      raise Exception.CreateFmt('Data Matrix failed (%d)', [Pdf.LastErrorCode]);

    if Pdf.DrawPDF417SymbolEx(20, 50, 'Zustellung: Müller GmbH, Köln',
      0, 0, 0,  // orientación, columnas, filas: automáticas
      -1,       // nivel de error automático
      0.3, 3.0) <> 1 then
      raise Exception.Create('PDF417 failed');

    // Un escáner con soporte ECI debería devolver el texto alemán para ambos símbolos
    Pdf.BarcodePayloadEncoding := bpeSystemANSI;    // de vuelta al valor por defecto
    Pdf.SaveToFile(FileName);
  finally
    Pdf.Free;
  end;
end;

NewDocument ya crea la página 1 y la selecciona, así que los símbolos caen en la primera página sin llamada a NewPage. SetOrigin(1) mueve el origen a la esquina superior izquierda, de modo que Top pasa a ser la distancia del borde superior del símbolo al borde superior de la página. Con el origen por defecto en la esquina inferior izquierda, un Top de 10 mm deja ese borde 10 mm por encima del borde inferior de la hoja, y un símbolo de 11 mm se sale de ella. DrawDataMatrixSymbol devuelve 1 si tiene éxito. Con datos que no puede codificar —un payload que ya no cabe en el símbolo más grande una vez contado el marcador, o el tamaño fijo que se haya pedido— devuelve 0, pone LastErrorCode en 302 y no dibuja nada, así que el ejemplo trata cualquier valor distinto de 1 como un error

¿Debe llevar el marcador ECI toda etiqueta?

No, y el valor por defecto lo refleja. BarcodePayloadEncoding admite tres valores, y cada uno encaja con una población de lectores distinta:

  • bpeSystemANSI (el valor por defecto) convierte el texto por la página de códigos ANSI del sistema y no escribe marcador, que es lo que esperan las maquetaciones de etiquetas construidas con las funciones QR, PDF417 y Data Matrix de PDFlibPas
  • bpeUTF8 escribe bytes UTF-8 sin marcador, para sistemas cerrados en los que el software propio lee el código de barras y ya asume UTF-8
  • bpeUTF8WithECI escribe bytes UTF-8 y los etiqueta con ECI 000026

El precio de etiquetarlo todo es el soporte en los lectores. El procesado de ECI es una opción de configuración en muchos escáneres y, según cómo esté ese ajuste, un equipo puede rechazar el símbolo o pasar el designador al host como texto: la convención del AIM es una barra invertida y seis dígitos, así que la aplicación recibe \000026Müller GmbH, Köln. Activa el marcador símbolo a símbolo, para payloads que contengan texto no ASCII, y despliégalo junto con el cambio de perfil del escáner. Un payload de un solo byte sigue siendo una opción razonable cuando todos los nombres caben en la página de códigos que asumen los lectores. La ü es el byte FC tanto en Windows-1252 como en ISO-8859-1, así que una dirección alemana escrita con bpeSystemANSI en un Windows de Europa occidental se decodifica bien en un lector Data Matrix que no sabe nada de ECI. El texto japonés no tiene ese salvavidas

Tamaño del símbolo: selección automática, plantillas fijas y rectángulos

Las dos palabras de código del marcador rara vez actúan solas. En codificación ASCII la línea del destinatario con bpeSystemANSI guarda ü y ö como bytes sueltos por encima de 127, a dos palabras de código cada uno, y la línea entera cuesta 19 palabras de código, lo que cabe en un símbolo 20×20 con sus 22 palabras de código de datos. Como UTF-8 las dos letras se convierten en cuatro bytes altos y la línea cuesta 23. El marcador la deja en 25. Eso necesita 22×22, y el salto viene solo de los bytes UTF-8, porque 23 ya desborda el 20×20. Una plantilla que fija SymbolSize en 9 (20×20) recibe un 0 y el error 302 de DrawDataMatrixSymbol en cuanto cambia la codificación, y en la ranura del código de barras no se dibuja nada

El dimensionado automático puede cambiar la forma. Con SymbolSize en 0, PDFlibPas recorre en orden la lista de tamaños del ISO/IEC 16022 y toma la primera entrada cuya capacidad de datos aguante el flujo. Los seis tamaños rectangulares están en esa lista entre los cuadrados. Un payload que llenaba un símbolo de 26×26 (44 palabras de código de datos) necesita 46 con el marcador, y la siguiente entrada que aguanta 46 es 16×48 con 49, por delante de 32×32 con 62. A 0,5 mm por módulo, un cuadrado de 13 mm se convierte en una tira de 8 × 24 mm. Un 22×22 lleno hace lo mismo: 30 palabras de código más dos caen en 16×36. Los payloads pequeños se quedan cuadrados: tres palabras de código que llenaban un 10×10 se convierten en cinco y caben en 12×12, que precede al 8×18 en la lista. Si la etiqueta reserva una ranura cuadrada, fija SymbolSize en el cuadrado que puedas permitirte (16 para 32×32) y deja que el error 302 te avise cuando un nombre es demasiado largo para él; el dimensionado automático va bien para maquetaciones que admiten ambas formas

PDF417 crece con otra regla. Con ErrorLevel en -1, el codificador planifica la corrección de errores a partir de los niveles mínimos recomendados del ISO/IEC 15438, que suben en 41, 161 y 321 palabras de código, descriptor de longitud incluido. Un flujo de 39 palabras de código pasa a 41 con el marcador, el nivel mínimo sube de 2 a 3 y el bloque de corrección de errores que planifica crece de 8 a 16 palabras de código. Son diez palabras de código extra. Con columnas y filas automáticas, el codificador distribuye el rectángulo a partir de ese total mayor, así que un payload justo por debajo de un escalón gana más área de la que sugieren sus dos palabras de código de marcador

¿Qué codificación deja un Data Matrix UTF-8 pequeño?

Compara los dos costes directamente. La codificación ASCII empaqueta una pareja de dígitos en una palabra de código y el ASCII plano a una por carácter, pero cada byte por encima de 127 cuesta dos: un Upper Shift (235) y el byte menos 127. Base 256 paga un latch y un campo de longitud una sola vez —una palabra de código de longitud hasta 249 bytes, dos a partir de ahí— y luego una palabra de código por byte, sin empaquetado de dígitos. Para texto sin rachas de dígitos, Base 256 gana en cuanto el payload junta tres bytes altos. La línea de Müller ya los junta, con 21 palabras de código frente a 23. Las rachas numéricas largas devuelven la balanza hacia ASCII, porque cada pareja de dígitos ahorra una palabra de código ahí. El ayudante de abajo cuenta los dos costes y dibuja con el modo más barato; el ASCII puro no lleva marcador alguno, porque se lee idéntico bajo cualquier juego de caracteres:

// Dibuja un Data Matrix para texto Unicode con la codificación más barata
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);                    // pareja de dígitos: una palabra de código
      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 + una palabra de código de longitud
  else
    Base256Cost := Length(Bytes) + 3;    // latch + dos palabras de código de longitud

  Saved := Pdf.BarcodePayloadEncoding;
  try
    if HighBytes = 0 then
    begin
      Pdf.BarcodePayloadEncoding := bpeSystemANSI;  // ASCII puro: sin marcador
      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;

Para 東京都千代田区 la forma UTF-8 son 21 bytes, todos por encima de 127. Con el marcador, Base 256 necesita 25 palabras de código de datos y la codificación ASCII 44, que por la tabla de capacidades es un símbolo 22×22 frente a uno de 26×26 con el mismo tamaño de módulo. Ese 26×26 está lleno. Una palabra de código más y salta a 16×48. Los payloads GS1 (modo 7) se quedan fuera del ayudante porque sus cadenas de elementos son ASCII. Los códigos QR toman su modo de datos por el argumento EncodeOptions de DrawQRCode, y los símbolos Aztec dibujados por PDFlibPas llevan una bandera ECI 26 automáticamente siempre que los bytes del payload sean UTF-8 válido con al menos un carácter no ASCII

Costes de codificación ASCII frente a Base 256 para códigos de barras Data Matrix de PDFlibPas en Delphi, con totales de palabras de código calculados y el modo que elige el ayudante
Base 256 gana en cuanto aparecen tres o más bytes altos, mientras que los payloads con muchos dígitos devuelven el coste hacia la codificación ASCII

Para la línea de Müller, el marcador cuesta dos palabras de código, mientras que el paso de 20×20 a 22×22 —de 10 mm a 11 mm con módulos de 0,5 mm— lo causan los bytes UTF-8. Si la ranura de tu etiqueta tiene ese milímetro extra, pon BarcodePayloadEncoding en bpeUTF8WithECI en la instancia de TPDFlib de la PDFlibPas Delphi PDF Library justo antes de dibujar el símbolo del destinatario, y devuélvelo a bpeSystemANSI para los símbolos heredados de la misma página