Source: hws.edu-examples/trackball-rotator.js

  1. /**
  2.  * @file
  3.  *
  4.  * Summary.
  5.  *
  6.  * <p>The TrackballRotator class implements an <a href="/WebGL/labs/WebGL/extras/doc/Arcball.pdf">ArcBall</a> like interface.</p>
  7.  * Create by {@link https://dl.acm.org/profile/81100026146 Ken Shoemake} in 1992,
  8.  * it is the de facto <a href="/WebGL/labs/WebGL/extras/doc/shoemake92-arcball.pdf">standard</a>
  9.  * for interactive 3D model manipulation and visualization.
  10.  * <p>The class defines the following methods for an object rotator of type TrackballRotator:</p>
  11.  * <ul>
  12.  *    <li>{@link TrackballRotator#getViewMatrix}() <br>
  13.  *        Returns the view transformation matrix as a regular JavaScript
  14.  *        array of 16 elements, in {@link https://en.wikipedia.org/wiki/Row-_and_column-major_order column-major} order,
  15.  *        suitable for use with
  16.  *        {@link https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/uniformMatrix gl.uniformMatrix4fv}
  17.  *        or for further transformation with the {@link https://glmatrix.net glMatrix} library {@link mat4} class.</li>
  18.  *    <li>{@link TrackballRotator#setViewMatrix}(matrix) <br>
  19.  *        Sets the view matrix.
  20.  *    <li>{@link TrackballRotator#setView}(viewDistance, viewpointDirection, viewUp) <br>
  21.  *        Sets up the view, where the
  22.  *        parameters are optional and are used in the same way as the corresponding parameters
  23.  *        in the constructor.</li>
  24.  *    <li>{@link TrackballRotator#setViewDistance}(viewDistance) <br>
  25.  *        Sets the distance of the viewer from the origin without
  26.  *        changing the direction of view. <br>
  27.  *        The parameter must be a positive number.
  28.  *    <li>{@link TrackballRotator#getViewDistance}() <br>
  29.  *        Returns the current value.</li>
  30.  *    <li>{@link TrackballRotator#setRotationCenter}(vector) <br>
  31.  *        Sets the center of rotation. <br>
  32.  *        The parameter must be an array of (at least) three numbers.
  33.  *        The view is rotated about this point. <br>
  34.  *        Usually, you want the rotation center to be the point that
  35.  *        appears at the middle of the canvas, but that is not a requirement. <br>
  36.  *        The initial value is effectively equal to [0,0,0].</li>
  37.  *    <li>{@link TrackballRotator#getRotationCenter}() <br>
  38.  *        Returns the current value.</li>
  39.  * </ul>
  40.  *
  41.  * @since 19/11/2022
  42.  * @author David J. Eck and modified by Paulo Roma
  43.  * @see <a href="/WebGL/hws.edu-examples/trackball-rotator.js">source</a>
  44.  * @see https://math.hws.edu/graphicsbook/source/webgl/cube-with-trackball-rotator.html
  45.  * @see https://math.hws.edu/graphicsbook/source/webgl/trackball-rotator.js
  46.  * @see https://math.hws.edu/graphicsbook/source/webgl/skybox-and-env-map.html
  47.  * @see <img src="/WebGL/lib/arcball4.png" width="256">
  48.  */
  50. /**
  51.  * <p>An object of type TrackballRotator can be used to implement a
  52.  * {@link https://www.xarg.org/2021/07/trackball-rotation-using-quaternions/ trackball}-like mouse rotation
  53.  * of a WebGL scene about the origin. </p>
  54.  *
  55.  * Only the first parameter to the constructor is required.
  56.  * When an object is created, mouse event handlers are set up on the canvas to respond to rotation.<br>
  57.  * It will also work with a touchscreen.
  58.  */
  59. class TrackballRotator {
  60.     /**
  61.      * <p>Constructor of TrackballRotator.</p>
  62.      * @param {HTMLCanvasElement} canvas the HTML canvas element used for WebGL drawing.
  63.      *    The user will rotate the scene by dragging the mouse on this canvas.
  64.      *    This parameter is required.
  65.      * @param {function} callback if present must be a function, which is called whenever the rotation changes.
  66.      *    It is typically the function that draws the scene.
  67.      * @param {Number} viewDistance if present must be a positive number. Gives the distance of the viewer
  68.      *    from the origin. If not present, the length is zero, which can be OK for orthographic projection,
  69.      *    but never for perspective projection.
  70.      * @param {Array<Number>} viewpointDirection if present must be an array of three numbers, not all zero.
  71.      *    The view is from the direction of this vector towards the origin (0,0,0). If not present,
  72.      *    the value [0,0,10] is used. This is just the initial value for viewpointDirection; it will
  73.      *    be modified by rotation.
  74.      * @param {Array<Number>} viewUp if present must be an array of three numbers. Gives a vector that will
  75.      *    be seen as pointing upwards in the view. If not present, the value is [0,1,0].
  76.      *    Cannot be a multiple of viewpointDirection. This is just the initial value for
  77.      *    viewUp; it will be modified by rotation.
  78.      */
  79.     constructor(canvas, callback, viewDistance, viewpointDirection, viewUp) {
  80.         var unitx = new Array(3);
  81.         var unity = new Array(3);
  82.         var unitz = new Array(3);
  84.         /**
  85.          * View distance, that is, the z-coord in eye coordinates.
  86.          * @type {Number}
  87.          */
  88.         var viewZ;
  90.         /**
  91.          * <p>Center of view and rotation is about this point.</p>
  92.          * Default is [0,0,0].
  93.          * @type {Array<Number>}
  94.          */
  95.         var center;
  97.         /**
  98.          * Set up the view, where the parameters are optional,
  99.          * and are used in the same way, <br>
  100.          * as the corresponding parameters in the constructor.
  101.          * @param {Number} viewDistance distance of the viewer from the origin.
  102.          * @param {Array<Number>} viewpointDirection direction of view is from this point towards the origin (0,0,0).
  103.          * @param {Array<Number>} viewUp view up vector.
  104.          */
  105.         this.setView = function (viewDistance, viewpointDirection, viewUp) {
  106.             unitz =
  107.                 viewpointDirection === undefined
  108.                     ? [0, 0, 10]
  109.                     : viewpointDirection;
  110.             viewUp = viewUp === undefined ? [0, 1, 0] : viewUp;
  111.             viewZ = viewDistance;
  112.             normalize(unitz, unitz);
  113.             copy(unity, unitz);
  114.             scale(unity, unity, dot(unitz, viewUp));
  115.             subtract(unity, viewUp, unity);
  116.             normalize(unity, unity);
  117.             cross(unitx, unity, unitz);
  118.         };
  120.         /**
  121.          * Returns the view transformation matrix as a regular JavaScript
  122.          * array of 16 elements, in column-major order, <br>
  123.          * suitable for use with
  124.          * {@link https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/uniformMatrix gl.uniformMatrix4fv}
  125.          * or, for further transformation, with the glMatrix library {@link https://glmatrix.net/docs/module-mat4.html mat4} class.
  126.          * @return {Array<Number>} view matrix.
  127.          */
  128.         this.getViewMatrix = function () {
  129.             var mat = [
  130.                 unitx[0],
  131.                 unity[0],
  132.                 unitz[0],
  133.                 0,
  134.                 unitx[1],
  135.                 unity[1],
  136.                 unitz[1],
  137.                 0,
  138.                 unitx[2],
  139.                 unity[2],
  140.                 unitz[2],
  141.                 0,
  142.                 0,
  143.                 0,
  144.                 0,
  145.                 1,
  146.             ];
  147.             if (center !== undefined) {
  148.                 // multiply on left by translation by rotationCenter, on right by translation by -rotationCenter
  149.                 var t0 =
  150.                     center[0] -
  151.                     mat[0] * center[0] -
  152.                     mat[4] * center[1] -
  153.                     mat[8] * center[2];
  154.                 var t1 =
  155.                     center[1] -
  156.                     mat[1] * center[0] -
  157.                     mat[5] * center[1] -
  158.                     mat[9] * center[2];
  159.                 var t2 =
  160.                     center[2] -
  161.                     mat[2] * center[0] -
  162.                     mat[6] * center[1] -
  163.                     mat[10] * center[2];
  164.                 mat[12] = t0;
  165.                 mat[13] = t1;
  166.                 mat[14] = t2;
  167.             }
  168.             if (viewZ !== undefined) {
  169.                 mat[14] -= viewZ;
  170.             }
  171.             return mat;
  172.         };
  174.         /**
  175.          * Sets the view matrix.
  176.          * @param {Float32Array} matrix view matrix.
  177.          */
  178.         this.setViewMatrix = function (matrix) {
  179.             unitx[0] = matrix[0];
  180.             unity[0] = matrix[1];
  181.             unitz[0] = matrix[2];
  182.             unitx[1] = matrix[4];
  183.             unity[1] = matrix[5];
  184.             unitz[1] = matrix[6];
  185.             unitx[2] = matrix[8];
  186.             unity[2] = matrix[9];
  187.             unitz[2] = matrix[10];
  188.         };
  190.         /**
  191.          * Returns the viewDistance.
  192.          * @return {Number} view distance.
  193.          */
  194.         this.getViewDistance = function () {
  195.             return viewZ;
  196.         };
  198.         /**
  199.          * Sets the distance of the viewer from the origin without
  200.          * changing the direction of view. <br>
  201.          * The parameter must be a positive number.
  202.          * @param {Number} viewDistance view distance.
  203.          */
  204.         this.setViewDistance = function (viewDistance) {
  205.             viewZ = viewDistance;
  206.         };
  208.         /**
  209.          * Returns the current rotation center.
  210.          * @returns {Array<Number>} center or [0,0,0], if undefined.
  211.          */
  212.         this.getRotationCenter = function () {
  213.             return center === undefined ? [0, 0, 0] : center;
  214.         };
  216.         /**
  217.          * <p>Sets the center of rotation.</p>
  218.          * The parameter must be an array of (at least) three numbers.
  219.          * The view is rotated about this point.
  220.          * <p>Usually, you want the rotation center to be the point that appears
  221.          * at the middle of the canvas, but that is not a requirement.</p>
  222.          * The initial value is effectively equal to [0,0,0].
  223.          * @param {Array<Number>} rotationCenter center of rotation.
  224.          */
  225.         this.setRotationCenter = function (rotationCenter) {
  226.             center = rotationCenter;
  227.         };
  229.         this.setView(viewDistance, viewpointDirection, viewUp);
  230.         canvas.addEventListener("mousedown", doMouseDown, false);
  231.         canvas.addEventListener("touchstart", doTouchStart, false);
  233.         function applyTransvection(e1, e2) {
  234.             // rotate vector e1 onto e2
  235.             function reflectInAxis(axis, source, destination) {
  236.                 var s =
  237.                     2 *
  238.                     (axis[0] * source[0] +
  239.                         axis[1] * source[1] +
  240.                         axis[2] * source[2]);
  241.                 destination[0] = s * axis[0] - source[0];
  242.                 destination[1] = s * axis[1] - source[1];
  243.                 destination[2] = s * axis[2] - source[2];
  244.             }
  245.             normalize(e1, e1);
  246.             normalize(e2, e2);
  247.             var e = [0, 0, 0];
  248.             add(e, e1, e2);
  249.             normalize(e, e);
  250.             var temp = [0, 0, 0];
  251.             reflectInAxis(e, unitz, temp);
  252.             reflectInAxis(e1, temp, unitz);
  253.             reflectInAxis(e, unitx, temp);
  254.             reflectInAxis(e1, temp, unitx);
  255.             reflectInAxis(e, unity, temp);
  256.             reflectInAxis(e1, temp, unity);
  257.         }
  259.         var centerX, centerY, radius2;
  260.         var prevx, prevy;
  261.         var dragging = false;
  262.         var touchStarted = false;
  264.         function doMouseDown(evt) {
  265.             if (dragging) return;
  266.             dragging = true;
  267.             centerX = canvas.width / 2;
  268.             centerY = canvas.height / 2;
  269.             var radius = Math.min(centerX, centerY);
  270.             radius2 = radius * radius;
  271.             document.addEventListener("mousemove", doMouseDrag, false);
  272.             document.addEventListener("mouseup", doMouseUp, false);
  273.             var box = canvas.getBoundingClientRect();
  274.             prevx = evt.clientX - box.left;
  275.             prevy = evt.clientY - box.top;
  276.         }
  277.         function doMouseDrag(evt) {
  278.             if (!dragging) return;
  279.             var box = canvas.getBoundingClientRect();
  280.             var x = evt.clientX - box.left;
  281.             var y = evt.clientY - box.top;
  282.             var ray1 = toRay(prevx, prevy);
  283.             var ray2 = toRay(x, y);
  284.             applyTransvection(ray1, ray2);
  285.             prevx = x;
  286.             prevy = y;
  287.             if (callback) {
  288.                 callback();
  289.             }
  290.         }
  291.         function doMouseUp(evt) {
  292.             if (dragging) {
  293.                 document.removeEventListener("mousemove", doMouseDrag, false);
  294.                 document.removeEventListener("mouseup", doMouseUp, false);
  295.                 dragging = false;
  296.             }
  297.         }
  298.         function doTouchStart(evt) {
  299.             if (evt.touches.length != 1) {
  300.                 doTouchCancel();
  301.                 return;
  302.             }
  303.             evt.preventDefault();
  304.             var r = canvas.getBoundingClientRect();
  305.             prevx = evt.touches[0].clientX - r.left;
  306.             prevy = evt.touches[0].clientY - r.top;
  307.             canvas.addEventListener("touchmove", doTouchMove, false);
  308.             canvas.addEventListener("touchend", doTouchEnd, false);
  309.             canvas.addEventListener("touchcancel", doTouchCancel, false);
  310.             touchStarted = true;
  311.             centerX = canvas.width / 2;
  312.             centerY = canvas.height / 2;
  313.             var radius = Math.min(centerX, centerY);
  314.             radius2 = radius * radius;
  315.         }
  316.         function doTouchMove(evt) {
  317.             if (evt.touches.length != 1 || !touchStarted) {
  318.                 doTouchCancel();
  319.                 return;
  320.             }
  321.             evt.preventDefault();
  322.             var r = canvas.getBoundingClientRect();
  323.             var x = evt.touches[0].clientX - r.left;
  324.             var y = evt.touches[0].clientY - r.top;
  325.             var ray1 = toRay(prevx, prevy);
  326.             var ray2 = toRay(x, y);
  327.             applyTransvection(ray1, ray2);
  328.             prevx = x;
  329.             prevy = y;
  330.             if (callback) {
  331.                 callback();
  332.             }
  333.         }
  334.         function doTouchEnd(evt) {
  335.             doTouchCancel();
  336.         }
  337.         function doTouchCancel() {
  338.             if (touchStarted) {
  339.                 touchStarted = false;
  340.                 canvas.removeEventListener("touchmove", doTouchMove, false);
  341.                 canvas.removeEventListener("touchend", doTouchEnd, false);
  342.                 canvas.removeEventListener("touchcancel", doTouchCancel, false);
  343.             }
  344.         }
  345.         function toRay(x, y) {
  346.             // converts a point (x,y) in pixel coords to a 3D ray by mapping interior of
  347.             // a circle in the plane to a hemisphere with that circle as equator.
  348.             var dx = x - centerX;
  349.             var dy = centerY - y;
  350.             var vx = dx * unitx[0] + dy * unity[0]; // The mouse point as a vector in the image plane.
  351.             var vy = dx * unitx[1] + dy * unity[1];
  352.             var vz = dx * unitx[2] + dy * unity[2];
  353.             var dist2 = vx * vx + vy * vy + vz * vz;
  354.             if (dist2 > radius2) {
  355.                 // Map a point ouside the circle to itself
  356.                 return [vx, vy, vz];
  357.             } else {
  358.                 var z = Math.sqrt(radius2 - dist2);
  359.                 return [
  360.                     vx + z * unitz[0],
  361.                     vy + z * unitz[1],
  362.                     vz + z * unitz[2],
  363.                 ];
  364.             }
  365.         }
  366.         function dot(v, w) {
  367.             return v[0] * w[0] + v[1] * w[1] + v[2] * w[2];
  368.         }
  369.         function length(v) {
  370.             return Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
  371.         }
  372.         function normalize(v, w) {
  373.             var d = length(w);
  374.             v[0] = w[0] / d;
  375.             v[1] = w[1] / d;
  376.             v[2] = w[2] / d;
  377.         }
  378.         function copy(v, w) {
  379.             v[0] = w[0];
  380.             v[1] = w[1];
  381.             v[2] = w[2];
  382.         }
  383.         function add(sum, v, w) {
  384.             sum[0] = v[0] + w[0];
  385.             sum[1] = v[1] + w[1];
  386.             sum[2] = v[2] + w[2];
  387.         }
  388.         function subtract(dif, v, w) {
  389.             dif[0] = v[0] - w[0];
  390.             dif[1] = v[1] - w[1];
  391.             dif[2] = v[2] - w[2];
  392.         }
  393.         function scale(ans, v, num) {
  394.             ans[0] = v[0] * num;
  395.             ans[1] = v[1] * num;
  396.             ans[2] = v[2] * num;
  397.         }
  398.         function cross(c, v, w) {
  399.             var x = v[1] * w[2] - v[2] * w[1];
  400.             var y = v[2] * w[0] - v[0] * w[2];
  401.             var z = v[0] * w[1] - v[1] * w[0];
  402.             c[0] = x;
  403.             c[1] = y;
  404.             c[2] = z;
  405.         }
  406.     }
  407. }