STLLoaderPlugin

Viewer plugin that loads models from STL files.

Overview

• Creates an Entity representing each model it loads, which will have Entity#isModel set true and will be registered by Entity#id in Scene#models.
• Creates an Entity for each object within the model, which will have Entity#isObject set true and will be registered by Entity#id in Scene#objects.
• When loading, can set the World-space position, scale and rotation of each model within World space, along with initial properties for all the model's Entitys.
• Supports both binary and ASCII formats.
• Supports double-precision vertex positions.
• Supports custom data source configuration.

Smoothing STL Normals

STL models are normally flat-shaded, however providing a smoothNormals parameter when loading gives a smooth appearance. Triangles in STL are disjoint, where each triangle has its own separate vertex positions, normals and (optionally) colors. This means that you can have gaps between triangles in an STL model. Normals for each triangle are perpendicular to the triangle's surface, which gives the model a faceted appearance by default.

The smoothNormals parameter causes the plugin to recalculate the STL normals, so that each normal's direction is the average of the orientations of the triangles adjacent to its vertex. When smoothing, each vertex normal is set to the average of the orientations of all other triangles that have a vertex at the same position, excluding those triangles whose direction deviates from the direction of the vertice's triangle by a threshold given in the smoothNormalsAngleThreshold loading parameter. This makes smoothing robust for hard edges.

Creating Entities for Objects

An STL model is normally a single mesh, however providing a splitMeshes parameter when loading will create a separate object Entity for each group of faces that share the same vertex colors. This option only works with binary STL files.

See the STLLoaderPlugin#load method for more info on loading options.

Usage

In the example below, we'll use an STLLoaderPlugin to load an STL model of a spur gear. When the model has loaded, we'll use the CameraFlightAnimation to fly the Camera to look at boundary of the model. We'll then get the model's Entity from the Scene and highlight the whole model.

• [Run this example]

// Create a xeokit Viewer
const viewer = new Viewer({
     canvasId: "myCanvas"
});

// Add an STLLoaderPlugin to the Viewer
var plugin = new STLLoaderPlugin(viewer);

// Load the STL model
var model = plugin.load({ // Model is an Entity
     id: "myModel",
     src: "./models/stl/binary/spurGear.stl",
     scale: [0.1, 0.1, 0.1],
     rotate: [90, 0, 0],
     translate: [100,0,0],
     edges: true,
     smoothNormals: true,                // Default
     smoothNormalsAngleThreshold: 20,    // Default
     splitMeshes: true                   // Default
});

// When the model has loaded, fit it to view
model.on("loaded", function() { // Model is an Entity
     viewer.cameraFlight.flyTo(model);
});

// Find the model Entity by ID
model = viewer.scene.models["myModel"];

// Update properties of the model Entity
model.highlight = [1,0,0];

// Destroy the model Entity
model.destroy();

Loading from a Pre-Loaded STL File

If we already have our STL file in memory (perhaps pre-loaded, or even generated in-client), then we can just pass that file data straight into the STLLoaderPlugin#load method. In the example below, to show how it's done, we'll pre-load our STL file data, then pass it straight into that method.

• [Run this example]

loadSTL("./models/stl/binary/spurGear.stl", (stlData) =>{

     const model = stlLoader.load({
         id: "myModel",
         stl: stlData,
         smoothNormals: true
     });

     model.on("loaded", () => {
         viewer.cameraFlight.jumpTo(model);
         viewer.scene.on("tick", () => {
             viewer.camera.orbitYaw(0.4);
         })
     });
 })

function loadSTL(src, ok, error) {
    const request = new XMLHttpRequest();
    request.overrideMimeType("application/json");
    request.open('GET', src, true);
    request.responseType = 'arraybuffer';
    request.onreadystatechange = function () {
        if (request.readyState === 4) {
            if (request.status === 200) {
                ok(request.response);
            } else if (error) {
                    error(request.statusText);
            }
        }
    };
    request.send(null);
}

Configuring a Custom Data Source

In the example below, we'll create the STLLoaderPlugin again, this time configuring it with a custom data source object, through which it can load STL files. For this example, our data source just loads them via HTTP, for simplicity. Once we've created the STLLoaderPlugin, we'll load our STL file as before.

• [Run this example]

// Our custom STL data access strategy - implementation happens to be the same as STLDefaultDataSource

class MyDataSource {
     getSTL(src, ok, error) {
         const request = new XMLHttpRequest();
         request.overrideMimeType("application/json");
         request.open('GET', src, true);
         request.responseType = 'arraybuffer';
         request.onreadystatechange = function () {
             if (request.readyState === 4) {
                 if (request.status === 200) {
                     ok(request.response);
                 } else {
                     error(request.statusText);
                 }
             }
         };
         request.send(null);
     }
 }

const stlLoader = new STLLoaderPlugin(viewer, {
     dataSource: new MyDataSource()
 });

// Load the STL model as before
var model = plugin.load({
     id: "myModel",
     src: "./models/stl/binary/spurGear.stl",
     scale: [0.1, 0.1, 0.1],
     rotate: [90, 0, 0],
     translate: [100,0,0],
     edges: true,
     smoothNormals: true,                // Default
     smoothNormalsAngleThreshold: 20,    // Default
     splitMeshes: true                   // Default
});

//...