# MzTranslator

Maya `.mz` 檔案格式 Translator 插件，使用 Maya Python API 開發。

## 檔案格式

`.mz` 檔案本質上是 ZIP 壓縮格式，內部包含 `data.ma` (Maya ASCII) 文件。

## 目錄結構

```
d:/workspace/MzTranslator/
├── mz_translator.py          # 插件入口，包含 MPxFileTranslator 和插件註冊
├── mz_core/
│   ├── __init__.py           # 模組初始化
│   ├── reader.py             # 讀取模組
│   └── writer.py             # 寫入模組
└── README.md                 # 使用說明
```

## 安裝方法

### 方法 1：直接載入 Python 模組

在 Maya 的 Python 腳本編輯器中執行：

```python
import sys
import os

# 添加插件路徑
plugin_path = 'd:/workspace/MzTranslator'
if plugin_path not in sys.path:
    sys.path.insert(0, plugin_path)

# 載入插件
import mz_translator
cmds.loadPlugin(mz_translator.__file__)
```

### 方法 2：使用 pluginManager

1. 打開 Maya
2. 進入 `Window > Settings/Preferences > Plugin Manager`
3. 點擊 `Browse` 找到 `mz_translator.py`
4. 勾選 `Loaded` 載入插件

## 使用方法

### 存儲 (Save/Export)

1. 選擇 `File > Save As...` 或 `File > Export All...`
2. 在文件類型下拉選單中選擇 `Mz File (*.mz)`
3. 選擇保存位置並點擊 `Save`

### 開啟 (Open/Import)

1. 選擇 `File > Open...` 或 `File > Import...`
2. 在文件類型下拉選單中選擇 `Mz File (*.mz)`
3. 選擇 `.mz` 文件並點擊 `Open`

## 功能特性

- **讀取支援**：從 `.mz` 檔案解壓縮並讀取 `data.ma`
- **寫入支援**：將 Maya 場景導出為 `.mz` 檔案（壓縮格式）
- **Export Options**：支援壓縮級別設定（0-9）

## 技術細節

### writer.py

- 使用 `tempfile` 建立臨時目錄
- 使用 Maya 的 `cmds.file()` 導出為 `.ma` 格式
- 使用 `zipfile` 將 `data.ma` 壓縮成 `.mz`

### reader.py

- 使用 `zipfile` 讀取 `.mz` 檔案
- 提取 `data.ma` 到臨時目錄
- 使用 Maya 的 `cmds.file()` 讀取場景
- 自動清理臨時檔案

### mz_translator.py

- 繼承 `maya.api.OpenMayaMPx.MPxFileTranslator`
- 實現 `writer()` 和 `reader()` 方法
- 包含 Maya 插件註冊函數 `initializePlugin()` 和 `uninitializePlugin()`

## 故障排除

### 問題：無法載入插件

確保插件路徑正確：
```python
import mz_translator
print(mz_translator.__file__)  # 確認路徑正確
```

### 問題：無法識別 .mz 檔案

確認 `.mz` 檔案是有效的 ZIP 格式（包含 `data.ma`）

### 問題：讀取後場景未更新

檢查臨時檔案是否有權限問題，或嘗試重新開啟 Maya

## 版本資訊

- Version: 1.0.0
- API: Maya Python API
- 支援 Maya 版本: 2017+