add doc

jsdoc-config.json

@@ -14,9 +14,17 @@
             "src/Core/Geographic/Coordinates.js",
             "src/Core/Layer/Layer.js",
             "src/Core/Prefab/GlobeView.js",
+            "src/Core/Prefab/Globe/GlobeLayer.js",
+            "src/Core/Prefab/Panorama/PanoramaLayer.js",
+            "src/Core/Prefab/Planar/PlanarLayer.js",
             "src/Core/Scheduler/Cache.js",
             "src/Core/Scheduler/Scheduler.js",
 
+            "src/Layer/ColorLayer.js",
+            "src/Layer/ElevationLayer.js",
+            "src/Layer/GeometryLayer.js",
+            "src/Layer/TiledGeometryLayer.js",
+
             "src/Parser/GeoJsonParser.js",
             "src/Parser/GpxParser.js",
             "src/Parser/VectorTileParser.js",

src/Core/Layer/Layer.js

@@ -1,43 +1,36 @@
 import * as THREE from 'three';
 import { STRATEGY_MIN_NETWORK_TRAFFIC } from '../../Layer/LayerUpdateStrategy';
 
-/**
- * Fires when layer sequence change (meaning when the order of the layer changes in the view)
- * @event Layer#sequence-property-changed
- * @property new {object}
- * @property new.sequence {number} the new value of the layer sequence
- * @property previous {object}
- * @property previous.sequence {number} the previous value of the layer sequence
- * @property target {Layer} dispatched on layer
- * @property type {string} sequence-property-changed
-*/
-/**
- * Fires when layer opacity change
- * @event Layer#opacity-property-changed
- * @property new {object}
- * @property new.opacity {object} the new value of the layer opacity
- * @property previous {object}
- * @property previous.opacity {object} the previous value of the layer opacity
- * @property target {Layer} dispatched on layer
- * @property type {string} opacity-property-changed
-*/
-/**
- * Fires when layer visibility change
- * @event Layer#visible-property-changed
- * @property new {object}
- * @property new.visible {object} the new value of the layer visibility
- * @property previous {object}
- * @property previous.visible {object} the previous value of the layer visibility
- * @property target {Layer} dispatched on layer
- * @property type {string} visible-property-changed
-*/
-
 class Layer extends THREE.EventDispatcher {
     /**
-     * Don't use directly constructor to instance a new Layer
-     * use addLayer in {@link View}
+     * Don't use directly constructor to instance a new Layer. Instead, use
+     * another available type of Layer, implement a new one inheriting from this
+     * one or use {@link View#addLayer}.
+     *
+     * @constructor
+     * @protected
+     *
+     * @param {string} id - The id of the layer, that should be unique. It is
+     * not mandatory, but an error will be emitted if this layer is added a
+     * {@link View} that already has a layer going by that id.
+     * @param {string} type - The type of the layer, used to determine
+     * operations to do on a layer later in the rendering loop. There are three
+     * type of layers in itowns:
+     * <ul>
+     *  <li><code>color</code>, used for simple layer containing a texture</li>
+     *  <li><code>elevation</code>, used for adding an elevation to the globe or
+     *  plane the layer is attached to</li>
+     *  <li><code>geometry</code>, used for complex layer containing meshes,
+     *  like a WFS layer with extruded buildings</li>
+     * <ul>
+     * @param {Object} [config] - Optional configuration, all elements in it
+     * will be merged as is in the layer. For example, if the configuration
+     * contains three elements <code>name, protocol, extent</code>, these
+     * elements will be available using <code>layer.name</code> or something
+     * else depending on the property name.
+     *
      * @example
-     * // add and create a new Layer
+     * // Add and create a new Layer
      * const newLayer = view.addLayer({options});
      *
      * // Change layer's visibilty
@@ -54,11 +47,6 @@ class Layer extends THREE.EventDispatcher {
      * const layerToListen = view.getLayers(layer => layer.id == 'idLayerToListen')[0];
      * layerToListen.addEventListener('visible-property-changed', (event) => console.log(event));
      * layerToListen.addEventListener('opacity-property-changed', (event) => console.log(event));
-     * @constructor
-     * @protected
-     * @param {string} id
-     * @param {string} type
-     * @param {Object} [config]
      */
     constructor(id, type, config = {}) {
         super();
@@ -96,6 +84,37 @@ class Layer extends THREE.EventDispatcher {
         this.defineLayerProperty('frozen', false);
     }
 
+    /**
+     * Defines a property for this layer, with a default value and a callback
+     * executed when the property changes.
+     * <br><br>
+     * When changing the property, it also emits an event, named following this
+     * convention: <code>${propertyName}-property-changed</code>, with
+     * <code>${propertyName}</code> being replaced by the name of the property.
+     * For example, if the added property name is <code>frozen</code>, it will
+     * emit a <code>frozen-property-changed</code>.
+     * <br><br>
+     * The emitted event has some properties assigned to it:
+     * <pre>
+     * event = {
+     *     new: {
+     *         ${propertyName}: * // the new value of the property
+     *     },
+     *     previous: {
+     *         ${propertyName}: * // the previous value of the property
+     *     },
+     *     target: Layer // the layer it has been dispatched from
+     *     type: string // the name of the emitted event
+     * }
+     * </pre>
+     *
+     * @param {string} propertyName - The name of the property, also used in
+     * the emitted event name.
+     * @param {*} defaultValue - The default set value.
+     * @param {function} [onChange] - The function executed when the property is
+     * changed. Parameters are the layer the property is defined on, and the
+     * name of the property.
+     */
     defineLayerProperty(propertyName, defaultValue, onChange) {
         const existing = Object.getOwnPropertyDescriptor(this, propertyName);
         if (!existing || !existing.set) {

src/Core/Prefab/Globe/GlobeLayer.js

@@ -5,22 +5,40 @@ import TiledGeometryLayer from '../../../Layer/TiledGeometryLayer';
 import { processTiledGeometryNode } from '../../../Process/TiledNodeProcessing';
 import { globeCulling, preGlobeUpdate, globeSubdivisionControl, globeSchemeTileWMTS, globeSchemeTile1 } from '../../../Process/GlobeTileProcessing';
 import BuilderEllipsoidTile from './BuilderEllipsoidTile';
-import Picking from '../../Picking';
 
 class GlobeLayer extends TiledGeometryLayer {
     /**
-     * A geometry layer to be used only with a {@link GlobeView}.
+     * A {@link TiledGeometryLayer} to use with a {@link GlobeView}. It has
+     * specific method for updating and subdivising its grid.
      *
      * @constructor
+     * @extends TiledGeometryLayer
      *
-     * @param {string} id
-     * @param {THREE.Object3D} object3d
-     * @param {Object} config
-     * @param {number} [config.maxSubdivisionLevel=18]
-     * @param {number} [config.sseSubdivisionThreshold=1]
-     * @param {number} [config.maxDeltaElevationLevel=4]
+     * @param {string} id - The id of the layer, that should be unique. It is
+     * not mandatory, but an error will be emitted if this layer is added a
+     * {@link View} that already has a layer going by that id.
+     * @param {THREE.Object3d} [object3d=THREE.Group] - The object3d used to
+     * contain the geometry of the TiledGeometryLayer. It is usually a
+     * <code>THREE.Group</code>, but it can be anything inheriting from a
+     * <code>THREE.Object3d</code>.
+     * @param {Object} [config] - Optional configuration, all elements in it
+     * will be merged as is in the layer. For example, if the configuration
+     * contains three elements <code>name, protocol, extent</code>, these
+     * elements will be available using <code>layer.name</code> or something
+     * else depending on the property name.
+     * @param {number} [config.maxSubdivisionLevel=18] - Maximum subdivision
+     * level for this tiled layer.
+     * @param {number} [config.sseSubdivisionThreshold=1] - Threshold level for
+     * the SSE.
+     * @param {number} [config.maxDeltaElevationLevel=4] - Maximum delta between
+     * two elevations tile.
+     *
+     * @throws {Error} <code>object3d</code> must be a valid
+     * <code>THREE.Object3d</code>.
      */
     constructor(id, object3d, config = {}) {
+        config.defaultPickingRadius = 5;
+
         super(id, object3d || new THREE.Group(), config);
 
         // Configure tiles
@@ -44,10 +62,6 @@ class GlobeLayer extends TiledGeometryLayer {
         this.builder = new BuilderEllipsoidTile();
     }
 
-    pickObjectsAt(view, mouse, radius = 5) {
-        return Picking.pickTilesAt(view, mouse, radius, this);
-    }
-
     preUpdate(context, changeSources) {
         preGlobeUpdate(context, this);
 

src/Core/Prefab/Panorama/PanoramaLayer.js

@@ -9,17 +9,33 @@ import ProjectionType from './Constants';
 
 class PanoramaLayer extends TiledGeometryLayer {
     /**
-     * A geometry layer to be used only with a {@link PanoramaView}.
+     * A {@link TiledGeometryLayer} to use with a {@link PanoramaView}. It has
+     * specific method for updating and subdivising its grid.
      *
      * @constructor
+     * @extends TiledGeometryLayer
      *
-     * @param {string} id
-     * @param {Coordinates} coordinates
-     * @param {string} type
-     * @param {Object} options
-     * @param {THREE.Object3D} options.object3d
-     * @param {number} options.ratio=1
-     * @param {number} [options.maxSubdivisionLevel=10]
+     * @param {string} id - The id of the layer, that should be unique. It is
+     * not mandatory, but an error will be emitted if this layer is added a
+     * {@link View} that already has a layer going by that id.
+     * @param {Coordinates} coordinates - The coordinates of the origin of the
+     * panorama.
+     * @param {THREE.Object3d} [object3d=THREE.Group] - The object3d used to
+     * contain the geometry of the TiledGeometryLayer. It is usually a
+     * <code>THREE.Group</code>, but it can be anything inheriting from a
+     * <code>THREE.Object3d</code>.
+     * @param {Object} [config] - Optional configuration, all elements in it
+     * will be merged as is in the layer. For example, if the configuration
+     * contains three elements <code>name, protocol, extent</code>, these
+     * elements will be available using <code>layer.name</code> or something
+     * else depending on the property name.
+     * @param {number} [config.maxSubdivisionLevel=10] - Maximum subdivision
+     * level for this tiled layer.
+     * @param {number} [config.ratio=1] - Ratio for building the panorama
+     * sphere.
+     *
+     * @throws {Error} <code>object3d</code> must be a valid
+     * <code>THREE.Object3d</code>.
      */
     constructor(id, coordinates, type, options) {
         super(id, options.object3d || new THREE.Group(), options);
@@ -90,7 +106,7 @@ class PanoramaLayer extends TiledGeometryLayer {
         }
 
         this.update = processTiledGeometryNode(panoramaCulling, subdivision);
-        this.builder = new PanoramaTileBuilder(type, options.ratio);
+        this.builder = new PanoramaTileBuilder(type, options.ratio || 1);
         this.segments = 8;
         this.quality = 0.5;
     }

src/Core/Prefab/Planar/PlanarLayer.js

@@ -8,18 +8,34 @@ import PlanarTileBuilder from './PlanarTileBuilder';
 
 class PlanarLayer extends TiledGeometryLayer {
     /**
-     * A geometry layer to be used only with a {@link PlanarView}.
+     * A {@link TiledGeometryLayer} to use with a {@link PlanarView}. It has
+     * specific method for updating and subdivising its grid.
      *
      * @constructor
+     * @extends TiledGeometryLayer
      *
-     * @param {string} id
-     * @param {THREE.Object3D} object3d
-     * @param {Extent} extent - the extent to define the layer within
-     * @param {Object} options
-     * @param {number} [options.maxSubdivisionLevel=5]
-     * @param {number} [options.maxDeltaElevationLevel=4]
+     * @param {string} id - The id of the layer, that should be unique. It is
+     * not mandatory, but an error will be emitted if this layer is added a
+     * {@link View} that already has a layer going by that id.
+     * @param {Extent} extent - The extent to define the layer within.
+     * @param {THREE.Object3d} [object3d=THREE.Group] - The object3d used to
+     * contain the geometry of the TiledGeometryLayer. It is usually a
+     * <code>THREE.Group</code>, but it can be anything inheriting from a
+     * <code>THREE.Object3d</code>.
+     * @param {Object} [config] - Optional configuration, all elements in it
+     * will be merged as is in the layer. For example, if the configuration
+     * contains three elements <code>name, protocol, extent</code>, these
+     * elements will be available using <code>layer.name</code> or something
+     * else depending on the property name.
+     * @param {number} [config.maxSubdivisionLevel=5] - Maximum subdivision
+     * level for this tiled layer.
+     * @param {number} [config.maxDeltaElevationLevel=4] - Maximum delta between
+     * two elevations tile.
+     *
+     * @throws {Error} <code>object3d</code> must be a valid
+     * <code>THREE.Object3d</code>.
      */
-    constructor(id, object3d, extent, options = {}) {
+    constructor(id, extent, object3d, options = {}) {
         super(id, object3d || new THREE.Group(), options);
 
         this.extent = extent;

src/Layer/ColorLayer.js

@@ -1,7 +1,61 @@
 import Layer from '../Core/Layer/Layer';
 import { updateLayeredMaterialNodeImagery } from '../Process/LayeredMaterialNodeProcessing';
 
+/**
+ * Fires when the visiblity of the layer has changed.
+ * @event ColorLayer#visible-property-changed
+ */
+/**
+ * Fires when the opacity of the layer has changed.
+ * @event ColorLayer#opacity-property-changed
+ */
+/**
+ * Fires when the sequence of the layer has changed, meaning that the order of
+ * the layer changed in the view it is attached to.
+ * @event ColorLayer#sequence-property-changed
+ */
+
 class ColorLayer extends Layer {
+    /**
+     * A simple layer, usually managing a texture to display on a view. For example,
+     * it can be an aerial view of the ground or a simple transparent layer with the
+     * roads displayed.
+     *
+     * @constructor
+     * @extends Layer
+     *
+     * @param {string} id - The id of the layer, that should be unique. It is
+     * not mandatory, but an error will be emitted if this layer is added a
+     * {@link View} that already has a layer going by that id.
+     * @param {Object} [config] - Optional configuration, all elements in it
+     * will be merged as is in the layer. For example, if the configuration
+     * contains three elements <code>name, protocol, extent</code>, these
+     * elements will be available using <code>layer.name</code> or something
+     * else depending on the property name.
+     *
+     * @example
+     * // Create a ColorLayer
+     * const color = new ColorLayer('roads', {
+     *     url: 'http://server.geo/wmts/SERVICE=WMTS&TILEMATRIX=%TILEMATRIX&TILEROW=%ROW&TILECOL=%COL',
+     *     protocol: 'wmts',
+     *     format: 'image/png',
+     *     transparent: true
+     * });
+     *
+     * // Add the layer
+     * view.addLayer(color);
+     *
+     * @example
+     * // Add and create a ColorLayer
+     * view.addLayer({
+     *     id: 'roads',
+     *     type: 'color',
+     *     url: 'http://server.geo/wmts/SERVICE=WMTS&TILEMATRIX=%TILEMATRIX&TILEROW=%ROW&TILECOL=%COL',
+     *     protocol: 'wmts',
+     *     format: 'image/png',
+     *     transparent: true
+     * });
+     */
     constructor(id, config) {
         super(id, 'color', config);
 

src/Layer/ElevationLayer.js

@@ -2,6 +2,43 @@ import Layer from '../Core/Layer/Layer';
 import { updateLayeredMaterialNodeElevation } from '../Process/LayeredMaterialNodeProcessing';
 
 class ElevationLayer extends Layer {
+    /**
+     * A simple layer, managing an elevation texture to add some reliefs on the
+     * plane or globe view for example.
+     *
+     * @constructor
+     * @extends Layer
+     *
+     * @param {string} id - The id of the layer, that should be unique. It is
+     * not mandatory, but an error will be emitted if this layer is added a
+     * {@link View} that already has a layer going by that id.
+     * @param {Object} [config] - Optional configuration, all elements in it
+     * will be merged as is in the layer. For example, if the configuration
+     * contains three elements <code>name, protocol, extent</code>, these
+     * elements will be available using <code>layer.name</code> or something
+     * else depending on the property name.
+     *
+     * @example
+     * // Create an ElevationLayer
+     * const elevation = new ElevationLayer('IGN_MNT', {
+     *     url: 'http://server.geo/wmts/SERVICE=WMTS&TILEMATRIX=%TILEMATRIX&TILEROW=%ROW&TILECOL=%COL',
+     *     protocol: 'wmts',
+     *     format: 'image/x-bil;bits=32',
+     * });
+     *
+     * // Add the layer
+     * view.addLayer(elevation);
+     *
+     * @example
+     * // Add and create an ElevationLayer
+     * view.addLayer({
+     *     id: 'IGN_MNT',
+     *     type: 'elevation',
+     *     url: 'http://server.geo/wmts/SERVICE=WMTS&TILEMATRIX=%TILEMATRIX&TILEROW=%ROW&TILECOL=%COL',
+     *     protocol: 'wmts',
+     *     format: 'image/x-bil;bits=32',
+     * });
+     */
     constructor(id, config) {
         super(id, 'elevation', config);
     }