xeokit Multi-Format Model Converter

An extensible tool for converting 3D models between various formats.

This module provides the ModelConverter class for converting 3D model data between multiple file formats.

Shape

classDiagram
    direction TB
    class ModelConverter {
      +loaders   : Map~id, ModelLoader~
      +exporters : Map~id, ModelExporter~
      +pipelines : Map~id, Pipeline~
      +convert(request) Promise~ModelConverterResult~
    }
    class ModelConverterParams {
      +loaders
      +exporters
      +pipelines
    }
    class ModelConverterRequest {
      +pipeline   : string
      +inputs     : Map
      +outputs    : Map
      +reports?   : Map
    }
    class ModelConverterResult {
      +outputs    : Map
      +inspection? : ModelConverterInspectionReport
      +manifest?   : ModelConverterManifestReport
      +stats?      : ModelConverterStatsReport
    }
    class ModelLoader {
      <<formats>>
    }
    class ModelExporter {
      <<formats>>
    }
    ModelConverter ..> ModelConverterParams : constructor
    ModelConverter ..> ModelConverterRequest : convert
    ModelConverter ..> ModelConverterResult : returns
    ModelConverter "1" *-- "*" ModelLoader
    ModelConverter "1" *-- "*" ModelExporter

Features

• Multi-format ingest — register any ModelLoader (DotBIM, IFC, glTF, LAZ, …) and the converter wires it into the pipeline.
• Multi-format export — same for ModelExporters (XGF, DotBIM, DataModel JSON, …).
• Declarative pipelines — pipelines.X = { inputs, outputs } pre-binds a named conversion (e.g. dotbim2xgf); the runtime resolves which loader / exporter to use from the registered maps.
• Reports — per-conversion inspection (validation findings), manifest (file inventory), and stats (timings, counts, sizes) reports are emitted alongside the outputs for downstream tooling.
• Programmatic API + CLI — same converter wraps inside the xeoconvert CLI binary; use either the class directly in a build pipeline or the binary from a shell script.

Installation

Install the xeokit SDK:

npm install @xeokit/sdk
Copy

Usage

Using the ModelConverter class

The ModelConverter manages conversions using:

• ModelLoaders: parse/ingest input formats into a Scene / Data
• ModelExporters: generate output formats from those models
• Pipelines: declarative workflows connecting inputs to outputs

You configure the converter with ModelConverterParams:

• loaders: a map of loader instances (keyed by id)
• exporters: a map of exporter instances (keyed by id)
• pipelines: a map of pipeline configs (keyed by pipeline id)

Note: outputs and reports in ModelConverterRequest are currently required by the type, but the converter does not automatically write files to disk. The converted file data is returned on ModelConverterResult.outputs, and it’s up to you to persist it (e.g., using fs.writeFile).

Converting a DotBIM file to XGF and DataModelParams JSON

1) Import dependencies

import { readFile, writeFile } from "fs/promises";

import { ModelConverter, type ModelConverterRequest } from "@xeokit/sdk/convert/modelConverter";
import { DotBIMLoader } from "@xeokit/sdk/formats/dotbim";
import { XGFExporter } from "@xeokit/sdk/formats/xgf";
import { DataModelExporter } from "@xeokit/sdk/model/data";
Copy

2) Set up the converter

Create a ModelConverter configured with loaders/exporters and a dotbim2xgf pipeline:

• DotBIMLoader loads .bim
• XGFExporter exports .xgf
• DataModelExporter exports semantic JSON

const modelConverter = new ModelConverter({
  loaders: {
    dotbim: new DotBIMLoader()
  },
  exporters: {
    xgf: new XGFExporter(),
    datamodel: new DataModelExporter()
  },
  pipelines: {
    dotbim2xgf: {
      inputs: {
        dotbim: {
          loader: "dotbim",
          options: {}
        }
      },
      outputs: {
        xgf: {
          exporter: "xgf",
          version: "1.0",
          options: {}
        },
        datamodel: {
          exporter: "datamodel",
          version: "1.0",
          options: {}
        }
      }
    }
  }
});
Copy

