MzTranslator/README.md

# MzTranslator

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` 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/
├── 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

### MzTranslate.mod
Maya module definition file that defines the module name and Python path.

### 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

# Add plugin path
plugin_path = 'd:/workspace/MzTranslator'
if plugin_path not in sys.path:
    sys.path.insert(0, plugin_path)

# Load plugin
import plug-ins.mz_translator as mz_translator
import maya.cmds as cmds
cmds.loadPlugin(mz_translator.__file__)
```

### Method 2: Using PluginManager

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)

Copy `MzTranslate.mod` to Maya's modules directory and configure the path.

## Usage

### Save/Export

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

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

- 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

- 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

- 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.)

## Version Info

- Version: 1.0.0
- 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.