Commands

Global Options

xconvert [OPTIONS] COMMAND [ARGS]...

Option	Description
--license PATH	Path to XVR1 license file (overrides env / default location)
--version	Print version and exit
-v, --verbose	Increase log verbosity (-v = INFO, -vv = DEBUG)
--help	Show help and exit

---

xconvert convert

Convert a 3D file to GLB (or FBX / OBJ / STL).

xconvert convert [OPTIONS] INPUT_FILE

Arguments

Argument	Required	Description
INPUT_FILE	Yes	Path to the source 3D file

Options

Option	Type	Default	Description
-o, --out	path	<input>.glb next to input	Output file path
-f, --format	glb|fbx|obj|stl	glb	Output format
--file-type	cad|mesh|pointcloud	auto-detected	Override file type detection
--optimize / --no-optimize	flag	disabled	Run mesh decimation pass
--target-ratio	float 0.01–1.0	—	Face reduction ratio (used with --optimize)
--rms	float	0.04	RMS quality target as fraction of bounding-box diagonal
--hausdorff	float (µm)	—	Hausdorff tolerance in microns; enables HDB decimation mode
--lods	int 1–3	—	Number of LOD levels to generate alongside the main output
--chunk / --no-chunk	flag	disabled	Spatially chunk output for browser streaming
--chunk-size	float	auto	World-space chunk cube size override
-w, --workers	int	4	CPU worker threads
--work-dir	path	system temp	Temp directory for intermediate files
--json	flag	disabled	Emit newline-delimited JSON progress on stdout
--help	—	—	Show help and exit

Examples

# Basic conversion
xconvert convert assembly.step --out assembly.glb

# With 3 LODs and spatial chunking (for XViewr viewer)
xconvert convert assembly.step --out assembly.glb --lods 3 --chunk

# Aggressive decimation
xconvert convert large.glb --optimize --target-ratio 0.2

# Hausdorff-bounded decimation (preserves geometry within 50µm)
xconvert convert precise.step --hausdorff 50

# CI with JSON progress stream
xconvert convert model.step --json 2>/dev/null

---

xconvert decimate

Decimate an existing GLB into multiple LOD levels.

xconvert decimate [OPTIONS] INPUT_GLB

Arguments

Argument	Required	Description
INPUT_GLB	Yes	Path to source GLB file

Options

Option	Type	Default	Description
-o, --out-dir	path	<input>_decimated/	Output directory
--rms	float	0.04	RMS quality target — lower = higher quality, more faces
--hausdorff	float (µm)	—	Hausdorff tolerance in µm; enables HDB mode instead of RMS
--initial-factor	float	—	Override initial face-count fraction for binary search
-w, --workers	int	4	Parallel worker processes
--json	flag	disabled	Emit newline-delimited JSON progress
--help	—	—	Show help and exit

Output

out-dir/
├── lod0.glb        # Highest quality (binary-search RMS target)
├── lod1.glb        # 75% of lod0 faces
├── lod2.glb        # 15% of lod0 faces
└── lod3.glb        # 4% of lod0 faces

Examples

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

# Tighter quality (fewer faces removed)
xconvert decimate model.glb --rms 0.01 --out-dir model_lods/

---

xconvert chunk

Spatially partition a GLB into browser-streamable chunks with LOD.

xconvert chunk [OPTIONS] INPUT_GLB

Arguments

Argument	Required	Description
INPUT_GLB	Yes	Path to source GLB file

Options

Option	Type	Default	Description
-o, --out-dir	path	<input>_chunks/	Output directory for chunks
--obj-dir	path	—	Pre-built OBJ decimation directory from xconvert decimate; skips re-decimation
--rms	float	0.04	RMS target for auto-decimation (ignored when --obj-dir is supplied)
--min-cubes	int	config default	Minimum number of spatial chunks
--max-cubes	int	config default	Maximum number of spatial chunks
--target-prims	int	config default	Target primitives per chunk
--max-verts	int	config default	Max vertices per chunk
-w, --workers	int	4	Worker threads
--json	flag	disabled	Emit newline-delimited JSON progress
--help	—	—	Show help and exit

Output

out-dir/
├── manifest.json
├── lod0/
│   ├── chunk_0000_lod0.glb
│   ├── chunk_0001_lod0.glb
│   └── ...
└── lod1/
    ├── chunk_0000_lod1.glb
    └── ...

Examples

# Chunk an existing GLB (runs decimation automatically)
xconvert chunk model.glb --out-dir model_chunks/

# Reuse decimation output from a previous decimate run (faster)
xconvert chunk model.glb --obj-dir model_lods/ --out-dir model_chunks/

---

xconvert info

Inspect a 3D file or verify binary tool availability.

xconvert info [OPTIONS] [INPUT_FILE]

Arguments

Argument	Required	Description
INPUT_FILE	No	Path to 3D file to inspect

Options

Option	Description
--json	Output inspection results as JSON
--check-binaries	Report status of bundled native binaries and exit (no file required)
--help	Show help and exit

Examples

# Check all native binaries are present
xconvert info --check-binaries

# Inspect a file
xconvert info model.glb
xconvert info model.step --json

---

JSON Progress Protocol

All commands support --json to emit newline-delimited JSON events on stdout. Logs always go to stderr, keeping the JSON stream clean.

xconvert convert model.step --json

Event types:

type	Fields	Description
start	file, format	Conversion started
progress	stage, progress (0–100), message	Stage update
result	files (list of output paths)	Completed successfully
error	message, code	Failed

Example stream:

{"type":"start","file":"model.step","format":"glb"}
{"type":"progress","stage":"convert","progress":15,"message":"Parsing STEP geometry"}
{"type":"progress","stage":"convert","progress":80,"message":"Exporting GLB"}
{"type":"result","files":["model.glb","model.edges.json"]}

---

Environment Variables

Variable	Description
XVIEWR_LICENSE_KEY	XVR1 token string or path to a .lic file
XCONVERT_XCAD_BIN	Override path to StepParserOCCT binary
XCONVERT_FBX2GLTF_BIN	Override path to FBX2glTF binary
DISPLAY	X display for headless rendering on Linux (set to :99 in Docker)