@xeokit/xeokit-sdk 2.4.0-alpha-81 → 2.4.0-alpha-82

package/src/plugins/AngleMeasurementsPlugin/AngleMeasurementsPlugin.js

@@ -0,0 +1,400 @@
+import {Plugin} from "../../viewer/Plugin.js";
+import {AngleMeasurement} from "./AngleMeasurement.js";
+import {AngleMeasurementsControl} from "./AngleMeasurementsControl.js";
+
+/**
+ * {@link Viewer} plugin for measuring angles.
+ *
+ * [<img src="https://user-images.githubusercontent.com/83100/63641903-61488180-c6b6-11e9-8e00-895b9d16dc4b.gif">](https://xeokit.github.io/xeokit-sdk/examples/#measurements_angle_createWithMouse)
+ *
+ * * [[Example 1: Model with angle measurements](https://xeokit.github.io/xeokit-sdk/examples/#measurements_angle_modelWithMeasurements)]
+ * * [[Example 2: Create angle measurements with mouse](https://xeokit.github.io/xeokit-sdk/examples/#measurements_angle_createWithMouse)]
+ *
+ * ## Overview
+ *
+ * * An {@link AngleMeasurement} shows the angle between two connected 3D line segments, given
+ * as three positions on the surface(s) of one or more {@link Entity}s.
+ * * As shown on the screen capture above, a AngleMeasurement has two wires that show the line segments, with a label that shows the angle between them.
+ * * Create AngleMeasurements programmatically with {@link AngleMeasurementsPlugin#createMeasurement}.
+ * * Create AngleMeasurements interactively using the {@link AngleMeasurementsControl}, located at {@link AngleMeasurementsPlugin#control}.
+ * * Existing AngleMeasurements are registered by ID in {@link AngleMeasurementsPlugin#measurements}.
+ * * Destroy AngleMeasurements using {@link AngleMeasurementsPlugin#destroyMeasurement}.
+ * * Configure global measurement units and scale via {@link Metrics}, located at {@link Scene#metrics}
+ *
+ * ## Example 1: Creating AngleMeasurements Programmatically
+ *
+ * In our first example, we'll use an {@link XKTLoaderPlugin} to load a model, and then use a AngleMeasurementsPlugin to programmatically create two {@link AngleMeasurement}s.
+ *
+ * Note how each AngleMeasurement has ````origin````, ````corner```` and  ````target````, which each indicate a 3D World-space
+ * position on the surface of an {@link Entity}. These can be aon the same Entity, or on different Entitys.
+ *
+ * [[Run example](https://xeokit.github.io/xeokit-sdk/examples/#measurements_angle_modelWithMeasurements)]
+ *
+ * ````JavaScript
+ * import {Viewer, XKTLoaderPlugin, AngleMeasurementsPlugin} from "xeokit-sdk.es.js";
+ *
+ * const viewer = new Viewer({
+ *     canvasId: "myCanvas",
+ *     transparent: true
+ * });
+ *
+ * viewer.scene.camera.eye = [-2.37, 18.97, -26.12];
+ * viewer.scene.camera.look = [10.97, 5.82, -11.22];
+ * viewer.scene.camera.up = [0.36, 0.83, 0.40];
+ *
+ * const xktLoader = new XKTLoaderPlugin(viewer);
+ *
+ * const angleMeasurements = new AngleMeasurementsPlugin(viewer);
+ *
+ * const model = xktLoader.load({
+ *      src: "./models/xkt/duplex/duplex.xkt"
+ * });
+ *
+ * model.on("loaded", () => {
+ *
+ *      const myMeasurement1 = angleMeasurements.createMeasurement({
+ *          id: "myAngleMeasurement1",
+ *          origin: {
+ *              entity: viewer.scene.objects["2O2Fr$t4X7Zf8NOew3FLOH"],
+ *              worldPos: [0.044, 5.998, 17.767]
+ *          },
+ *          corner: {
+ *              entity: viewer.scene.objects["2O2Fr$t4X7Zf8NOew3FLOH"],
+ *              worldPos: [0.044, 5.998, 17.767]
+ *          },
+ *          target: {
+ *              entity: viewer.scene.objects["2O2Fr$t4X7Zf8NOew3FLOH"],
+ *              worldPos: [4.738, 3.172, 17.768]
+ *          },
+ *          visible: true
+ *      });
+ *
+ *      const myMeasurement2 = angleMeasurements.createMeasurement({
+ *          id: "myAngleMeasurement2",
+ *          origin: {
+ *              entity: viewer.scene.objects["2O2Fr$t4X7Zf8NOew3FNr2"],
+ *              worldPos: [0.457, 2.532, 17.766]
+ *          },
+ *          corner: {
+ *              entity: viewer.scene.objects["2O2Fr$t4X7Zf8NOew3FNr2"],
+ *              worldPos: [0.457, 2.532, 17.766]
+ *          },
+ *          target: {
+ *              entity: viewer.scene.objects["1CZILmCaHETO8tf3SgGEXu"],
+ *              worldPos: [0.436, 0.001, 22.135]
+ *          },
+ *          visible: true
+ *      });
+ * });
+ * ````
+ *
+ * ## Example 2: Creating AngleMeasurements Interactively
+ *
+ * In our second example, we'll use an {@link XKTLoaderPlugin} to load a model, then we'll use the AngleMeasurementsPlugin's {@link AngleMeasurementsControl} to interactively create {@link AngleMeasurement}s with mouse or touch input.
+ *
+ * After we've activated the AngleMeasurementsControl, the first click on any {@link Entity} begins constructing a AngleMeasurement, fixing its
+ * origin to that Entity. The next click on any Entity will fix the AngleMeasurement's corner, and the next click after
+ * that will fix its target and complete the AngleMeasurement.
+ *
+ * The AngleMeasurementControl will then wait for the next click on any Entity, to begin constructing
+ * another AngleMeasurement, and so on, until deactivated again.
+ *
+ * [[Run example](https://xeokit.github.io/xeokit-sdk/examples/#measurements_angle_createWithMouse)]
+ *
+ * ````JavaScript
+ * import {Viewer, XKTLoaderPlugin, AngleMeasurementsPlugin} from "xeokit-sdk.es.js";
+ *
+ * const viewer = new Viewer({
+ *     canvasId: "myCanvas",
+ *     transparent: true
+ * });
+ *
+ * viewer.scene.camera.eye = [-2.37, 18.97, -26.12];
+ * viewer.scene.camera.look = [10.97, 5.82, -11.22];
+ * viewer.scene.camera.up = [0.36, 0.83, 0.40];
+ *
+ * const xktLoader = new XKTLoaderPlugin(viewer);
+ *
+ * const angleMeasurements = new AngleMeasurementsPlugin(viewer);
+ *
+ * const model = xktLoader.load({
+ *     src: "./models/xkt/duplex/duplex.xkt"
+ * });
+ *
+ * angleMeasurements.control.activate();  // <------------ Activate the AngleMeasurementsControl
+ * ````
+ *
+ * ## Example 4: Attaching Mouse Handlers
+ *
+ * In our fourth example, we'll attach even handlers to our plugin, to catch when the user
+ * hovers or right-clicks over our measurements.
+ *
+ * [[Run example](https://xeokit.github.io/xeokit-sdk/examples/#measurements_angle_modelWithMeasurements)]
+ *
+ * ````javascript
+ * import {Viewer, XKTLoaderPlugin, AngleMeasurementsPlugin} from "xeokit-sdk.es.js";
+ *
+ * const viewer = new Viewer({
+ *     canvasId: "myCanvas",
+ *     transparent: true
+ * });
+ *
+ * viewer.scene.camera.eye = [-2.37, 18.97, -26.12];
+ * viewer.scene.camera.look = [10.97, 5.82, -11.22];
+ * viewer.scene.camera.up = [0.36, 0.83, 0.40];
+ *
+ * const xktLoader = new XKTLoaderPlugin(viewer);
+ *
+ * const angleMeasurements = new AngleMeasurementsPlugin(viewer);
+ *
+ * angleMeasurements.on("mouseOver", (e) => {
+ *     e.measurement.setHighlighted(true);
+ * });
+ *
+ * angleMeasurements.on("mouseLeave", (e) => {
+ *     e.measurement.setHighlighted(false);
+ * });
+ *
+ * angleMeasurements.on("contextMenu", (e) => {
+ *     // Show context menu
+ *     e.event.preventDefault();
+ * });
+ *
+ * const model = xktLoader.load({
+ *      src: "./models/xkt/duplex/duplex.xkt"
+ * });
+ *
+ * model.on("loaded", () => {
+ *
+ *       angleMeasurementsPlugin.createMeasurement({
+ *             id: "angleMeasurement1",
+ *             origin: {
+ *                 entity: viewer.scene.objects["1CZILmCaHETO8tf3SgGEXu"],
+ *                 worldPos: [0.4158603637281142, 2.5193106917110457, 17.79972838299403]
+ *             },
+ *             corner: {
+ *                 entity: viewer.scene.objects["1CZILmCaHETO8tf3SgGEXu"],
+ *                 worldPos: [0.41857741956197625,0.0987169929481646,17.799763071093395]
+ *             },
+ *             target: {
+ *                 entity: viewer.scene.objects["1CZILmCaHETO8tf3SgGEXu"],
+ *                 worldPos: [5.235526066859247, 0.11580773869801986, 17.824891550941565]
+ *             },
+ *             visible: true
+ *         });
+ *
+ *         angleMeasurementsPlugin.createMeasurement({
+ *             id: "angleMeasurement2",
+ *             origin: {
+ *                 entity: viewer.scene.objects["2O2Fr$t4X7Zf8NOew3FNr2"],
+ *                 worldPos: [-0.00003814187850181838, 5.9996748076205115,17.79996871551525]
+ *             },
+ *             corner: {
+ *                 entity: viewer.scene.objects["2O2Fr$t4X7Zf8NOew3FNqI"],
+ *                 worldPos: [-0.0005214119318139865, 3.1010044228517595, 17.787656604483363]
+ *
+ *             },
+ *             target: {
+ *                 entity: viewer.scene.objects["1s1jVhK8z0pgKYcr9jt7AB"],
+ *                 worldPos: [ 8.380657312957396, 3.1055697628459553, 17.799220108187185]
+ *             },
+ *             visible: true
+ *         });
+ * });
+ * ````
+ */
+class AngleMeasurementsPlugin extends Plugin {
+
+    /**
+     * @constructor
+     * @param {Viewer} viewer The Viewer.
+     * @param {Object} [cfg]  Plugin configuration.
+     * @param {String} [cfg.id="AngleMeasurements"] Optional ID for this plugin, so that we can find it within {@link Viewer#plugins}.
+     * @param {HTMLElement} [cfg.container] Container DOM element for markers and labels. Defaults to ````document.body````.
+     * @param {string} [cfg.defaultColor=null] The default color of the dots, wire and label.
+    * @param {boolean} [cfg.defaultLabelsVisible=true] The default value of {@link AngleMeasurement.labelsVisible}.
+     * @param {number} [cfg.zIndex] If set, the wires, dots and labels will have this zIndex (+1 for dots and +2 for labels).
+    */
+    constructor(viewer, cfg = {}) {
+
+        super("AngleMeasurements", viewer);
+
+        this._container = cfg.container || document.body;
+
+        this._control = new AngleMeasurementsControl(this);
+
+        this._measurements = {};
+
+        this.defaultColor = cfg.defaultColor !== undefined ? cfg.defaultColor : "#00BBFF";
+        this.defaultLabelsVisible = cfg.defaultLabelsVisible !== false;
+        this.zIndex = cfg.zIndex || 10000;
+
+        this._onMouseOver = (event, measurement) => {
+            this.fire("mouseOver", {
+                plugin: this,
+                angleMeasurement: measurement,
+                measurement,
+                event
+            });
+        }
+
+        this._onMouseLeave = (event, measurement) => {
+            this.fire("mouseLeave", {
+                plugin: this,
+                angleMeasurement: measurement,
+                measurement,
+                event
+            });
+        };
+
+        this._onContextMenu = (event, measurement) => {
+            this.fire("contextMenu", {
+                plugin: this,
+                angleMeasurement: measurement,
+                measurement,
+                event
+            });
+        };
+    }
+
+    /**
+     * Gets the plugin's HTML container element, if any.
+     * @returns {*|HTMLElement|HTMLElement}
+     */
+    getContainerElement() {
+        return this._container;
+    }
+
+
+    /**
+     * @private
+     */
+    send(name, value) {
+
+    }
+
+    /**
+     * Gets the {@link AngleMeasurementsControl}, which creates {@link AngleMeasurement}s from user input.
+     *
+     * @type {AngleMeasurementsControl}
+     */
+    get control() {
+        return this._control;
+    }
+
+    /**
+     * Gets the existing {@link AngleMeasurement}s, each mapped to its {@link AngleMeasurement#id}.
+     *
+     * @type {{String:AngleMeasurement}}
+     */
+    get measurements() {
+        return this._measurements;
+    }
+
+    /**
+     * Creates an {@link AngleMeasurement}.
+     *
+     * The AngleMeasurement is then registered by {@link AngleMeasurement#id} in {@link AngleMeasurementsPlugin#measurements}.
+     *
+     * @param {Object} params {@link AngleMeasurement} configuration.
+     * @param {String} params.id Unique ID to assign to {@link AngleMeasurement#id}. The AngleMeasurement will be registered by this in {@link AngleMeasurementsPlugin#measurements} and {@link Scene.components}. Must be unique among all components in the {@link Viewer}.
+     * @param {Number[]} params.origin.worldPos Origin World-space 3D position.
+     * @param {Entity} params.origin.entity Origin Entity.
+     * @param {Number[]} params.corner.worldPos Corner World-space 3D position.
+     * @param {Entity} params.corner.entity Corner Entity.
+     * @param {Number[]} params.target.worldPos Target World-space 3D position.
+     * @param {Entity} params.target.entity Target Entity.
+     * @param {Boolean} [params.visible=true] Whether to initially show the {@link AngleMeasurement}.
+     * @returns {AngleMeasurement} The new {@link AngleMeasurement}.
+     */
+    createMeasurement(params = {}) {
+        if (this.viewer.scene.components[params.id]) {
+            this.error("Viewer scene component with this ID already exists: " + params.id);
+            delete params.id;
+        }
+        const origin = params.origin;
+        const corner = params.corner;
+        const target = params.target;
+        const measurement = new AngleMeasurement(this, {
+            id: params.id,
+            plugin: this,
+            container: this._container,
+            origin: {
+                entity: origin.entity,
+                worldPos: origin.worldPos
+            },
+            corner: {
+                entity: corner.entity,
+                worldPos: corner.worldPos
+            },
+            target: {
+                entity: target.entity,
+                worldPos: target.worldPos
+            },
+
+            visible: params.visible,
+            originVisible: true,
+            originWireVisible: true,
+            cornerVisible: true,
+            targetWireVisible: true,
+            targetVisible: true,
+            onMouseOver: this._onMouseOver,
+            onMouseLeave: this._onMouseLeave,
+            onContextMenu: this._onContextMenu
+        });
+        this._measurements[measurement.id] = measurement;
+        measurement.on("destroyed", () => {
+            delete this._measurements[measurement.id];
+        });
+        this.fire("measurementCreated", measurement);
+        return measurement;
+    }
+
+    /**
+     * Destroys a {@link AngleMeasurement}.
+     *
+     * @param {String} id ID of AngleMeasurement to destroy.
+     */
+    destroyMeasurement(id) {
+        const measurement = this._measurements[id];
+        if (!measurement) {
+            this.log("AngleMeasurement not found: " + id);
+            return;
+        }
+        measurement.destroy();
+        this.fire("measurementDestroyed", measurement);
+    }
+
+    /**
+     * Shows all or hides the angle label of each {@link AngleMeasurement}.
+     *
+     * @param {Boolean} labelsShown Whether or not to show the labels.
+     */
+    setLabelsShown(labelsShown) {
+        for (const [key, measurement] of Object.entries(this.measurements)) {
+            measurement.labelShown = labelsShown;
+        }
+    }
+
+    /**
+     * Destroys all {@link AngleMeasurement}s.
+     */
+    clear() {
+        const ids = Object.keys(this._measurements);
+        for (var i = 0, len = ids.length; i < len; i++) {
+            this.destroyMeasurement(ids[i]);
+        }
+    }
+
+    /**
+     * Destroys this AngleMeasurementsPlugin.
+     *
+     * Destroys all {@link AngleMeasurement}s first.
+     */
+    destroy() {
+        this.clear();
+        super.destroy();
+    }
+}
+
+export {AngleMeasurementsPlugin}

package/src/plugins/AngleMeasurementsPlugin/index.js

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