add some docs on UI customization, a jsdoc conf file, fix some class …

…links in the doc
cds-astro · Jun 11, 2024 · 2b5f8a7 · 2b5f8a7
1 parent 6df2ee9
commit 2b5f8a7
Show file tree

Hide file tree

Showing 15 changed files with 152 additions and 161 deletions.
diff --git a/examples/al-gw.html b/examples/al-gw.html
@@ -1,6 +1,8 @@
 <!doctype html>
 <html>
 <head>
+    <meta name="viewport" content="width=device-width, height=device-height, initial-scale=1.0, user-scalable=no">
+
 </head>
 <body>
     <div id="aladin-lite-div" style="width: 1024px; height: 768px"></div>

diff --git a/examples/al-init-custom-options.html b/examples/al-init-custom-options.html
@@ -1,14 +1,16 @@
 <!doctype html>
 <html>
-<head>
-</head>
+    <head>
+        <meta name="viewport" content="width=device-width, height=device-height, maximum-scale=1.0, initial-scale=1.0, user-scalable=no">
+    </head>
 <body>
 
-<div id="aladin-lite-div" style="width: 1024px; height: 768px"></div>
-<script>    let aladin;
-</script>
+
+<div id="aladin-lite-div" style="width: 768px; height: 512px"></div>
+
 <script type="module">
     import A from '../src/js/A.js';
+    let aladin;
     A.init.then(() => {
         aladin = A.aladin(
             '#aladin-lite-div',
@@ -17,26 +19,24 @@
                 projection: 'AIT', // set a projection
                 fov: 1.5, // initial field of view in degrees
                 target: 'NGC 2175', // initial target
-                cooFrame: 'galactic', // set galactic frame
-                reticleColor: '#00ff00', // change reticle color
-                reticleSize: 40, // change reticle size
-                gridOptions: {color: 'pink'},
-                showCooGrid: false, // set the grid
-                fullScreen: true,
-                inertia: false,
-                showStatusBar: true,
-                showShareControl: true,
-                showSettingsControl: true,
-                showLayersControl: true,
-                showZoomControl: true,
+                cooFrame: 'icrs', // set galactic frame
+                reticleColor: '#ff89ff', // change reticle color
+                reticleSize: 64, // change reticle size
                 showContextMenu: true,
-                showCooGridControl: true,
-                //showSimbadPointerControl: true,
-                showFullscreenControl: true,
             }
         );
     });
 </script>
+<style>
+    .aladin-location {
+        position: absolute;
+        left: 0.2rem;
+        top: 0.2rem;
+    }
 
+    .aladin-cooFrame {
+        display: none;
+    }
+</style>
 </body>
-</html>
+</html>
diff --git a/jsdoc.json b/jsdoc.json
@@ -0,0 +1,22 @@
+{
+    "plugins": [],
+    "recurseDepth": 10,
+    "source": {
+        "includePattern": ".+\\.js(doc|x)?$",
+        "excludePattern": "(^|\\/|\\\\)_"
+    },
+    "sourceType": "module",
+    "tags": {
+        "allowUnknownTags": true,
+        "dictionaries": ["jsdoc","closure"]
+    },
+    "templates": {
+        "cleverLinks": true,
+        "monospaceLinks": true
+    },
+    "opts": {
+        "readme": "./README.md",
+        "destination": "./docs/",
+        "tutorials": "./tutorials"
+    }
+}
diff --git a/package.json b/package.json
@@ -41,8 +41,8 @@
     "preview": "vite preview",
     "test:build": "cd src/core && cargo test --release --features webgl2",
     "test:unit": "vitest run",
