PythonでQRコードのエンコーディングモードを設定する

すべてのQRジェネレータはデフォルトでエンコーディングモードを自動的に選択しますが、ほとんどの場合そのデフォルトで問題ありません。制御が必要になる瞬間—たとえば製品コードの横にある数値ID、UTF-8として保存したくない日本語テキストのブロック、または生成するたびに同じバイト列が必要なペイロード—では問題が生じます。このガイドでは、Aspose.BarCode for Python via .NET を使用して、PythonでQRコードエンコーディングモードを設定する方法を明示的に示します。これにより、単一のQRシンボルが数値セグメント、英数字セグメント、バイトセグメント、漢字セグメントをそれぞれ最適なモードで保持できます。

Aspose.BarCode はこれらを独自の API 名 (QrExtCompactionMode) で コンパクションモード と呼び、QR 仕様自体では エンコーディングモード と呼びます。2 つの名前で同じ 4 つのモードであり、このガイドでは仕様およびほとんどの Python QR ライブラリで使用されている用語である「エンコーディングモード」を通して使用します。

QR エンコーディングモードがシンボルサイズとスキャン信頼性に影響する理由

QRコードの物理的なサイズは、ペイロードが必要とするビット数によって決まります。また、文字あたりのビット数は、そのセグメントで使用されるエンコーディングモードに完全に依存します。仕様では、密度が大きく異なる4つのデータモードが定義されています：

30桁の識別子は、数値モードで約100ビット、バイトモードで約240ビットかかります。その差は、シンボルを数バージョン上げるのに十分なことが多く、バージョンが上がると同じ印刷領域内にモジュールが増えます――モジュールが小さくなり、低解像度カメラや曲面包装、摩耗したラベルでの読み取り率が低下します。

自動モード選択はほとんどのペイロードをうまく処理します。データの形状が分かっていて、アナライザーがそれを認識しない場合には制限が生じます。たとえば、1 文字の文字で区切られた長い数値列や、バイトモードでは文字ごとに 3 バイトの UTF-8 を使用する日本語テキスト、またはライブラリのバージョン間で決定的な出力が必要な固定フォーマットの識別子などです。

手動でモードを設定する価値があるとき

モード切り替えは無料ではありません。各セグメント境界では、QR バージョンに応じて 4 ビットのモードインジケータと、8 から 16 ビットの文字数フィールドが書き込まれます。ペイロードを過度にセグメント化すると、ジェネレータに任せるよりも 大きい シンボルが生成される可能性があります。

モードを明示的に設定することで効果があるのは次の場合です：

• ペイロードには長く均一なランが含まれます — 40桁のシリアル、漢字の段落。
• 日本語テキストをエンコードしており、バイトモード（24ビット）ではなく、1文字あたり13ビットの漢字モードを使用したいです。
• 回帰テストやチェックサム検証のために、再現性がありバイト単位で同一の出力が必要です。

短いペイロードや、数文字ごとにタイプが変わるデータ、または自動解析がすでにうまく処理している URL などに対して、追加の複雑さを加える価値は通常ありません。以下の測定サブセクションでは、どのケースに該当するかを確認する方法を示しています。

PythonでQRエンコーディングモードを設定する2つの方法

Aspose.BarCode は同じエンコード結果に至る2つのルートを提供しており、コードを書く前に両方が存在する理由を知っておく価値があります。

ビルダーはより優れたデフォルトです。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

次に、インポートが解決するか確認してください。パッケージは .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. 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))

説明

• Each add_codetext_with_compaction_mode の各呼び出しは、1 つのセグメントのエンコーディングモードを設定します。順序が重要です — デコーダは、追加した順序でセグメントを連結して返します。
• 英数字セットは意図的に狭く定義されています：数字、英大文字 A‑Z、スペース、そして $%*+-./:。そのため ASPOSE2026 は英数字モードに適合しますが、aspose2026 は適合しません。小文字はセットに含まれないため、そのセグメントは BYTES を使用しなければなりません。小文字を ALPHA_NUMERIC に渡すことは、このようにモードを設定する際に最も一般的なミスです。
• Kanji セグメントは \u3062 以降を使用していますが、これは正しい漢字ではなくひらがなです。Kanji モードは Shift-JIS の2バイト範囲をカバーしており、かなも含まれるため、これらは各 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. EXTENDED モードで 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(...) は失敗ケースを明示的にします。認識失敗は例外を投げるのではなく空のイテラブルを返すため、失敗した読み取りに対してガードなしの 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 コードのエンコーディングモードを設定する際は、2 つの質問に要約されます：どのセグメントがどのモードになるか、そしてジェネレータにその選択を尊重させる方法です。QrExtCodetextBuilder と QrExtCompactionMode はアプリケーションコードで最初の質問に答えます；QREncodeMode.EXTENDED はジェネレータ側で二番目の質問に答えます。このガイドでは、ビルダー API とそれが生成するインラインセレクタ構文の両方を取り上げ、4 セグメントの QR シンボルを生成し、デコードされたペイロードを検証し、そして自動モードと比較したサイズ差を測定しました。

