Artigo Técnico

UTF-8 em Data Matrix e PDF417: o marcador ECI 26

Uma etiqueta de armazém grava o destinatário Müller GmbH, Köln em UTF-8 num símbolo Data Matrix, e todo leitor portátil do chão de fábrica devolve Müller GmbH, Köln. Definir a propriedade BarcodePayloadEncoding do PDFlibPas como bpeUTF8WithECI coloca um marcador ECI 000026 na frente dos dados, que diz aos leitores de Data Matrix e PDF417 para decodificar os bytes como UTF-8

Por que um payload UTF-8 decodifica como Müller?

O símbolo não carrega declaração de charset, então o leitor recorre ao conjunto de caracteres single-byte padrão da simbologia, que no Data Matrix é ISO-8859-1. Um ü em UTF-8 são os dois bytes C3 BC, que o ISO-8859-1 mapeia para à e ¼; ö vira ö do mesmo jeito. Os bytes em si estão intactos. Extended Channel Interpretation é a declaração de charset do mundo dos códigos de barras. O registro de ECI da AIM atribui números a conjuntos de caracteres, com o 000026 entre eles para UTF-8, e um símbolo que abre com um designador ECI diz ao leitor em conformidade para decodificar tudo o que vem depois naquele conjunto de caracteres. Para o símbolo, o designador é dado comum. Ele ocupa dois codewords nas duas simbologias discutidas aqui, conta para a capacidade e é protegido pela mesma correção de erros Reed-Solomon para códigos de barras 2D que o payload atrás dele

Como os mesmos bytes UTF-8 decodificam de duas formas em códigos de barras PDFlibPas a partir do Delphi: sem marcador ECI é um chute ISO-8859-1, com ECI 000026 é UTF-8
o símbolo armazena apenas bytes, então o designador ECI 000026 é o que diz ao leitor que os bytes são UTF-8 e não um chute ISO-8859-1

Posições do codeword ECI em Data Matrix e PDF417

Cada simbologia tem um slot fixo para o marcador. Coloque-o em qualquer outro lugar e o símbolo ou não decodifica ou decodifica com lixo na frente:

Slots de codeword para o marcador ECI UTF-8 em símbolos Data Matrix, GS1 Data Matrix e PDF417 do PDFlibPas a partir do Delphi, cada um fixo antes do payload
toda simbologia fixa o designador ECI num slot inicial definido, e o PDFlibPas o grava antes de as codificações dependentes de posição rodarem
  • Data Matrix (ISO/IEC 16022): codeword 241, depois o número ECI mais um na forma de codeword único usada para valores abaixo de 127, ou seja, 27 para UTF-8. Ele abre o stream de dados
  • GS1 Data Matrix: o FNC1 (codeword 232) precisa ficar na primeira posição, então o PDFlibPas coloca o marcador logo depois dele se você pedir um; como as strings de elemento GS1 vêm de um subconjunto de ASCII, a leitura é a mesma sem ele
  • PDF417 (ISO/IEC 15438): o codeword 0 é o descritor de comprimento do símbolo, e o marcador vem em seguida como codewords 927 e 26, antes do primeiro codeword de dados

Base 256 é o caso difícil. Essa codificação, o modo compacto do Data Matrix para bytes arbitrários, embaralha cada codeword com um valor pseudoaleatório derivado da sua posição absoluta no símbolo, (149 × position mod 255) + 1. Se o marcador entra depois do embaralhamento, todo byte atrás dele foi embaralhado para uma posição dois lugares antes da que o leitor vê, e o payload inteiro desembralha para valores errados. A codificação EDIFACT tem uma versão mais suave da mesma dependência — a posição de unlatch dela desloca dois lugares quando o marcador entra na frente. O PDFlibPas grava o marcador no stream de codewords antes de qualquer um desses passos rodar, e a checagem de capacidade que escolhe o tamanho do símbolo já o inclui. O código da etiqueta para as duas simbologias:

uses
  SysUtils, PDFlibrary;

procedure PrintConsigneeLabel(const FileName: string);
var
  Pdf: TPDFlib;
