Python에서 QR 코드 인코딩 모드 설정

모든 QR 생성기는 기본적으로 인코딩 모드를 자동으로 선택하며, 대부분의 경우 이 기본값으로 충분합니다. 그러나 숫자 ID를 제품 코드 옆에 넣거나, UTF-8로 저장하고 싶지 않은 일본어 텍스트 블록을 사용하거나, 매번 생성할 때 동일한 바이트가 필요하는 페이로드와 같이 제어가 필요할 때는 기본값이 더 이상 적합하지 않게 됩니다. 이 가이드는 Aspose.BarCode for Python via .NET을 사용하여 Python에서 QR 코드 인코딩 모드 설정을 명시적으로 수행하는 방법을 보여줍니다. 이를 통해 단일 QR 심볼이 숫자 세그먼트, 영숫자 세그먼트, 바이트 세그먼트 및 한자 세그먼트를 각각 가장 적합한 모드에 저장하여 포함할 수 있습니다.

Aspose.BarCode는 자체 API 이름(QrExtCompactionMode)에서 이러한 compaction modes를 호출하고 QR 사양 자체에서는 이를 encoding modes라고 부릅니다. 두 이름 아래 동일한 네 가지 모드이며, 이 가이드에서는 사양 및 대부분의 Python QR 라이브러리에서 사용하는 용어이므로 전체적으로 “encoding mode"를 사용합니다.

QR 인코딩 모드가 심볼 크기와 스캔 신뢰성에 영향을 미치는 이유

QR 코드의 물리적 크기는 페이로드에 필요한 비트 수에 의해 결정되며, 문자당 비트 수는 해당 세그먼트에 사용된 인코딩 모드에 전적으로 의존합니다. 사양에서는 현저히 다른 밀도를 가진 네 가지 데이터 모드를 정의합니다.

30자리 식별자는 숫자 모드에서는 대략 100비트, 바이트 모드에서는 240비트가 소요됩니다. 이 차이는 종종 심볼을 여러 QR 버전으로 올리기에 충분하며, 높은 버전은 동일한 인쇄 영역에 더 많은 모듈을 의미합니다 — 모듈이 작아지고 저해상도 카메라, 곡선 포장 및 마모된 라벨에서 읽기율이 낮아집니다.

자동 모드 선택은 대부분의 페이로드를 잘 처리합니다. 데이터의 형태를 알고 분석기가 이를 알지 못할 때는 제한적이 됩니다: 하나의 문자에 의해 끊어진 긴 숫자 연속, 바이트 모드가 문자당 세 개의 UTF-8 바이트를 사용하게 되는 일본어 텍스트, 또는 라이브러리 버전 간에 결정적인 출력을 원할 때의 고정 형식 식별자.

모드를 수동으로 설정하는 것이 가치가 있을 때

모드 전환은 무료가 아닙니다. 각 세그먼트 경계마다 QR 버전에 따라 8~16비트의 문자 수 필드와 함께 4비트 모드 표시기가 기록됩니다. 페이로드를 과도하게 세그먼트하면 생성기가 결정하도록 두는 것보다 더 큰 심볼이 생성될 수 있습니다.

모드를 명시적으로 설정하면 효과가 있는 경우:

• 페이로드에는 긴 동질적인 구간이 포함됩니다 — 40자리 시리얼 번호와 한자 단락.
• 일본어 텍스트를 인코딩하고 있으며 바이트 모드 24비트 대신 문자당 13비트인 한자 모드를 원합니다.
• 회귀 테스트나 체크섬 검증을 위해 재현 가능하고 바이트가 동일한 출력을 필요로 합니다.

짧은 페이로드, 몇 글자마다 유형이 바뀌는 데이터, 또는 자동 분석이 이미 잘 처리하는 URL과 같은 경우에는 추가 복잡성을 도입할 가치가 보통 없습니다. 아래 측정 하위 섹션에서는 어떤 경우에 해당하는지 확인하는 방법을 보여줍니다.

