Update README.md
This commit is contained in:
parent
4eb266b623
commit
06a5c55cc2
205
README.md
205
README.md
|
|
@ -1,111 +1,186 @@
|
|||
# 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/
|
||||
├── mz_translator.py # 插件入口，包含 MPxFileTranslator 和插件註冊
|
||||
├── mz_core/
|
||||
│ ├── __init__.py # 模組初始化
|
||||
│ ├── reader.py # 讀取模組
|
||||
│ └── writer.py # 寫入模組
|
||||
└── README.md # 使用說明
|
||||
├── MzTranslate.mod # Maya module definition file
|
||||
├── setup.py # Setup configuration (Cython build)
|
||||
├── plug-ins/
|
||||
│ └── mz_translator.py # Plugin entry point (MPxFileTranslator)
|
||||
├── python/
|
||||
│ └── 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
|
||||
import sys
|
||||
import os
|
||||
|
||||
# 添加插件路徑
|
||||
# Add plugin path
|
||||
plugin_path = 'd:/workspace/MzTranslator'
|
||||
if plugin_path not in sys.path:
|
||||
sys.path.insert(0, plugin_path)
|
||||
|
||||
# 載入插件
|
||||
import mz_translator
|
||||
# Load plugin
|
||||
import plug-ins.mz_translator as mz_translator
|
||||
import maya.cmds as cmds
|
||||
cmds.loadPlugin(mz_translator.__file__)
|
||||
```
|
||||
|
||||
### 方法 2：使用 pluginManager
|
||||
### Method 2: Using PluginManager
|
||||
|
||||
1. 打開 Maya
|
||||
2. 進入 `Window > Settings/Preferences > Plugin Manager`
|
||||
3. 點擊 `Browse` 找到 `mz_translator.py`
|
||||
4. 勾選 `Loaded` 載入插件
|
||||
1. Open Maya
|
||||
2. Go to `Window > Settings/Preferences > Plugin Manager`
|
||||
3. Click `Browse` to find `mz_translator.py` in the `plug-ins` folder
|
||||
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...`
|
||||
2. 在文件類型下拉選單中選擇 `Mz File (*.mz)`
|
||||
3. 選擇保存位置並點擊 `Save`
|
||||
## Usage
|
||||
|
||||
### 開啟 (Open/Import)
|
||||
### Save/Export
|
||||
|
||||
1. 選擇 `File > Open...` 或 `File > Import...`
|
||||
2. 在文件類型下拉選單中選擇 `Mz File (*.mz)`
|
||||
3. 選擇 `.mz` 文件並點擊 `Open`
|
||||
1. Select `File > Save As...` or `File > Export All...`
|
||||
2. Select `MayaZip (*.mz)` from the file type dropdown
|
||||
3. Choose save location and click `Save`
|
||||
4. Configure compression level in the options dialog (0=none, 9=maximum)
|
||||
|
||||
## 功能特性
|
||||
### Open/Import
|
||||
|
||||
- **讀取支援**：從 `.mz` 檔案解壓縮並讀取 `data.ma`
|
||||
- **寫入支援**：將 Maya 場景導出為 `.mz` 檔案（壓縮格式）
|
||||
- **Export Options**：支援壓縮級別設定（0-9）
|
||||
1. Select `File > Open...` or `File > Import...`
|
||||
2. Select `MayaZip (*.mz)` from the file type dropdown
|
||||
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
|
||||
|
||||
- 使用 `tempfile` 建立臨時目錄
|
||||
- 使用 Maya 的 `cmds.file()` 導出為 `.ma` 格式
|
||||
- 使用 `zipfile` 將 `data.ma` 壓縮成 `.mz`
|
||||
- Uses `tempfile` to create temporary directory
|
||||
- Uses Maya's `cmds.file()` to export as `.ma` format
|
||||
- Uses `zipfile` to compress `data.ma` into `.mz`
|
||||
- Supports configurable compression levels (0-9)
|
||||
|
||||
### reader.py
|
||||
|
||||
- 使用 `zipfile` 讀取 `.mz` 檔案
|
||||
- 提取 `data.ma` 到臨時目錄
|
||||
- 使用 Maya 的 `cmds.file()` 讀取場景
|
||||
- 自動清理臨時檔案
|
||||
- Uses `zipfile` to read `.mz` files
|
||||
- Extracts `data.ma` to temporary directory
|
||||
- Uses Maya's `MFileIO` or `cmds.file()` to read the scene
|
||||
- Auto cleanup temporary files via `SceneClosed` scriptJob
|
||||
|
||||
### mz_translator.py
|
||||
|
||||
- 繼承 `maya.api.OpenMayaMPx.MPxFileTranslator`
|
||||
- 實現 `writer()` 和 `reader()` 方法
|
||||
- 包含 Maya 插件註冊函數 `initializePlugin()` 和 `uninitializePlugin()`
|
||||
- Inherits `maya.api.OpenMayaMPx.MPxFileTranslator`
|
||||
- Implements all required virtual methods
|
||||
- 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.)
|
||||
|
||||
確保插件路徑正確：
|
||||
```python
|
||||
import mz_translator
|
||||
print(mz_translator.__file__) # 確認路徑正確
|
||||
```
|
||||
|
||||
### 問題：無法識別 .mz 檔案
|
||||
|
||||
確認 `.mz` 檔案是有效的 ZIP 格式（包含 `data.ma`）
|
||||
|
||||
### 問題：讀取後場景未更新
|
||||
|
||||
檢查臨時檔案是否有權限問題，或嘗試重新開啟 Maya
|
||||
|
||||
## 版本資訊
|
||||
## Version Info
|
||||
|
||||
- Version: 1.0.0
|
||||
- API: Maya Python API
|
||||
- 支援 Maya 版本: 2017+
|
||||
- API: Maya Python API (OpenMayaMPx)
|
||||
- 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