michaelschiemer/tests/debug/FORMAT-INFO-FIX-SUMMARY.md

Format Information Placement Fix - Complete Analysis

Problem Discovery

QR codes were technically correct (data placement, Reed-Solomon, all function patterns) but completely unrecognizable by scanner apps.

Critical Test Result

• Python Reference QR Code: ✅ WORKS (user confirmed: "der python code funktioniert")
• Our Implementation: ❌ FAILED (user confirmed: "der andere nicht")

Root Cause

Format Information horizontal placement was INCORRECT.

What Was Wrong

Before Fix:

• Applied bit swap pattern [0,1,2,3,4,5,6,7,8,10,9,11,13,12,14] when WRITING
• This created DOUBLE swapping (once in bit order, once in column order)
• Result: Horizontal ≠ Vertical format info

// ❌ WRONG - Double swapping
$bitIndices = [0, 1, 2, 3, 4, 5, 6, 7, 8, 10, 9, 11, 13, 12, 14];
for ($i = 0; $i < 15; $i++) {
    $bitIndex = $bitIndices[$i];  // First swap
    $bit = ($formatBits >> (14 - $bitIndex)) & 1;
    $matrix = $matrix->setModuleAt(8, $columns[$i], $module);  // Second swap in column order
}

The Fix

After Fix:

• Write bits SEQUENTIALLY (0-14)
• Let the COLUMN ORDER create the natural swap
• Result: Horizontal = Vertical format info ✅

// ✅ CORRECT - Sequential placement
for ($i = 0; $i < 15; $i++) {
    $bit = ($formatBits >> (14 - $i)) & 1;  // Sequential bits
    $module = $bit === 1 ? Module::dark() : Module::light();
    $matrix = $matrix->setModuleAt(8, $columns[$i], $module);  // Column order creates natural swap
}

Technical Details

Format Information Structure

• 15 bits total
• Bits 0-4: EC level + Mask pattern (5 data bits)
• Bits 5-14: BCH(15,5) error correction (10 parity bits)
• XOR mask: 101010000010010

Placement Columns (Horizontal)

[0, 1, 2, 3, 4, 5, 7, 8, 20, 19, 18, 17, 16, 15, 14]
                ^  ^  ↓-  ↓-  ↓-  ↓-  ↓-  ↓-  ↓-
         (skip 6 - timing separator)
                      (right-to-left order creates swap effect)

Verification Results

Before Fix:

Horizontal: 101111001111010
Vertical:   101111001111100
Match: ❌

After Fix:

Horizontal: 101111001111100
Vertical:   101111001111100
Match: ✅ PERFECT!

Why This Matters

Format information tells the scanner:

1. Which error correction level to use
2. Which mask pattern was applied to data

Without correct format info:

• Scanner can't decode the mask pattern
• Data appears corrupted
• QR code is completely unreadable

With correct format info:

• Scanner knows how to unmask data
• Error correction works properly
• QR code scans successfully

Files Changed

/home/michael/dev/michaelschiemer/src/Framework/QrCode/Structure/FormatInformation.php

Method: applyFormatBitsHorizontal() (lines 105-120)

Change:

• Removed $bitIndices array
• Changed from $bitIndices[$i] to sequential $i
• Updated comment to explain column order creates swap

Testing

Test Files Created

1. tests/debug/generate-reference-qr.py - Python reference QR code
2. tests/debug/compare-matrices.php - Bit-by-bit comparison
3. tests/debug/decode-python-format.php - Reverse engineer Python's placement
4. tests/debug/find-horizontal-pattern.php - Discovered bit mapping
5. tests/debug/debug-last-bits.php - Debug specific bit positions
6. tests/debug/analyze-horizontal-issue.php - Identified double-swap problem
7. tests/debug/final-verification.php - Complete verification

Generated QR Codes

1. public/qrcode-python-large.png - Python reference (✅ WORKS)
2. public/qrcode-CORRECTED.png - After initial fix attempt
3. public/qrcode-FINAL.png - After complete fix (✅ SHOULD WORK)

Next Steps

User Testing Required: Test qrcode-FINAL.png with smartphone scanner:

• URL: https://localhost/qrcode-FINAL.png
• Expected result: Decodes to "HELLO WORLD"

If successful, QR code implementation is COMPLETE! ✅

Lessons Learned

1. Don't assume bit placement patterns - verify against working reference
2. Column/Row order matters - can create implicit swapping
3. Test with real scanners - technical correctness ≠ scanner compatibility
4. Python qrcode library is excellent reference - ISO-compliant and battle-tested
5. Format information is critical - without it, nothing else matters