기술 문서

Delphi 2D 바코드에서 Müller가 Müller가 되는 이유

창고 라벨은 수신인 Müller GmbH, Köln을 UTF-8로 Data Matrix 심볼에 담는데, 현장의 모든 휴대용 스캐너는 이를 Müller GmbH, Köln으로 읽어 돌려줍니다. PDFlibPas 속성 BarcodePayloadEncoding을 bpeUTF8WithECI로 설정하면 데이터 앞에 ECI 000026 마커가 붙고, 이것이 Data Matrix와 PDF417 리더에게 바이트를 UTF-8로 디코딩하라고 알려 줍니다

UTF-8 페이로드가 왜 Müller로 디코딩되는가

심볼에는 문자셋 선언이 없으므로 리더는 해당 심볼로지의 기본 1바이트 문자셋, Data Matrix라면 ISO-8859-1로 떨어집니다. UTF-8 ü는 C3 BC 두 바이트인데, ISO-8859-1에서 이는 Ã과 ¼로 대응됩니다. ö도 같은 방식으로 ö가 되죠. 바이트 자체는 온전합니다. Extended Channel Interpretation은 바코드 세계의 문자셋 선언입니다. AIM ECI 레지스트리는 문자셋에 번호를 부여하는데, 그중 000026이 UTF-8입니다. ECI 디지네이터로 시작하는 심볼은 규격을 따르는 리더에게 그 뒤의 모든 것을 해당 문자셋으로 디코딩하라고 말합니다. 심볼 입장에서 디지네이터는 그저 평범한 데이터일 뿐입니다. 이 글에서 다루는 두 심볼로지 모두에서 두 코드워드를 차지하고, 용량에 포함되며, 뒤에 오는 페이로드와 마찬가지로 2D 바코드의 Reed-Solomon 오류 정정으로 보호됩니다

PDFlibPas Delphi 바코드에서 같은 UTF-8 바이트가 두 가지로 디코딩되는 흐름: ECI 마커가 없으면 ISO-8859-1 추측, ECI 000026이면 UTF-8
심볼은 바이트만 저장하므로, 바이트가 ISO-8859-1 추측이 아니라 UTF-8임을 리더에게 알려 주는 것은 ECI 000026 디지네이터입니다

Data Matrix와 PDF417에서 ECI 코드워드 위치

각 심볼로지마다 마커를 위한 고정 슬롯이 있습니다. 다른 곳에 넣으면 심볼은 디코딩에 실패하거나 앞에 쓰레기를 붙인 채 디코딩됩니다:

Delphi로 만드는 PDFlibPas Data Matrix, GS1 Data Matrix, PDF417 심볼에서 ECI UTF-8 마커의 코드워드 슬롯: 각각 페이로드 앞의 고정 위치
모든 심볼로지는 ECI 디지네이터를 선행 고정 슬롯에 고정하며, PDFlibPas는 위치 의존 인코딩이 실행되기 전에 이를 기록합니다
  • Data Matrix(ISO/IEC 16022): 코드워드 241, 그다음 127 미만 값에 쓰이는 단일 코드워드 형식으로 ECI 번호 + 1, 즉 UTF-8은 27입니다. 데이터 스트림의 맨 앞을 엽니다
  • GS1 Data Matrix: FNC1(코드워드 232)은 첫 번째 위치를 지켜야 하므로, 요청하면 PDFlibPas는 그 바로 뒤에 마커를 놓습니다. 다만 GS1 엘리먼트 스트링은 ASCII 부분집합으로 이루어져 있어 마커가 없어도 똑같이 읽힙니다
  • PDF417(ISO/IEC 15438): 코드워드 0은 심볼 길이 디스크립터이고, 마커는 코드워드 927과 26으로 이어져 첫 데이터 코드워드 앞에 놓입니다

