Metafile Render

Windows metafiles, ready for the modern web.

English · 简体中文

Quick start · Usage · Reference

Overview

Metafile Render converts Windows Metafile (WMF) and Enhanced Metafile (EMF) graphics into SVG, PNG, JPEG, and WebP. Use it to display legacy graphics in a browser or process metafile images extracted from Office documents.

• Cross-platform — runs on Linux, macOS, and Windows.
• Simple setup — only Pillow and pyclipper; no Office or external converter required.
• Python and CLI — integrate a single function or convert files from your terminal.
• Visible diagnostics — inspect partial rendering, approximations, and skipped content.

Quick start

Requires GIL-enabled CPython 3.11–3.14.

pip install metafile-render

Convert an existing EMF file to SVG:

metafile-render input.emf -o output.svg

WMF files use the same command. The output extension selects the format.

Usage

Python

from pathlib import Path
from metafile_render import render_metafile

result = render_metafile(
    Path("input.emf").read_bytes(),
    output_format="svg",
)
Path("output.svg").write_bytes(result.data)

print(result.width, result.height, result.media_type)
if result.partial:
    print("Partial rendering.")
for item in result.diagnostics:
    print(item.code, item.message)

render_metafile() takes bytes and returns image bytes, dimensions, format information, and diagnostics. Its default output is PNG at 200 DPI.

Canvas limits may reduce the requested dimensions. See the API reference for result fields and error handling.

Command line

metafile-render input.emf -o output.png --dpi 300
metafile-render input.emf -o output.webp
metafile-render input.emf -o transparent.png --backend replay
metafile-render input.wmf -o sized.png --size 800 600
python -m metafile_render input.emf -o output.jpg --force

Supported extensions: .svg, .png, .jpg, .jpeg, and .webp. The output directory must exist. Use --force to replace an existing output; input and output must be different files. Diagnostics are printed to stderr.

Rendering notes

The Rust extension is required. Releases provide cp311-abi3 wheels for Linux x86-64/aarch64, Windows x64/ARM64, and macOS 14+ arm64. Pure Python wheels and source distributions are not published.

Approximated or skipped content is reported through partial=True and diagnostics. Font substitution or a backend fallback alone does not mark a result as partial. Malformed, unsupported, or over-budget inputs can raise MetafileError; the CLI reports conversion errors with a nonzero exit code. A completed partial conversion exits with code 0.

Text cleanup reports text_control_filtered when paragraph separators or XML-invalid characters are removed from a single-line text run. A known RAQM layout failure skips only the affected text command and reports text_layout_failed. Both set partial=True; explicit character advances, background rectangles, and unrelated drawing commands are preserved.

Documentation and support

• Agent skill — conversion workflows and diagnostic handling for agents. Copy the skills/metafile-render directory into your agent's supported skills directory to use it.
• Technical reference — full API and CLI contracts, formats, fonts, and resource limits.
• Development guide — local checks, architecture, benchmarks, and publishing.
• Report an issue — include a sample file, conversion options, and diagnostics when possible.

License

MIT · Copyright © 2026 Xiaomeng Zhao (myhloli).