3) Perform the conversion

Provide the input via fileData (or use filePath to let the converter read it). Outputs are returned in result.outputs.

const dotBIMFileData = JSON.parse(await readFile("model.bim", "utf-8"));

const request: ModelConverterRequest = {
  pipeline: "dotbim2xgf",
  inputs: {
    dotbim: { fileData: dotBIMFileData }
    // Alternative:
    // dotbim: { filePath: "model.bim" }
  }
};

const result = await modelConverter.convert(request);

const xgfOutput = result.outputs.xgf;
const datamodelOutput = result.outputs.datamodel;

// XGF is typically binary (ArrayBuffer)
await writeFile("model.xgf", xgfOutput.fileData);

// DataModelParams is JSON
await writeFile("model.json", JSON.stringify(datamodelOutput.fileData, null, 2), "utf-8");
Copy

Converting XGF and DataModelParams JSON back to DotBIM

1) Import dependencies

import { readFile, writeFile } from "fs/promises";

import { ModelConverter, type ModelConverterRequest } from "@xeokit/sdk/convert/modelConverter";
import { DotBIMExporter } from "@xeokit/sdk/formats/dotbim";
import { XGFLoader } from "@xeokit/sdk/formats/xgf";
import { DataModelImporter } from "@xeokit/sdk/model/data";
Copy

2) Set up the converter

Configure loaders for XGF + DataModelParams, and a DotBIM exporter:

const modelConverter = new ModelConverter({
  loaders: {
    xgf: new XGFLoader(),
    datamodel: new DataModelImporter()
  },
  exporters: {
    dotbim: new DotBIMExporter()
  },
  pipelines: {
    xgf2dotbim: {
      inputs: {
        xgf: {
          loader: "xgf",
          sceneModel: "mySceneModel",
          options: {}
        },
        datamodel: {
          loader: "datamodel",
          dataModel: "myDataModel",
          options: {}
        }
      },
      outputs: {
        dotbim: {
          exporter: "dotbim",
          sceneModel: "mySceneModel",
          dataModel: "myDataModel",
          version: "1.1",
          options: {}
        }
      }
    }
  }
});
Copy

3) Perform the conversion

const xgfFileData = await readFile("model.xgf");
const datamodelFileData = JSON.parse(await readFile("model.json", "utf-8"));

const request: ModelConverterRequest = {
  pipeline: "xgf2dotbim",
  inputs: {
    xgf: { fileData: xgfFileData },
    datamodel: { fileData: datamodelFileData }
  }
};

const result = await modelConverter.convert(request);

await writeFile("model.bim", result.outputs.dotbim.fileData, "utf-8");
Copy

Advanced usage

Sharing models across multiple inputs and outputs

Use sceneModel / dataModel ids to make multiple inputs populate the same models, and multiple outputs export from those same models.

import type { ModelConverterRequest } from "@xeokit/sdk/convert/modelConverter";

const modelConverter = new ModelConverter({
  loaders: {
    xgf: new XGFLoader(),
    datamodel: new DataModelImporter()
  },
  exporters: {
    xgf: new XGFExporter(),
    datamodel: new DataModelExporter()
  },
  pipelines: {
    roundTripLike: {
      inputs: {
        geom:   { loader: "xgf", sceneModel: "main", dataModel: "main" },
        props:  { loader: "datamodel", dataModel: "main" }
      },
      outputs: {
        outGeom:  { exporter: "xgf", sceneModel: "main", dataModel: "main", version: "1.0" },
        outProps: { exporter: "datamodel", dataModel: "main", version: "1.0" }
      }
    }
  }
});

const request: ModelConverterRequest = {
  pipeline: "roundTripLike",
  inputs: {
    geom:  { filePath: "model.xgf" },
    props: { filePath: "model.json" }
  }
};

const result = await modelConverter.convert(request);

await writeFile("out/model.xgf", result.outputs.outGeom.fileData);
await writeFile("out/model.json", JSON.stringify(result.outputs.outProps.fileData, null, 2), "utf-8");
Copy