Python에서 QR 인코딩 모드를 설정하는 두 가지 방법

Aspose.BarCode는 동일한 인코딩 결과에 대한 두 가지 경로를 제공하며, 코드를 작성하기 전에 두 경로가 모두 존재하는 이유를 아는 것이 좋습니다.

빌더가 더 나은 기본값입니다. QrExtCompactionMode.NUMERIC은 존재하거나 즉시 AttributeError를 발생시킵니다, 반면 문자열에서 잘못 입력된 \numm은 조용히 페이로드 데이터가 되어 라벨을 스캔할 때만 나타납니다. 두 접근 방식 모두 동일한 QREncodeMode.EXTENDED 생성기 설정을 사용하므로, 하위 단계에서 아무것도 변경하지 않고도 전환할 수 있습니다.

Python에서 QR 코드 인코딩 모드 설정: 단계별

1. 설치 및 개발 환경 준비

Aspose.BarCode for Python via .NET은 50개 이상의 심볼(시모볼리)과 QR을 포함한 생성, 인식 및 조작을 지원하는 크로스 플랫폼 라이브러리입니다. PyPI에서 설치하세요:

pip install aspose-barcode-for-python-via-net

버전을 확인하십시오. 이 API는 26.6 이상이 필요합니다:

pip show aspose-barcode

그런 다음 import가 해결되는지 확인하십시오. 패키지는 .NET 런타임에 바인딩되므로, 성공적인 import는 디스크에 파일이 존재하는 것보다 더 많은 정보를 제공합니다.

from aspose.barcode.generation import QREncodeMode, QrExtCompactionMode

print("Aspose.BarCode imported successfully.")
print("EXTENDED mode available:", hasattr(QREncodeMode, "EXTENDED"))
print("Encoding modes:", [m for m in dir(QrExtCompactionMode) if m.isupper()])

Output:

Aspose.BarCode imported successfully.
EXTENDED mode available: True
Encoding modes: ['ALPHA_NUMERIC', 'AUTO', 'BYTES', 'KANJI', 'NUMERIC']

EXTENDED가 없으면, 26.6 이전 버전을 사용 중이며 계속 진행하기 전에 업그레이드해야 합니다.

라이선스 파일이 있는 경우, 생성 또는 인식 호출을 하기 전에 애플리케이션 시작 시 한 번 적용하십시오:

from aspose.barcode import License

license = License()
license.set_license("Aspose.BarCode.Python.NET.lic")

2. QrExtCodetextBuilder와 함께 각 세그먼트의 인코딩 모드 설정

QrExtCodetextBuilder는 세그먼트의 순서가 지정된 목록을 보유합니다. 각 호출은 데이터를 해당 인코딩 모드와 함께 추가하며, get_extended_codetext()는 이를 생성기가 이해하는 확장 형식 문자열로 조합합니다.

1. 생성 클래스를 가져옵니다.
2. QrExtCodetextBuilder 를 생성합니다.
3. QrExtCompactionMode.NUMERIC 로 숫자 세그먼트를 추가합니다.
4. QrExtCompactionMode.ALPHA_NUMERIC 로 알파벳‑숫자 세그먼트를 추가합니다.
5. QrExtCompactionMode.BYTES 로 바이트 세그먼트를 추가합니다.
6. QrExtCompactionMode.KANJI 로 한자 세그먼트를 추가합니다.
7. 결합된 확장 코드 텍스트를 가져옵니다.

from aspose.barcode.barcoderecognition import BarCodeReader, DecodeType
from aspose.barcode.generation import (
    BarcodeGenerator,
    EncodeTypes,
    QREncodeMode,
    QrExtCodetextBuilder,
    QrExtCompactionMode,
)

# Instantiate the Builder.
text_builder = QrExtCodetextBuilder()

