xeokit Multi-Format File Converter

CLI tool for converting 3D models between various formats.

xeoconvert is a Node.js command-line utility that converts 3D model or data files between formats. Pre-defined pipelines describe how each input file flows into one or more output files; optional inspection / auto-fix passes catch data integrity issues before export.

Wraps the ModelConverter class — same engine, scriptable from a shell.

Tasks

Each run does one of four things. The flags select which; all four share one internal sequence — load, optionally inspect, optionally fix, optionally export.

flowchart LR
    G([Run]) --> C[Convert]
    G --> CO[Convert + optimize]
    G --> V[Validate]
    G --> O[Optimize in place]
    C --> C1[load A] --> C2[export B] --> C3[B]
    CO --> CO1[load A] --> CO2[inspect + fix] --> CO3[export B] --> CO4[B + reports]
    V --> V1[load A] --> V2[inspect] --> V3[reports only]
    O --> O1[load A] --> O2[inspect + fix] --> O3[export A] --> O4[A + reports]

Installation

npm install @xeokit/sdk
Copy

Usage

Two ways to name input and output:

• --in <file> --out <file> — loader and exporter resolved from the file extensions. Covers the single-input/single-output case.
• --pipeline <name> --<inputId> <file> --<outputId> <file> — a registered pipeline for multi-input/output, coordinate-system conversion, or the ambiguous .json formats. The pipeline declares the required ids; the CLI reports which are missing.

Add --log to any command for progress output.

Convert

Load one format, write another.

node xeoconvert.js --in model.glb --out model.xgf
Copy

Multi-output via a named pipeline (geometry to XGF, semantics to a DataModel):

node xeoconvert.js --pipeline ifc2xgf --ifc model.ifc \
  --xgf model.xgf --datamodel model.json
Copy

Some target formats cannot represent every source feature. The --conversion-report reporter records what each exporter dropped or flattened (for example, triplanar textures the format has no projection for):

node xeoconvert.js --in model.xgf --out model.gltf \
  --conversion-report conversion.json
Copy

Convert + optimize

Convert and clean the SceneModel in the same pass. --inspect-fix runs applyFixes before export, so the output is already deduplicated and re-quantised.

node xeoconvert.js --in model.glb --out model.xgf \
  --inspect-fix --inspect-checks all \
  --optimization-report optimization.json --conversion-report conversion.json
Copy

Validate

Load and inspect; write no model file. Omit --out (or use a pipeline with no outputs) and request an inspection report.

node xeoconvert.js --in model.xgf \
  --inspect --inspect-checks all --inspection-report inspection.json
Copy

Inspection runs sceneModelInspector on each loaded SceneModel. Results also surface on ModelConverterResult.inspection.

To gate a conversion on validation, combine --out with --inspect (without --inspect-fix): the export aborts if inspection finds errors, unless --no-fail-on-inspect-errors downgrades the gate to advisory.

Optimize in place

Rewrite a file in its own format with fixes applied. Same in/out extension.

node xeoconvert.js --in model.xgf --out model.xgf \
  --inspect-fix --inspect-checks all --optimization-report optimization.json
Copy

Reference

Pipelines

--pipeline <name> with the listed input/output arg ids. A pipeline with no outputs is validate-only.

Formats by extension

In --in/--out mode the loader and exporter are resolved from the file extension. Same in/out extension is an in-place optimize/validate.

Use --loader / --exporter to override resolution for the ambiguous .json scenemodel/datamodel pair.

Inspection flags

• --inspect — enable inspection. Implied by any other --inspect-* flag.
• --inspect-fix — run applyFixes after inspection (skipped if errors are present).
• --inspect-checks <list> — comma-separated opt-in checks: dup, similar, dense, large, quality, objects, textures, geom-far, all.
• --no-fail-on-inspect-errors — export even when inspection found errors. Default aborts.
• --inspect-async — use inspectSceneModelAsync so very large models don't block.

Configuration flags

Tune which checks and fixes run, or print the effective config. These don't write models.

• --config <file> — full rule config (inspections, optimizations, dataInspections, plugins).
• --inspect-config <file> — inspection overrides only.
• --optimize-config <file> — optimization (fix) overrides only.
• --print-config — print the merged config to stdout and exit.

Report flags

Each writes JSON to the given path; omit the flag to skip the report. A path is required when the flag is present.

• --inspection-report <file> — validation findings.
• --optimization-report <file> — what --inspect-fix changed. Empty unless fixes ran.
• --conversion-report <file> — per-output fidelity (see below).
• --stats-report <file> — sizes, formats, counts.
• --manifest-report <file> — inventory of written files.

Conversion report

Records how faithfully each output was produced. Each output's status is ok (no warnings/errors), lossy (something dropped or flattened) or failed (the export threw). errors entries are tagged with their output, or null for a run-level failure. Exporters surface these via the onWarning export option; currently emitted for triplanar (world-projected) textures the glTF, FBX, USDZ and XKT exporters cannot represent.

The AECMaterials model uses triplanar texturing, which glTF can't represent:

node xeoconvert.js --in AECMaterials/xgf/model.xgf --out AECMaterials.gltf \
  --conversion-report AECMaterials-conversion.json
Copy

AECMaterials-conversion.json:

{
    "summary": {
        "outputs": 1, "ok": 0, "lossy": 1, "failed": 0, "warnings": 1, "errors": 0,
        "byOutput": {
            "out": { "filePath": "AECMaterials.gltf", "fileFormat": "glTF",
                     "fileFormatVersion": "2", "fileDataSizeBytes": 137552, "status": "lossy" }
        }
    },
    "warnings": [
        { "output": "out", "fileFormat": "glTF",
          "message": "[glTF] Dropped 63 texture(s) on 21 material(s): they are sampled via triplanar (world-projected) texturing, which glTF cannot represent — those materials are exported as flat colour. Export to XGF to keep them." }
    ],
    "errors": []
}
Copy

Behaviour

• Output files are written only for the --out / --<outputId> paths supplied; missing directories are created.
• fileDataType sets encoding — json minified, text as-is, binary as a Buffer.
• Exit code is 1 on success, -1 on error.