Налаштування режимів кодування QR‑коду в Python

Кожен генератор QR за замовчуванням вибирає режим кодування, і в більшості випадків це налаштування підходить. Воно перестає підходити в той момент, коли вам потрібен контроль — числовий ідентифікатор поруч із кодом продукту, блок японського тексту, який ви не хочете зберігати у UTF-8, або корисне навантаження, де потрібні однакові байти щоразу при генерації. У цьому посібнику показано, як встановити режими кодування QR‑коду в Python явно, використовуючи Aspose.BarCode for Python via .NET, щоб один QR‑символ міг містити числовий сегмент, алфавітно‑цифровий сегмент, байтовий сегмент і сегмент Kanji — кожен збережений у режимі, який найкраще підходить.

Aspose.BarCode називає їх режими стиснення у своїх API назвах (QrExtCompactionMode) і специфікація QR називає їх режимами кодування. Це ті ж чотири режими під різними назвами, і в цьому посібнику використовується термін “режим кодування” протягом усього тексту, оскільки саме так називає їх специфікація та більшість бібліотек QR для Python.

Чому режими кодування QR впливають на розмір символу та надійність сканування

Фізичний розмір QR‑коду визначається кількістю біт, необхідних для його корисного навантаження, а кількість біт на символ повністю залежить від режиму кодування, використаного для цього сегмента. Специфікація визначає чотири режими даних з помітно різною щільністю:

30-цифровий ідентифікатор вимагає приблизно 100 біт у числовому режимі та 240 біт у байтовому режимі. Така різниця часто достатня, щоб підняти символ на кілька версій QR, а вища версія означає більше модулів у тому ж друкованому полі — менші модулі та нижчий рівень зчитування на камерах низької роздільної здатності, вигнутих упаковках та зношених етикетках.

Автоматичний вибір режиму добре справляється з більшістю корисних навантажень. Він стає обмежуючим, коли ви знаєте структуру своїх даних, а аналізатор — ні: довгий числовий рядок, розірваний однією літерою, японський текст, для якого байтовий режим витрачатиме три байти UTF-8 на символ, або ідентифікатор фіксованого формату, де потрібен детермінований вихід між версіями бібліотеки.

Коли встановлення режиму вручну варте того

Перемикання режиму не безкоштовне. Кожна межа сегмента записує чотирибітовий індикатор режиму плюс поле кількості символів від восьми до шістнадцяти бітів залежно від версії QR. Занадто багато сегментування корисного навантаження може створити більший символ, ніж коли генератор сам вирішує.

Встановлення режиму явно окупається, коли:

• Корисне навантаження містить довгі, однорідні послідовності — 40-цифровий серійний номер, абзац канжі.
• Ви кодуєте японський текст і хочете режим канжі з 13 бітами на символ замість байтового режиму з 24 бітами.
• Вам потрібен відтворюваний, байтово‑ідентичний результат для регресійних тестів або перевірки контрольної суми.

Зазвичай не варто додавати складність для коротких корисних навантажень, даних, які змінюють тип кожні кілька символів, або URL‑адрес, які автоматичний аналіз вже добре обробляє. Підрозділ вимірювання нижче показує, як перевірити, у якому випадку ви знаходитесь.

Два способи встановлення режимів кодування QR у Python

Aspose.BarCode пропонує два шляхи до одного й того ж закодованого результату, і варто знати, чому обидва існують, перш ніж писати код.

Будівник є кращим за замовчуванням. QrExtCompactionMode.NUMERIC або існує, або одразу піднімає AttributeError, у той час як помилково введений \numm у рядку безшумно перетворюється на дані корисного навантаження і з’являється лише коли хтось сканує мітку. Обидва підходи використовують однакове налаштування генератора QREncodeMode.EXTENDED, тому ви можете перемикатися між ними, не змінюючи нічого нижче.

Встановлення режимів кодування QR‑коду у Python: крок за кроком

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