ビルダーをアプリケーションコードで使用することを推奨します — これにより、スキャナーではなく呼び出し側でモードエラーを検出できます。また、測定ステップは維持してください。モードを手動で設定することは、長い均質なペイロードでは実際に有利であり、短い混在ペイロードではモード切り替えのオーバーヘッドが節約分を上回るため、純粋に不利です。両方を生成し、モジュール数を比較して、結果に基づいてどちらのコードを維持するか決定してください。

FAQ

1. QRコードのエンコーディングモードとは何か、なぜ使用するのか？ エンコーディングモードは、QRジェネレータにデータのセグメント（数値、英数字、バイト、または漢字）をどのように扱うかを指示します。各モードはデータ密度が異なるため、セグメントごとに適切なモードを選択することで、QRバージョン（したがってシンボル）をできるだけ小さく保つことができます。Aspose.BarCodeではこれらをコンパクションモードと呼び、QR仕様ではエンコーディングモードと呼びます。

2. QrExtCompactionMode がサポートするエンコーディングモードはどれですか？ QrExtCompactionMode は NUMERIC、ALPHA_NUMERIC、BYTES、および KANJI を提供し、ISO/IEC 18004 で定義された 4 つの QR データモードと一致します。

3. QrExtCodetextBuilder を使用すべきか、インライン EXTENDED セレクタを使用してモードを設定すべきか？ アプリケーションコードではビルダーを使用してください。型チェックが行われ、バックスラッシュエスケープのミスを防ぎ、拡張コードテキストを自動的に組み立ててくれます。インラインセレクタは、コードテキストが設定、データベース、またはビルダーを呼び出せない別のシステムから取得される場合に便利です。

4. EXTENDEDエンコードモードは、標準のQRエンコードモードとどのように異なりますか？ EXTENDEDモードでは、ジェネレーターがコードテキストを事前定義されたセグメントの系列として読み取り、各セグメントが独自のエンコーディングモードを持つようにします。文字列全体に対して自動モード検出を実行する代わりです。

5. 1つのQRコードの異なる部分に対して異なるエンコーディングモードを設定できますか？
   はい。QrExtCodetextBuilder に複数のセグメントを追加し、それぞれに異なる QrExtCompactionMode を指定すると、ビルダーはそれらすべてをカバーする単一の拡張コードテキストを生成します。

6. 混合エンコーディングモードで生成されたQRコードは標準のリーダーと互換性がありますか？
   はい。マルチセグメントエンコーディングはQR仕様の一部であるため、準拠したスキャナーはペイロードを正しくデコードし、結合されたデータを返します。

7. エンコーディングモードを手動で設定すると、常に小さな QR コードが生成されますか？ いいえ。各セグメント境界にはモードインジケータと文字数フィールドが必要になるため、データを多数の短いセグメントに分割するとシンボルが大きくなることがあります。手動でモードを選択するのは、数値データや漢字データの長く均一な連続がある場合に効果的です。

8. QrExtCodetextBuilder を使用して QR エンコーディングモードを設定するにはライセンスが必要ですか？ ライセンスなしで API を評価できますが、評価制限が適用されます。Aspose のウェブサイトから取得できる無料の一時ライセンスにより、テスト中の制限が解除され、実運用にはフルライセンスが必要です。

9. これらの API をサポートしている Aspose.BarCode for python-net のバージョンは何ですか？ QrExtCodetextBuilder、QrExtCompactionMode、および QREncodeMode.EXTENDED は Aspose.BarCode for Python via .NET 26.6 以降で利用可能です。

続きを読む

• PythonでMaxiCodeバーコードを生成する
• PythonでCode 93バーコードジェネレータを構築する
• Pythonでロゴ付きバーコードとQRコードを生成する