itowns 2.45.1 → 2.45.2-next.1

package/lib/Core/Prefab/GlobeView.d.ts

@@ -0,0 +1,65 @@
+export namespace GLOBE_VIEW_EVENTS {
+    let GLOBE_INITIALIZED: string;
+    let LAYER_ADDED: string;
+    let LAYER_REMOVED: string;
+    let COLOR_LAYERS_ORDER_CHANGED: string;
+}
+export default GlobeView;
+declare class GlobeView extends View {
+    /**
+     * Creates a view of a globe.
+     *
+     * @extends View
+     *
+     * @example <caption><b>Instance GlobeView.</b></caption>
+     * var viewerDiv = document.getElementById('viewerDiv');
+     * const placement = {
+     *     coord: new itowns.Coordinates('EPSG:4326', 2.351323, 48.856712),
+     *     range: 25000000,
+     * }
+     * var view = new itowns.GlobeView(viewerDiv, placement);
+     *
+     * @param {HTMLDivElement} viewerDiv - Where to attach the view and display it
+     * in the DOM.
+     * @param {CameraTransformOptions|Extent} placement - An object to place view
+     * @param {object} [options] - See options of {@link View}.
+     * @param {Object} [options.controls] - See options of {@link GlobeControls}
+     * @param {Object} [options.webXR] - WebXR configuration - its presence alone
+     * enable WebXR to switch on VR visualization. (optional).
+     * @param {function} [options.webXR.callback] - WebXR rendering callback (optional).
+     * @param {boolean} [options.webXR.controllers] - Enable the webXR controllers handling (optional).
+     */
+    constructor(viewerDiv: HTMLDivElement, placement?: CameraTransformOptions | Extent, options?: {
+        controls?: Object | undefined;
+        webXR?: {
+            callback?: Function | undefined;
+            controllers?: boolean | undefined;
+        } | undefined;
+    });
+    isGlobeView: boolean;
+    tileLayer: GlobeLayer;
+    controls: GlobeControls | undefined;
+    webXR: WebXR | undefined;
+    /**
+     * Add layer in viewer.
+     * The layer id must be unique.
+     *
+     * The `layer.whenReady` is a promise that resolves when
+     * the layer is done. This promise is also returned by
+     * `addLayer` allowing to chain call.
+     *
+     * The layer added is attached, by default to `GlobeLayer` (`GlobeView.tileLayer`).
+     * If you want add a unattached layer use `View#addLayer` parent method.
+     *
+     * @param {LayerOptions|Layer|GeometryLayer} layer The layer to add in view.
+     * @return {Promise} a promise resolved with the new layer object when it is fully initialized or rejected if any error occurred.
+     */
+    addLayer(layer: LayerOptions | Layer | GeometryLayer): Promise<any>;
+    getPixelsToDegrees(pixels: number | undefined, screenCoord: any): number;
+    getPixelsToDegreesFromDistance(pixels?: number, distance?: number): number;
+    getMetersToDegrees(meters?: number): number;
+}
+import View from '../../Core/View';
+import GlobeLayer from '../../Core/Prefab/Globe/GlobeLayer';
+import GlobeControls from '../../Controls/GlobeControls';
+import WebXR from '../../Renderer/WebXR';

package/lib/Core/Prefab/GlobeView.js

@@ -5,6 +5,7 @@ import { Coordinates, ellipsoidSizes } from '@itowns/geographic';
 import GlobeLayer from "./Globe/GlobeLayer.js";
 import Atmosphere from "./Globe/Atmosphere.js";
 import CameraUtils from "../../Utils/CameraUtils.js";
