1 /*
  2     Copyright 2008-2023
  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 /**
 32  * Create linear spaces of dimension at least one,
 33  * i.e. lines and planes.
 34  */
 35 import JXG from '../jxg';
 36 import Const from '../base/constants';
 37 import Type from '../utils/type';
 38 import Mat from '../math/math';
 39 import Geometry from '../math/geometry';
 40 
 41 // -----------------------
 42 //  Lines
 43 // -----------------------
 44 
 45 /**
 46  * Constructor for 3D lines.
 47  * @class Creates a new 3D line object. Do not use this constructor to create a 3D line. Use {@link JXG.View3D#create} with type {@link Line3D} instead.
 48  *
 49  * @augments JXG.GeometryElement3D
 50  * @augments JXG.GeometryElement
 51  * @param {View3D} view
 52  * @param {Point3D|Array} point
 53  * @param {Array} direction
 54  * @param {Array} range
 55  * @param {Object} attributes
 56  * @see JXG.Board#generateName
 57  */
 58 JXG.Line3D = function (view, point, direction, range, attributes) {
 59     this.constructor(view.board, attributes, Const.OBJECT_TYPE_LINE3D, Const.OBJECT_CLASS_3D);
 60     this.constructor3D(view, 'line3d');
 61 
 62     this.board.finalizeAdding(this);
 63 
 64     /**
 65      * 3D point which - together with a direction - defines the line.
 66      * @type JXG.Point3D
 67      *
 68      * @see JXG.Line3D#direction
 69      */
 70     this.point = point;
 71 
 72     /**
 73      * Direction which - together with a point - defines the line. Array of numbers or functions (of length 3) or function
 74      * returning array of length 3.
 75      *
 76      * @type Array,Function
 77      * @see JXG.Line3D#point
 78      */
 79     this.direction = direction;
 80 
 81     /**
 82      * Range [r1, r2] of the line. r1, r2 can be numbers or functions.
 83      * The 3D line goes from (point + r1 * direction) to (point + r2 * direction)
 84      * @type Array
 85      */
 86     this.range = range || [-Infinity, Infinity];
 87 
 88     /**
 89      * Starting point of the 3D line
 90      * @type JXG.Point3D
 91      * @private
 92      */
 93     this.point1 = null;
 94 
 95     /**
 96      * End point of the 3D line
 97      * @type JXG.Point3D
 98      * @private
 99      */
100     this.point2 = null;
101 
102     this.methodMap = Type.deepCopy(this.methodMap, {
103         // TODO
104     });
105 };
106 JXG.Line3D.prototype = new JXG.GeometryElement();
107 Type.copyPrototypeMethods(JXG.Line3D, JXG.GeometryElement3D, 'constructor3D');
108 
109 JXG.extend(
110     JXG.Line3D.prototype,
111     /** @lends JXG.Line3D.prototype */ {
112         /**
113          * Determine one end point of a 3D line from point, direction and range.
114          *
115          * @param {Number|function} r
116          * @private
117          * @returns Array
118          */
119         getPointCoords: function (r) {
120             var p = [],
121                 d = [],
122                 i,
123                 r0;
124 
125             p = [this.point.X(), this.point.Y(), this.point.Z()];
126 
127             if (Type.isFunction(this.direction)) {
128                 d = this.direction();
129             } else {
130                 for (i = 1; i < 4; i++) {
131                     d.push(Type.evaluate(this.direction[i]));
132                 }
133             }
134 
135             r0 = Type.evaluate(r);
136             // TODO: test also in the finite case
137             if (Math.abs(r0) === Infinity) {
138                 r = this.view.intersectionLineCube(p, d, r0);
139             }
140 
141             return [p[0] + d[0] * r0, p[1] + d[1] * r0, p[2] + d[2] * r0];
142         },
143 
144         update: function () {
145             return this;
146         },
147 
148         updateRenderer: function () {
149             this.needsUpdate = false;
150             return this;
151         }
152     }
153 );
154 
155 /**
156  * @class This element is used to provide a constructor for a 3D line.
157  * @pseudo
158  * @description There are two possibilities to create a Line3D object.
159  * <p>
160  * First: the line in 3D is defined by two points in 3D (Point3D).
161  * The points can be either existing points or coordinate arrays of
162  * the form [x, y, z].
163  * <p>Second: the line in 3D is defined by a point (or coordinate array [x, y, z])
164  * a direction given as array [x, y, z] and an optional range
165  * given as array [s, e]. The default value for the range is [-Infinity, Infinity].
166  * <p>
167  * All numbers can also be provided as functions returning a number.
168  *
169  * @name Line3D
170  * @augments JXG.GeometryElement3D
171  * @constructor
172  * @type JXG.Line3D
173  * @throws {Exception} If the element cannot be constructed with the given parent
174  * objects an exception is thrown.
175  * @param {JXG.Point3D,array,function_JXG.Point3D,array,function} point1,point2 First and second defining point.
176  * @param {JXG.Point3D,array,function_array,function_array,function} point,direction,range Alternatively, point, direction and range can be supplied.
177  * <ul>
178  * <li> point: Point3D or array of length 3
179  * <li> direction: array of length 3 or function returning an array of numbers or function returning an array
180  * <li> range: array of length 2, elements can also be functions.
181  * </ul>
182  *
183  * @example
184  *     var bound = [-5, 5];
185  *     var view = board.create('view3d',
186  *         [[-6, -3], [8, 8],
187  *         [bound, bound, bound]],
188  *         {});
189  *     var p = view.create('point3d', [1, 2, 2], { name:'A', size: 5 });
190  *     // Lines through 2 points
191  *     var l1 = view.create('line3d', [[1, 3, 3], [-3, -3, -3]], {point1: {visible: true}, point2: {visible: true} });
192  *     var l2 = view.create('line3d', [p, l1.point1]);
193  *
194  *     // Line by point, direction, range
195  *     var l3 = view.create('line3d', [p, [0, 0, 1], [-2, 4]]);
196  *
197  * </pre><div id='JXG05f9baa4-6059-4502-8911-6a934f823b3d' class='jxgbox' style='width: 300px; height: 300px;'></div>
198  * <script type='text/javascript'>
199  *     (function() {
200  *         var board = JXG.JSXGraph.initBoard('JXG05f9baa4-6059-4502-8911-6a934f823b3d',
201  *             {boundingbox: [-8, 8, 8,-8], axis: false, showcopyright: false, shownavigation: false});
202  *         var bound = [-5, 5];
203  *         var view = board.create('view3d',
204  *             [[-6, -3], [8, 8],
205  *             [bound, bound, bound]],
206  *             {});
207  *         var p = view.create('point3d', [1, 2, 2], { name:'A', size: 5 });
208  *         // Lines through 2 points
209  *         var l1 = view.create('line3d', [[1, 3, 3], [-3, -3, -3]], {name: 'll1', point1: {visible: true}, point2: {visible: true} });
210  *         var l2 = view.create('line3d', [p, l1.point1]);
211  *         // Line by point, direction, range
212  *         var l3 = view.create('line3d', [p, [0, 0, 1], [-2, 4]]);
213  *     })();
214  *
215  * </script><pre>
216  *
217  */
218 JXG.createLine3D = function (board, parents, attributes) {
219     var view = parents[0],
220         attr, points,
221         point, direction, range,
222         point1, point2, el;
223 
224     attr = Type.copyAttributes(attributes, board.options, 'line3d');
225 
226     // In any case, parents[1] contains a point or point coordinates
227 
228     if (
229         Type.isPoint3D(parents[2]) ||
230         (parents.length === 3 && (Type.isArray(parents[2]) || Type.isFunction(parents[2])))
231     ) {
232         // Line defined by two points; [view, point1, point2]
233 
234         point1 = Type.providePoints3D(view, [parents[1]], attributes, 'line3d', ['point1'])[0];
235         point2 = Type.providePoints3D(view, [parents[2]], attributes, 'line3d', ['point2'])[0];
236         direction = function () {
237             return [point2.X() - point1.X(), point2.Y() - point1.Y(), point2.Z() - point1.Z()];
238         };
239         range = [0, 1];
240         el = new JXG.Line3D(view, point1, direction, range, attr);
241     } else {
242         // Line defined by point, direction and range
243         point = Type.providePoints3D(view, [parents[1]], attributes, 'line3d', ['point'])[0];
244 
245         // Directions are handled as arrays of length 4,
246         // i.e. with homogeneous coordinates.
247         if (Type.isFunction(parents[2])) {
248             direction = parents[2];
249         } else if (parents[2].length === 3) {
250             direction = [1].concat(parents[2]);
251         } else if (parents[2].length === 4) {
252             direction = parents[2];
253         } else {
254             // TODO Throw error
255         }
256         range = parents[3];
257 
258         points = Type.providePoints3D(
259             view,
260             [
261                 [0, 0, 0],
262                 [0, 0, 0]
263             ],
264             attributes,
265             'line3d',
266             ['point1', 'point2']
267         );
268 
269         // Create a line3d with two dummy points
270         el = new JXG.Line3D(view, point, direction, range, attr);
271 
272         // Now set the real points which define the line
273         /**
274          * @ignore
275          */
276         points[0].F = function () {
277             return el.getPointCoords(Type.evaluate(el.range[0]));
278         };
279         points[0].prepareUpdate().update();
280         point1 = points[0];
281 
282         /**
283          * @ignore
284          */
285         points[1].F = function () {
286             return el.getPointCoords(Type.evaluate(el.range[1]));
287         };
288         points[1].prepareUpdate().update();
289         point2 = points[1];
290     }
291     // TODO Throw error
292 
293     attr = el.setAttr2D(attr);
294     el.element2D = view.create('segment', [point1.element2D, point2.element2D], attr);
295     el.addChild(el.element2D);
296     el.inherits.push(el.element2D);
297     el.element2D.setParents(el);
298     // el.setParents([point1.id, point2.id]);
299 
300     point1.addChild(el);
301     point2.addChild(el);
302     el.point1 = point1;
303     el.point2 = point2;
304 
305     el.update();
306     el.element2D.prepareUpdate().update().updateRenderer();
307     return el;
308 };
309 JXG.registerElement('line3d', JXG.createLine3D);
310 
311 // -----------------------
312 //  Planes
313 // -----------------------
314 
315 /**
316  * Constructor for 3D planes.
317  * @class Creates a new 3D plane object. Do not use this constructor to create a 3D plane. Use {@link JXG.Board#create} with type {@link Plane3D} instead.
318  *
319  * @augments JXG.GeometryElement3D
320  * @augments JXG.GeometryElement
321  * @param {View3D} view
322  * @param {Point3D,Array} point
323  * @param {Array} direction1
324  * @param {Array} range1
325  * @param {Array} direction2
326  * @param {Array} range2
327  * @param {Object} attributes
328  * @see JXG.Board#generateName
329  */
330 JXG.Plane3D = function (view, point, dir1, range1, dir2, range2, attributes) {
331     this.constructor(view.board, attributes, Const.OBJECT_TYPE_PLANE3D, Const.OBJECT_CLASS_3D);
332     this.constructor3D(view, 'plane3d');
333 
334     this.board.finalizeAdding(this);
335 
336     /**
337      * 3D point which - together with two direction vectors - defines the plane.
338      *
339      * @type JXG.Point3D
340      *
341      * @see JXG.3D#direction1
342      * @see JXG.3D#direction2
343      */
344     this.point = point;
345 
346     /**
347      * Two linearly independent vectors - together with a point - define the plane. Each of these direction vectors is an
348      * array of numbers or functions (of length 3) or function returning array of length 3.
349      *
350      * @type Array,Function
351      *
352      * @see JXG.Plane3D#point
353      * @see JXG.Plane3D#direction2
354      */
355     this.direction1 = dir1;
356 
357     /**
358      * Two linearly independent vectors - together with a point - define the plane. Each of these direction vectors is an
359      * array of numbers or functions (of length 3) or function returning array of length 3.
360      *
361      * @type Array,Function
362      * @see JXG.Plane3D#point
363      * @see JXG.Plane3D#direction1
364      */
365     this.direction2 = dir2;
366 
367     /**
368      * Range [r1, r2] of {@link direction1}. The 3D line goes from (point + r1 * direction1) to (point + r2 * direction1)
369      * @type {Array}
370      */
371     this.range1 = range1 || [-Infinity, Infinity];
372 
373     /**
374      * Range [r1, r2] of {@link direction2}. The 3D line goes from (point + r1 * direction2) to (point + r2 * direction2)
375      * @type {Array}
376      */
377     this.range2 = range2 || [-Infinity, Infinity];
378 
379     /**
380      * Direction vector 1 of the 3D plane. Contains the evaluated coordinates from {@link direction1} and {@link range1}.
381      * @type Array
382      * @private
383      *
384      * @see updateNormal
385      */
386     this.vec1 = [0, 0, 0];
387 
388     /**
389      * Direction vector 2 of the 3D plane. Contains the evaluated coordinates from {@link direction2} and {@link range2}.
390      *
391      * @type Array
392      * @private
393      *
394      * @see updateNormal
395      */
396     this.vec2 = [0, 0, 0];
397 
398     this.grid = null;
399 
400     /**
401          * Normal vector of the plane. Left hand side of the Hesse normal form.
402 
403         * @type Array
404          * @private
405          *
406          * @see updateNormal
407          *
408          */
409     this.normal = [0, 0, 0];
410 
411     /**
412          * Right hand side of the Hesse normal form.
413 
414         * @type Array
415          * @private
416          *
417          * @see updateNormal
418          *
419          */
420     this.d = 0;
421 
422     this.updateNormal();
423 
424     this.methodMap = Type.deepCopy(this.methodMap, {
425         // TODO
426     });
427 };
428 JXG.Plane3D.prototype = new JXG.GeometryElement();
429 Type.copyPrototypeMethods(JXG.Plane3D, JXG.GeometryElement3D, 'constructor3D');
430 
431 JXG.extend(
432     JXG.Plane3D.prototype,
433     /** @lends JXG.Plane3D.prototype */ {
434         /**
435          * Update the Hesse normal form of the plane, i.e. update normal vector and right hand side.
436          * Updates also {@link vec1} and {@link vec2}.
437          *
438          * @name JXG.Plane3D#updateNormal
439          * @function
440          * @returns {Object} Reference to the Plane3D object
441          * @private
442          * @example
443          *    plane.updateNormal();
444          *
445          */
446         updateNormal: function () {
447             var i, len;
448             for (i = 0; i < 3; i++) {
449                 this.vec1[i] = Type.evaluate(this.direction1[i]);
450                 this.vec2[i] = Type.evaluate(this.direction2[i]);
451             }
452 
453             this.normal = Mat.crossProduct(this.vec1, this.vec2);
454 
455             len = Mat.norm(this.normal);
456             if (Math.abs(len) > Mat.eps) {
457                 for (i = 0; i < 3; i++) {
458                     this.normal[i] /= len;
459                 }
460             }
461             this.d = Mat.innerProduct(this.point.coords.slice(1), this.normal, 3);
462 
463             return this;
464         },
465 
466         updateDataArray: function () {
467             var s1, e1, s2, e2, c2d, l1, l2,
468                 planes = ['xPlaneRear', 'yPlaneRear', 'zPlaneRear'],
469                 points = [],
470                 v1 = [0, 0, 0],
471                 v2 = [0, 0, 0],
472                 q = [0, 0, 0],
473                 p = [0, 0, 0],
474                 d, i, j, a, b, first, pos, pos_akt,
475                 view = this.view;
476 
477             this.dataX = [];
478             this.dataY = [];
479 
480             this.updateNormal();
481 
482             // Infinite plane
483             if (
484                 this.elType !== 'axisplane3d' &&
485                 view.defaultAxes &&
486                 Type.evaluate(this.range1[0]) === -Infinity &&
487                 Type.evaluate(this.range1[1]) === Infinity &&
488                 Type.evaluate(this.range2[0]) === -Infinity &&
489                 Type.evaluate(this.range2[1]) === Infinity
490             ) {
491                 // Start with the rear plane.
492                 // Determine the intersections with the view bbox3d
493                 // For each face of the bbox3d we determine two points
494                 // which are the ends of the intersection line.
495                 // We start with the three rear planes.
496                 for (j = 0; j < planes.length; j++) {
497                     p = view.intersectionPlanePlane(this, view.defaultAxes[planes[j]]);
498 
499                     if (p[0].length === 3 && p[1].length === 3) {
500                         // This test is necessary to filter out intersection lines which are
501                         // identical to intersections of axis planes (they would occur twice).
502                         for (i = 0; i < points.length; i++) {
503                             if (
504                                 (Geometry.distance(p[0], points[i][0], 3) < Mat.eps &&
505                                     Geometry.distance(p[1], points[i][1], 3) < Mat.eps) ||
506                                 (Geometry.distance(p[0], points[i][1], 3) < Mat.eps &&
507                                     Geometry.distance(p[1], points[i][0], 3) < Mat.eps)
508                             ) {
509                                 break;
510                             }
511                         }
512                         if (i === points.length) {
513                             points.push(p.slice());
514                         }
515                     }
516 
517                     // Point on the front plane of the bbox3d
518                     p = [0, 0, 0];
519                     p[j] = view.bbox3D[j][1];
520 
521                     // d is the rhs of the Hesse normal form of the front plane.
522                     d = Mat.innerProduct(p, view.defaultAxes[planes[j]].normal, 3);
523                     p = view.intersectionPlanePlane(this, view.defaultAxes[planes[j]], d);
524 
525                     if (p[0].length === 3 && p[1].length === 3) {
526                         // Do the same test as above
527                         for (i = 0; i < points.length; i++) {
528                             if (
529                                 (Geometry.distance(p[0], points[i][0], 3) < Mat.eps &&
530                                     Geometry.distance(p[1], points[i][1], 3) < Mat.eps) ||
531                                 (Geometry.distance(p[0], points[i][1], 3) < Mat.eps &&
532                                     Geometry.distance(p[1], points[i][0], 3) < Mat.eps)
533                             ) {
534                                 break;
535                             }
536                         }
537                         if (i === points.length) {
538                             points.push(p.slice());
539                         }
540                     }
541                 }
542 
543                 // Concatenate the intersection points to a polygon.
544                 // If all wents well, each intersection should appear
545                 // twice in the list.
546                 first = 0;
547                 pos = first;
548                 i = 0;
549                 do {
550                     p = points[pos][i];
551                     if (p.length === 3) {
552                         c2d = view.project3DTo2D(p);
553                         this.dataX.push(c2d[1]);
554                         this.dataY.push(c2d[2]);
555                     }
556                     i = (i + 1) % 2;
557                     p = points[pos][i];
558 
559                     pos_akt = pos;
560                     for (j = 0; j < points.length; j++) {
561                         if (j !== pos && Geometry.distance(p, points[j][0]) < Mat.eps) {
562                             pos = j;
563                             i = 0;
564                             break;
565                         }
566                         if (j !== pos && Geometry.distance(p, points[j][1]) < Mat.eps) {
567                             pos = j;
568                             i = 1;
569                             break;
570                         }
571                     }
572                     if (pos === pos_akt) {
573                         console.log('Error: update plane3d: did not find next', pos);
574                         break;
575                     }
576                 } while (pos !== first);
577 
578                 c2d = view.project3DTo2D(points[first][0]);
579                 this.dataX.push(c2d[1]);
580                 this.dataY.push(c2d[2]);
581             } else {
582                 // 3D bounded flat
583                 s1 = Type.evaluate(this.range1[0]);
584                 e1 = Type.evaluate(this.range1[1]);
585                 s2 = Type.evaluate(this.range2[0]);
586                 e2 = Type.evaluate(this.range2[1]);
587 
588                 q = this.point.coords.slice(1);
589 
590                 v1 = this.vec1.slice();
591                 v2 = this.vec2.slice();
592                 l1 = Mat.norm(v1, 3);
593                 l2 = Mat.norm(v2, 3);
594                 for (i = 0; i < 3; i++) {
595                     v1[i] /= l1;
596                     v2[i] /= l2;
597                 }
598 
599                 for (j = 0; j < 4; j++) {
600                     switch (j) {
601                         case 0:
602                             a = s1;
603                             b = s2;
604                             break;
605                         case 1:
606                             a = e1;
607                             b = s2;
608                             break;
609                         case 2:
610                             a = e1;
611                             b = e2;
612                             break;
613                         case 3:
614                             a = s1;
615                             b = e2;
616                     }
617                     for (i = 0; i < 3; i++) {
618                         p[i] = q[i] + a * v1[i] + b * v2[i];
619                     }
620                     c2d = view.project3DTo2D(p);
621                     this.dataX.push(c2d[1]);
622                     this.dataY.push(c2d[2]);
623                 }
624                 // Close the curve
625                 this.dataX.push(this.dataX[0]);
626                 this.dataY.push(this.dataY[0]);
627             }
628             return { X: this.dataX, Y: this.dataY };
629         },
630 
631         update: function () {
632             return this;
633         },
634 
635         updateRenderer: function () {
636             this.needsUpdate = false;
637             return this;
638         }
639     }
640 );
641 
642 // TODO docs
643 JXG.createPlane3D = function (board, parents, attributes) {
644     var view = parents[0],
645         attr,
646         point,
647         dir1 = parents[2],
648         dir2 = parents[3],
649         range1 = parents[4] || [-Infinity, Infinity],
650         range2 = parents[5] || [-Infinity, Infinity],
651         el,
652         grid;
653 
654     point = Type.providePoints3D(view, [parents[1]], attributes, 'plane3d', ['point'])[0];
655     if (point === false) {
656         // TODO Throw error
657     }
658 
659     attr = Type.copyAttributes(attributes, board.options, 'plane3d');
660     el = new JXG.Plane3D(view, point, dir1, range1, dir2, range2, attr);
661     point.addChild(el);
662 
663     attr = el.setAttr2D(attr);
664     el.element2D = view.create('curve', [[], []], attr);
665 
666     /**
667      * @ignore
668      */
669     el.element2D.updateDataArray = function () {
670         var ret = el.updateDataArray();
671         this.dataX = ret.X;
672         this.dataY = ret.Y;
673     };
674     el.addChild(el.element2D);
675     el.inherits.push(el.element2D);
676     el.element2D.setParents(el);
677 
678     attr = Type.copyAttributes(attributes.mesh3d, board.options, 'mesh3d');
679     if (
680         Math.abs(el.range1[0]) !== Infinity &&
681         Math.abs(el.range1[1]) !== Infinity &&
682         Math.abs(el.range2[0]) !== Infinity &&
683         Math.abs(el.range2[1]) !== Infinity
684     ) {
685         grid = view.create('mesh3d', [
686                 function () {
687                     return point.coords;
688                 },
689                 dir1, range1, dir2, range2
690             ], attr
691         );
692         el.grid = grid;
693         el.addChild(grid);
694         el.inherits.push(grid);
695         grid.setParents(el);
696     }
697 
698     el.element2D.prepareUpdate().update();
699     if (!board.isSuspendedUpdate) {
700         el.element2D.updateVisibility().updateRenderer();
701     }
702 
703     return el;
704 };
705 JXG.registerElement('plane3d', JXG.createPlane3D);
706