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:

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:

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

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.