mtl — Wavefront MTL Loader

Loads Wavefront MTL files into a SceneModel.

Overview

MTLLoader parses MTL files and creates SceneMaterials within a SceneModel.

MTL files define surface appearance for OBJ geometry, including:

• diffuse, ambient, and specular colors
• texture maps (eg. diffuse maps)
• transparency and illumination models

This loader is typically used alongside an OBJLoader that references the same materials.

Shape

classDiagram
    direction TB
    class MTLLoader {
      +format : "MTL"
      +load(params, options?) Promise~void~
    }
    class MTLExporter {
      +format : "MTL"
      +write(params, options?) Promise~string~
    }
    class ModelLoader {
      <<formats>>
    }
    class ModelExporter {
      <<formats>>
    }
    ModelLoader <|-- MTLLoader
    ModelExporter <|-- MTLExporter

Features

• Wavefront MTL — material companion to OBJ.
• Diffuse + ambient + specular — classic Phong material parameters mapped to PBR equivalents in SceneMaterial.
• Texture map support — map_Kd, map_Ks, map_Bump, etc. loaded into matching SceneTextures.

Installation

npm install @xeokit/sdk
Copy

Example: loading an MTL file

import { Scene } from "@xeokit/sdk/model/scene";
import { Viewer } from "@xeokit/sdk/viewing/viewer";
import { WebGLRenderer } from "@xeokit/sdk/viewing/webGLRenderer";
import { ViewController } from "@xeokit/sdk/viewing/viewController";
import { MTLLoader } from "@xeokit/sdk/formats/mtl";

const handleError = (error: string) => {
  console.error(error);
};

// 1) Create scene + viewer
const scene = new Scene();
const viewer = new Viewer({ scene });
new WebGLRenderer({ viewer });

// 2) Create a view
const viewResult = viewer.createView({
  id: "myView",
  elementId: "myCanvas"
});

if (!viewResult.ok) {
  handleError(viewResult.error);
  return;
}

const view = viewResult.value;

// 3) Enable camera control
new ViewController(view, {});

// 4) Create a SceneModel to receive materials
const sceneModelResult = scene.createModel({ id: "myModel" });

if (!sceneModelResult.ok) {
  handleError(sceneModelResult.error);
  return;
}

const sceneModel = sceneModelResult.value;

// 5) Create loader
const mtlLoader = new MTLLoader();

// 6) Load MTL file
fetch("model.mtl")
  .then(r => r.text())
  .then(fileData => {
    return mtlLoader.load({
      fileData,
      sceneModel
    });
  })
  .then(() => {
    // Materials are now available on the SceneModel
  })
  .catch(err => {
    sceneModel.destroy();
    handleError(`Error loading MTL -> ${err}`);
  });
Copy

Notes

• MTL files define materials only, not geometry.
• Typically used together with OBJ loading workflows.
• Materials are attached to the provided SceneModel.