# Numeric Segment — 3 Digits per 10 Bits.
text_builder.add_codetext_with_compaction_mode(
    QrExtCompactionMode.NUMERIC, "1234567"
)

# Alphanumeric Segment — Uppercase and Digits Only, 2 Characters per 11 Bits.
text_builder.add_codetext_with_compaction_mode(
    QrExtCompactionMode.ALPHA_NUMERIC, "ASPOSE2026"
)

# Byte Segment — Lowercase Forces Byte Mode, 8 Bits per Character.
text_builder.add_codetext_with_compaction_mode(
    QrExtCompactionMode.BYTES, "aspose2026"
)

# Kanji Segment — Shift-JIS Double-Byte Characters, 13 Bits Each.
text_builder.add_codetext_with_compaction_mode(
    QrExtCompactionMode.KANJI,
    "\u3062\u3063\u3064\u3065\u3066\u3067\u3068\u3069\u306A",
)

# Assemble the Final Extended Codetext.
codetext = text_builder.get_extended_codetext()
print("Extended codetext:", repr(codetext))

설명

• 각 add_codetext_with_compaction_mode 호출은 하나의 세그먼트에 대한 인코딩 모드를 설정합니다. 순서가 중요합니다 — 디코더는 추가한 순서대로 세그먼트를 연결하여 반환합니다.
• 알파벳‑숫자 집합은 의도적으로 좁게 정의되어 있습니다: 숫자, 대문자 A‑Z, 공백, 그리고 $%*+-./:. 그래서 ASPOSE2026은 알파벳‑숫자 모드에 맞지만 aspose2026은 맞지 않습니다. 소문자는 집합에 포함되지 않으므로 해당 세그먼트는 BYTES를 사용해야 합니다. 소문자를 ALPHA_NUMERIC에 전달하는 것은 이러한 방식으로 모드를 설정할 때 가장 흔히 발생하는 실수입니다.
• Kanji 세그먼트는 \u3062 이후를 사용하며, 이는 실제 Kanji가 아니라 히라가나입니다. Kanji 모드는 Shift‑JIS 이중 바이트 범위를 포함하는데, 여기에는 가나가 포함되므로 각각 13비트로 인코딩됩니다. 이는 UTF‑8에서 각각 24비트를 사용하게 되는 바이트 모드와 대비됩니다.
• get_extended_codetext()는 생성기가 EXTENDED 모드에서 파싱하는 문자열을 생성합니다. repr()으로 한 번 출력해 보는 것이 좋습니다 — 이렇게 하면 빌더가 내보내는 선택자 구문을 확인할 수 있으며, 이는 다음 하위 섹션에서 수동으로 작성하는 내용과 정확히 일치합니다.

3. 인코딩 모드를 인라인으로 설정, 빌더 없이

코드 텍스트가 Python 코드 외부에서 시작될 경우, 선택자를 사용하여 각 세그먼트의 모드를 직접 설정할 수 있습니다. 백슬래시가 앞에 붙은 마커는 다음 마커가 나타날 때까지 모든 문자를 제어합니다:

# Equivalent to the Builder Output Above, Written Directly.
codetext = (
    r"\num1234567"
    r"\alnumASPOSE2026"
    r"\byteaspose2026"
    "\\kanji\u3062\u3063\u3064\u3065\u3066\u3067\u3068\u3069\u306A"
)

이스케이프에 유의하세요. 일반 Python 문자열에서 "\num"은 선택자가 아니라 줄 바꿈 뒤에 um이 오는 것입니다. 원시 문자열(r"...")은 이 문제를 피하지만, 원시 문자열은 \u 이스케이프도 차단하므로 위의 한자 라인에서는 \\kanji를 사용한 일반 문자열을 사용합니다. 이러한 이스케이프 함정은 섹션 2에서 빌더를 선호하는 실용적인 이유입니다.

4. 확장 모드에서 QR 바코드 생성

