Quick Start

This page shows the most common workflows. See Commands for full option reference.

---

Convert a CAD file to GLB

# Linux
xconvert convert model.step --out model.glb

# Windows
xconvert convert "C:\Models\assembly.STEP" --out "C:\Models\assembly.glb"

Output: model.glb and model.edges.json (edge lines for the viewer).

---

Convert with optimization (LODs + chunking)

For large models intended for the XViewr browser viewer, generate LOD levels and spatially chunk the output. When --chunk is combined with GLB output, one of --rms or --hausdorff is required.

xconvert convert model.step \
  --out model.glb \
  --lods 3 \
  --chunk \
  --rms 0.04

Output:

output/
├── model.glb                # Full-quality GLB
└── chunks/
    ├── manifest.json
    ├── lod0/
    │   ├── chunk_0000_lod0.glb
    │   └── ...
    └── lod1/
        └── ...

---

Decimate an existing GLB

decimate produces a two-tier set (lod0.glb + lod1.glb) plus per-primitive OBJ intermediates that chunk can reuse. Pass --rms for an RMS budget or --hausdorff for geometric-error-bounded decimation.

xconvert decimate model.glb --out-dir model_lods/ --rms 0.04

---

Chunk an existing GLB

xconvert chunk model.glb --out-dir model_chunks/ --rms 0.04

# Reuse a prior `decimate` run to skip re-decimation
xconvert chunk model.glb --obj-dir model_lods/ --out-dir model_chunks/

---

Bulk-convert a folder of mesh parts

Use batch when you have a directory of individual parts (STL/OBJ/PLY) and want paired <part>_lod0.glb + <part>_lod1.glb outputs and a manifest.

# LOD0 exact original, LOD1 at ~55% (class-scaled)
xconvert batch ./parts/ --model-units mm

# HDB-bounded LOD0 + tight LOD1
xconvert batch ./parts/ --lod0-hausdorff 100 --lod1-ratio 0.25 --model-units mm

---

Check tool and binary status

xconvert info --check-binaries

---

Inspect a 3D file

xconvert info model.glb
xconvert info model.step --json   # machine-readable output

---

CI / automation (JSON progress)

Use --json to receive newline-delimited progress events on stdout:

xconvert convert model.step --json | while read line; do
  echo "$line" | python3 -c "import sys,json; m=json.load(sys.stdin); print(m['type'], m.get('progress',''))"
done

Progress event types: start, progress, result, error.

---

Docker quick-start

docker run --rm \
  -v "$(pwd)/models:/data" \
  optellix/xconvert:latest \
  xconvert convert /data/model.step --out /data/model.glb --lods 3 --chunk