Meshify

meshify — 3D mesh optimization agent skill

English | 简体中文

Scope

Prepares 3D models for delivery on the web, AR, and mobile: simplification, part splitting, texturing, format conversion, LOD chains, one-command compression. Every command writes a meshify.report/v1 manifest (JSON) and reports results through semantic exit codes.

Always report results to the user in the user's own language. This document is English; that choice only affects what you read, not what you say to the user.

• Zero-install baseline: runs on Node ≥ 18.17 (Tier0: WASM geometry kernel)
• CAD support: STEP/STP needs Tier1 (Python/uv + gmsh); when missing, exit 5 with install instructions
• Never overwrites by default: artifacts go to <input-dir>/<input-name>.meshify/, re-running is idempotent; overwriting requires an explicit --overwrite

Support matrix (quick reference)

Input formats: glb gltf obj stl ply (Tier0 reads directly) / step stp (Tier1 only). FBX and others are not supported (exit 3).

Decision tree (in order)

Got a model
  ├─ Don't know its structure? → meshify inspect model.glb --json   # faces/submeshes/materials/textures/animations
  ├─ It's a STEP? → meshify doctor first to confirm Tier1; install if needed (references/cad-step.md)
  ├─ Too large / too many faces?
  │    ├─ Single object → meshify simplify --ratio 0.5
  │    ├─ Assembly to split → meshify segment --mode connected
  │    └─ Cut in half → meshify segment --mode plane --axis x
  ├─ Needs textures → meshify texture --map box --image tex.png
  ├─ Needs another format → meshify convert --to stl|obj|ply|gltf
  ├─ Needs progressive loading → meshify lod --levels 3 --ratio 0.5
  └─ Web delivery in one step → meshify optimize --ratio 0.5 --texture-size 2048
After each command: read report.json (or --json stdout) and check warnings and reduction metrics

Artifact commands default to --preview-html (simplify/segment/texture/convert/lod/optimize): it generates a before/after comparison page, the fastest way to verify the result by eye. Omit the flag when the user explicitly declines a preview, or for batch/unattended runs (the HTML embeds the model as base64 at roughly 1.33x the artifact size; three.js loads from a CDN and needs network).

What semantic mode is not: --mode semantic clusters by orientation + position; it does not recognize parts. Use connected to split an assembly; use semantic only to partition by appearance (flat/curved/differently oriented regions).

Command examples

# Structure analysis (the agent's first step; --json for the full manifest)
meshify inspect model.glb --json

# Simplify to 30% (per-submesh, materials kept; submeshes <200 faces skipped with a warning)
meshify simplify model.glb --ratio 0.3 --preview-html

# Exact target face count + error bound
meshify simplify model.glb --target-faces 50000 --error 0.005 --preview-html

# Connected-component split (first choice for assemblies; drops fragments <50 faces)
meshify segment model.glb --mode connected --min-faces 50 --preview-html

# Plane cut: slider semantics (-1..1 mapped across the bbox) or native coordinates
meshify segment model.glb --mode plane --axis x --position 0 --preview-html
meshify segment model.glb --mode plane --origin "0,10,0" --normal "0,1,0"

# Texture (box projection; generates UVs when missing and discloses it)
meshify texture model.glb --map box --image diffuse.png --metallic 0.1 --preview-html

# Format conversion (STL for slicers)
meshify convert model.glb --to stl --preview-html

# Three LOD levels (100%/50%/25%)
meshify lod model.glb --levels 3 --ratio 0.5 --preview-html

# Web delivery: simplify + textures capped at 2048 + meshopt compression
meshify optimize model.glb --ratio 0.5 --texture-size 2048 --preview-html

# STEP (CAD) → GLB: needs Tier1
meshify convert part.step --to glb

# A part authored lying down (real up axis is not the CAD-default Z): upright it while converting
meshify convert part.step --to glb --up-axis auto --preview-html

# Environment check (run before and after installing Tier1)
meshify doctor

Global options (all commands): -o <path> explicit output path, --json manifest to stdout, --overwrite, --tier auto|ts|py, --force to process an oversize input once. --preview-html follows the default policy above: artifact commands include it unless the flag is omitted.

Reading the report (meshify.report/v1)

Each command writes a manifest at <input-name>.meshify/<input-name>.<op>.report.json (reports are the tool's own logs and may be overwritten automatically; only model artifacts are governed by --overwrite). With --json the same content goes to stdout.

{
  "schema": "meshify.report/v1",
  "tool": { "name": "meshify", "version": "0.1.0", "tier": "ts-wasm" },  // or python-uv
  "command": "simplify",
  "input":  { "path": "...", "format": "glb", "vertices": 54, "faces": 32,
              "meshes": [ { "name": "boxA", "material": "red", "has_uv": true, ... } ],
              "materials": 3, "textures": [], "bbox": [[...],[...]], "has_animation": false },
  "output": { "path": "...glb", "bytes": 441100, "vertices": 14082, "faces": 14082,
              "files": [ { "path": "...", "bytes": 441100, "role": "asset" } ] },
  "params": { "ratio": 0.3 },
  "metrics": { "face_reduction": 0.7, "byte_reduction": 0.47, "duration_ms": 200 },
  "warnings": [ { "code": "SMALL_MESH_SKIPPED", "message": "...", "mesh": "boxA" } ],
  "errors": [],
  "exit_code": 0
}

How to read it: metrics.face_reduction/byte_reduction shows the effect; warnings[].code shows degradations (not failures); non-empty errors means failure. Full warning-code table in references/troubleshooting.md.

Failed runs also produce a manifest: non-zero exits (unreadable input, parameter conflicts, empty scene, and other early failures) still write a minimal manifest (errors[] with the reason, params.failed_early: true, input stats zeroed as a fallback), and the --json stdout contract is unchanged. Always "parse the stdout manifest first; on failure read errors + exit_code". Field-level detail in references/report-schema.md.

Exit codes (decide by code)

Tier routing (when Python runs)

1. Input contains animation/skinning/morphs → forced Tier0 (the trimesh pipeline would drop animation), writes SKIN_ANIMATION_PRESERVED
2. Input is STEP → forced Tier1; when not installed → exit 5 + install instructions (no TS fallback; this is a capability boundary, not a malfunction)
3. Everything else defaults to Tier0; --tier py explicitly requests Tier1, exit 5 if unavailable
4. meshopt/draco/WebP compression in optimize is Tier0-only — under --tier py the output is an uncompressed baseline with a TIER_DOWNGRADED disclosure

Details in references/tiering.md.

Output layout

model.glb
model.meshify/
  ├─ model.inspect.report.json      # per-command reports
  ├─ model.simplified.glb           # single-file artifact
  ├─ model.segment-plane.glb        # merged segmentation artifact (part-level scene)
  ├─ model.segment-plane/part_000.glb ...   # Tier1 multi-part directory
  ├─ model.lod0.glb / lod1.glb ...  # LOD chain (Tier0)
  └─ *.preview.html                 # --preview-html comparison page (self-contained single file, opens directly in a browser)

Troubleshooting pointers

• Environment problems (WASM load failure / uv missing / low disk) → meshify doctor, or references/troubleshooting.md
• STEP conversion failures / precision tuning → references/cad-step.md
• Per-command parameter detail → references/{simplify,segment,texture,convert,optimize}.md
• Dual-kernel differences and consistency → references/tiering.md; host compatibility → references/support-matrix.md
• Manifest field-level documentation → references/report-schema.md
• Chinese translations (for human readers) → SKILL.zh-CN.md + references/zh-CN/; these English files are the operative copy for the agent