Update README.md
This commit is contained in:
parent
4eb266b623
commit
06a5c55cc2
205
README.md
205
README.md
|
|
@ -1,111 +1,186 @@
|
||||||
# MzTranslator
|
# MzTranslator
|
||||||
|
|
||||||
Maya `.mz` 檔案格式 Translator 插件，使用 Maya Python API 開發。
|
Maya `.mz` file format Translator plugin, developed using Maya Python API. This plugin allows Maya to read and write `.mz` files, which are ZIP-compressed archives containing Maya ASCII (`.ma`) files.
|
||||||
|
|
||||||
## 檔案格式
|
## File Format
|
||||||
|
|
||||||
`.mz` 檔案本質上是 ZIP 壓縮格式，內部包含 `data.ma` (Maya ASCII) 文件。
|
`.mz` files are ZIP compressed archives that contain a `data.ma` file (Maya ASCII format). This format provides:
|
||||||
|
- Compression: Reduces file size compared to plain `.ma` files
|
||||||
|
- Single file: All scene data in one archive
|
||||||
|
|
||||||
## 目錄結構
|
## Directory Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
d:/workspace/MzTranslator/
|
d:/workspace/MzTranslator/
|
||||||
├── mz_translator.py # 插件入口，包含 MPxFileTranslator 和插件註冊
|
├── MzTranslate.mod # Maya module definition file
|
||||||
├── mz_core/
|
├── setup.py # Setup configuration (Cython build)
|
||||||
│ ├── __init__.py # 模組初始化
|
├── plug-ins/
|
||||||
│ ├── reader.py # 讀取模組
|
│ └── mz_translator.py # Plugin entry point (MPxFileTranslator)
|
||||||
│ └── writer.py # 寫入模組
|
├── python/
|
||||||
└── README.md # 使用說明
|
│ └── mz_core/
|
||||||
|
│ ├── __init__.py # Module initialization & exports
|
||||||
|
│ ├── reader.py # Reader module (extract .mz to temp)
|
||||||
|
│ ├── reader.c # Reader C extension (compiled)
|
||||||
|
│ ├── writer.py # Writer module (export scene to .mz)
|
||||||
|
│ └── writer.c # Writer C extension (compiled)
|
||||||
|
├── plans/
|
||||||
|
│ └── plan.md # Project architecture plan
|
||||||
|
├── .vscode/
|
||||||
|
│ └── settings.json # VS Code settings
|
||||||
|
└── README.md # This documentation
|
||||||
```
|
```
|
||||||
|
|
||||||
## 安裝方法
|
## Project Components
|
||||||
|
|
||||||
### 方法 1：直接載入 Python 模組
|
### MzTranslate.mod
|
||||||
|
Maya module definition file that defines the module name and Python path.
|
||||||
|
|
||||||
在 Maya 的 Python 腳本編輯器中執行：
|
### plug-ins/mz_translator.py
|
||||||
|
Main plugin entry point that:
|
||||||
|
- Implements `MzFileTranslator` class inheriting from `maya.api.OpenMayaMPx.MPxFileTranslator`
|
||||||
|
- Registers the plugin with Maya via `initializePlugin()` and `uninitializePlugin()`
|
||||||
|
- Provides file identification via `identifyFile()`
|
||||||
|
- Handles writing via `writer()` method
|
||||||
|
- Handles reading via `reader()` method
|
||||||
|
- Provides export options UI via `optionsScript()`
|
||||||
|
|
||||||
|
### python/mz_core/
|
||||||
|
|
||||||
|
#### __init__.py
|
||||||
|
Module initialization that exports:
|
||||||
|
- `read_scene_from_mz` - Read scene from .mz file
|
||||||
|
- `read_to_temp_file` - Extract .mz to temporary file
|
||||||
|
- `get_file_info` - Get .mz file information
|
||||||
|
- `write_scene_to_mz` - Write scene to .mz file
|
||||||
|
- `get_export_options` - Get export options
|
||||||
|
|
||||||
|
#### reader.py
|
||||||
|
Reader module that:
|
||||||
|
- `read_scene_from_mz()` - Reads .mz file, returns content or writes to buffer
|
||||||
|
- `read_to_temp_file()` - Extracts .mz to temporary directory
|
||||||
|
- `get_file_info()` - Returns file size and archive contents
|
||||||
|
|
||||||
|
#### writer.py
|
||||||
|
Writer module that:
|
||||||
|
- `write_scene_to_mz()` - Exports current Maya scene to .mz file
|
||||||
|
- `_export_to_ma()` - Exports scene as Maya ASCII format
|
||||||
|
- `get_export_options()` - Returns compression level options
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
### Method 1: Direct Python Module Loading
|
||||||
|
|
||||||
|
Execute in Maya's Python Script Editor:
|
||||||
|
|
||||||
```python
|
```python
|
||||||
import sys
|
import sys
|
||||||
import os
|
|
||||||
|
|
||||||
# 添加插件路徑
|
# Add plugin path
|
||||||
plugin_path = 'd:/workspace/MzTranslator'
|
plugin_path = 'd:/workspace/MzTranslator'
|
||||||
if plugin_path not in sys.path:
|
if plugin_path not in sys.path:
|
||||||
sys.path.insert(0, plugin_path)
|
sys.path.insert(0, plugin_path)
|
||||||
|
|
||||||
# 載入插件
|
# Load plugin
|
||||||
import mz_translator
|
import plug-ins.mz_translator as mz_translator
|
||||||
|
import maya.cmds as cmds
|
||||||
cmds.loadPlugin(mz_translator.__file__)
|
cmds.loadPlugin(mz_translator.__file__)
|
||||||
```
|
```
|
||||||
|
|
||||||
### 方法 2：使用 pluginManager
|
### Method 2: Using PluginManager
|
||||||
|
|
||||||
1. 打開 Maya
|
1. Open Maya
|
||||||
2. 進入 `Window > Settings/Preferences > Plugin Manager`
|
2. Go to `Window > Settings/Preferences > Plugin Manager`
|
||||||
3. 點擊 `Browse` 找到 `mz_translator.py`
|
3. Click `Browse` to find `mz_translator.py` in the `plug-ins` folder
|
||||||
4. 勾選 `Loaded` 載入插件
|
4. Check `Loaded` to load the plugin
|
||||||
|
|
||||||
## 使用方法
|
### Method 3: Maya Module (Optional)
|
||||||
|
|
||||||
### 存儲 (Save/Export)
|
Copy `MzTranslate.mod` to Maya's modules directory and configure the path.
|
||||||
|
|
||||||
1. 選擇 `File > Save As...` 或 `File > Export All...`
|
## Usage
|
||||||
2. 在文件類型下拉選單中選擇 `Mz File (*.mz)`
|
|
||||||
3. 選擇保存位置並點擊 `Save`
|
|
||||||
|
|
||||||
### 開啟 (Open/Import)
|
### Save/Export
|
||||||
|
|
||||||
1. 選擇 `File > Open...` 或 `File > Import...`
|
1. Select `File > Save As...` or `File > Export All...`
|
||||||
2. 在文件類型下拉選單中選擇 `Mz File (*.mz)`
|
2. Select `MayaZip (*.mz)` from the file type dropdown
|
||||||
3. 選擇 `.mz` 文件並點擊 `Open`
|
3. Choose save location and click `Save`
|
||||||
|
4. Configure compression level in the options dialog (0=none, 9=maximum)
|
||||||
|
|
||||||
## 功能特性
|
### Open/Import
|
||||||
|
|
||||||
- **讀取支援**：從 `.mz` 檔案解壓縮並讀取 `data.ma`
|
1. Select `File > Open...` or `File > Import...`
|
||||||
- **寫入支援**：將 Maya 場景導出為 `.mz` 檔案（壓縮格式）
|
2. Select `MayaZip (*.mz)` from the file type dropdown
|
||||||
- **Export Options**：支援壓縮級別設定（0-9）
|
3. Select the `.mz` file and click `Open`
|
||||||
|
|
||||||
## 技術細節
|
## Features
|
||||||
|
|
||||||
|
- **Read Support**: Extract and read `data.ma` from `.mz` files
|
||||||
|
- **Write Support**: Export Maya scenes to `.mz` files with compression
|
||||||
|
- **Export Options**: Configurable compression level (0-9)
|
||||||
|
- **File Identification**: Automatic detection of `.mz` format
|
||||||
|
- **Temporary File Management**: Automatic cleanup of temporary files
|
||||||
|
|
||||||
|
## Technical Details
|
||||||
|
|
||||||
### writer.py
|
### writer.py
|
||||||
|
|
||||||
- 使用 `tempfile` 建立臨時目錄
|
- Uses `tempfile` to create temporary directory
|
||||||
- 使用 Maya 的 `cmds.file()` 導出為 `.ma` 格式
|
- Uses Maya's `cmds.file()` to export as `.ma` format
|
||||||
- 使用 `zipfile` 將 `data.ma` 壓縮成 `.mz`
|
- Uses `zipfile` to compress `data.ma` into `.mz`
|
||||||
|
- Supports configurable compression levels (0-9)
|
||||||
|
|
||||||
### reader.py
|
### reader.py
|
||||||
|
|
||||||
- 使用 `zipfile` 讀取 `.mz` 檔案
|
- Uses `zipfile` to read `.mz` files
|
||||||
- 提取 `data.ma` 到臨時目錄
|
- Extracts `data.ma` to temporary directory
|
||||||
- 使用 Maya 的 `cmds.file()` 讀取場景
|
- Uses Maya's `MFileIO` or `cmds.file()` to read the scene
|
||||||
- 自動清理臨時檔案
|
- Auto cleanup temporary files via `SceneClosed` scriptJob
|
||||||
|
|
||||||
### mz_translator.py
|
### mz_translator.py
|
||||||
|
|
||||||
- 繼承 `maya.api.OpenMayaMPx.MPxFileTranslator`
|
- Inherits `maya.api.OpenMayaMPx.MPxFileTranslator`
|
||||||
- 實現 `writer()` 和 `reader()` 方法
|
- Implements all required virtual methods
|
||||||
- 包含 Maya 插件註冊函數 `initializePlugin()` 和 `uninitializePlugin()`
|
- File translator name: "MayaZip"
|
||||||
|
- Extension: "mz"
|
||||||
|
- Provides export options UI dialog
|
||||||
|
|
||||||
## 故障排除
|
## Requirements
|
||||||
|
|
||||||
### 問題：無法載入插件
|
- Maya 2017 or later
|
||||||
|
- Maya Python API
|
||||||
|
- Python standard library (zipfile, tempfile, os, etc.)
|
||||||
|
|
||||||
確保插件路徑正確：
|
## Version Info
|
||||||
```python
|
|
||||||
import mz_translator
|
|
||||||
print(mz_translator.__file__) # 確認路徑正確
|
|
||||||
```
|
|
||||||
|
|
||||||
### 問題：無法識別 .mz 檔案
|
|
||||||
|
|
||||||
確認 `.mz` 檔案是有效的 ZIP 格式（包含 `data.ma`）
|
|
||||||
|
|
||||||
### 問題：讀取後場景未更新
|
|
||||||
|
|
||||||
檢查臨時檔案是否有權限問題，或嘗試重新開啟 Maya
|
|
||||||
|
|
||||||
## 版本資訊
|
|
||||||
|
|
||||||
- Version: 1.0.0
|
- Version: 1.0.0
|
||||||
- API: Maya Python API
|
- API: Maya Python API (OpenMayaMPx)
|
||||||
- 支援 Maya 版本: 2017+
|
- Supported Maya versions: 2017+
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Issue: Plugin fails to load
|
||||||
|
|
||||||
|
Verify plugin path is correct:
|
||||||
|
```python
|
||||||
|
import plug-ins.mz_translator as mz_translator
|
||||||
|
print(mz_translator.__file__) # Confirm path is correct
|
||||||
|
```
|
||||||
|
|
||||||
|
Also check for import errors in the mz_core module.
|
||||||
|
|
||||||
|
### Issue: Cannot recognize .mz files
|
||||||
|
|
||||||
|
Confirm `.mz` file is valid ZIP format (contains `data.ma`):
|
||||||
|
```python
|
||||||
|
import zipfile
|
||||||
|
with zipfile.ZipFile('your_file.mz', 'r') as zf:
|
||||||
|
print(zf.namelist()) # Should contain 'data.ma'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Issue: Scene not updated after reading
|
||||||
|
|
||||||
|
Check if temporary files have permission issues, or try restarting Maya. The plugin registers a `SceneClosed` scriptJob for cleanup.
|
||||||
|
|
||||||
|
### Issue: Export options not appearing
|
||||||
|
|
||||||
|
The options dialog is provided via `optionsScript()` method. Some Maya versions may handle this differently.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue