@xeokit/xeokit-sdk 2.5.2-beta-10 → 2.5.2-beta-13

package/src/src/plugins/OBJLoaderPlugin/index.js

@@ -0,0 +1 @@
+export * from "./OBJLoaderPlugin.js";

package/src/src/plugins/STLLoaderPlugin/STLDefaultDataSource.js

@@ -0,0 +1,33 @@
+/**
+ * Default data access strategy for {@link STLLoaderPlugin}.
+ *
+ * This implementation simply loads STL files using XMLHttpRequest.
+ */
+class STLDefaultDataSource {
+
+    /**
+     * Gets STL data.
+     *
+     * @param {String|Number} src Identifies the STL file.
+     * @param {Function} ok Fired on successful loading of the STL file.
+     * @param {Function} error Fired on error while loading the STL file.
+     */
+    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);
+    }
+}
+
+export {STLDefaultDataSource};

package/src/src/plugins/STLLoaderPlugin/STLLoaderPlugin.js

@@ -0,0 +1,274 @@
+import {Node} from "../../viewer/scene/nodes/Node.js";
+import {Plugin} from "../../viewer/Plugin.js";
+import {STLSceneGraphLoader} from "./STLSceneGraphLoader.js";
+import {utils} from "../../viewer/scene/utils.js";
+import {STLDefaultDataSource} from "./STLDefaultDataSource.js";
+
+/**
+ * {@link Viewer} plugin that loads models from <a href="https://en.wikipedia.org/wiki/STL_(file_format)">STL</a> files.
+ *
+ * ## Overview
+ *
+ * * Creates an {@link Entity} representing each model it loads, which will have {@link Entity#isModel} set ````true```` and will be registered by {@link Entity#id} in {@link Scene#models}.
+ * * Creates an {@link Entity} for each object within the model, which will have {@link Entity#isObject} set ````true```` and will be registered by {@link Entity#id} in {@link 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 {@link Entity}s.
+ * * 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 {@link Entity} for each group of faces that share the same vertex colors. This option
+ * only works with binary STL files.
+ *
+ * See the {@link 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 {@link CameraFlightAnimation} to fly the {@link Camera} to look at boundary of the model. We'll
+ * then get the model's {@link Entity} from the {@link Scene} and highlight the whole model.
+ *
+ *  * [[Run this example](https://xeokit.github.io/xeokit-sdk/examples/#loading_STL_SpurGear)]
+ *
+ * ````javascript
+ * // 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 {@link 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](https://xeokit.github.io/xeokit-sdk/examples/#loading_STL_dataAsParam)]
+ *
+ * ````javascript
+ * 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](https://xeokit.github.io/xeokit-sdk/examples/#loading_STL_dataSource)]
+ *
+ * ````javascript
+ * // 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
+ * });
+ *
+ * //...
+ *````
+ *
+ * @class STLLoaderPlugin
+ */
+class STLLoaderPlugin extends Plugin {
+
+    /**
+     * @constructor
+     *
+     * @param {Viewer} viewer The Viewer.
+     * @param {Object} [cfg]  Plugin configuration.
+     * @param {String} [cfg.id="STLLoader"] Optional ID for this plugin, so that we can find it within {@link Viewer#plugins}.
+     * @param {Object} [cfg.dataSource] A custom data source through which the STLLoaderPlugin can load STL files. Defaults to an instance of {@link STLDefaultDataSource}, which loads over HTTP.
+     */
+    constructor(viewer, cfg = {}) {
+
+        super("STLLoader", viewer, cfg);
+
+        /**
+         * @private
+         */
+        this._sceneGraphLoader = new STLSceneGraphLoader();
+
+        this.dataSource = cfg.dataSource;
+    }
+
+    /**
+     * Sets a custom data source through which the STLLoaderPlugin can load STL files.
+     *
+     * Default value is {@link STLDefaultDataSource}, which loads via an XMLHttpRequest.
+     *
+     * @type {Object}
+     */
+    set dataSource(value) {
+        this._dataSource = value || new STLDefaultDataSource();
+    }
+
+    /**
+     * Gets the custom data source through which the STLLoaderPlugin can load STL files.
+     *
+     * Default value is {@link STLDefaultDataSource}, which loads via an XMLHttpRequest.
+     *
+     * @type {Object}
+     */
+    get dataSource() {
+        return this._dataSource;
+    }
+
+    /**
+     * Loads an STL model from a file into this STLLoaderPlugin's {@link Viewer}.
+     *
+     * @param {*} params Loading parameters.
+     * @param {String} params.id ID to assign to the model's root {@link Entity}, unique among all components in the Viewer's {@link Scene}.
+     * @param {String} [params.src] Path to an STL file. Overrides the ````stl```` parameter.
+     * @param {String} [params.stl] Contents of an STL file, either binary of ASCII. Overridden by the ````src```` parameter.
+     * @param {Boolean} [params.edges=false] Whether or not to renders the model with edges emphasized.
+     * @param {Number[]} [params.origin=[0,0,0]] The model's World-space double-precision 3D origin. Use this to position the model within xeokit's World coordinate system, using double-precision coordinates.
+     * @param {Number[]} [params.position=[0,0,0]] The model single-precision 3D position, relative to the ````origin```` parameter.
+     * @param {Number[]} [params.scale=[1,1,1]] The model's scale.
+     * @param {Number[]} [params.rotation=[0,0,0]] The model's orientation, given as Euler angles in degrees, for each of the X, Y and Z axis.
+     * @param {Number[]} [params.matrix=[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. Relative to ````origin````.
+     * @param {Boolean} [params.backfaces=false] When true, allows visible backfaces, wherever specified in the STL.  When false, ignores backfaces.
+     * @param {Boolean} [params.smoothNormals=true] When true, automatically converts face-oriented normals to vertex normals for a smooth appearance.
+     * @param {Number} [params.smoothNormalsAngleThreshold=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.
+     * @param {Number} [params.edgeThreshold=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.
+     * @param {Boolean} [params.splitMeshes=true] When true, creates a separate {@link Mesh} for each group of faces that share the same vertex colors. Only works with binary STL.
+     * @returns {Entity} Entity representing the model, which will have {@link Entity#isModel} set ````true```` and will be registered by {@link Entity#id} in {@link Scene#models}
+     */
+    load(params) {
+
+        if (params.id && this.viewer.scene.components[params.id]) {
+            this.error("Component with this ID already exists in viewer: " + params.id + " - will autogenerate this ID");
+            delete params.id;
+        }
+
+        const modelNode = new Node(this.viewer.scene, utils.apply(params, {
+            isModel: true
+        }));
+
+        const src = params.src;
+        const stl = params.stl;
+
+        if (!src && !stl) {
+            this.error("load() param expected: either 'src' or 'stl'");
+            return modelNode;
+        }
+
+        if (src) {
+            this._sceneGraphLoader.load(this, modelNode, src, params);
+        } else {
+            this._sceneGraphLoader.parse(this, modelNode, stl, params);
+        }
+
+        return modelNode;
+    }
+}
+
+
+export {STLLoaderPlugin}

