MzTranslator/plans/plan.md

MzTranslator 架構設計

概述

使用 Maya Python API 建立一個 .mz 檔案格式的 Maya Translator 插件。

.mz 檔案格式

• 本質是 ZIP 壓縮格式
• 內部包含 data.ma 文件（Maya ASCII 格式）

系統架構

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