세그먼트별 모드를 설정해도 생성기가 이를 읽도록 지시받기 전까지는 효과가 없습니다. QREncodeMode.EXTENDED 없이 세그먼트 정보는 무시되고 선택자 마커는 리터럴 페이로드 텍스트로 인코딩됩니다.

1. BarcodeGenerator를 EncodeTypes.QR와 확장된 코드 텍스트로 생성합니다.
2. encode_mode를 QREncodeMode.EXTENDED로 설정합니다.
3. 해상도를 구성하고, 필요에 따라 오류 정정 수준 및 여백을 설정합니다.
4. 바코드를 무손실 PNG로 저장합니다.

# Create the QR Generator with the Extended Codetext.
gen = BarcodeGenerator(EncodeTypes.QR, codetext)

# Switch to EXTENDED Mode So the Per-Segment Modes Are Respected.
gen.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED

# Render at Print Resolution Rather Than Upscaling Later.
gen.parameters.resolution = 300

# Save the Generated QR Code.
gen.save("extended_qr.png")

print("QR code generated and saved as extended_qr.png")

설명

• gen.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED 은 세그먼트 파싱을 활성화하는 라인입니다. 이를 제외하면 생성기는 리터럴 텍스트 \num1234567... 를 포함하는 유효하고 스캔 가능한 QR 코드를 생성합니다 — 그래서 다음 섹션에서는 가정하지 않고 검증합니다.
• gen.parameters.resolution = 300 은 인쇄 해상도로 렌더링합니다. 라벨 프린터나 포장 아트워크용 심볼은 최종 크기로 생성되어야 하며, 이후에 확대해서는 안 됩니다. 확대하면 모듈 가장자리가 부드러워집니다.
• save 는 무손실 PNG를 저장합니다. 2D 심볼리즘에는 JPEG를 피하십시오 — 압축 아티팩트가 디코더가 샘플링하는 모듈 그리드를 흐리게 합니다.

5. 인코딩 모드가 적용되었는지 확인

성공적인 생성은 세그먼트별 모드가 적용되었는지에 대해 아무것도 증명하지 못합니다. 디코드 단계가 올바르게 인코딩된 심볼과 선택자 마커를 데이터로 가지고 있는 심볼을 구분하는 부분입니다.

1. 파일 경로와 DecodeType.QR을 사용하여 BarCodeReader를 초기화합니다.
2. 읽기가 실패했을 경우를 확인할 수 있도록 결과를 구체화합니다.
3. 디코딩된 텍스트를 예상된 연결 문자열과 비교합니다.

EXPECTED = (
    "1234567"
    "ASPOSE2026"
    "aspose2026"
    "\u3062\u3063\u3064\u3065\u3066\u3067\u3068\u3069\u306A"
)

# Initialise the QR Code Reader.
reader = BarCodeReader("extended_qr.png", DecodeType.QR)
results = list(reader.read_bar_codes())

if not results:
    raise ValueError("No QR code was detected in extended_qr.png.")

for result in results:
    decoded = result.code_text
    print("BarCode CodeText:", decoded)

if "\\num" in decoded or "\\alnum" in decoded:
        print("Selectors were encoded literally — check that encode_mode is EXTENDED.")
    elif decoded == EXPECTED:
        print("Verified: all four segments decoded and concatenated as expected.")
    else:
        print("Mismatch. Expected:", EXPECTED)

설명

• DecodeType.QR는 QR 기호만 인식하도록 제한하며, 이는 모든 지원되는 심볼을 스캔하는 것보다 빠르고 잘못된 기호가 다른 것으로 디코딩되는 것을 방지합니다.
• list(...)는 실패 경우를 명시적으로 나타냅니다. 인식 실패 시 예외를 발생시키는 대신 빈 iterable을 반환하므로, 실패한 읽기에 대해 보호되지 않은 for 루프는 조용히 종료되고 성공으로 처리됩니다.
• 리터럴 \num을 확인하면 이 워크플로우에서 가장 흔한 실수인 세그먼트를 올바르게 설정했지만 encode_mode를 설정하지 않은 경우를 잡아냅니다.
• 디코딩된 페이로드는 모든 모드 정보가 인코딩 중에 소비된 후 원시 세그먼트를 연결한 것입니다. 인코딩 모드는 데이터의 일부가 아니라 인코더에 대한 지시사항입니다.

