doc: update some deprecated doc

docs/config.json

@@ -99,7 +99,8 @@
             ],
 
             "Renderer": [
-                "OrientedImageMaterial"
+                "OrientedImageMaterial",
+                "Camera"
             ],
 
             "3D Tiles": [

examples/misc_orthographic_camera.html

@@ -48,7 +48,7 @@
 
             // instantiate PlanarView with an orthographic camera
             const view = new itowns.PlanarView(viewerDiv, extent, {
-                cameraType: itowns.CAMERA_TYPE.ORTHOGRAPHIC,
+                camera: { type: itowns.CAMERA_TYPE.ORTHOGRAPHIC },
             });
             setupLoadingScreen(viewerDiv, view);
 

examples/view_2d_map.html

@@ -31,7 +31,7 @@
             // By default itowns' tiles geometry have a "skirt" (ie they have a height),
             // but in case of orthographic we don't need this feature, so disable it
             var view = new itowns.PlanarView(viewerDiv, extent, { disableSkirt: true, maxSubdivisionLevel: 10,
-                cameraType: itowns.CAMERA_TYPE.ORTHOGRAPHIC,
+                camera: { type: itowns.CAMERA_TYPE.ORTHOGRAPHIC },
                 controls: {
                     // Faster zoom in/out speed
                     zoomInFactor: 1,

src/Controls/GlobeControls.js

@@ -147,9 +147,8 @@ let previous;
  *
  * @class      GlobeControls
  * @param      {GlobeView}  view the view where the control will be used
- * @param      {object} placement
- * @param      {Coordinates}  placement.targetCoordinate the target looked by camera, at initialization
- * @param      {number}  placement.range distance between the target looked and camera, at initialization
+ * @param      {CameraTransformOptions} placement   the camera placement options at initialisation, see
+ * {@link CameraTransformOptions} in {@link CameraUtils}.
  * @param      {object}  options
  * @param      {number}  options.zoomSpeed Speed zoom with mouse
  * @param      {number}  options.rotateSpeed Speed camera rotation in orbit and panoramic mode
@@ -1162,7 +1161,7 @@ class GlobeControls extends THREE.EventDispatcher {
      * @param      {number}   [params.zoom]   zoom
      * @param      {number}   [params.scale]   scale
      * @param      {boolean}  isAnimated  Indicates if animated
-     * @return     {Promise}  A promise that resolves when transformation is opened
+     * @return     {Promise}  A promise that resolves when transformation is complete
      */
     lookAtCoordinate(params = {}, isAnimated = this.isAnimationEnabled()) {
         if (params.zoom) {

src/Core/Prefab/PlanarView.js

@@ -15,19 +15,19 @@ class PlanarView extends View {
      * @example <caption><b>Enable WebGl 1.0 instead of WebGl 2.0.</b></caption>
      * var viewerDiv = document.getElementById('viewerDiv');
      * const extent = new Extent('EPSG:3946', 1837816.94334, 1847692.32501, 5170036.4587, 5178412.82698);
-     * var view = new itowns.GlobeView(viewerDiv, extent, {  renderer: { isWebGL2: false } });
+     * var view = new itowns.PlanarView(viewerDiv, extent, {  renderer: { isWebGL2: false } });
      *
      * @example <caption><b>Instance with placement on the ground.</b></caption>
      * var viewerDiv = document.getElementById('viewerDiv');
      * const extent = new Extent('EPSG:3946', 1837816.94334, 1847692.32501, 5170036.4587, 5178412.82698);
-     * var view = new itowns.GlobeView(viewerDiv, extent, { placement: { heading: -49.6, range: 6200, tilt: 17 } });
+     * var view = new itowns.PlanarView(viewerDiv, extent, { placement: { heading: -49.6, range: 6200, tilt: 17 } });
      *
      * @param {HTMLDivElement} viewerDiv - Where to attach the view and display it
      * in the DOM.
      * @param {Extent} extent - The ground extent.
      * @param {object=} options - See options of {@link View}.
-     * @param {boolean} [options.noControls] - If true, no controls are associated to the view.
-     * @param {object=} [options.controls] - options for the PlanarControls associated to the view, if
+     * @param {boolean} [options.noControls=false] - If true, no controls are associated to the view.
+     * @param {object=} [options.controls] - options for the {@link PlanarControls} associated to the view, if
      * `options.noControls` is false.
      */
     constructor(viewerDiv, extent, options = {}) {
@@ -36,8 +36,8 @@ class PlanarView extends View {
         // If an orthographic camera is requested (by options.cameraType), the extent height is passed in options when
         // calling view constructor. Doing so allows Camera constructor (called in view constructor) to access it, and
         // set the frustrum in order to see the total extent height.
-        if (options.cameraType === CAMERA_TYPE.ORTHOGRAPHIC) {
-            options.orthoExtent = extent.dimensions().y;
+        if (options.camera && options.camera.type === CAMERA_TYPE.ORTHOGRAPHIC) {
+            options.camera.orthoExtent = extent.dimensions().y;
         }
         // Setup View
         super(extent.crs, viewerDiv, options);

src/Core/View.js

@@ -120,11 +120,25 @@ class View extends THREE.EventDispatcher {
     /**
      * Constructs an Itowns View instance
      *
+     * @example <caption><b>Create a view with a custom Three.js camera.</b></caption>
+     * var viewerDiv = document.getElementById('viewerDiv');
+     * var customCamera = itowns.THREE.PerspectiveCamera();
+     * var view = itowns.View('EPSG:4326', viewerDiv, { camera: { cameraThree: customCamera } });
+     *
+     * @example <caption><b>Create a view with an orthographic camera, and grant it with Three.js custom controls.</b></caption>
+     * var viewerDiv = document.getElementById('viewerDiv');
+     * var view = itowns.View('EPSG:4326', viewerDiv, { camera: { type: itowns.CAMERA_TYPE.ORTHOGRAPHIC } });
+     * var customControls = itowns.THREE.OrbitControls(view.camera.camera3D, viewerDiv);
+     *
+     * @example <caption><b>Enable WebGl 1.0 instead of WebGl 2.0.</b></caption>
+     * var viewerDiv = document.getElementById('viewerDiv');
+     * const extent = new Extent('EPSG:3946', 1837816.94334, 1847692.32501, 5170036.4587, 5178412.82698);
+     * var view = new itowns.View('EPSG:4326', viewerDiv, {  renderer: { isWebGL2: false } });
+     *
      * @param {string} crs - The default CRS of Three.js coordinates. Should be a cartesian CRS.
      * @param {HTMLElement} viewerDiv - Where to instanciate the Three.js scene in the DOM
      * @param {Object=} options - Optional properties.
-     * @param {Camera}  [options.camera] - A camera to use with the view.
-     * @param {CAMERA_TYPE} [options.cameraType=CAMERA_TYPE.PERSPECTIVE] - The type of the camera (`CAMERA_TYPE.PERSPECTIVE` or `CAMERA_TYPE.ORTHOGRAPHIC`).
+     * @param {object} [options.camera] - Options for the camera associated to the view. See {@link Camera} options.
      * @param {?MainLoop} options.mainLoop - {@link MainLoop} instance to use, otherwise a default one will be constructed
      * @param {?(WebGLRenderer|object)} options.renderer - {@link WebGLRenderer} instance to use, otherwise
      * a default one will be constructed. In this case, if options.renderer is an object, it will be used to
@@ -167,7 +181,7 @@ class View extends THREE.EventDispatcher {
             this.referenceCrs,
             this.mainLoop.gfxEngine.getWindowSize().x,
             this.mainLoop.gfxEngine.getWindowSize().y,
-            options);
+            options.camera);
 
         this._frameRequesters = { };
         this._layers = [];

src/Renderer/Camera.js

@@ -1,11 +1,14 @@
-/**
- * Wrapper around three.js camera to expose some geographic helpers.
- */
-
 import * as THREE from 'three';
 import Coordinates from 'Core/Geographic/Coordinates';
 import DEMUtils from 'Utils/DEMUtils';
 
+/**
+ * @typedef     {object}    Camera~CAMERA_TYPE
+ * Stores the different types of camera usable in iTowns.
+ *
+ * @property    {number}    PERSPECTIVE     Perspective type of camera
+ * @property    {number}    ORTHOGRAPHIC    Orthographic type of camera
+ */
 export const CAMERA_TYPE = {
     PERSPECTIVE: 0,
     ORTHOGRAPHIC: 1,
@@ -59,16 +62,35 @@ function updatePreSse(camera, height, fov) {
     }
 }
 
+/**
+ * Wrapper around Three.js camera to expose some geographic helpers.
+ *
+ * @param   {string}                crs                                     The camera's coordinate projection system
+ * @param   {number}                width                                   The width (in pixels) of the view the camera is
+ * associated to.
+ * @param   {number}                height                                  The height (in pixels) of the view the camera is
+ * associated to.
+ * @param   {object}                [options]                               Options for the camera.
+ * @param   {THREE.Camera}          [options.cameraThree]                   A custom Three.js camera object to wrap around.
+ * @param   {Camera~CAMERA_TYPE}    [options.type=CAMERA_TYPE.PERSPECTIVE]  The type of the camera. See {@link CAMERA_TYPE}.
+ * @param   {number}                [options.orthoExtent=50]                The height of the extent that a camera from type
+ * `CAMERA_TYPE.ORTHOGRAPHIC` must cover initially.
+ * @constructor
+ */
 function Camera(crs, width, height, options = {}) {
     Object.defineProperty(this, 'crs', { get: () => crs });
 
-    if (options.camera) {
-        this.camera3D = options.camera;
+    if (options.isCamera) {
+        console.warn('options.camera parameter is deprecated. Use options.camera.cameraThree to place a custom ' +
+            'camera as a parameter. See the documentation of Camera.');
+        this.camera3D = options;
+    } else if (options.cameraThree) {
+        this.camera3D = options.cameraThree;
     } else {
         const aspect = width / height;
         const orthoExtent = options.orthoExtent || 50;
 
-        switch (options.cameraType) {
+        switch (options.type) {
             case CAMERA_TYPE.ORTHOGRAPHIC:
                 this.camera3D = new THREE.OrthographicCamera(
                     orthoExtent * aspect / -2, orthoExtent * aspect / 2,

test/unit/planarControls.js

@@ -12,7 +12,7 @@ describe('Planar Controls', function () {
     const extent = new Extent('EPSG:4326', -100, 100, -100, 100);
 
     const viewPerspective = new PlanarView(renderer.domElement, extent, { renderer });
-    const viewOrtho = new PlanarView(renderer.domElement, extent, { renderer, cameraType: CAMERA_TYPE.ORTHOGRAPHIC });
+    const viewOrtho = new PlanarView(renderer.domElement, extent, { renderer, camera: { type: CAMERA_TYPE.ORTHOGRAPHIC } });
 
     const controlsPerspective = viewPerspective.controls;
     const controlsOrtho = viewOrtho.controls;

test/unit/view.js

@@ -132,15 +132,15 @@ describe('Viewer', function () {
     it('Should create the correct camera from type', () => {
         const view = new View('EPSG:4326', renderer.domElement, {
             renderer,
-            cameraType: CAMERA_TYPE.ORTHOGRAPHIC,
+            camera: { type: CAMERA_TYPE.ORTHOGRAPHIC },
         });
         assert.ok(view.camera.camera3D.isOrthographicCamera);
     });
     it('should create the correct camera from specific camera', () => {
         const camera = new THREE.PerspectiveCamera(50, 0.5);
         const view = new View('', renderer.domElement, {
             renderer,
-            camera,
+            camera: { cameraThree: camera },
         });
         assert.equal(view.camera.camera3D, camera);
     });