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.

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 wiring 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/modelconverter";
import { DotBIMLoader } from "@xeokit/sdk/formats/dotbim";
import { XGFExporter } from "@xeokit/sdk/formats/xgf";
import { DataModelParamsExporter } from "@xeokit/sdk/data";
Copy

2) Set up the converter

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

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

const modelConverter = new ModelConverter({
  loaders: {
    dotbim: new DotBIMLoader()
  },
  exporters: {
    xgf: new XGFExporter(),
    datamodel: new DataModelParamsExporter()
  },
  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/modelconverter";
import { DotBIMExporter } from "@xeokit/sdk/formats/dotbim";
import { XGFLoader } from "@xeokit/sdk/formats/xgf";
import { DataModelParamsLoader } from "@xeokit/sdk/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 DataModelParamsLoader()
  },
  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/modelconverter";

const modelConverter = new ModelConverter({
  loaders: {
    xgf: new XGFLoader(),
    datamodel: new DataModelParamsLoader()
  },
  exporters: {
    xgf: new XGFExporter(),
    datamodel: new DataModelParamsExporter()
  },
  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