6. 수동으로 모드 설정이 도움이 되었는지 측정

인코딩 모드를 수동으로 설정하는 것은 최적화이므로 가정하지 말고 측정하십시오. 두 방법 모두에서 동일한 페이로드를 생성하고 비교하십시오:

RAW = "1234567ASPOSE2026aspose2026"

# Automatic Mode Selection.
auto = BarcodeGenerator(EncodeTypes.QR, RAW)
auto.save("qr_auto.png")

# Manually Set Modes per Segment.
builder = QrExtCodetextBuilder()
builder.add_codetext_with_compaction_mode(QrExtCompactionMode.NUMERIC, "1234567")
builder.add_codetext_with_compaction_mode(QrExtCompactionMode.ALPHA_NUMERIC, "ASPOSE2026")
builder.add_codetext_with_compaction_mode(QrExtCompactionMode.BYTES, "aspose2026")

manual = BarcodeGenerator(EncodeTypes.QR, builder.get_extended_codetext())
manual.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED
manual.save("qr_manual.png")

print("Compare qr_auto.png and qr_manual.png — count modules along one edge.")

각 이미지의 한 변을 따라 모듈을 셉니다. QR 버전 n 심볼은 17 + 4n 모듈 정사각형이며, 따라서 버전 2는 25×25이고 버전 3은 29×29입니다. 두 경우가 동일한 버전에 도달하면 자동 분석이 이미 최적의 세분화를 찾았으며, 모드를 수동으로 설정하는 것은 이득 없이 유지 보수 부담이 됩니다. 배송 전에 이를 발견하는 것은 낭비된 단계가 아니라 유용한 결과입니다.

무료 라이선스 받기

Aspose는 평가 제한을 해제하고 테스트를 위한 전체 기능을 활용할 수 있는 임시 무료 라이선스를 제공합니다. Aspose 임시 라이선스 페이지에서 라이선스를 요청하고, 생성 또는 인식 호출을 수행하기 전에 적용하십시오.

무료 추가 리소스

• 제품 문서
• API 참조
• 무료 온라인 바코드 앱

결론

Python에서 QR 코드 인코딩 모드를 설정하는 것은 두 가지 질문으로 요약됩니다: 어떤 세그먼트가 어떤 모드를 사용해야 하는지, 그리고 생성기에 그 선택을 어떻게 적용하도록 지시하는지. QrExtCodetextBuilder와 QrExtCompactionMode는 애플리케이션 코드에서 첫 번째 질문에 답하고; QREncodeMode.EXTENDED는 생성기에서 두 번째 질문에 답합니다. 이 가이드는 빌더 API와 그것이 생성하는 인라인 선택자 구문을 모두 다루며, 네 개 세그먼트 QR 심볼을 생성하고, 디코드된 페이로드를 검증하며, 자동 모드와 비교한 크기 차이를 측정합니다.

빌더를 애플리케이션 코드에 선호하세요 — 호출 지점에서 모드 오류를 잡아주어 스캐너에서 잡는 것보다 좋습니다. 그리고 측정 단계를 유지하세요. 모드를 수동으로 설정하는 것은 긴 동질 페이로드에서는 실제 이점이 되고, 짧은 혼합 페이로드에서는 모드 전환 오버헤드가 절감 효과를 초과하여 순손실이 됩니다. 두 가지를 모두 생성하고, 모듈 수를 비교한 뒤 결과에 따라 유지할 코드를 결정하세요.

