reedsolo 1.5.4

高级 RSCodec 类的基本用法

# Initialization
>>> from reedsolo import RSCodec
>>> rsc = RSCodec(10)  # 10 ecc symbols

# Encoding
>>> rsc.encode([1,2,3,4])
b'\x01\x02\x03\x04,\x9d\x1c+=\xf8h\xfa\x98M'
>>> rsc.encode(bytearray([1,2,3,4]))
bytearray(b'\x01\x02\x03\x04,\x9d\x1c+=\xf8h\xfa\x98M')
>>> rsc.encode(b'hello world')
b'hello world\xed%T\xc4\xfd\xfd\x89\xf3\xa8\xaa'
# Note that chunking is supported transparently to encode any string length.

# Decoding (repairing)
>>> rsc.decode(b'hello world\xed%T\xc4\xfd\xfd\x89\xf3\xa8\xaa')[0]
b'hello world'
>>> rsc.decode(b'heXlo worXd\xed%T\xc4\xfdX\x89\xf3\xa8\xaa')[0]     # 3 errors
b'hello world'
>>> rsc.decode(b'hXXXo worXd\xed%T\xc4\xfdX\x89\xf3\xa8\xaa')[0]     # 5 errors
b'hello world'
>>> rsc.decode(b'hXXXo worXd\xed%T\xc4\xfdXX\xf3\xa8\xaa')[0]        # 6 errors - fail
Traceback (most recent call last):
  ...
reedsolo.ReedSolomonError: Too many (or few) errors found by Chien Search for the errata locator polynomial!

1.0 之前用户的重要升级通知：请注意RSCodec.decode()返回 3 个变量：

1. 解码（更正）的消息

2. 解码的消息和纠错码（本身也被纠正）

3. 以及勘误表的位置列表（错误和擦除）

这是一个例子：

>>> tampered_msg = b'heXlo worXd\xed%T\xc4\xfdX\x89\xf3\xa8\xaa'
>>> decoded_msg, decoded_msgecc, errata_pos = rsc.decode(tampered_msg)
>>> print(decoded_msg)  # decoded/corrected message
bytearray(b'hello world')
>>> print(decoded_msgecc)  # decoded/corrected message and ecc symbols
bytearray(b'hello world\xed%T\xc4\xfd\xfd\x89\xf3\xa8\xaa')
>>> print(errata_pos)  # errata_pos is returned as a bytearray, hardly intelligible
bytearray(b'\x10\t\x02')
>>> print(list(errata_pos))  # convert to a list to get the errata positions as integer indices
[16, 9, 2]

由于我们使用设置为 10 个纠错码 (ecc) 符号的编解码器未能解码 6 个错误，因此让我们尝试使用更大的编解码器，具有 12 个 ecc 符号。

>>> rsc = RSCodec(12)  # using 2 more ecc symbols (to correct max 6 errors or 12 erasures)
>>> rsc.encode(b'hello world')
b'hello world?Ay\xb2\xbc\xdc\x01q\xb9\xe3\xe2='
>>> rsc.decode(b'hello worXXXXy\xb2XX\x01q\xb9\xe3\xe2=')[0]         # 6 errors - ok, but any more would fail
b'hello world'
>>> rsc.decode(b'helXXXXXXXXXXy\xb2XX\x01q\xb9\xe3\xe2=', erase_pos=[3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 15, 16])[0]  # 12 erasures - OK
b'hello world'

这表明我们可以解码两倍于错误（位置未知）的擦除（我们自己提供错误的位置）。这是纠错与擦除校正相比的成本。

要获得可以独立纠正（即不同时）的最大错误或擦除数：

>>> maxerrors, maxerasures = rsc.maxerrata(verbose=True)
This codec can correct up to 6 errors and 12 erasures independently
>>> print(maxerrors, maxerasures)
6 12

要获得可以同时纠正的最大错误和擦除数，您需要指定您期望的错误或擦除数：

>>> maxerrors, maxerasures = rsc.maxerrata(erasures=6, verbose=True)  # we know the number of erasures, will calculate how many errors we can afford
This codec can correct up to 3 errors and 6 erasures simultaneously
>>> print(maxerrors, maxerasures)
3 6
>>> maxerrors, maxerasures = rsc.maxerrata(errors=5, verbose=True)  # we know the number of errors, will calculate how many erasures we can afford
This codec can correct up to 5 errors and 2 erasures simultaneously
>>> print(maxerrors, maxerasures)
5 2

请注意，如果一个块具有比maxerrata()方法计算的 Singleton Bound 更多的错误和擦除，编解码器将尝试引发ReedSolomonError异常，但很可能也不会检测到任何错误（这是错误的理论限制校正码）。换句话说，纠错码不能可靠地检测到消息的块是否在单例界限之外被破坏。如果您想在勘误检测中获得更高的可靠性，请在您的消息上使用校验和或哈希，例如 SHA 或 MD5，这些更可靠并且对勘误的数量没有限制（唯一的潜在问题是冲突，但概率非常非常低）。