package/src/src/plugins/STLLoaderPlugin/STLSceneGraphLoader.js

@@ -0,0 +1,313 @@
+import {Mesh} from "../../viewer/scene/mesh/Mesh.js";
+import {ReadableGeometry} from "../../viewer/scene/geometry/ReadableGeometry.js";
+import {MetallicMaterial} from "../../viewer/scene/materials/MetallicMaterial.js";
+import {math} from "../../viewer/scene/math/math.js";
+import {worldToRTCPositions} from "../../viewer/scene/math/rtcCoords.js";
+import {core} from "../../viewer/scene/core.js";
+
+const tempVec3a = math.vec3();
+
+/**
+ * @private
+ */
+class STLSceneGraphLoader {
+
+    load(plugin, modelNode, src, options, ok, error) {
+
+        options = options || {};
+
+        const spinner = plugin.viewer.scene.canvas.spinner;
+        spinner.processes++;
+
+        plugin.dataSource.getSTL(src, function (data) { // OK
+                parse(plugin, modelNode, data, options);
+                try {
+                    const binData = ensureBinary(data);
+                    if (isBinary(binData)) {
+                        parseBinary(plugin, binData, modelNode, options);
+                    } else {
+                        parseASCII(plugin, ensureString(data), modelNode, options);
+                    }
+                    spinner.processes--;
+                    core.scheduleTask(function () {
+                        modelNode.fire("loaded", true, false);
+                    });
+                    if (ok) {
+                        ok();
+                    }
+                } catch (e) {
+                    spinner.processes--;
+                    plugin.error(e);
+                    if (error) {
+                        error(e);
+                    }
+                    modelNode.fire("error", e);
+                }
+            },
+            function (msg) {
+                spinner.processes--;
+                plugin.error(msg);
+                if (error) {
+                    error(msg);
+                }
+                modelNode.fire("error", msg);
+            });
+    }
+
+    parse(plugin, modelNode, data, options) {
+        const spinner = plugin.viewer.scene.canvas.spinner;
+        spinner.processes++;
+        try {
+            const binData = ensureBinary(data);
+            if (isBinary(binData)) {
+                parseBinary(plugin, binData, modelNode, options);
+            } else {
+                parseASCII(plugin, ensureString(data), modelNode, options);
+            }
+            spinner.processes--;
+            core.scheduleTask(function () {
+                modelNode.fire("loaded", true, false);
+            });
+        } catch (e) {
+            spinner.processes--;
+            modelNode.fire("error", e);
+        }
+    }
+}
+
+function parse(plugin, modelNode, data, options) {
+    try {
+        const binData = ensureBinary(data);
+        if (isBinary(binData)) {
+            parseBinary(plugin, binData, modelNode, options);
+        } else {
+            parseASCII(plugin, ensureString(data), modelNode, options);
+        }
+    } catch (e) {
+        modelNode.fire("error", e);
+    }
+}
+
+function isBinary(data) {
+    const reader = new DataView(data);
+    const numFaces = reader.getUint32(80, true);
+    const faceSize = (32 / 8 * 3) + ((32 / 8 * 3) * 3) + (16 / 8);
+    const numExpectedBytes = 80 + (32 / 8) + (numFaces * faceSize);
+    if (numExpectedBytes === reader.byteLength) {
+        return true;
+    }
+    const solid = [115, 111, 108, 105, 100];
+    for (var i = 0; i < 5; i++) {
+        if (solid[i] !== reader.getUint8(i, false)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+function parseBinary(plugin, data, modelNode, options) {
+    const reader = new DataView(data);
+    const faces = reader.getUint32(80, true);
+    let r;
+    let g;
+    let b;
+    let hasColors = false;
+    let colors;
+    let defaultR;
+    let defaultG;
+    let defaultB;
+    let lastR = null;
+    let lastG = null;
+    let lastB = null;
+    let newMesh = false;
+    let alpha;
+    for (let index = 0; index < 80 - 10; index++) {
+        if ((reader.getUint32(index, false) === 0x434F4C4F /*COLO*/) &&
+            (reader.getUint8(index + 4) === 0x52 /*'R'*/) &&
+            (reader.getUint8(index + 5) === 0x3D /*'='*/)) {
+            hasColors = true;
+            colors = [];
+            defaultR = reader.getUint8(index + 6) / 255;
+            defaultG = reader.getUint8(index + 7) / 255;
+            defaultB = reader.getUint8(index + 8) / 255;
+            alpha = reader.getUint8(index + 9) / 255;
+        }
+    }
+    const material = new MetallicMaterial(modelNode, { // Share material with all meshes
+        roughness: 0.5
+    });
+    // var material = new PhongMaterial(modelNode, { // Share material with all meshes
+    //     diffuse: [0.4, 0.4, 0.4],
+    //     reflectivity: 1,
+    //     specular: [0.5, 0.5, 1.0]
+    // });
+    let dataOffset = 84;
+    let faceLength = 12 * 4 + 2;
+    let positions = [];
+    let normals = [];
+    let splitMeshes = options.splitMeshes;
+    for (let face = 0; face < faces; face++) {
+        let start = dataOffset + face * faceLength;
+        let normalX = reader.getFloat32(start, true);
+        let normalY = reader.getFloat32(start + 4, true);
+        let normalZ = reader.getFloat32(start + 8, true);
+        if (hasColors) {
+            let packedColor = reader.getUint16(start + 48, true);
+            if ((packedColor & 0x8000) === 0) {
+                r = (packedColor & 0x1F) / 31;
+                g = ((packedColor >> 5) & 0x1F) / 31;
+                b = ((packedColor >> 10) & 0x1F) / 31;
+            } else {
+                r = defaultR;
+                g = defaultG;
+                b = defaultB;
+            }
+            if (splitMeshes && r !== lastR || g !== lastG || b !== lastB) {
+                if (lastR !== null) {
+                    newMesh = true;
+                }
+                lastR = r;
+                lastG = g;
+                lastB = b;
+            }
+        }
+        for (let i = 1; i <= 3; i++) {
+            let vertexstart = start + i * 12;
+            positions.push(reader.getFloat32(vertexstart, true));
+            positions.push(reader.getFloat32(vertexstart + 4, true));
+            positions.push(reader.getFloat32(vertexstart + 8, true));
+            normals.push(normalX, normalY, normalZ);
+            if (hasColors) {
+                colors.push(r, g, b, 1); // TODO: handle alpha
+            }
+        }
+        if (splitMeshes && newMesh) {
+            addMesh(modelNode, positions, normals, colors, material, options);
+            positions = [];
+            normals = [];
+            colors = colors ? [] : null;
+            newMesh = false;
+        }
+    }
+    if (positions.length > 0) {
+        addMesh(modelNode, positions, normals, colors, material, options);
+    }
+}
+
+function parseASCII(plugin, data, modelNode, options) {
+    const faceRegex = /facet([\s\S]*?)endfacet/g;
+    let faceCounter = 0;
+    const floatRegex = /[\s]+([+-]?(?:\d+.\d+|\d+.|\d+|.\d+)(?:[eE][+-]?\d+)?)/.source;
+    const vertexRegex = new RegExp('vertex' + floatRegex + floatRegex + floatRegex, 'g');
+    const normalRegex = new RegExp('normal' + floatRegex + floatRegex + floatRegex, 'g');
+    const positions = [];
+    const normals = [];
+    const colors = null;
+    let normalx;
+    let normaly;
+    let normalz;
+    let result;
+    let verticesPerFace;
+    let normalsPerFace;
+    let text;
+    while ((result = faceRegex.exec(data)) !== null) {
+        verticesPerFace = 0;
+        normalsPerFace = 0;
+        text = result[0];
+        while ((result = normalRegex.exec(text)) !== null) {
+            normalx = parseFloat(result[1]);
+            normaly = parseFloat(result[2]);
+            normalz = parseFloat(result[3]);
+            normalsPerFace++;
+        }
+        while ((result = vertexRegex.exec(text)) !== null) {
+            positions.push(parseFloat(result[1]), parseFloat(result[2]), parseFloat(result[3]));
+            normals.push(normalx, normaly, normalz);
+            verticesPerFace++;
+        }
+        if (normalsPerFace !== 1) {
+            plugin.error("Error in normal of face " + faceCounter);
+        }
+        if (verticesPerFace !== 3) {
+            plugin.error("Error in positions of face " + faceCounter);
+        }
+        faceCounter++;
+    }
+    const material = new MetallicMaterial(modelNode, {
+        roughness: 0.5
+    });
+    // var material = new PhongMaterial(modelNode, {
+    //     diffuse: [0.4, 0.4, 0.4],
+    //     reflectivity: 1,
+    //     specular: [0.5, 0.5, 1.0]
+    // });
+    addMesh(modelNode, positions, normals, colors, material, options);
+}
+
+function addMesh(modelNode, positions, normals, colors, material, options) {
+
+    const indices = new Int32Array(positions.length / 3);
+    for (let ni = 0, len = indices.length; ni < len; ni++) {
+        indices[ni] = ni;
+    }
+
+    normals = normals && normals.length > 0 ? normals : null;
+    colors = colors && colors.length > 0 ? colors : null;
+
+    if (options.smoothNormals) {
+        math.faceToVertexNormals(positions, normals, options);
+    }
+
+    const origin = tempVec3a;
+
+    worldToRTCPositions(positions, positions, origin);
+
+    const geometry = new ReadableGeometry(modelNode, {
+        primitive: "triangles",
+        positions: positions,
+        normals: normals,
+        colors: colors,
+        indices: indices
+    });
+
+    const mesh = new Mesh(modelNode, {
+        origin: (origin[0] !== 0 || origin[1] !== 0 || origin[2] !== 0) ? origin : null,
+        geometry: geometry,
+        material: material,
+        edges: options.edges
+    });
+
+    modelNode.addChild(mesh);
+}
+
+function ensureString(buffer) {
+    if (typeof buffer !== 'string') {
+        return decodeText(new Uint8Array(buffer));
+    }
+    return buffer;
+}
+
+function ensureBinary(buffer) {
+    if (typeof buffer === 'string') {
+        const arrayBuffer = new Uint8Array(buffer.length);
+        for (let i = 0; i < buffer.length; i++) {
+            arrayBuffer[i] = buffer.charCodeAt(i) & 0xff; // implicitly assumes little-endian
+        }
+        return arrayBuffer.buffer || arrayBuffer;
+    } else {
+        return buffer;
+    }
+}
+
+function decodeText(array) {
+    if (typeof TextDecoder !== 'undefined') {
+        return new TextDecoder().decode(array);
+    }
+    let s = '';
+    for (let i = 0, il = array.length; i < il; i++) {
+        s += String.fromCharCode(array[i]); // Implicitly assumes little-endian.
+    }
+    return decodeURIComponent(escape(s));
+}
+
+export {STLSceneGraphLoader}

package/src/src/plugins/STLLoaderPlugin/index.js

@@ -0,0 +1,2 @@
+export * from "./STLDefaultDataSource.js";
+export * from "./STLLoaderPlugin.js";