자주 묻는 질문

1. QR 코드 인코딩 모드란 무엇이며 왜 사용해야 하나요? 인코딩 모드는 QR 생성기가 데이터 세그먼트를 어떻게 처리할지(숫자, 영숫자, 바이트 또는 한자) 알려줍니다. 각 모드는 데이터 밀도가 다르므로 세그먼트마다 적절한 모드를 선택하면 QR 버전, 즉 심볼을 가능한 작게 유지할 수 있습니다. Aspose.BarCode는 이를 압축 모드라고 부르고, QR 사양에서는 인코딩 모드라고 부릅니다.

2. QrExtCompactionMode이 지원하는 인코딩 모드는 무엇입니까? QrExtCompactionMode은 NUMERIC, ALPHA_NUMERIC, BYTES, KANJI를 제공하며, ISO/IEC 18004에 정의된 네 가지 QR 데이터 모드와 일치합니다.

3. 모드 설정에 QrExtCodetextBuilder를 사용해야 하나요, 아니면 인라인 EXTENDED 선택자를 사용해야 하나요? 응용 프로그램 코드에서는 빌더를 사용하세요. 빌더는 타입 검사를 수행하고, 백슬래시 이스케이프 실수를 방지하며, 확장된 코덱스트를 자동으로 조립해 줍니다. 인라인 선택자는 코덱스트가 구성 파일, 데이터베이스 또는 빌더를 호출할 수 없는 다른 시스템에서 전달될 때 유용합니다.

4. EXTENDED 인코드 모드는 표준 QR 인코드 모드와 어떻게 다릅니까? EXTENDED 모드는 전체 문자열에 대해 자동 모드 감지를 수행하는 대신, 코드를 미리 정의된 여러 세그먼트로 읽으며 각 세그먼트마다 고유한 인코딩 모드를 사용하도록 생성기를 동작시킵니다.

5. 한 QR 코드의 서로 다른 부분에 대해 다른 인코딩 모드를 설정할 수 있나요? 예. QrExtCodetextBuilder에 여러 세그먼트를 추가하고 각각 다른 QrExtCompactionMode를 사용하면, 빌더가 모든 세그먼트를 포함하는 단일 확장 코드 텍스트를 생성합니다.

6. 혼합 인코딩 모드로 생성된 QR 코드가 표준 리더와 호환됩니까?
   예. 다중 세그먼트 인코딩은 QR 사양의 일부이므로, 모든 호환 스캐너가 페이로드를 올바르게 디코딩하고 연결된 데이터를 반환합니다.

7. 인코딩 모드를 수동으로 설정하면 항상 더 작은 QR 코드를 생성합니까? 아니요. 각 세그먼트 경계는 모드 표시기와 문자 수 필드를 필요로 하므로 데이터를 많은 짧은 세그먼트로 나누면 심볼이 더 커질 수 있습니다. 수동 모드 선택은 숫자 또는 한자 데이터의 길고 균일한 구간에서 효과적입니다.

8. QR 인코딩 모드를 QrExtCodetextBuilder로 설정하려면 라이선스가 필요합니까? 라이선스 없이 API를 평가할 수 있지만 평가 제한이 적용됩니다. Aspose 웹사이트에서 제공하는 무료 임시 라이선스를 사용하면 테스트 중에 이러한 제한이 해제되며, 실제 운영에서는 정식 라이선스가 필요합니다.

9. Aspose.BarCode for python-net의 어떤 버전이 이러한 API를 지원합니까? QrExtCodetextBuilder, QrExtCompactionMode, 및 QREncodeMode.EXTENDED는 Aspose.BarCode for Python via .NET 26.6 및 이후 버전에서 사용할 수 있습니다.

더 읽기

• Python에서 MaxiCode 바코드 생성
• Python에서 Code 93 바코드 생성기 구축
• Python에서 로고가 포함된 바코드 및 QR 코드 생성