-    "doc": "jsdoc -d doc --readme README.md src/js src/js/shapes && cp aladin-logo.png doc/",
-    "doc:dev": "npm run doc && open doc/index.html"
+    "doc": "jsdoc -c jsdoc.json src/js src/js/shapes && cp aladin-logo.png docs/",
+    "doc:dev": "npm run doc && open docs/index.html"
   },
   "devDependencies": {
     "happy-dom": "^10.11.0",

diff --git a/src/js/A.js b/src/js/A.js
@@ -33,7 +33,7 @@ import { GraphicOverlay } from "./Overlay.js";
 import { Circle } from "./shapes/Circle.js";
 import { Ellipse } from "./shapes/Ellipse.js";
 import { Polyline } from "./shapes/Polyline.js";
-import { Line } from "./shapes/Line.js";
+import { Vector } from "./shapes/Vector.js";
 
 import { Catalog } from "./Catalog.js";
 import { ProgressiveCat } from "./ProgressiveCat.js";
@@ -192,14 +192,7 @@ A.marker = function (ra, dec, options, data) {
  * @returns {Polyline}
  */
 A.polygon = function (raDecArray, options) {
-    const numVertices = raDecArray.length;
-
-    if (numVertices < 3) {
-        // Cannot define a polygon from that
-        throw 'Cannot define a polygon from less than 3 vertices';
-    }
-
-    const lastVertexIdx = numVertices - 1;
+    const lastVertexIdx = raDecArray.length - 1;
 
     // User gave a closed polygon, so we remove the last vertex
     if (raDecArray[0][0] == raDecArray[lastVertexIdx][0] && raDecArray[0][1] == raDecArray[lastVertexIdx][1]) {
@@ -208,7 +201,7 @@ A.polygon = function (raDecArray, options) {
     }
 
     options = options || {};
-    options.closed = true;
+    //options.closed = true;
 
     return new Polyline(raDecArray, options);
 };
@@ -268,26 +261,6 @@ A.ellipse = function (ra, dec, radiusRaDeg, radiusDecDeg, rotationDeg, options)
     return new Ellipse([ra, dec], radiusRaDeg, radiusDecDeg, rotationDeg, options);
 };
 
-/**
- * Creates a line shape
- *
- * @function
- * @memberof A
- * @name line
- *
- * @param {number} ra1 - Right Ascension (RA) coordinate of the center in degrees.
- * @param {number} dec1 - Declination (Dec) coordinate of the center in degrees.
- * @param {number} ra2 - Right Ascension (RA) coordinate of the center in degrees.
- * @param {number} dec2 - Declination (Dec) coordinate of the center in degrees.
- * @param {CooFrame} [frame] - Frame in which the coordinates are given. If none, the frame used is icrs/j2000.
- * @param {ShapeOptions} options - Options for configuring the line.
- * 
- * @returns {Line}
- */
- A.line = function (ra1, dec1, ra2, dec2, frame, options) {
-    return new Line(ra1, dec1, ra2, dec2, frame, options);
-};
-
 /**
  * Creates a vector shape
  *
@@ -301,12 +274,12 @@ A.ellipse = function (ra, dec, radiusRaDeg, radiusDecDeg, rotationDeg, options)
  * @param {number} dec2 - Declination (Dec) coordinate of the center in degrees.
  * @param {ShapeOptions} options - Options for configuring the vector.
  * 
- * @returns {Line}
+ * @returns {Vector}
  */
 A.vector = function (ra1, dec1, ra2, dec2, options) {
     options['arrow'] = true;
 
-    return A.line(ra1, dec1, ra2, dec2, options);
+    return new Vector(ra1, dec1, ra2, dec2, options);
 }
 
 /**

diff --git a/src/js/Aladin.js b/src/js/Aladin.js
@@ -1988,7 +1988,7 @@ aladin.on("positionChanged", ({ra, dec}) => {
      * Select specific objects in the view
      * 
      * @memberof Aladin
-     * @param {?Array.<Source, Footprint, Circle, Ellipse, Polyline, Line>} objects - If null is passed then nothing will be selected and sources already selected will be deselected
+     * @param {?Array.<Source, Footprint, Circle, Ellipse, Polyline, Vector>} objects - If null is passed then nothing will be selected and sources already selected will be deselected
      */
     Aladin.prototype.selectObjects = function (objects) {
         if (!objects) {

diff --git a/src/js/Catalog.js b/src/js/Catalog.js
@@ -34,23 +34,22 @@ import { VOTable } from "./vo/VOTable.js";
 import { ObsCore } from "./vo/ObsCore.js";
 import A from "./A.js";
 import { Polyline } from "./shapes/Polyline.js";
-import { Line } from "./shapes/Line.js";
+import { Vector } from "./shapes/Vector.js";
 import { Ellipse } from "./shapes/Ellipse.js";
 import { Circle } from "./shapes/Circle.js";
 import { Footprint } from "./Footprint.js";
 
 /**
- * Represents a catalog with configurable options for display and interaction.
  *
  * @namespace
  * @typedef {Object} Catalog
  */
 export let Catalog = (function () {
     /**
-     * Constructor function for creating a new catalog instance.
+     * Represents a catalog with configurable options for display and interaction.
      *
-     * @constructor
-     * @memberof Catalog
+     * @class
+     * @constructs Catalog
      * @param {Object} options - Configuration options for the catalog.
      * @param {string} options.url - The URL of the catalog.
      * @param {string} [options.name="catalog"] - The name of the catalog.
@@ -583,7 +582,7 @@ export let Catalog = (function () {
                         shape instanceof Circle ||
                         shape instanceof Polyline ||
                         shape instanceof Ellipse ||
-                        shape instanceof Line
+                        shape instanceof Vector
                     ) {
                         shape = new Footprint(shape, source);
                     }

diff --git a/src/js/DefaultActionsForContextMenu.js b/src/js/DefaultActionsForContextMenu.js
@@ -180,7 +180,7 @@ export let DefaultActionsForContextMenu = (function () {
 
                                 files.forEach(file => {
                                     const url = URL.createObjectURL(file);
-                                    A.catalogFromURL(url, { name: file.name, onClick: 'showTable'}, (catalog) => {
+                                    A.catalogFromURL(url, { name: file.name, hoverColor: 'yellow', onClick: 'showTable'}, (catalog) => {
                                         a.addCatalog(catalog);
                                     }, false);
                                 });

diff --git a/src/js/MOC.js b/src/js/MOC.js
@@ -30,18 +30,12 @@ import { ALEvent } from "./events/ALEvent.js";
 * @property {number} [options.opacity=1.0] - The opacity of the MOC
 */
 
-/**
- * Represents a Multi-Order-Coverage with configurable options for display and interaction.
- *
- * @namespace
- * @typedef {Object} MOC
- */
 export let MOC = (function() {
     /**
-     * Constructor function for creating a new catalog instance.
+     * Represents a Multi-Order-Coverage with configurable options for display and interaction.
      *
-     * @constructor
-     * @memberof MOC
+     * @class
+     * @constructs MOC
      * @param {MOCOptions} options - Configuration options for the MOC.
      */
     let MOC = function(options) {

diff --git a/src/js/Overlay.js b/src/js/Overlay.js
@@ -45,18 +45,12 @@ import { Color } from './Color';
 * @property {Array.<number>} [options.lineDash=[]] - Dash line option. See the segments property {@link https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash#segments| here}
 */
 
-/**
- * Represents an overlay containing Footprints, whether it is 
- *
- * @namespace
- * @typedef {Object} GraphicOverlay
- */
 export let GraphicOverlay = (function() {
     /**
-     * Constructor function for creating a new graphical overlay instance.
+     * Represents an overlay containing Footprints, whether it is 
      *
-     * @constructor
-     * @memberof GraphicOverlay
+     * @class
+     * @constructs GraphicOverlay
      * @param {GraphicOverlayOptions} options - Configuration options for the overlay.
      */
    let GraphicOverlay = function(options) {

diff --git a/src/js/shapes/Circle.js b/src/js/shapes/Circle.js
@@ -31,18 +31,12 @@
 import { Utils } from "./../Utils";
 import { GraphicOverlay } from "./../Overlay.js";
 
-/**
- * Represents an circle shape
- *
- * @namespace
- * @typedef {Object} Circle
- */
 export let Circle = (function() {
     /**
      * Constructor function for creating a new circle.
      *
-     * @constructor
-     * @memberof Circle
+     * @class
+     * @constructs Circle
      * @param {number[]} centerRaDec - right-ascension/declination 2-tuple of the circle's center in degrees
      * @param {number} radius - radius in degrees
      * @param {ShapeOptions} options - Configuration options for the circle

diff --git a/src/js/shapes/Ellipse.js b/src/js/shapes/Ellipse.js
@@ -36,8 +36,8 @@ export let Ellipse = (function() {
     /**
      * Constructor function for creating a new ellipse.
      *
-     * @constructor
-     * @memberof Ellipse
+     * @class
+     * @constructs Ellipse
      * @param {number[]} centerRaDec - right-ascension/declination 2-tuple of the ellipse's center in degrees
      * @param {number} a - half-major axis length in degrees
      * @param {number} b - half-minor axis length in degrees

diff --git a/src/js/shapes/Polyline.js b/src/js/shapes/Polyline.js
@@ -51,12 +51,6 @@ import { ProjectionEnum } from "../ProjectionEnum.js";
 * @property {string} [options.hoverColor] -  A hovered color
 */
 
-/**
- * Represents a polyline shape
- *
- * @namespace
- * @typedef {Object} Polyline
- */
 export let Polyline = (function() {
 
     function _calculateMag2ForNoSinProjections(l, view) {
@@ -106,10 +100,10 @@ export let Polyline = (function() {
     }*/
 
     /**
-     * Constructor function for creating a new polyline.
+     * Represents a polyline shape
      *
-     * @constructor
-     * @memberof Polyline
+     * @class
+     * @constructs Polyline
      * @param {Array.<number[]>} raDecArray - right-ascension/declination 2-tuple array describing the polyline's vertices in degrees
      * @param {ShapeOptions} options - Configuration options for the polyline. Additional properties:
      * @param {boolean} [options.closed=false] - Close the polyline, default to false.
@@ -348,47 +342,6 @@ export let Polyline = (function() {
                     return true;
                 };
             }
-        /*} else if (view.projection === ProjectionEnum.HPX) {
-            drawLine = (v0, v1) => {
-                const line = new Line(v0.x, v0.y, v1.x, v1.y);
-
-                if (_isAcrossCollignonZoneForHpxProjection(line, view)) {
-                    return;
-                } 
-
-                if (line.isInsideView(view.width, view.height)) {
-                    const mag2 = _calculateMag2ForNoSinProjections(line, view);
-
-                    if (mag2 < 0.1) {
-                        line.draw(ctx);
-                    }
-                }
-            };
-
-            if (this.closed && this.fill) {
-                fillPoly = (v0, v1, index) => {
-                    const line = new Line(v0.x, v0.y, v1.x, v1.y);
-
-                    if (_isAcrossCollignonZoneForHpxProjection(line, view)) {
-                        return;
-                    } 
-
-                    const mag2 = _calculateMag2ForNoSinProjections(line, view);
-
-                    if (mag2 < 0.1) {
-                        if (index === 0) {
-                            ctx.beginPath();
-                            ctx.moveTo(line.x1, line.y1);
-                        } else {
-                            ctx.lineTo(line.x1, line.y1);
-                        }
-
-                        return true;
-                    } else {
-                        return false;
-                    }
-                };
-            }*/
         } else {
             drawLine = (v0, v1) => {
                 const l = {x1: v0.x, y1: v0.y, x2: v1.x, y2: v1.y};