Base 256이 까다로운 사례입니다. 임의 바이트를 위한 Data Matrix의 압축 인코딩인 이 모드는 각 코드워드를 심볼 내 절대 위치에서 유도한 의사 난수 값, (149 × position mod 255) + 1로 스크램블합니다. 스크램블 후에 마커를 앞에 붙이면 뒤의 모든 바이트가 리더가 보는 위치보다 두 자리 앞 위치 기준으로 스크램블된 셈이라, 페이로드 전체가 엉뚱한 값으로 복원됩니다. EDIFACT 인코딩은 같은 의존성의 온건한 버전을 지닙니다. 마커가 앞에 들어가면 unlatch 위치가 둘 밀려 납니다. PDFlibPas는 어느 쪽 단계도 실행되기 전에 코드워드 스트림에 마커를 기록하고, 심볼 크기를 고르는 용량 검사도 이미 이를 포함합니다. 두 심볼로지의 라벨 코드입니다:

uses
  SysUtils, PDFlibrary;

procedure PrintConsigneeLabel(const FileName: string);
var
  Pdf: TPDFlib;
begin
  Pdf := TPDFlib.Create;
  try
    Pdf.NewDocument;                                // 페이지 1을 만들고 선택합니다
    Pdf.SetPageSize('A4');
    Pdf.SetMeasurementUnits(1);                     // 밀리미터
    Pdf.SetOrigin(1);                               // Top은 위쪽 가장자리부터 측정합니다

    Pdf.BarcodePayloadEncoding := bpeUTF8WithECI;   // UTF-8 바이트 + ECI 000026
    if Pdf.DrawDataMatrixSymbol(20, 20, 0.5, 'Müller GmbH, Köln',
      1,      // Encoding: 1 = ASCII 인코딩
      0,      // SymbolSize: 0 = 맞는 표의 첫 크기
      100) <> 1 then                                // 일반 방향, 기본 1모듈 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,  // 방향, 열, 행: 자동
      -1,       // 오류 레벨 자동
      0.3, 3.0) <> 1 then
      raise Exception.Create('PDF417 failed');

    // ECI를 아는 스캐너는 두 심볼 모두에서 독일어 텍스트를 돌려줘야 합니다
    Pdf.BarcodePayloadEncoding := bpeSystemANSI;    // 기본값으로 되돌림
    Pdf.SaveToFile(FileName);
  finally
    Pdf.Free;
  end;
end;

NewDocument는 이미 페이지 1을 만들고 선택하므로 NewPage 호출 없이도 심볼이 첫 페이지에 놓입니다. SetOrigin(1)은 원점을 왼쪽 위 구석으로 옮겨 Top이 심볼 윗면에서 페이지 위쪽까지의 거리가 되게 합니다. 기본인 왼쪽 아래 원점에서는 Top 10 mm가 그 가장자리를 용지 바닥에서 10 mm 위에 놓고, 11 mm 심볼은 용지 밖으로 삐져 나갑니다. DrawDataMatrixSymbol은 성공 시 1을 반환합니다. 인코딩할 수 없는 데이터, 즉 마커까지 세면 최대 심볼을 넘는 페이로드나 지정한 고정 크기에 대해서는 0을 반환하고 LastErrorCode를 302로 설정하며 아무것도 그리지 않으므로, 예제는 1이 아닌 모든 값을 오류로 취급합니다

모든 라벨이 ECI 마커를 달아야 하는가

아니며, 기본값도 그를 반영합니다. BarcodePayloadEncoding은 세 값을 받는데, 각각이 서로 다른 리더 집단에 맞습니다:

  • bpeSystemANSI(기본값)는 텍스트를 시스템 ANSI 코드 페이지로 변환하고 마커를 쓰지 않습니다. PDFlibPas QR, PDF417, Data Matrix 함수로 만든 라벨 레이아웃이 기대하는 동작입니다
  • bpeUTF8은 마커 없이 UTF-8 바이트를 씁니다. 자체 소프트웨어가 바코드를 읽고 이미 UTF-8을 가정하는 폐쇄 시스템용입니다
  • bpeUTF8WithECI는 UTF-8 바이트를 쓰고 ECI 000026로 표시합니다

