Error correction level is much lower than it should, so much encoding can fail

[fgrieu]

Summary: two independent issues combine to reduce the error-correction level used much below standard. With low ec_percent, encoding can fail.

ISO 24778, which defines Aztec code, has:

11.2 User selection of minimum error correction level

The design of Aztec Code technically allows a symbol to include as little as none or as much as 99 % in error correction codewords, though both limits are unsound. The recommended level of error correction for normal use is 23 % of symbol capacity plus 3 codewords more. Thus a 5-layer symbol which holds 120 codewords should normally include at least 28 + 3 checkwords, leaving up to 89 codewords for encoding the data message. Print programs should enforce this level as the default.

Users, judging their applications to be especially benign or critical, may choose to specify an alternate minimum error correction percentage, ranging from below 10 % to above 50 % plus always, for data security, 3 additional checkwords. This is called a “minimum” percentage because, depending on message length, the symbology will typically have to add extra checkwords above this minimum to fill out the symbol.

Main problem is, the formula used in find_suitable_matrix_size makes the addition 3 bits, not 3 codewords/checkwords:

# calculate minimum required number of bits
required_bits_count = int(math.ceil((len(out_bits) + 3) * 100.0 / (100 - ec_percent)))

This results in considerably less error correction words than the standard recommends.

An independent issue going in the same direction is that the bit(s) added for bit stuffing in get_data_codewords are not accounted for. There are typically many when the data contains long sequences of 0x00 or long sequences 0xFF (though some do creep in in other situations, e.g. when encoding O O O O... ).

With the two issues combined, and with the parameter ec_percent low, the number of error correction words can become negative, making encoding impossible. That happens e.g. when encoding 212 bytes 0xFF with ec_percent=10 (twice the minimum recommended). out_bits is 212x8+21 = 1717, required_bits_count is 1912, which find_suitable_matrix_size determines fits the 1920 bits limit for 8 layers (49 x 49). However there are about 212x8/7 > 240 stuffing bits added, and 1717 + 240 = 1957 > 1920, thus encoding is impossible.

This report is for https://github.com/dlenski/aztec_code_generator/blob/master/aztec_code_generator.py of 2024-12-17