Firestore中高效存储位级别数据：使用位掩码优化紧凑型数据存储

/**
 * 将一系列3位数值打包到一个64位整数中。
 * 每个数值必须在0到7之间。
 * @param {number[]} values - 要打包的3位数值数组。
 * @returns {number} - 包含所有打包值的单个整数。
 * @throws {Error} 如果任何值超出3位范围。
 */
function pack3BitValues(values) {
  let packedValue = 0;
  for (let i = 0; i < values.length; i++) {
    const value = values[i];
    if (value < 0 || value > 7) {
      throw new Error(`Value ${value} at index ${i} is out of 3-bit range (0-7).`);
    }
    // 将当前值左移到其在packedValue中的位置，然后进行位或操作
    // (value & 0b111) 确保只取值的最低3位
    packedValue |= (value & 0b111) << (i * 3);
  }
  return packedValue;
}

/**
 * 从一个打包的整数中解包指定索引处的3位数值。
 * @param {number} packedValue - 包含打包值的整数。
 * @param {number} index - 要解包的值的索引（从0开始）。
 * @returns {number} - 解包后的3位数值。
 */
function unpack3BitValue(packedValue, index) {
  // 将packedValue右移到所需值位于最低3位，然后与0b111进行位与操作以提取
  return (packedValue >> (index * 3)) & 0b111;
}

// 编码（写入Firestore前）
const pixelColors = [0, 3, 7, 1, 5];
const packedData = pack3BitValues(pixelColors);
console.log("Packed Data:", packedData); // 示例输出：Packed Data: 13992 (二进制: 0011011100010000)

// 假设我们将 packedData 存储在 Firestore 的一个文档字段中，例如 `docRef.update({ pixels: packedData });`

// 解码（从Firestore读取后）
// 假设从 Firestore 读取到 packedData
const retrievedPackedData = packedData; // 模拟从 Firestore 读取

// 解包第一个像素的颜色
const color0 = unpack3BitValue(retrievedPackedData, 0);
console.log("Color at index 0:", color0); // 输出: Color at index 0: 0

// 解包第二个像素的颜色
const color1 = unpack3BitValue(retrievedPackedData, 1);
console.log("Color at index 1:", color1); // 输出: Color at index 1: 3

// 解包所有像素的颜色
const unpackedColors = [];
for (let i = 0; i < pixelColors.length; i++) { // 假设我们知道原始的像素数量
  unpackedColors.push(unpack3BitValue(retrievedPackedData, i));
}
console.log("Unpacked Colors:", unpackedColors); // 输出: Unpacked Colors: [0, 3, 7, 1, 5]

// 示例：将多行3位像素数据存储为打包整数数组
function packRowsOf3BitValues(rowsOfValues) {
  return rowsOfValues.map(row => pack3BitValues(row));
}

function unpackRowsOf3BitValues(packedRows, numValuesPerRow) {
  return packedRows.map(packedRow => {
    const row = [];
    for (let i = 0; i < numValuesPerRow; i++) {
      row.push(unpack3BitValue(packedRow, i));
    }
    return row;
  });
}

// 示例数据：两行像素，每行3个像素
const allPixelRows = [
  [0, 1, 2], // row 0
  [7, 6, 5]  // row 1
];

const packedRowsForFirestore = packRowsOf3BitValues(allPixelRows);
console.log("Packed Rows for Firestore:", packedRowsForFirestore); // [ 198, 471 ]

// 存储到 Firestore: docRef.update({ canvasData: packedRowsForFirestore });

// 从 Firestore 读取后解包
const retrievedPackedRows = packedRowsForFirestore; // 模拟读取
const unpackedAllRows = unpackRowsOf3BitValues(retrievedPackedRows, 3); // 3是每行的像素数量
console.log("Unpacked All Rows:", unpackedAllRows); // [ [ 0, 1, 2 ], [ 7, 6, 5 ] ]