전부 표시하는 대가는 리더 지원입니다. ECI 처리는 많은 스캐너에서 설정 옵션이고, 이 설정에 따라 장치는 심볼을 거부하거나 디지네이터를 텍스트로 호스트에 넘길 수 있습니다. AIM 관례는 역슬래시 뒤 여섯 자리 숫자라 애플리케이션은 \000026Müller GmbH, Köln을 받습니다. 마커는 non-ASCII 텍스트를 담는 페이로드에 심볼 단위로 켜고, 스캐너 프로파일 변경과 함께 롤아웃하세요. 모든 이름이 리더가 가정하는 코드 페이지에 들어맞는다면 1바이트 페이로드도 여전히 합리적 선택입니다. ü는 Windows-1252와 ISO-8859-1 모두에서 바이트 FC이므로, 서유럽 Windows 시스템에서 bpeSystemANSI로 쓴 독일어 주소는 ECI를 한 번도 들어 보지 못한 Data Matrix 리더에서도 올바르게 디코딩됩니다. 일본어 텍스트에는 그런 fallback이 없습니다

심볼 크기: 자동 선택, 고정 템플릿, 사각형

마커의 두 코드워드가 혼자 작동하는 경우는 드뭅니다. ASCII 인코딩에서 bpeSystemANSI 기준 수신인 줄은 ü와 ö를 127을 넘는 단일 바이트로 담아 각각 두 코드워드를 먹고, 줄 전체는 19 코드워드로 22개 데이터 코드워드를 지닌 20×20 심볼에 들어맞습니다. UTF-8로는 두 문자가 high byte 넷이 되어 줄이 23 코드워드이고, 마커가 25로 만듭니다. 그러면 22×22이 필요한데, 단계 상승은 UTF-8 바이트만으로 오는 것입니다. 23만으로도 이미 20×20을 넘으니까요. SymbolSize를 9(20×20)로 고정한 템플릿은 인코딩이 바뀌는 순간 DrawDataMatrixSymbol에서 0과 오류 302를 받고 바코드 슬롯에는 아무것도 그려지지 않습니다

자동 크기 선택은 모양을 바꿀 수 있습니다. SymbolSize가 0이면 PDFlibPas는 ISO/IEC 16022 크기 목록을 순서대로 훑고 스트림을 담는 데이터 용량을 지닌 첫 항목을 택합니다. 여섯 개의 사각형 크기는 그 목록에서 정사각형 사이에 끼어 있습니다. 26×26 심볼(44 데이터 코드워드)을 채우던 페이로드는 마커를 더해 46이 필요하고, 46을 담는 다음 항목은 62의 32×32보다 앞선 49의 16×48입니다. 모듈당 0.5 mm로는 13 mm 정사각형이 8 × 24 mm 스트립이 됩니다. 꽉 찬 22×22도 같은 일을 겪습니다. 30 코드워드에 둘을 더하면 16×36에 놓입니다. 작은 페이로드는 정사각형을 유지합니다. 10×10을 채우던 세 코드워드는 다섯이 되어 목록에서 8×18보다 앞선 12×12에 들어맞습니다. 라벨이 정사각형 슬롯을 예약해 둔다면 감당 가능한 정사각형(32×32는 16)으로 SymbolSize를 고정하고 이름이 너무 길 때는 오류 302가 말하게 두세요. 두 모양을 다 받아 줄 수 있는 레이아웃이라면 자동 크기 선택이 맞습니다

PDF417은 다른 규칙으로 자랍니다. ErrorLevel이 -1이면 인코더는 ISO/IEC 15438의 권장 최소 레벨에서 오류 정정을 계획하는데, 이는 길이 디스크립터까지 포함해 41, 161, 321 코드워드에서 단계 상승합니다. 39 코드워드 스트림은 마커로 41이 되고, 최소 레벨은 2에서 3으로 움직이며, 계획되는 오류 정정 블록은 8에서 16 코드워드로 자랍니다. 코드워드 열 개가 추가로 드는 셈입니다. 열과 행이 자동이면 인코더는 그 커진 총량으로 사각형을 배치하므로, 단계 경계 바로 아래에 붙어 있던 페이로드는 마커 두 코드워드가 암시하는 것보다 넓은 면적을 얻습니다

