Init Repo

2026-03-26 08:27:38 +08:00
commit 4eb266b623
12 changed files with 22763 additions and 0 deletions
@@ -0,0 +1,78 @@
+# MzTranslator 架構設計
+
+## 概述
+使用 Maya Python API 建立一個 `.mz` 檔案格式的 Maya Translator 插件。
+
+## .mz 檔案格式
+- 本質是 ZIP 壓縮格式
+- 內部包含 `data.ma` 文件（Maya ASCII 格式）
+
+## 系統架構
+
+```mermaid
+graph TB
+    subgraph Maya
+        A[Maya GUI] -->|另存為/開啟| B[mz_translator.py]
+    end
+    
+    subgraph Core
+        B --> D[mz_writer]
+        B --> E[mz_reader]
+    end
+    
+    subgraph FileSystem
+        D --> F[.mz]
+        E --> F
+    end
+```
+
+## 實現步驟
+
+### 1. 文件結構
+
+```
+d:/workspace/MzTranslator/
+├── mz_translator.py          # 插件入口，包含 MPxFileTranslator 和插件註冊
+└── mz_core/
+    ├── __init__.py           # 模組初始化
+    ├── reader.py             # 讀取模組
+    └── writer.py             # 寫入模組
+```
+
+### 2. mz_translator.py
+- 繼承 `maya.api.MPxFileTranslator`
+- 包含 `initializePlugin()` 和 `uninitializePlugin()` 函數
+- `writer(fileObject, options)`: 調用 mz_writer
+- `reader(fileObject, options)`: 調用 mz_reader
+- `haveWriteSupport()` / `haveReadSupport()`: 返回 True
+- `fileType()` / `defaultExtension()`: 返回 "mz"
+- `optionsScript()`: Export Options UI
+
+### 3. MzTranslator/mz/core/mz_writer.py
+- `write_to_mz(filePath, options)`: 將 Maya 場景寫入 .mz
+- 內部調用 Maya API 寫入 temp data.ma
+- 使用 zipfile 壓縮成 .mz
+
+### 4. MzTranslator/mz/core/mz_reader.py
+- `read_from_mz(filePath, buffer)`: 從 .mz 讀取
+- 使用 zipfile 解壓縮
+- 讀取到內存緩衝區
+
+### 5. Export Options 對話框
+- 版本號
+- 壓縮等級
+
+## 技術要點
+
+1. **MPxFileTranslator 繼承**: 使用 `maya.app.audio.MPxFileTranslator`
+
+2. **Stream I/O**: reader 使用 buffer/stream 讀取
+
+3. **臨時文件管理**: 使用 `tempfile` 模組
+
+4. **Error Handling**: 處理各種異常情況
+
+## 預期行為
+
+- **保存**: Maya 另存為 → 選擇 .mz → 導出到 temp data.ma → 壓縮成 .mz
+- **開啟**: 選擇 .mz 文件 → 解壓讀取 data.ma → 加載到 Maya