begin
  Pdf := TPDFlib.Create;
  try
    Pdf.NewDocument;                                // cria e seleciona a página 1
    Pdf.SetPageSize('A4');
    Pdf.SetMeasurementUnits(1);                     // milímetros
    Pdf.SetOrigin(1);                               // Top é medido a partir da borda superior

    Pdf.BarcodePayloadEncoding := bpeUTF8WithECI;   // bytes UTF-8 + ECI 000026
    if Pdf.DrawDataMatrixSymbol(20, 20, 0.5, 'Müller GmbH, Köln',
      1,      // Encoding: 1 = codificação ASCII
      0,      // SymbolSize: 0 = primeiro tamanho da tabela que acomoda
      100) <> 1 then                                // orientação normal, quiet zone padrão de 1 módulo
      raise Exception.CreateFmt('Data Matrix failed (%d)', [Pdf.LastErrorCode]);

    if Pdf.DrawPDF417SymbolEx(20, 50, 'Zustellung: Müller GmbH, Köln',
      0, 0, 0,  // orientação, colunas, linhas: automático
      -1,       // nível de erro automático
      0.3, 3.0) <> 1 then
      raise Exception.Create('PDF417 failed');

    // Um scanner com suporte a ECI deve devolver o texto alemão nos dois símbolos
    Pdf.BarcodePayloadEncoding := bpeSystemANSI;    // de volta ao padrão
    Pdf.SaveToFile(FileName);
  finally
    Pdf.Free;
  end;
end;

O NewDocument já cria a página 1 e a seleciona, então os símbolos caem na primeira página sem chamada a NewPage. O SetOrigin(1) move a origem para o canto superior esquerdo, o que faz do Top a distância da borda superior do símbolo até o topo da página. Com a origem padrão no canto inferior esquerdo, um Top de 10 mm põe essa borda 10 mm acima do fim da folha, e um símbolo de 11 mm escapa dela. O DrawDataMatrixSymbol retorna 1 em caso de sucesso. Para dados que ele não consegue codificar — um payload que estoura o maior símbolo quando o marcador entra na conta, ou o tamanho fixo que você pediu — ele retorna 0, define LastErrorCode como 302 e não desenha nada, então o exemplo trata qualquer coisa diferente de 1 como erro

Toda etiqueta deve carregar o marcador ECI?

Não, e o padrão reflete isso. O BarcodePayloadEncoding aceita três valores, e cada um serve a uma população diferente de leitores:

  • bpeSystemANSI (o padrão) converte o texto pela página de código ANSI do sistema e não grava marcador, que é o que os layouts de etiqueta feitos com as funções QR, PDF417 e Data Matrix do PDFlibPas esperam
  • bpeUTF8 grava bytes UTF-8 sem marcador, para sistemas fechados em que o seu próprio software lê o código de barras e já assume UTF-8
  • bpeUTF8WithECI grava bytes UTF-8 e os rotula com ECI 000026

O preço de rotular tudo é o suporte dos leitores. O processamento de ECI é uma opção de configuração em muitos scanners, e dependendo dessa configuração o aparelho pode recusar o símbolo ou passar o designador ao host como texto: a convenção da AIM é uma barra invertida e seis dígitos, então a aplicação recebe \000026Müller GmbH, Köln. Ligue o marcador por símbolo, para payloads com texto não ASCII, e faça o rollout junto com a mudança de perfil do scanner. Um payload single-byte continua sendo escolha razoável quando todo nome cabe na página de código que os seus leitores assumem. O ü é o byte FC tanto em Windows-1252 quanto em ISO-8859-1, então um endereço alemão escrito sob bpeSystemANSI num Windows da Europa Ocidental decodifica corretamente num leitor de Data Matrix que nunca ouviu falar de ECI. Texto japonês não tem esse fallback

Tamanho do símbolo: seleção automática, templates fixos e retângulos

Os dois codewords do marcador raramente agem sozinhos. Na codificação ASCII, a linha do destinatário sob bpeSystemANSI guarda ü e ö como bytes únicos acima de 127, a dois codewords cada, e a linha inteira custa 19 codewords, o que cabe num símbolo 20×20 com seus 22 codewords de dados. Em UTF-8 as duas letras viram quatro bytes altos e a linha custa 23. O marcador leva a 25. Isso pede 22×22, e o salto vem só dos bytes UTF-8, porque 23 já estoura o 20×20. Um template que fixa SymbolSize em 9 (20×20) recebe 0 e o erro 302 do DrawDataMatrixSymbol assim que a codificação muda, e nada é desenhado no slot do código de barras