要检查消息是否在给定纠错符号的情况下被篡改，无需解码，请使用check()方法：

# Checking
>> rsc.check(b'hello worXXXXy\xb2XX\x01q\xb9\xe3\xe2=')  # Tampered message will return False
[False]
>> rmes, rmesecc, errata_pos = rsc.decode(b'hello worXXXXy\xb2XX\x01q\xb9\xe3\xe2=')
>> rsc.check(rmesecc)  # Corrected or untampered message will return True
[True]
>> print('Number of detected errors and erasures: %i, their positions: %s' % (len(errata_pos), list(errata_pos)))
Number of detected errors and erasures: 6, their positions: [16, 15, 12, 11, 10, 9]

默认情况下，大多数 Reed-Solomon 编解码器仅限于可以编码为 256 位且最大长度为 256 个字符的字符。但是这个编解码器是通用的，你可以通过增加 Galois Field 来减少或增加长度和最大字符值：

# To use longer chunks or bigger values than 255 (may be very slow)
>> rsc = RSCodec(12, nsize=4095)  # always use a power of 2 minus 1
>> rsc = RSCodec(12, c_exp=12)  # alternative way to set nsize=4095
>> mes = 'a' * (4095-12)
>> mesecc = rsc.encode(mes)
>> mesecc[2] = 1
>> mesecc[-1] = 1
>> rmes, rmesecc, errata_pos = rsc.decode(mesecc)
>> rsc.check(mesecc)
[False]
>> rsc.check(rmesecc)
[True]

请注意，RSCodec类支持透明分块，因此您无需增加 Galois 字段以支持更长的消息，但字符仍将限制为 256 位（或您使用c_exp设置的任何字段）。

通过直接访问数学函数的低级使用

如果你想要完全控制，你可以跳过 API 直接使用库。就是这样：

首先，您需要初始化预先计算的表：

>> import reedsolo as rs
>> rs.init_tables(0x11d)

专业提示：如果您收到错误：ValueError: byte must be in range(0, 256)，请检查您的素数多项式是否适合您的领域。专业提示2：默认情况下，您只能编码最大长度和最大符号值 = 256 的消息。如果要编码更大的消息，请使用以下内容（其中 c_exp 是您的伽罗瓦域的指数，例如，12 = 最大长度2^12 = 4096):

>> prim = rs.find_prime_polys(c_exp=12, fast_primes=True, single=True)
>> rs.init_tables(c_exp=12, prim=prim)

让我们定义我们的 RS 消息和 ecc 大小：

>> n = 255  # length of total message+ecc
>> nsym = 12  # length of ecc
>> mes = "a" * (n-nsym)  # generate a sample message

为了优化，您可以预先计算生成多项式：

>> gen = rs.rs_generator_poly_all(n)

然后编码：

>> mesecc = rs.rs_encode_msg(mes, nsym, gen=gen[nsym])

让我们篡改我们的消息：

>> mesecc[1] = 0

解码：

>> rmes, recc, errata_pos = rs.rs_correct_msg(mesecc, nsym, erase_pos=erase_pos)

请注意，消息和 ecc 都已更正（当然，如果可能的话）。专业提示：如果您知道一些擦除位置，可以在列表中指定它们erase_pos以使修复能力加倍。但您也可以只指定一个空列表。

您可以检查纠正了多少错误和/或擦除，这对于设计自适应比特率算法很有用：

>> print('A total of %i errata were corrected over all chunks of this message.' % len(errata_pos))

如果解码失败，它通常会自动检查并引发您可以处理的 ReedSolomonError 异常。但是，如果您想手动检查修复的消息是否正确，您可以这样做：

>> rs.rs_check(rmes + recc, nsym)

注意：如果你想使用多个不同参数的reedsolomon，你需要在调用reedsolo函数之前备份全局并恢复它们：

>> rs.init_tables()
>> global gf_log, gf_exp, field_charac
>> bak_gf_log, bak_gf_exp, bak_field_charac = gf_log, gf_exp, field_charac

然后，您可以随时执行以下操作：

>> global gf_log, gf_exp, field_charac
>> gf_log, gf_exp, field_charac = bak_gf_log, bak_gf_exp, bak_field_charac
>> mesecc = rs.rs_encode_msg(mes, nsym)
>> rmes, recc, errata_pos = rs.rs_correct_msg(mesecc, nsym)

如果您使用 RSCodec，则不需要全局备份，它将被自动管理。

阅读源代码的注释以获取有关其工作原理的更多信息，以及如果您需要与其他 RS 编解码器交互可以设置的各种参数。