mtlx

MaterialX SDK for JavaScript and TypeScript, on Web and Node.js.

mtlx parses, validates, packages, and transforms MaterialX materials: loose .mtlx documents, the spec-compliant .mtlz container, and relaxed .mtlx.zip archives. It is the library behind the mtlx.ben3d.ca viewer and the "Mtlx Viewer" VS Code extension.

Packages

Package	Description
mtlx-core	Parse, validate, package, and transform MaterialX. Pure and browser-safe; Node helpers under mtlx-core/node, texture processing under mtlx-core/textures.
mtlx-cli	The mtlx command: check, info, and transform (convert, pack, unpack, resize textures).
website	Drag-and-drop viewer and validator at mtlx.ben3d.ca, plus these docs.
mtlx-vscode-extension	"Mtlx Viewer": preview, inspect, and convert MaterialX files inside VS Code.

Scripting

npm install mtlx-core
Copy

import { transform } from 'mtlx-core';
import { loadMaterialXPackage, writeMaterialXPackage } from 'mtlx-core/node';
import { resizeTextures } from 'mtlx-core/textures';

// Load a .mtlx (with its textures), .mtlz, or .mtlx.zip into memory.
const pkg = await loadMaterialXPackage('material.mtlx');

// Apply transforms in order.
await transform(pkg, resizeTextures({ maxImageSize: 2048, imageFormat: 'webp' }));

// Write back out as any format.
await writeMaterialXPackage(pkg, 'material.mtlz');
Copy

In the browser, the root entry works on bytes and text with no filesystem:

import { checkMaterialXZipArchive, parseMaterialX, validateDocument } from 'mtlx-core';

const issues = validateDocument(parseMaterialX(xmlText));
const archiveIssues = checkMaterialXZipArchive(new Uint8Array(await file.arrayBuffer()));
Copy

See Concepts and the API reference.

Command line

npm install --global mtlx-cli
Copy

mtlx check material.mtlx
mtlx info material.mtlz --format json
mtlx transform material.mtlx material.mtlz                    # pack
mtlx transform material.mtlz out/material.mtlx                # unpack
mtlx transform material.mtlx material.mtlz --max-image-size 2048 --image-format webp
Copy

See the command line guide.

Contributing

See CONTRIBUTING.md for setup, testing, and release steps, and CHANGELOG.md for what has changed.

Credits

Created by Ben Houston, sponsored by Land of Assets. The library design follows patterns from Don McCurdy's glTF Transform. Sample materials come from material-samples.com.

License

MIT