O dimensionamento automático pode mudar a forma. Com SymbolSize em 0, o PDFlibPas percorre a lista de tamanhos da ISO/IEC 16022 em ordem e toma a primeira entrada cuja capacidade de dados acomoda o stream. Os seis tamanhos retangulares ficam nessa lista entre os quadrados. Um payload que preenchia um símbolo 26×26 (44 codewords de dados) precisa de 46 com o marcador, e a próxima entrada que comporta 46 é 16×48 com 49, antes do 32×32 com 62. A 0,5 mm por módulo, um quadrado de 13 mm vira uma faixa de 8 × 24 mm. Um 22×22 cheio faz o mesmo: 30 codewords mais dois caem no 16×36. Payloads pequenos continuam quadrados — três codewords que preenchiam um 10×10 viram cinco e cabem no 12×12, que precede o 8×18 na lista. Se a etiqueta reserva um slot quadrado, fixe o SymbolSize no quadrado que você pode pagar (16 para 32×32) e deixe o erro 302 avisar quando um nome é longo demais para ele; o dimensionamento automático serve a layouts que aceitam qualquer uma das formas

O PDF417 cresce por outra regra. Com ErrorLevel em -1, o encoder planeja a correção de erros a partir dos níveis mínimos recomendados da ISO/IEC 15438, que sobem em 41, 161 e 321 codewords, descritor de comprimento incluído. Um stream de 39 codewords vira 41 com o marcador, o nível mínimo passa de 2 para 3, e o bloco de correção de erros planejado cresce de 8 para 16 codewords. São dez codewords extras. Com colunas e linhas automáticas, o encoder monta o retângulo a partir desse total maior, então um payload parado logo abaixo de um degrau ganha mais área do que os dois codewords do marcador sugerem

Qual codificação mantém um Data Matrix UTF-8 pequeno?

Compare os dois custos diretamente. A codificação ASCII empacota um par de dígitos num codeword e ASCII puro a um por caractere, mas todo byte acima de 127 custa dois: um Upper Shift (235) e o byte menos 127. O Base 256 paga um latch e um campo de comprimento uma vez — um codeword de comprimento até 249 bytes, dois além disso — e depois um codeword por byte, sem empacotamento de dígitos. Para texto sem sequências de dígitos, o Base 256 ganha assim que o payload tem três bytes altos. A linha de Müller já tem, com 21 codewords contra 23. Sequências numéricas longas empurram o equilíbrio de volta para o ASCII, porque cada par de dígitos economiza um codeword lá. O helper abaixo conta os dois custos e desenha com o modo mais barato; ASCII puro não ganha marcador algum, já que lê de forma idêntica sob qualquer conjunto de caracteres:

// Desenha um Data Matrix para texto Unicode com a codificação mais 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);                    // par de dígitos: um codeword
      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 + um codeword de comprimento
  else
    Base256Cost := Length(Bytes) + 3;    // latch + dois codewords de comprimento

  Saved := Pdf.BarcodePayloadEncoding;
  try
    if HighBytes = 0 then
    begin
      Pdf.BarcodePayloadEncoding := bpeSystemANSI;  // ASCII puro: sem 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 東京都千代田区, a forma UTF-8 tem 21 bytes, todos acima de 127. Com o marcador, o Base 256 precisa de 25 codewords de dados e a codificação ASCII de 44, o que pela tabela de capacidade dá um símbolo 22×22 contra um 26×26 no mesmo tamanho de módulo. Esse 26×26 está cheio. Um codeword a mais e ele salta para 16×48. Payloads GS1 (mode 7) ficam fora do helper porque as strings de elemento deles são ASCII. Códigos QR recebem o data mode pelo argumento EncodeOptions do DrawQRCode, e símbolos Aztec desenhados pelo PDFlibPas carregam uma flag ECI 26 automaticamente sempre que os bytes do payload são UTF-8 válido com pelo menos um caractere não ASCII

Custos de codificação ASCII versus Base 256 para códigos de barras Data Matrix do PDFlibPas em Delphi, com totais de codewords calculados e o modo que o helper escolhe
o Base 256 ganha quando aparecem três ou mais bytes altos, enquanto payloads cheios de dígitos puxam o custo de volta para a codificação ASCII

Para a linha de Müller, o marcador custa dois codewords, enquanto a mudança de 20×20 para 22×22 — 10 mm para 11 mm em módulos de 0,5 mm — é causada pelos bytes UTF-8. Se o slot da sua etiqueta tem esse milímetro extra, defina o BarcodePayloadEncoding como bpeUTF8WithECI na instância de TPDFlib da PDFlibPas Delphi PDF Library logo antes de o símbolo do destinatário ser desenhado, e volte para bpeSystemANSI nos símbolos legados da mesma página