+import WebXR from "../../Renderer/WebXR.js";
 
 /**
  * Fires when the view is completely loaded. Controls and view's functions can be called then.
@@ -76,6 +77,10 @@ class GlobeView extends View {
    * @param {CameraTransformOptions|Extent} placement - An object to place view
    * @param {object} [options] - See options of {@link View}.
    * @param {Object} [options.controls] - See options of {@link GlobeControls}
+   * @param {Object} [options.webXR] - WebXR configuration - its presence alone
+   * enable WebXR to switch on VR visualization. (optional).
+   * @param {function} [options.webXR.callback] - WebXR rendering callback (optional).
+   * @param {boolean} [options.webXR.controllers] - Enable the webXR controllers handling (optional).
    */
   constructor(viewerDiv) {
     let placement = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
@@ -106,6 +111,10 @@ class GlobeView extends View {
 
     // GlobeView needs this.camera.resize to set perpsective matrix camera
     this.camera.resize(viewerDiv.clientWidth, viewerDiv.clientHeight);
+    if (options.webXR) {
+      this.webXR = new WebXR(this, typeof options.webXR === 'boolean' ? {} : options.webXR);
+      this.webXR.initializeWebXR();
+    }
   }
 
   /**

package/lib/Core/Prefab/Planar/PlanarLayer.d.ts

@@ -0,0 +1,38 @@
+export default PlanarLayer;
+/**
+ * @property {boolean} isPlanarLayer - Used to checkout whether this layer is a
+ * PlanarLayer. Default is true. You should not change this, as it is used
+ * internally for optimisation.
+ * @extends TiledGeometryLayer
+ */
+declare class PlanarLayer extends TiledGeometryLayer {
+    /**
+     * A {@link TiledGeometryLayer} to use with a {@link PlanarView}. It has
+     * specific method for updating and subdivising its grid.
+     *
+     * @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
+     * `THREE.Group`, but it can be anything inheriting from a `THREE.Object3d`.
+     * @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 `name, protocol, extent`, these elements will be
+     * available using `layer.name` or something else depending on the property
+     * name.
+     * @param {number} [config.maxSubdivisionLevel=5] - Maximum subdivision
+     * level for this tiled layer.
+     *
+     * @throws {Error} `object3d` must be a valid `THREE.Object3d`.
+     */
+    constructor(id: string, extent: Extent, object3d?: THREE.Object3d, config?: {
+        maxSubdivisionLevel?: number | undefined;
+    });
+    isPlanarLayer: boolean;
+    extent: Extent;
+    minSubdivisionLevel: any;
+}
+import TiledGeometryLayer from '../../../Layer/TiledGeometryLayer';
+import * as THREE from 'three';

package/lib/Core/Prefab/Planar/PlanarTileBuilder.d.ts

@@ -0,0 +1,32 @@
+import * as THREE from 'three';
+import { Coordinates, Extent } from '@itowns/geographic';
+import { ShareableExtent, TileBuilder, TileBuilderParams } from '../TileBuilder';
+/** Specialized parameters for the [PlanarTileBuilder]. */
+export interface PlanarTileBuilderParams extends TileBuilderParams {
+    crs: string;
+    uvCount?: number;
+    nbRow: number;
+}
+/**
+ * TileBuilder implementation for the purpose of generating planar
+ * tile arrangements.
+ */
+export declare class PlanarTileBuilder implements TileBuilder<PlanarTileBuilderParams> {
+    private _uvCount;
+    private _transform;
+    private _crs;
+    constructor(options: {
+        projection?: string;
+        crs: string;
+        uvCount?: number;
+    });
+    get uvCount(): number;
+    get crs(): string;
+    prepare(params: TileBuilderParams): PlanarTileBuilderParams;
+    center(extent: Extent): THREE.Vector3;
+    vertexPosition(coordinates: Coordinates): THREE.Vector3;
+    vertexNormal(): THREE.Vector3;
+    uProject(u: number, extent: Extent): number;
+    vProject(v: number, extent: Extent): number;
+    computeShareableExtent(extent: Extent): ShareableExtent;
+}

package/lib/Core/Prefab/PlanarView.d.ts

@@ -0,0 +1,33 @@
+export default PlanarView;
+declare class PlanarView extends View {
+    /**
+     * @extends View
+     *
+     * @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.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=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.
+     * @param {CameraUtils~CameraTransformOptions|Extent} [options.placement] - The
+     * {@link CameraUtils~CameraTransformOptions} to apply to view's camera or the extent it must display at
+     * initialization. By default, camera will display the view's extent (given in `extent` parameter).
+     */
+    constructor(viewerDiv: HTMLDivElement, extent: Extent, options?: {
+        noControls?: boolean | undefined;
+        controls?: Object | undefined;
+    });
+    isPlanarView: boolean;
+    controls: PlanarControls | undefined;
+    tileLayer: PlanarLayer;
+    addLayer(layer: any): Promise<any>;
+}
+import View from '../../Core/View';
+import PlanarControls from '../../Controls/PlanarControls';
+import PlanarLayer from './Planar/PlanarLayer';

package/lib/Core/Prefab/TileBuilder.d.ts

@@ -0,0 +1,63 @@
+import * as THREE from 'three';
+import { TileGeometry } from '../../Core/TileGeometry';
+import type { Extent } from '@itowns/geographic';
+import { Coordinates } from '@itowns/geographic';
+export type GpuBufferAttributes = {
+    index: THREE.BufferAttribute | null;
+    position: THREE.BufferAttribute;
+    normal: THREE.BufferAttribute;
+    uvs: THREE.BufferAttribute[];
+};
+/**
+ * Reference to a tile's extent with rigid transformations.
+ * Enables reuse of geometry, saving a bit of memory.
+ */
+export type ShareableExtent = {
+    shareableExtent: Extent;
+    quaternion: THREE.Quaternion;
+    position: THREE.Vector3;
+};
+export interface TileBuilderParams {
+    /** Whether to build the skirt. */
+    disableSkirt: boolean;
+    /** Whether to render the skirt. */
+    hideSkirt: boolean;
+    /** Number of segments (edge loops) inside tiles. */
+    segments: number;
+    /** Buffer for projected points. */
+    coordinates: Coordinates;
+    extent: Extent;
+    level: number;
+    center: THREE.Vector3;
+}
+export interface TileBuilder<SpecializedParams extends TileBuilderParams> {
+    crs: string;
+    /** Convert builder-agnostic params to specialized ones. */
+    prepare(params: TileBuilderParams): SpecializedParams;
+    /**
+     * Computes final offset of the second texture set.
+     * Only relevant in the case of more than one texture sets.
+     */
+    computeExtraOffset?: (params: SpecializedParams) => number;
+    /** Get the center of the current tile as a 3D vector. */
+    center(extent: Extent): THREE.Vector3;
+    /** Converts an x/y tile-space position to its equivalent in 3D space. */
+    vertexPosition(coordinates: Coordinates): THREE.Vector3;
+    /** Gets the geodesic normal of the last processed vertex. */
+    vertexNormal(): THREE.Vector3;
+    /** Project horizontal texture coordinate to world space. */
+    uProject(u: number, extent: Extent): number;
+    /** Project vertical texture coordinate to world space. */
+    vProject(v: number, extent: Extent): number;
+    /**
+     * Compute shareable extent to pool geometries together.
+     * The geometry of tiles on the same latitude is the same with an added
+     * rigid transform.
+     */
+    computeShareableExtent(extent: Extent): ShareableExtent;
+}
+export declare function newTileGeometry(builder: TileBuilder<TileBuilderParams>, params: TileBuilderParams): Promise<{
+    geometry: TileGeometry;
+    quaternion: THREE.Quaternion;
+    position: THREE.Vector3;
+}>;

package/lib/Core/Prefab/computeBufferTileGeometry.d.ts

@@ -0,0 +1,17 @@
+import type { TileBuilder, TileBuilderParams } from '../../Core/Prefab/TileBuilder';
+export declare function getBufferIndexSize(segments: number, noSkirt: boolean): number;
+type Option<T> = T | undefined;
+type IndexArray = Option<Uint8Array | Uint16Array | Uint32Array>;
+export type Buffers = {
+    index: IndexArray;
+    position: Float32Array;
+    normal: Float32Array;
+    uvs: [Option<Float32Array>, Option<Float32Array>];
+};
+type BufferCache = {
+    index: Exclude<IndexArray, undefined>;
+    uv: Float32Array;
+};
+/** Compute buffers describing a tile according to a builder and its params. */
+export declare function computeBuffers(builder: TileBuilder<TileBuilderParams>, params: TileBuilderParams, cache?: BufferCache): Buffers;
+export {};

package/lib/Core/Scheduler/Cache.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Cache policies for flushing. Those policies can be used when something is
+ * [set]{@link Cache.set} into the Cache, as the lifetime property.
+ */
+export type CACHE_POLICIES = {
+    /**
+     * - The entry is never flushed, except when the
+     * `all` flag is set to `true` when calling {@link Cache.flush}.
+     */
+    INFINITE: number;
+    /**
+     * - Shortcut for texture resources. Time is 15 minutes.
+     */
+    TEXTURE: number;
+    /**
+     * - Shortcut for geometry resources. Time is 15 minutes.
+     * minutes.
+     */
+    GEOMETRY: number;
+};
+export namespace CACHE_POLICIES {
+    let INFINITE: number;
+    let TEXTURE: number;
+    let GEOMETRY: number;
+}

package/lib/Core/Scheduler/CancelledCommandException.d.ts

@@ -0,0 +1,12 @@
+export default CancelledCommandException;
+/**
+ * Custom error thrown when cancelling commands. Allows the caller to act differently if needed.
+ * @class
+ * @param {Command} command
+ */
+declare class CancelledCommandException {
+    constructor(command: any);
+    command: any;
+    isCancelledCommandException: boolean;
+    toString(): string;
+}

package/lib/Core/Scheduler/Scheduler.d.ts

@@ -0,0 +1,106 @@
+export default Scheduler;
+/**
+ * The Scheduler is in charge of managing the [Providers]{@link Provider} that
+ * are used to gather resources needed to display the layers on a {@link View}.
+ * There is only one instance of a Scheduler per webview, and it is instanciated
+ * with the creation of the first view.
+ *
+ * @constructor
+ */
+declare function Scheduler(): void;
+declare class Scheduler {
+    defaultQueue: {
+        queue(command: any): void;
+        storages: Map<any, any>;
+        counters: {
+            executing: number;
+            executed: number;
+            failed: number;
+            cancelled: number;
+            pending: number;
+        };
+        execute(cmd: any, provider: any): any;
+    };
+    hostQueues: Map<any, any>;
+    providers: {};
+    maxCommandsPerHost: number;
+    initDefaultProviders(): void;
+    runCommand(command: any, queue: any, executingCounterUpToDate: any): void;
+    execute(command: any): any;
+    /**
+     * A Provider has the responsability to handle protocols and datablobs. Given a
+     * data request (see {@link Provider#executeCommand} for details about this
+     * request), it fetches serialized datasets, file content or even file chunks.
+     *
+     * @interface Provider
+     */
+    /**
+     * When adding a layer to a view, some preprocessing can be done on it, before
+     * fetching or creating resources attached to it. For example, in the WMTS and
+     * WFS providers (included in iTowns), default options to the layer are added if
+     * some are missing.
+     *
+     * @param {Layer} layer
+     * @param {View} [view]
+     * @param {Scheduler} [scheduler]
+     * @param {Layer} [parentLayer]
+     */
+    /**
+     * In the {@link Scheduler} loop, this function is called every time the layer
+     * needs new information about itself. For tiled layers, it gets the necessary
+     * tiles, given the current position of the camera on the map. For simple layers
+     * like a GPX trace, it gets the data once.
+     * <br><br>
+     * It passes a `command` object as a parameter, with the `view` and the `layer`
+     * always present. The other parameters are optional.
+     *
+     * @function
+     * @name Provider#executeCommand
+     *
+     * @param {Object} command
+     * @param {View} command.view
+     * @param {Layer} command.layer
+     * @param {TileMesh} [command.requester] - Every layer is attached to a tile.
+     * @param {number} [command.targetLevel] - The target level is used when there
+     * is a tiled layer, such as WMTS or TMS, but not in case like a GPX layer.
+     *
+     * @return {Promise} The {@link Scheduler} always expect a Promise as a result,
+     * resolving to an object containing sufficient information for the associated
+     * processing to the current layer. For example, see the
+     * [LayeredMaterialNodeProcessing#updateLayeredMaterialNodeElevation]{@link
+     * https://github.com/iTowns/itowns/blob/master/src/Process/LayeredMaterialNodeProcessing.js}
+     * class or other processing class.
+     */
+    /**
+     * Adds a provider for a specified protocol. The provider will be used when
+     * executing the queue to provide resources. See {@link Provider} for more
+     * informations.
+     * By default, some protocols are already set in iTowns: WMTS, WMS, WFS, TMS,
+     * XYZ, PotreeConverter, Rasterizer, 3D-Tiles and Static.
+     * <br><br>
+     * Warning: if the specified protocol has already a provider attached to it, the
+     * current provider will be overwritten by the given provider.
+     *
+     * @param {string} protocol - The name of the protocol to add. This is the
+     * `protocol` parameter put inside the configuration when adding a layer. The
+     * capitalization of the name is not taken into account here.
+     * @param {Provider} provider - The provider to link to the protocol, that must
+     * respect the {@link Provider} interface description.
+     *
+     * @throws {Error} an error if any method of the {@link Provider} is not present
+     * in the provider.
+     */
+    addProtocolProvider(protocol: string, provider: Provider): void;
+    /**
+     * Get a specific {@link Provider} given a particular protocol.
+     *
+     * @param {string} protocol
+     *
+     * @return {Provider}
+     */
+    getProtocolProvider(protocol: string): Provider;
+    commandsWaitingExecutionCount(): number;
+    commandsRunningCount(): number;
+    resetCommandsCount(type: any): any;
+    deQueue(queue: any): any;
+}