Потім перевірте, чи імпорт успішно розв’язується. Пакет прив’язується до середовища виконання .NET, тому успішний імпорт повідомляє більше, ніж просто наявність файлів на диску:

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. Додайте сегмент Kanji за допомогою 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 встановлює режим кодування для одного сегмента. Порядок має значення — декодер повертає сегменти, об’єднані у послідовності, в якій ви їх додали.
• Набір alphanumeric навмисно обмежений: цифри, великі літери A‑Z, пробіл та $%*+-./:. Ось чому ASPOSE2026 підходить для alphanumeric режиму, а aspose2026 — ні. Маленькі літери не входять до набору, тому цей сегмент повинен використовувати BYTES. Передача нижнього регістру в ALPHA_NUMERIC — найпоширеніша помилка при встановленні режимів таким чином.
• Сегмент Kanji використовує \u3062 і далі, що є хіраганою, а не справжніми кандзі. Режим Kanji охоплює діапазон двобайтових символів Shift‑JIS, який включає кана, тому ці символи кодуються 13 бітами кожен, замість 24 бітів, які зайняв би режим байтів у UTF‑8.
• get_extended_codetext() генерує рядок, який генератор аналізує у режимі EXTENDED. Виведення його за допомогою repr() варто виконати один раз — це показує синтаксис селектора, який генерує builder, і саме те, що наступний підрозділ пише вручну.

3. Встановити режим кодування inline, без Builder

Коли кодовий текст походить ззовні вашого коду 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 вище використовує звичайний рядок з \\kanji. Ця пастка з екрануванням є практичним аргументом на користь використання будівельника у розділі 2.

4. Створити QR‑штрих-код у режимі EXTENDED

Встановлення режимів per‑segment не має жодного ефекту, доки генератор не отримає інструкцію їх читати. Без 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 — це рядок, який активує розбір сегментів. Якщо його пропустити, генератор створює дійсний, сканований QR‑код, що містить буквальний текст \num1234567... — саме тому наступний підрозділ перевіряє, а не припускає.
• gen.parameters.resolution = 300 відтворює з роздільною здатністю для друку. Символи, призначені для етикеткових принтерів або пакувального оформлення, слід генерувати у кінцевому розмірі, а не масштабувати пізніше, оскільки це пом’якшує краї модулів.
• save записує без втрат PNG. Уникайте JPEG для будь‑якої 2D‑символіки — артефакти стиснення розмивають сітку модулів, яку сканує декодер.

5. Перевірте, чи застосовано режим кодування

Успішне генерування нічого не доводить щодо того, чи спрацювали режими per‑segment. Крок декодування — це те, що розрізняє правильно закодований символ від того, який несе маркери селектора як дані.

1. Ініціалізуйте BarCodeReader з шляхом до файлу та DecodeType.QR.
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(...) робить випадок помилки явним. При невдачі розпізнавання повертається порожній ітерабельний об’єкт замість виключення, тому незахищений цикл 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
• Безкоштовні онлайн додатки для штрих‑коду

Висновок

Налаштування режимів кодування QR‑коду в Python зводиться до двох питань: який сегмент отримує який режим і як повідомити генератору дотримуватися цього вибору. QrExtCodetextBuilder і QrExtCompactionMode відповідають на перше питання в коді застосунку; QREncodeMode.EXTENDED відповідає на друге на рівні генератора. У цьому посібнику розглянуто як API будівельника, так і синтаксис інлайн‑вибору, який він генерує, створюючи QR‑символ з чотирма сегментами, перевіряючи декодований вміст і вимірюючи різницю у розмірі порівняно з автоматичним режимом.

Віддавайте перевагу builder’у для коду застосунку — він ловить помилки режиму на місці виклику, а не в сканері. І залишайте крок вимірювання. Встановлення режиму вручну дає реальну вигоду для довгих однорідних навантажень і призводить до чистого збитку для коротких змішаних, де накладні витрати на перемикання режиму перевищують економію. Генеруйте обидва, порівнюйте кількість модулів і нехай результат вирішує, який код підтримувати.

FAQs

1. Що таке режим кодування QR‑коду і навіщо його використовувати? Режим кодування вказує генератору QR, як обробляти сегмент даних — числовий, алфавітно‑цифровий, байтовий або Канжі. Кожен режим має різну щільність даних, тому вибір правильного режиму для кожного сегмента дозволяє зберегти версію QR і, відповідно, символ якомога меншим. Aspose.BarCode називає їх режимами стискання; специфікація QR називає їх режимами кодування.

2. Які режими кодування підтримує QrExtCompactionMode?
   QrExtCompactionMode забезпечує NUMERIC, ALPHA_NUMERIC, BYTES та KANJI, що відповідає чотирьом режимам даних QR, визначеним у ISO/IEC 18004.

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 та пізніше.

Читати далі

• Створення штрих‑коду MaxiCode у Python
• Створення генератора штрих‑коду Code 93 у Python
• Створення штрих‑коду та QR‑коду з логотипом у Python