Reference Source
public class | source

STLLoaderPlugin

Extends:

Plugin → 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.

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.

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

// Add an STLLoaderPlugin to the Viewer
var plugin = new STLLoaderPlugin(viewer, {
     id: "STLModels"  // Default value
});

// We can also get the plugin by its ID on the Viewer
plugin = viewer.plugins.STLModels;

// 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();

Constructor Summary

Public Constructor
public

constructor(viewer: Viewer, cfg: Object)

Method Summary

Public Methods
public

load(params: *): Entity

Loads an STL model from a file into this STLLoaderPlugin's Viewer.

Inherited Summary

From class Plugin
public

ID for this Plugin, unique within its Viewer.

public

The Viewer that contains this Plugin.

public

Destroys this Plugin and removes it from its Viewer.

public

error(msg: String)

Logs an error message to the JavaScript developer console, prefixed with the ID of this Plugin.

public

fire(event: String, value: Object)

Fires an event at this Plugin.

public

log(msg: String)

Logs a message to the JavaScript developer console, prefixed with the ID of this Plugin.

public

on(event: String, callback: Function)

Subscribes to an event fired at this Plugin.

public

warn(msg: String)

Logs a warning message to the JavaScript developer console, prefixed with the ID of this Plugin.

Public Constructors

public constructor(viewer: Viewer, cfg: Object) source

Creates this Plugin and installs it into the given Viewer.

Override:

Plugin#constructor

Params:

NameTypeAttributeDescription
viewer Viewer

The Viewer.

cfg Object

Plugin configuration.

cfg.id String
  • optional
  • default: "GLTFLoader"

Optional ID for this plugin, so that we can find it within Viewer#plugins.

Public Methods

public load(params: *): Entity source

Loads an STL model from a file into this STLLoaderPlugin's Viewer.

Params:

NameTypeAttributeDescription
params *

Loading parameters.

params.id String

ID to assign to the model's root Entity, unique among all components in the Viewer's Scene.

params.src String

Path to an STL file.

params.edges Boolean
  • optional
  • default: false

Whether or not xeogl renders the model with edges emphasized.

params.position Number[]
  • optional
  • default: [0,0,0]

The model World-space 3D position.

params.scale Number[]
  • optional
  • default: [1,1,1]

The model's World-space scale.

params.rotation Number[]
  • optional
  • default: [0,0,0]

The model's World-space rotation, as Euler angles given in degrees, for each of the X, Y and Z axis.

params.matrix Number[]
  • optional
  • default: [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]

The model's world transform matrix. Overrides the position, scale and rotation parameters.

params.backfaces Boolean
  • optional
  • default: false

When true, allows visible backfaces, wherever specified in the STL. When false, ignores backfaces.

params.smoothNormals Boolean
  • optional
  • default: true

When true, automatically converts face-oriented normals to vertex normals for a smooth appearance.

params.smoothNormalsAngleThreshold Number
  • optional
  • default: 20

When xraying, highlighting, selecting or edging, this is the threshold angle between normals of adjacent triangles, below which their shared wireframe edge is not drawn.

params.edgeThreshold Number
  • optional
  • default: 20

When xraying, highlighting, selecting or edging, this is the threshold angle between normals of adjacent triangles, below which their shared wireframe edge is not drawn.

params.splitMeshes Boolean
  • optional
  • default: true

When true, creates a separate Mesh for each group of faces that share the same vertex colors. Only works with binary STL.

Return:

Entity

Entity representing the model, which will have Entity#isModel set true and will be registered by Entity#id in Scene#models