어떤 인코딩이 UTF-8 Data Matrix를 작게 유지하는가

두 비용을 정면으로 비교해 봅시다. ASCII 인코딩은 숫자 쌍을 코드워드 하나에 담고 평범한 ASCII는 문자당 하나씩이지만, 127을 넘는 바이트는 모두 두 개씩 듭니다. Upper Shift(235)와 바이트 - 127이죠. Base 256은 latch와 길이 필드를 한 번만 지불합니다. 249바이트까지는 길이 코드워드 하나, 그를 넘으면 둘입니다. 그리고 바이트당 코드워드 하나, 숫자 패킹은 없습니다. 숫자 연속이 없는 텍스트라면 페이로드가 high byte 셋을 담는 순간 Base 256이 이깁니다. Müller 줄은 이미 그렇습니다. 21 코드워드 대 23이죠. 긴 숫자 연속은 저울을 다시 ASCII 쪽으로 밀어 넣습니다. 숫자 쌍 하나하나가 코드워드를 아껴 주니까요. 아래 헬퍼는 두 비용을 세어 더 싼 모드로 그립니다. 순수 ASCII는 어떤 문자셋에서도 똑같이 읽히므로 마커를 전혀 붙이지 않습니다:

// 더 싼 인코딩으로 Unicode 텍스트용 Data Matrix를 그립니다
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);                    // 숫자 쌍: 코드워드 하나
      Inc(I, 2);
      Continue;
    end;
    if Ord(Bytes[I]) > 127 then
    begin
      Inc(HighBytes);
      Inc(AsciiCost, 2);                 // Upper Shift + (바이트 - 127)
    end
    else
      Inc(AsciiCost);
    Inc(I);
  end;
  if Length(Bytes) <= 249 then
    Base256Cost := Length(Bytes) + 2     // latch + 길이 코드워드 하나
  else
    Base256Cost := Length(Bytes) + 3;    // latch + 길이 코드워드 둘

  Saved := Pdf.BarcodePayloadEncoding;
  try
    if HighBytes = 0 then
    begin
      Pdf.BarcodePayloadEncoding := bpeSystemANSI;  // 순수 ASCII: 마커 없음
      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;

東京都千代田区의 UTF-8 형태는 21바이트로 전부 127을 넘습니다. 마커를 더하면 Base 256은 25 데이터 코드워드, ASCII 인코딩은 44가 필요하고, 용량표로는 같은 모듈 크기에서 22×22 심볼 대 26×26 심볼입니다. 그 26×26은 꽉 찼습니다. 코드워드 하나만 더해도 16×48로 뛰어 오릅니다. GS1 페이로드(모드 7)는 엘리먼트 스트링이 ASCII라 헬퍼 바깥에 둡니다. QR 코드는 DrawQRCode의 EncodeOptions 인자로 데이터 모드를 넘기고, PDFlibPas가 그리는 Aztec 심볼은 페이로드 바이트가 non-ASCII 문자를 하나 이상 담은 유효한 UTF-8이면 ECI 26 플래그를 자동으로 실어 나릅니다

Delphi의 PDFlibPas Data Matrix 바코드에 대한 ASCII 대 Base 256 인코딩 비용: 계산된 코드워드 총계와 헬퍼가 고르는 모드
high byte가 셋 이상 나타나는 순간 Base 256이 이기지만, 숫자가 많은 페이로드는 비용을 다시 ASCII 인코딩 쪽으로 밀어 돌립니다

Müller 줄에서 마커 비용은 코드워드 둘이지만, 20×20에서 22×22로의 이동, 즉 0.5 mm 모듈 기준 10 mm에서 11 mm로의 변화는 UTF-8 바이트가 일으킵니다. 라벨 슬롯에 그 1 mm가 여유가 있다면 PDFlibPas Delphi PDF Library의 TPDFlib 인스턴스에서 수신인 심볼을 그리기 직전에 BarcodePayloadEncoding을 bpeUTF8WithECI로 설정하고, 같은 페이지의 기존 심볼에는 bpeSystemANSI로 되돌리세요