1 /*
  2     Copyright 2008-2024
  3         Matthias Ehmann,
  4         Carsten Miller,
  5         Andreas Walter,
  6         Alfred Wassermann
  7 
  8     This file is part of JSXGraph.
  9 
 10     JSXGraph is free software dual licensed under the GNU LGPL or MIT License.
 11 
 12     You can redistribute it and/or modify it under the terms of the
 13 
 14       * GNU Lesser General Public License as published by
 15         the Free Software Foundation, either version 3 of the License, or
 16         (at your option) any later version
 17       OR
 18       * MIT License: https://github.com/jsxgraph/jsxgraph/blob/master/LICENSE.MIT
 19 
 20     JSXGraph is distributed in the hope that it will be useful,
 21     but WITHOUT ANY WARRANTY; without even the implied warranty of
 22     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 23     GNU Lesser General Public License for more details.
 24 
 25     You should have received a copy of the GNU Lesser General Public License and
 26     the MIT License along with JSXGraph. If not, see <https://www.gnu.org/licenses/>
 27     and <https://opensource.org/licenses/MIT/>.
 28  */
 29 /*global JXG:true, define: true*/
 30 
 31 import JXG from "../jxg.js";
 32 import Const from "../base/constants.js";
 33 import Mat from "../math/math.js";
 34 import Geometry from "../math/geometry.js";
 35 import Type from "../utils/type.js";
 36 //, GeometryElement3D) {
 37 
 38 /**
 39  * A 3D point is the basic geometric element.
 40  * @class Creates a new 3D point object. Do not use this constructor to create a 3D point. Use {@link JXG.View3D#create} with
 41  * type {@link Point3D} instead.
 42  * @augments JXG.GeometryElement3D
 43  * @augments JXG.GeometryElement
 44  * @param {JXG.View3D} view The 3D view the point is drawn on.
 45  * @param {Function|Array} F Array of numbers, array of functions or function returning an array with defines the user coordinates of the point.
 46  * @parame {JXG.GeometryElement3D} slide Object the 3D point should be bound to. If null, the point is a free point.
 47  * @param {Object} attributes An object containing visual properties like in {@link JXG.Options#point3d} and
 48  * {@link JXG.Options#elements}, and optional a name and an id.
 49  * @see JXG.Board#generateName
 50  */
 51 JXG.Point3D = function (view, F, slide, attributes) {
 52     this.constructor(view.board, attributes, Const.OBJECT_TYPE_POINT3D, Const.OBJECT_CLASS_3D);
 53     this.constructor3D(view, "point3d");
 54 
 55     this.board.finalizeAdding(this);
 56 
 57     // add the new point to its view's point list
 58     if (view.visProp.depthorderpoints) {
 59         view.points.push(this);
 60     }
 61 
 62     /**
 63      * Homogeneous coordinates of a Point3D, i.e. array of length 4: [w, x, y, z]. Usually, w=1 for finite points and w=0 for points
 64      * which are infinitely far.
 65      *
 66      * @example
 67      *   p.coords;
 68      *
 69      * @name Point3D#coords
 70      * @type Array
 71      * @private
 72      */
 73     this.coords = [0, 0, 0, 0];
 74 
 75     /**
 76      * Function or array of functions or array of numbers defining the coordinates of the point, used in {@link updateCoords}.
 77      *
 78      * @name Point3D#F
 79      * @function
 80      * @private
 81      *
 82      * @see updateCoords
 83      */
 84     this.F = F;
 85 
 86     /**
 87      * Optional slide element, i.e. element the Point3D lives on.
 88      *
 89      * @example
 90      *   p.slide;
 91      *
 92      * @name Point3D#slide
 93      * @type JXG.GeometryElement3D
 94      * @default null
 95      * @private
 96      *
 97      */
 98     this.slide = slide;
 99 
100     /**
101      * Get x-coordinate of a 3D point.
102      *
103      * @name X
104      * @memberOf Point3D
105      * @function
106      * @returns {Number}
107      *
108      * @example
109      *   p.X();
110      */
111     this.X = function () {
112         return this.coords[1];
113     };
114 
115     /**
116      * Get y-coordinate of a 3D point.
117      *
118      * @name Y
119      * @memberOf Point3D
120      * @function
121      * @returns Number
122      *
123      * @example
124      *   p.Y();
125      */
126     this.Y = function () {
127         return this.coords[2];
128     };
129 
130     /**
131      * Get z-coordinate of a 3D point.
132      *
133      * @name Z
134      * @memberOf Point3D
135      * @function
136      * @returns Number
137      *
138      * @example
139      *   p.Z();
140      */
141     this.Z = function () {
142         return this.coords[3];
143     };
144 
145     /**
146      * Store the last position of the 2D point for the optimizer.
147      *
148      * @type Array
149      * @private
150      */
151     this._params = [];
152 
153     this._c2d = null;
154 
155     this.methodMap = Type.deepCopy(this.methodMap, {
156         // TODO
157     });
158 };
159 JXG.Point3D.prototype = new JXG.GeometryElement();
160 Type.copyPrototypeMethods(JXG.Point3D, JXG.GeometryElement3D, "constructor3D");
161 
162 JXG.extend(
163     JXG.Point3D.prototype,
164     /** @lends JXG.Point3D.prototype */ {
165         /**
166          * Update the homogeneous coords array.
167          *
168          * @name updateCoords
169          * @memberOf Point3D
170          * @function
171          * @returns {Object} Reference to the Point3D object
172          * @private
173          * @example
174          *    p.updateCoords();
175          */
176         updateCoords: function () {
177             var i;
178 
179             if (Type.isFunction(this.F)) {
180                 // this.coords = [1].concat(Type.evaluate(this.F));
181                 this.coords = Type.evaluate(this.F);
182                 this.coords.unshift(1);
183             } else {
184                 this.coords[0] = 1;
185                 for (i = 0; i < 3; i++) {
186                     // Attention: if F is array of numbers, coords are not updated.
187                     // Otherwise, dragging will not work anymore.
188                     if (Type.isFunction(this.F[i])) {
189                         this.coords[i + 1] = Type.evaluate(this.F[i]);
190                     }
191                 }
192             }
193             return this;
194         },
195 
196         /**
197          * Initialize the coords array.
198          *
199          * @private
200          * @returns {Object} Reference to the Point3D object
201          */
202         initCoords: function () {
203             var i;
204 
205             if (Type.isFunction(this.F)) {
206                 // this.coords = [1].concat(Type.evaluate(this.F));
207                 this.coords = Type.evaluate(this.F);
208                 this.coords.unshift(1);
209             } else {
210                 this.coords[0] = 1;
211                 for (i = 0; i < 3; i++) {
212                     this.coords[i + 1] = Type.evaluate(this.F[i]);
213                 }
214             }
215             return this;
216         },
217 
218         /**
219          * Normalize homogeneous coordinates such the the first coordinate (the w-coordinate is equal to 1 or 0)-
220          *
221          * @name normalizeCoords
222          * @memberOf Point3D
223          * @function
224          * @returns {Object} Reference to the Point3D object
225          * @private
226          * @example
227          *    p.normalizeCoords();
228          */
229         normalizeCoords: function () {
230             if (Math.abs(this.coords[0]) > Mat.eps) {
231                 this.coords[1] /= this.coords[0];
232                 this.coords[2] /= this.coords[0];
233                 this.coords[3] /= this.coords[0];
234                 this.coords[0] = 1.0;
235             }
236             return this;
237         },
238 
239         /**
240          * Set the position of a 3D point.
241          *
242          * @name setPosition
243          * @memberOf Point3D
244          * @function
245          * @param {Array} coords 3D coordinates. Either of the form [x,y,z] (Euclidean) or [w,x,y,z] (homogeneous).
246          * @param {Boolean} [noevent] If true, no events are triggered.
247          * @returns {Object} Reference to the Point3D object
248          *
249          * @example
250          *    p.setPosition([1, 3, 4]);
251          */
252         setPosition: function (coords, noevent) {
253             var c = this.coords;
254                 // oc = this.coords.slice(); // Copy of original values
255 
256             if (coords.length === 3) {
257                 // Euclidean coordinates
258                 c[0] = 1.0;
259                 c[1] = coords[0];
260                 c[2] = coords[1];
261                 c[3] = coords[2];
262             } else {
263                 // Homogeneous coordinates (normalized)
264                 c[0] = coords[0];
265                 c[1] = coords[1];
266                 c[2] = coords[2];
267                 c[3] = coords[2];
268                 this.normalizeCoords();
269             }
270 
271             // console.log(el.emitter, !noevent, oc[0] !== c[0] || oc[1] !== c[1] || oc[2] !== c[2] || oc[3] !== c[3]);
272             // Not yet working TODO
273             // if (el.emitter && !noevent &&
274             //     (oc[0] !== c[0] || oc[1] !== c[1] || oc[2] !== c[2] || oc[3] !== c[3])) {
275             //     this.triggerEventHandlers(['update3D'], [oc]);
276             // }
277             return this;
278         },
279 
280         update: function (drag) {
281             var c3d, foot;
282 
283             // Update is called from two methods:
284             // Once in setToPosition and
285             // once in the subsequent board.update
286             if (
287                 this.element2D.draggable() &&
288                 Geometry.distance(this._c2d, this.element2D.coords.usrCoords) !== 0
289             ) {
290                 if (this.slide) {
291                     this.coords = this.slide.projectScreenCoords(
292                         [this.element2D.X(), this.element2D.Y()],
293                         this._params
294                     );
295                     this.element2D.coords.setCoordinates(
296                         Const.COORDS_BY_USER,
297                         this.view.project3DTo2D(this.coords)
298                     );
299                 } else {
300                     if (this.view.isVerticalDrag()) {
301                         // Drag the point in its vertical to the xy plane
302                         c3d = this.view.project2DTo3DVertical(this.element2D, this.coords);
303                     } else {
304                         // Drag the point in its xy plane
305                         foot = [1, 0, 0, this.coords[3]];
306                         c3d = this.view.project2DTo3DPlane(this.element2D, [1, 0, 0, 1], foot);
307                     }
308                     if (c3d[0] !== 0) {
309                         this.coords = this.view.project3DToCube(c3d);
310                     }
311                 }
312             } else {
313                 this.updateCoords();
314                 if (this.slide) {
315                     this.coords = this.slide.projectCoords(
316                         [this.X(), this.Y(), this.Z()],
317                         this._params
318                     );
319                 }
320                 // Update 2D point from its 3D view
321                 this.element2D.coords.setCoordinates(
322                     Const.COORDS_BY_USER,
323                     this.view.project3DTo2D([1, this.X(), this.Y(), this.Z()])
324                 );
325             }
326             this._c2d = this.element2D.coords.usrCoords.slice();
327 
328             return this;
329         },
330 
331         updateRenderer: function () {
332             this.needsUpdate = false;
333             return this;
334         },
335 
336         /**
337          * Check whether a point's homogeneous coordinate vector is zero.
338          * @returns {Boolean} True if the coordinate vector is zero; false otherwise.
339          */
340         isIllDefined: function () {
341             return Type.cmpArrays(this.coords, [0, 0, 0, 0]);
342         },
343 
344         /**
345          * Calculate the distance from one point to another. If one of the points is on the plane at infinity, return positive infinity.
346          * @param {JXG.Point3D} pt The point to which the distance is calculated.
347          * @returns {Number} The distance
348          */
349         distance: function (pt) {
350             var eps_sq = Mat.eps * Mat.eps,
351                 c_this = this.coords,
352                 c_pt = pt.coords;
353 
354             if (c_this[0] * c_this[0] > eps_sq && c_pt[0] * c_pt[0] > eps_sq) {
355                 return Mat.hypot(
356                     c_pt[1] - c_this[1],
357                     c_pt[2] - c_this[2],
358                     c_pt[3] - c_this[3]
359                 );
360             } else {
361                 return Number.POSITIVE_INFINITY;
362             }
363         },
364 
365         // Not yet working
366         __evt__update3D: function (oc) {}
367     }
368 );
369 
370 /**
371  * @class This element is used to provide a constructor for a 3D Point.
372  * @pseudo
373  * @description A Point3D object is defined by 3 coordinates [x,y,z].
374  * <p>
375  * All numbers can also be provided as functions returning a number.
376  *
377  * @name Point3D
378  * @augments JXG.Point3D
379  * @constructor
380  * @throws {Exception} If the element cannot be constructed with the given parent
381  * objects an exception is thrown.
382  * @param {number,function_number,function_number,function} x,y,z The coordinates are given as x, y, z consisting of numbers of functions.
383  * @param {array,function} F Alternatively, the coordinates can be supplied as
384  *  <ul>
385  *   <li>array arr=[x,y,z] of length 3 consisting of numbers or
386  *   <li>function returning an array [x,y,z] of length 3 of numbers.
387  * </ul>
388  *
389  * @example
390  *    var bound = [-5, 5];
391  *    var view = board.create('view3d',
392  *        [[-6, -3], [8, 8],
393  *        [bound, bound, bound]],
394  *        {});
395  *    var p = view.create('point3d', [1, 2, 2], { name:'A', size: 5 });
396  *    var q = view.create('point3d', function() { return [p.X(), p.Y(), p.Z() - 3]; }, { name:'B', size: 5, fixed: true });
397  *
398  * </pre><div id="JXGb9ee8f9f-3d2b-4f73-8221-4f82c09933f1" class="jxgbox" style="width: 300px; height: 300px;"></div>
399  * <script type="text/javascript">
400  *     (function() {
401  *         var board = JXG.JSXGraph.initBoard('JXGb9ee8f9f-3d2b-4f73-8221-4f82c09933f1',
402  *             {boundingbox: [-8, 8, 8,-8], axis: false, showcopyright: false, shownavigation: false});
403  *         var bound = [-5, 5];
404  *         var view = board.create('view3d',
405  *             [[-6, -3], [8, 8],
406  *             [bound, bound, bound]],
407  *             {});
408  *         var p = view.create('point3d', [1, 2, 2], { name:'A', size: 5 });
409  *         var q = view.create('point3d', function() { return [p.X(), p.Y(), p.Z() - 3]; }, { name:'B', size: 5 });
410  *     })();
411  *
412  * </script><pre>
413  *
414  */
415 JXG.createPoint3D = function (board, parents, attributes) {
416     //   parents[0]: view
417     // followed by
418     //   parents[1]: function or array
419     // or
420     //   parents[1..3]: coordinates
421 
422     var view = parents[0],
423         attr, F, slide, c2d, el;
424 
425     // If the last element of parents is a 3D object,
426     // the point is a glider on that element.
427     if (parents.length > 2 && Type.exists(parents[parents.length - 1].is3D)) {
428         slide = parents.pop();
429     } else {
430         slide = null;
431     }
432 
433     if (parents.length === 2) {
434         // [view, array|fun] (Array [x, y, z] | function) returning [x, y, z]
435         F = parents[1];
436     } else if (parents.length === 4) {
437         // [view, x, y, z], (3 numbers | functions)
438         F = parents.slice(1);
439     } else {
440         throw new Error(
441             "JSXGraph: Can't create point3d with parent types '" +
442                 typeof parents[0] +
443                 "' and '" +
444                 typeof parents[1] +
445                 "'." +
446                 "\nPossible parent types: [[x,y,z]], [x,y,z]"
447         );
448         //  "\nPossible parent types: [[x,y,z]], [x,y,z], [element,transformation]"); // TODO
449     }
450 
451     attr = Type.copyAttributes(attributes, board.options, 'point3d');
452     el = new JXG.Point3D(view, F, slide, attr);
453     el.initCoords();
454 
455     c2d = view.project3DTo2D(el.coords);
456 
457     attr = el.setAttr2D(attr);
458     el.element2D = view.create('point', c2d, attr);
459     el.element2D.view = view;
460     el.addChild(el.element2D);
461     el.inherits.push(el.element2D);
462     el.element2D.setParents(el);
463 
464     // if this point is a glider, record that in the update tree
465     if (el.slide) {
466         el.slide.addChild(el);
467         el.setParents(el.slide);
468     }
469 
470     el._c2d = el.element2D.coords.usrCoords.slice(); // Store a copy of the coordinates to detect dragging
471 
472     return el;
473 };
474 
475 JXG.registerElement("point3d", JXG.createPoint3D);
476