reedsolo 1.7.0

使用高级RSCodec类的基本用法

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

# Encoding
# just a list of numbers/symbols:
>>> rsc.encode([1,2,3,4])
b'\x01\x02\x03\x04,\x9d\x1c+=\xf8h\xfa\x98M'
# bytearrays are accepted and the output will be matched:
>>> rsc.encode(bytearray([1,2,3,4]))
bytearray(b'\x01\x02\x03\x04,\x9d\x1c+=\xf8h\xfa\x98M')
# encoding a byte string is as easy:
>>> rsc.encode(b'hello world')
b'hello world\xed%T\xc4\xfd\xfd\x89\xf3\xa8\xaa'
# Note: strings of any length, even if longer than the Galois field, will be encoded as well using transparent chunking.

# Decoding (repairing)
>>> rsc.decode(b'hello world\xed%T\xc4\xfd\xfd\x89\xf3\xa8\xaa')[0]  # original
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()方法计算的单个界限，编解码器将尝试引发ReedSolomonError异常，但可能根本不会检测到任何错误（这是纠错码的理论限制）。换句话说，纠错码在检测单个界限以上的消息块是否损坏时不可靠。如果您希望有更高的可靠性在错误检测中，请使用SHA或MD5等校验和或哈希对您的消息进行校验，这些校验和或哈希可靠性更高，并且没有擦除数量的限制（唯一潜在的问题是碰撞，但概率非常低）。

注意：要捕获ReedSolomonError异常，请勿忘记首先导入它：from reedsolo import ReedSolomonError

要检查给定其纠错符号的消息是否被篡改，而不进行解码，请使用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]

默认情况下，大多数里德-所罗门编解码器限制为可以编码在256位内的字符，长度最大为256个字符。但这个编解码器是通用的，您可以通过增加伽罗瓦域来增加或减少长度和最大字符值。

# 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 类支持透明分块，因此您不需要增加伽罗瓦域来支持更长的消息，但字符仍然限制在 256 位（或您使用 c_exp 设置的任何域）。

通过直接访问数学函数的底层用法

如果您想要完全控制，可以跳过 API，直接使用库。下面是方法：

首先您需要初始化预计算表。

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

小贴士：如果您收到错误：ValueError: byte 必须在范围(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 编解码器接口。