本文详解如何安全地将 numpy 二进制矩阵序列化为单字节字符串并准确还原，重点解决 utf-8 编码导致的多字节污染问题，提供 numba 友好、零依赖的纯位操作实现方案。
本文详解如何安全地将 numpy 二进制矩阵序列化为单字节字符串并准确还原，重点解决 utf-8 编码导致的多字节污染问题，提供 numba 友好、零依赖的纯位操作实现方案。
在科学计算与嵌入式场景中，常需将二进制矩阵（如邻接矩阵、掩码图）高效压缩为紧凑字节流，并保证可逆还原。您当前的 matrix_to_ascii 和 ascii_to_matrix 逻辑本身位操作正确，但核心缺陷在于字符串编码语义不匹配：matrix_to_ascii() 生成的是含控制字符（如 \x00）和非 ASCII 字符（如 ÷, ß）的“伪文本”，而 Python 默认 .encode() 使用 UTF-8 —— 它会将 ÷（U+00F7）编码为 b'\xc3\xb7'（2 字节），ß（U+00DF）编码为 b'\xc3\x9f'（2 字节），彻底破坏原始 1 字节/字符的映射关系，导致后续解码时字节长度膨胀、位序错乱。
✅ 正确做法是强制使用 单字节编码（如 'iso-8859-1' 或 'latin-1'），它确保每个 Unicode 码点 0–255 直接映射为对应字节值（即 chr(247).encode('latin-1') == b'\xf7'），完全保持 matrix_to_ascii 的输出字节一一对应。
以下是修复后的完整、Numba 兼容实现：
import numpy as np
def flatten_and_pad_to_multiple_of_8(binary_matrix):
rows, cols = binary_matrix.shape
current_length = rows * cols
padded_length = ((current_length + 7) // 8) * 8
flat_bits = np.zeros(padded_length, dtype=np.uint8)
idx = 0
for i in range(rows):
for j in range(cols):
flat_bits[idx] = binary_matrix[i, j]
idx += 1
return flat_bits
def matrix_to_bytes(matrix):
"""Convert binary matrix to bytes object (Numba-safe)"""
flat_bits = flatten_and_pad_to_multiple_of_8(matrix)
byte_list = []
for i in range(0, len(flat_bits), 8):
byte = 0
for j in range(8):
byte = (byte << 1) | flat_bits[i + j]
byte_list.append(byte)
return bytes(byte_list) # 返回 bytes，非 str
def bytes_to_matrix(byte_data, original_shape):
"""Convert bytes back to binary matrix (Numba-safe)"""
rows, cols = original_shape
total_bits = rows * cols
binary_matrix = np.zeros((rows, cols), dtype=np.uint8)
bit_idx = 0
for byte_val in byte_data:
if bit_idx >= total_bits:
break
# 从最高位（MSB）开始提取：bit 7 → bit 0
for shift in range(7, -1, -1):
if bit_idx < total_bits:
bit = (byte_val >> shift) & 1
binary_matrix[bit_idx // cols, bit_idx % cols] = bit
bit_idx += 1
else:
break
return binary_matrix
# ✅ 使用示例（无需 encode/decode 字符串）
matrix = np.array([
[0, 1, 1, 1, 1],
[1, 0, 1, 1, 1],
[1, 1, 0, 1, 1],
[1, 1, 1, 0, 1],
[1, 1, 1, 1, 0]
], dtype=np.uint8)
# 序列化：直接得到 bytes
encoded = matrix_to_bytes(matrix)
print("Encoded bytes:", encoded) # e.g., b'}\xf7\xdf\x00'
# 反序列化：输入 bytes，输出矩阵
restored = bytes_to_matrix(encoded, matrix.shape)
print("Restored equal?", np.array_equal(matrix, restored)) # True
# ⚠️ 注意事项：
# 1. 绝对避免中间经过 str → encode() 链路（尤其不用默认 UTF-8）；
# 2. `matrix_to_bytes` 返回 `bytes`，而非 `str`，消除编码歧义；
# 3. `bytes_to_matrix` 直接接收 `bytes` 对象，内部遍历 `bytearray` 或 `bytes` 的整数值，完全兼容 Numba；
# 4. 填充逻辑已保证总位数为 8 的倍数，解码时无需额外处理末尾冗余位；
# 5. 若需进一步压缩（如 LZ4），直接对 `bytes` 对象操作，安全高效。该方案彻底规避了字符串编码陷阱，所有操作均基于 uint8 数值与 bytes 原生类型，100% 兼容 Numba 的 @njit 编译（只要禁用 Python I/O 和动态类型）。记住关键原则：二进制数据 ≠ 文本数据，应始终以 bytes 为载体流转，而非借道 str。
