From d16c796f1828b0d3609d63b7d9508c5fcbee0415 Mon Sep 17 00:00:00 2001 From: mgermerie <73115044+mgermerie@users.noreply.github.com> Date: Thu, 14 Jan 2021 14:43:57 +0100 Subject: [PATCH] doc: update some deprecated doc --- docs/config.json | 3 ++- examples/misc_orthographic_camera.html | 2 +- examples/view_2d_map.html | 2 +- src/Controls/GlobeControls.js | 7 +++-- src/Core/Prefab/PlanarView.js | 12 ++++----- src/Core/View.js | 20 +++++++++++--- src/Renderer/Camera.js | 36 +++++++++++++++++++++----- test/unit/planarControls.js | 2 +- test/unit/view.js | 4 +-- 9 files changed, 62 insertions(+), 26 deletions(-) diff --git a/docs/config.json b/docs/config.json index ae5542b886..aa3334c911 100644 --- a/docs/config.json +++ b/docs/config.json @@ -99,7 +99,8 @@ ], "Renderer": [ - "OrientedImageMaterial" + "OrientedImageMaterial", + "Camera" ], "3D Tiles": [ diff --git a/examples/misc_orthographic_camera.html b/examples/misc_orthographic_camera.html index 3cfd7f9de5..c7c34fc62b 100644 --- a/examples/misc_orthographic_camera.html +++ b/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); diff --git a/examples/view_2d_map.html b/examples/view_2d_map.html index 65f4e62ca2..c587dc0e7c 100644 --- a/examples/view_2d_map.html +++ b/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, diff --git a/src/Controls/GlobeControls.js b/src/Controls/GlobeControls.js index 235e45686e..c4b7dcd9ca 100644 --- a/src/Controls/GlobeControls.js +++ b/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) { diff --git a/src/Core/Prefab/PlanarView.js b/src/Core/Prefab/PlanarView.js index 9c1063835c..58dc98b9ed 100644 --- a/src/Core/Prefab/PlanarView.js +++ b/src/Core/Prefab/PlanarView.js @@ -15,19 +15,19 @@ class PlanarView extends View { * @example Enable WebGl 1.0 instead of WebGl 2.0. * 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 Instance with placement on the ground. * 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); diff --git a/src/Core/View.js b/src/Core/View.js index 344f5e1634..25bb043deb 100644 --- a/src/Core/View.js +++ b/src/Core/View.js @@ -120,11 +120,25 @@ class View extends THREE.EventDispatcher { /** * Constructs an Itowns View instance * + * @example Create a view with a custom Three.js camera. + * var viewerDiv = document.getElementById('viewerDiv'); + * var customCamera = itowns.THREE.PerspectiveCamera(); + * var view = itowns.View('EPSG:4326', viewerDiv, { camera: { cameraThree: customCamera } }); + * + * @example Create a view with an orthographic camera, and grant it with Three.js custom controls. + * 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 Enable WebGl 1.0 instead of WebGl 2.0. + * 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 = []; diff --git a/src/Renderer/Camera.js b/src/Renderer/Camera.js index 16786672eb..f13855e189 100644 --- a/src/Renderer/Camera.js +++ b/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, diff --git a/test/unit/planarControls.js b/test/unit/planarControls.js index 40d5005134..b4a13b0f79 100644 --- a/test/unit/planarControls.js +++ b/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; diff --git a/test/unit/view.js b/test/unit/view.js index b7d0fa397d..ae6bdca343 100644 --- a/test/unit/view.js +++ b/test/unit/view.js @@ -132,7 +132,7 @@ 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); }); @@ -140,7 +140,7 @@ describe('Viewer', function () { 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); });