Terminal
Terminal/Skill
Reference and guide for writing Python scripts that import, repair, optimize and export CAD and 3D files with the Asset Transformer SDK.
By Unity
Works with
npx skills add unity-technologies/industry-ai-workflows --skill at-scriptingThis skill is the source of truth for writing Python against the Asset Transformer SDK (pxz). It serves two audiences:
run_python tool — the primary target. Code runs in-process inside the running Pixyz session.at-upa-scripting, which layers UPA-container conventions (argparse, workspace paths, no-Asset-Manager-write) on top of this same API. Both defer to pxz-api-reference.md in this folder for the API surface.The API surface is documented in pxz-api-reference.md next to this file. It is authoritative: if a function, class, parameter, or constant is not listed there, it does not exist in this SDK version — do not call it. See Accuracy guardrails.
run_python toolThe Asset Transformer MCP runs code like this:
exec(compile(code, "<mcp_run_python>", "exec"), {"pxz": pxz})
So when you write a script for run_python:
pxz is already in scope as a global. You do not import pxz. (You may still from pxz import scene, algo, io, ... for brevity, or just use pxz.scene.* — the module attributes are all reachable off the global.)pxz.initialize(), core.configureLicenseServer, core.checkLicense, core.needToken, etc. If init is broken, the server is misconfigured — not your script.run_python (and every other AT MCP tool) operates on the same live session. A model you imported in one call is still there in the next. Do not assume an empty scene — call pxz.scene.getRoot() / getChildren(root) to see what's loaded, and clear_scene (or delete children of root) if you need a clean slate.pxz is guaranteed in the globals. The standard library is importable (import math, os, json, …), but there is no argparse-style input channel — inputs are literals in the code you write, or values you read from the live scene.print(...) is how you surface results (counts, ids, paths). Print the things the caller needs to see.run_python vs. the UPA custom-script actionrun_python (this skill's default) | UPA "Execute custom script" (see at-upa-scripting) | |
|---|---|---|
pxz availability | global, pre-initialized | imported (import pxz), pre-initialized by runtime |
| Inputs | literals / live scene | argparse over sys.argv |
| Scene lifetime | stateful across tool calls | fresh per job |
| Entry point | bare statements run top-to-bottom | main() + if __name__ == "__main__" guard |
| File paths | wherever you point them | /workspace/input, /workspace/output |
| Write to Asset Manager | not this tool's job (chain an AM tool/action) | not possible (chain an AM action) |
When a user's script is clearly destined for a pipeline, switch to the at-upa-scripting conventions. When it's an interactive/one-off transformation against the live MCP session, use the in-process style below.
Local run_python (and every other AT MCP tool) consumes a Pixyz license seat. If check_license fails or no license server is configured, do not stop — fall back to remote execution:
compile(code, "<script>", "exec") or python -m py_compile) — no pxz or license needed.at-upa-scripting conventions for the script body (argparse, /workspace paths, main() guard) and pipeline-authoring for the surrounding pipeline JSON.Tell the user clearly about the trade-off: remote execution works without a seat, but local execution and fast local iteration require a license. To unlock full local capabilities they should contact their Unity account representative or sales: https://unity.com/contact-us?reason=Speak+to+Sales&step=3&topic=Industrial+Solutions
pxz has no object model. Every entity — occurrence, part, mesh, material, image, viewer, baking session, and every CAD BRep entity (body, face, edge, curve, surface) — is an opaque int id. There is no scene.Node, scene.Material, or cad.Body object.
root = pxz.scene.getRoot().pxz.algo.tessellate([root], ...).scene.getOccurrenceName(occ), scene.deleteOccurrences([occ]), scene.getChildren(occ). There is no scene.getName, scene.deleteNodes, node.name.io.exportScene(fileName, root=0) infers format from the file extension — there is no format=/binaryGLTF=/embedTextures= keyword. Per-format tuning goes through core.setModuleProperty("io", "<key>", "<value>") before the export call.For run_python, prefer small, flat, top-to-bottom scripts that print what they did. You do not need argparse or a main() guard (though defining helper functions is fine and encouraged for anything non-trivial):
# pxz is already global and initialized — no import, no initialize().
root = pxz.scene.getRoot()
# 1. Import a model into the live scene.
model = pxz.io.importScene(r"C:\models\bracket.step")
# 2. Prepare: repair + tessellate relative to the model's size.
pxz.algo.repairCAD([model], 0.1, True)
pxz.algo.tessellateRelativelyToAABB([model], maxSag=-1, sagRatio=0.005,
maxLength=-1, maxAngle=20.0)
pxz.algo.repairMesh([model], 0.01, True, True)
# 3. Report and export.
tris = pxz.scene.getPolygonCount([model], asTriangleCount=True)
print(f"triangles after prep: {tris}")
pxz.io.exportScene(r"C:\out\bracket.glb", model)
Wrap genuinely multi-step, state-changing work in an undo/redo step so the session stays clean and reversible (the built-in AT MCP tools do this):
pxz.core.startUndoRedoStep(stepName="run_python: decimate")
try:
pxz.algo.decimateTarget([root], ["ratio", 0.5])
finally:
pxz.core.endUndoRedoStep()
Prefer adapting a vetted examples/ script over generating from scratch. Current examples:
import-prepare-export.py — in-process import → repair → tessellate (relative to AABB) → repair mesh → export GLB, with triangle-count reporting.inspect-scene.py — walk the live stateful scene, report per-occurrence names / triangle counts / AABB without mutating anything (safe to run first when you don't know what's loaded).High-level building blocks (all detailed in pxz-api-reference.md):
io.importScene, io.importFiles, io.exportScene (extension-driven), io.getImportFormats / io.getExportFormats.algo.repairCAD, algo.assembleCAD, algo.tessellate / algo.tessellateRelativelyToAABB, algo.repairMesh.algo.decimate, algo.decimateTarget(occ, ["ratio", r]) / (occ, ["polygonCount", n]), algo.removeHoles, algo.deletePatches, scene.mergePartOccurrences*, scene.convertSimilarPartOccurrencesToInstances* (via algo), algo.removeOccludedGeometries.algo.automaticUVMapping, algo.unwrapUV, algo.repackUV, algo.mapUvOn*.algo.combineMaterials(occ, BakeOption(...)) for the high-level AO-into-materials path; algo.beginBakingSession + algo.bake*Map + algo.endBakingSession for explicit control.scene.getChildren, scene.getPolygonCount, scene.getAABB, scene.findOccurrencesByProperty, scene.getFilteredOccurrences, scene.deleteOccurrences, scene.hide / show.view.takeScreenshot (offscreen viewer); raytrace.renderImage only when ray-traced quality is required.tessellateRelativelyToAABB (a sagRatio scales with model size) over a fixed maxSag when you don't know the model's scale.convertSimilarPartOccurrencesToInstances*) rather than duplicating mesh data.For large assemblies, prefer approaches that:
Because the scene is stateful in run_python, also: clean up after yourself (delete scratch occurrences, core.endUndoRedoStep) so later tool calls start from a predictable state.
When a chosen approach materially affects performance, add a one-line comment explaining why.
run_python scripts, do not re-import or re-initialize pxz.The full pxz API surface is documented in pxz-api-reference.md next to this file. If a function or class is not listed there, it does not exist in this SDK version. Do not generate code that calls it — verify first, or tell the user the SDK doesn't support what they're asking for.
Specifically, do not invent:
scene.Node, scene.NodeType, scene.getName, scene.deleteNodes, cad.Body objects — pxz uses integer handles, not objects. Real names: scene.getOccurrenceName, scene.deleteOccurrences, etc.io.exportScene — the real signature is exportScene(fileName: str, root: int = 0). Format is inferred from extension; per-format options are set via core.setModuleProperty("io", ...) before the export call.If something is uncertain or undocumented:
Version. The reference is verified against the installed 2026.4.0.0 stubs — the exact surface run_python executes against. Prefer functions confirmed in pxz-api-reference.md; when in doubt, probe the live SDK (print([n for n in dir(pxz.algo) if "decimate" in n.lower()])) before relying on a call.
Ground-truth source for the reference: the *.pyi type stubs shipped inside the installed pxz package. Re-extract the reference if the SDK is upgraded.
When a script fails or behaves incorrectly, work through these in order:
scene.getChildren(scene.getRoot()) to see what's actually loaded.io.getExportFormats)?list[int], not int. Check the signature in pxz-api-reference.md.tessellateRelativelyToAABB when scale is unknown.Identify the likely cause, explain why it fails, describe how to verify, then provide the corrected snippet.
/workspace paths, no-AM-write, main() guard) → see at-upa-scripting, which uses this reference for the API surface.pipeline-authoring.