自訂檔案格式說明 - pondahai/epaper_ime GitHub Wiki

自訂檔案格式說明 (Custom File Formats)

為了在資源受限的系統上實現高效的資料存取，我們設計了一套自訂的檔案格式。所有這些格式都由 tools/ 目錄下的 Python 腳本生成。

---

1. 字型系統 (Font System)

由 font_converter.py 生成，包含兩個檔案：

檔案一：查找表 (.map)

• 檔名: [font_name]_[size].map (例如 msjh_24.map)
• 格式: JSON
• 用途: 提供一個從 Unicode 碼 到 點陣圖資料 的快速索引。在 Python 模擬器中，它被完全載入記憶體以實現快速查找。
• 結構:

  {
      "metadata": {
          "font_name": "msjh_24",
          "font_size": 24,
          "format": "1-byte-grayscale"
      },
      "characters": {
          "20320": [ 0, 24, 24 ],
          "22909": [ 576, 24, 24 ],
          "...": "[...]"
      }
  }
  

  • metadata: 包含字型名稱、大小和點陣圖格式等元數據。
  • characters: 一個字典對象。
    • 鍵 (Key): 字元的 Unicode 碼點（以字串形式表示）。
    • 值 (Value): 一個包含三個元素的陣列 [offset, width, height]。
      • offset: 該字元點陣圖在對應的 .font 檔案中的起始位元組位置。
      • width: 點陣圖的寬度（像素）。
      • height: 點陣圖的高度（像素）。

檔案二：點陣資料 (.font)

• 檔名: [font_name]_[size].font (例如 msjh_24.font)
• 格式: 純二進位 (Raw Binary)
• 用途: 緊湊地儲存所有字元的實際點陣圖資料。
• 結構:
  • 檔案由所有字元的點陣圖資料按順序拼接而成。
  • 每個字元的點陣圖資料大小為 width * height 位元組。
  • 每個位元組代表一個像素的灰度值（0 為黑，255 為白），這使得字元邊緣可以實現平滑的抗鋸齒效果。
  • 程式透過 .map 檔獲取偏移和尺寸，然後直接從這個檔案的指定位置讀取所需資料。

---

2. 輸入法系統 (IME System)

由 ime_converter.py 生成，也包含兩個檔案：

檔案一：查詢索引 (.idx)

• 檔名: [ime_name].idx (例如 zhuyin.idx)
• 格式: JSON
• 用途: 提供一個從注音輸入碼到候選字串的快速索引。
• 結構:

  {
      "ㄈㄟ1": [ 0, 18 ],
      "ㄈㄟ2": [ 18, 3 ],
      "ㄈㄟ3": [ 21, 15 ],
      "ㄋㄧ3": [ 12345, 6 ],
      "...": "[...]"
  }
  

  • 鍵 (Key): 經過處理的標準化注音輸入碼。聲調被替換為數字（1-5），例如 ㄋㄧˇ 變為 ㄋㄧ3。
  • 值 (Value): 一個包含兩個元素的陣列 [offset, length]。
    • offset: 該輸入碼對應的候選字字串在 .dat 檔案中的起始位元組位置。
    • length: 該候選字字串的位元組長度（以 UTF-8 編碼計）。

檔案二：候選字資料 (.dat)

• 檔名: [ime_name].dat (例如 zhuyin.dat)
• 格式: 純二進位 (Raw Binary)
• 用途: 緊湊地儲存所有輸入碼對應的候選字字串。
• 結構:
  • 檔案由所有候選字字串按順序拼接而成。
  • 所有字串均使用 UTF-8 進行編碼。
  • 程式透過 .idx 檔獲取偏移和長度，然後直接從這個檔案的指定位置讀取對應的候選字資料。

---