itowns 2.45.1 → 2.45.2-next.0

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;
+}

package/lib/Core/Style.d.ts

@@ -0,0 +1,248 @@
+export function readExpression(property: any, ctx: any): any;
+/**
+ * StyleContext stores metadata of one FeatureGeometry that are needed for its style computation:
+ * type of feature and what is needed (fill, stroke or draw a point, etc.) as well as where to get its
+ * properties and its coordinates (for base_altitude).
+ *
+ * @property {number}               zoom Current zoom to display the FeatureGeometry.
+ * @property {Object}               collection The FeatureCollection to which the FeatureGeometry is attached.
+ * @property {Object}               properties Properties of the FeatureGeometry.
+ * @property {string}               type Geometry type of the feature. Can be `point`, `line`, or `polygon`.
+ * @property {StyleOptions|Function}featureStyle StyleOptions object (or a function returning one) to get style
+ *                                  information at feature and FeatureGeometry level from the data parsed.
+ * @property {Coordinates}          coordinates The coordinates (in world space) of the last vertex (x, y, z) set with
+ *                                  setLocalCoordinatesFromArray().
+ * private properties:
+ * @property {Coordinates}          worldCoord @private Coordinates object to store coordinates in world space.
+ * @property {Coordinates}          localCoordinates @private Coordinates object to store coordinates in local space.
+ * @property {boolean}              worldCoordsComputed @private Have the world coordinates already been computed
+ *                                      from the local coordinates?
+ * @property {Feature}              feature  @private The itowns feature of interest.
+ * @property {FeatureGeometry}      geometry  @private The FeatureGeometry to compute the style.
+ */
+export class StyleContext {
+    setZoom(zoom: any): void;
+    zoom: any;
+    setFeature(f: any): void;
+    setGeometry(g: any): void;
+    setCollection(c: any): void;
+    collection: any;
+    setLocalCoordinatesFromArray(vertices: any, offset: any): Coordinates;
+    get properties(): any;
+    get type(): any;
+    get featureStyle(): any;
+    get coordinates(): Coordinates;
+    #private;
+}
+export default Style;
+import { Coordinates } from '@itowns/geographic';
+/**
+ * A Style is a class that defines the visual appearance of {@link
+ * FeatureCollection} and {@link Feature}. It is taken into account when drawing
+ * them in textures that will be placed onto tiles.
+ *
+ * As there are five basic elements present in `Features`, there are also five
+ * main components in a `Style` object:
+ * - `fill` is for all fillings and polygons
+ * - `stroke` is for all lines and polygons edges
+ * - `point` is for all points
+ * - `text` contains all {@link Label} related things
+ * - `icon` defines the appearance of icons attached to label.
+ *
+ * Many style property can be set to functions. When that is the case, the function's
+ * return type must necessarily be the same as the types (other than function) of the property.
+ * For instance, if the `fill.pattern` property is set to a function, this function must return
+ * an `Image`, a `Canvas`, or `String`.
+ * The first parameter of functions used to set `Style` properties is always an object containing
+ * the properties of the features displayed with the current `Style` instance.
+ *
+ * @property {Object} fill - Polygons and fillings style.
+ * @property {String|Function|THREE.Color} fill.color - Defines the main color of the filling. Can be
+ * any [valid color
+ * string](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
+ * Default is no value, indicating that no filling needs to be done.
+ * If the `Layer` is a `GeometryLayer` you can use `THREE.Color`.
+ * @property {Image|Canvas|String|Object|Function} [fill.pattern] - Defines a pattern to fill the
+ * surface with. It can be an `Image` to use directly, an url to fetch the pattern or an object containing
+ * the url of the image to fetch and the transformation to apply.
+ * from. See [this example] (http://www.itowns-project.org/itowns/examples/#source_file_geojson_raster)
+ * for how to use.
+ * @property {Image|String} [fill.pattern.source] - The image or the url to fetch the pattern image
+ * @property {Object} [fill.pattern.cropValues] - The x, y, width and height (in pixel) of the sub image to use.
+ * @property {THREE.Color} [fill.pattern.color] - Can be any [valid color string]
+ * @property {Number|Function} fill.opacity - The opacity of the color or of the
+ * pattern. Can be between `0.0` and `1.0`. Default is `1.0`.
+ * For a `GeometryLayer`, this opacity property isn't used.
+ * @property {Number|Function} fill.base_altitude - Only for {@link GeometryLayer}, defines altitude
+ * for each coordinate.
+ * If `base_altitude` is `undefined`, the original altitude is kept, and if it doesn't exist
+ * then the altitude value is set to 0.
+ * @property {Number|Function} [fill.extrusion_height] - Only for {@link GeometryLayer} and if user sets it.
+ * If defined, polygons will be extruded by the specified amount.
+ * @property {Object} stroke - Lines and polygons edges.
+ * @property {String|Function|THREE.Color} stroke.color The color of the line. Can be any [valid
+ * color string](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
+ * Default is no value, indicating that no stroke needs to be done.
+ * If the `Layer` is a `GeometryLayer` you can use `THREE.Color`.
+ * @property {Number|Function} stroke.opacity - The opacity of the line. Can be between
+ * `0.0` and `1.0`. Default is `1.0`.
+ * For a `GeometryLayer`, this opacity property isn't used.
+ * @property {Number|Function} stroke.width - The width of the line. Default is `1.0`.
+ * @property {Number|Function} stroke.base_altitude - Only for {@link GeometryLayer}, defines altitude
+ * for each coordinate.
+ * If `base_altitude` is `undefined`, the original altitude is kept, and if it doesn't exist
+ * then the altitude value is set to 0.
+ *
+ * @property {Object} point - Point style.
+ * @property {String|Function} point.color - The color of the point. Can be any [valid
+ * color string](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
+ * Default is no value, indicating that no point will be shown.
+ * @property {Number|Function} point.radius - The radius of the point, in pixel. Default
+ * is `2.0`.
+ * @property {String|Function} point.line - The color of the border of the point. Can be
+ * any [valid color
+ * string](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
+ * Not supported for `GeometryLayer`.
+ * @property {Number|Function} point.width - The width of the border, in pixel. Default
+ * is `0.0` (no border).
+ * @property {Number|Function} point.opacity - The opacity of the point. Can be between
+ * `0.0` and `1.0`. Default is `1.0`.
+ * Not supported for `GeometryLayer`.
+ * @property {Number|Function} point.base_altitude - Only for {@link GeometryLayer}, defines altitude
+ * for each coordinate.
+ * If `base_altitude` is `undefined`, the original altitude is kept, and if it doesn't exist
+ * then the altitude value is set to 0.
+ * @property {Object} point.model - 3D model to instantiate at each point position
+
+ *
+ * @property {Object} text - All things {@link Label} related.
+ * @property {String|Function} text.field - A string representing a property key of
+ * a `FeatureGeometry` enclosed in brackets, that will be replaced by the value of the
+ * property for each geometry. For example, if each geometry contains a `name` property,
+ * `text.field` can be set to `{name}`. Default is no value, indicating that no
+ * text will be displayed.
+ *
+ * It's also possible to create more complex expressions. For example, you can combine
+ * text that will always be displayed (e.g. `foo`) and variable properties (e.g. `{bar}`)
+ * like the following: `foo {bar}`. You can also use multiple variables in one field.
+ * Let's say for instance that you have two properties latin name and local name of a
+ * place, you can write something like `{name_latin} - {name_local}` which can result
+ * in `Marrakesh - مراكش` for example.
+ * @property {String|Function} text.color - The color of the text. Can be any [valid
+ * color string](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
+ * Default is `#000000`.
+ * @property {String|Number[]|Function} text.anchor - The anchor of the text relative to its
+ * position (see {@link Label} for the position). Can be one of the following values: `top`,
+ * `left`, `bottom`, `right`, `center`, `top-left`, `top-right`, `bottom-left`
+ * or `bottom-right`. Default is `center`.
+ *
+ * It can also be defined as an Array of two numbers. Each number defines an offset (in
+ * fraction of the label width and height) between the label position and the top-left
+ * corner of the text. The first value is the horizontal offset, and the second is the
+ * vertical offset. For example, `[-0.5, -0.5]` will be equivalent to `center`.
+ * @property {Array|Function} text.offset - The offset of the text, depending on its
+ * anchor, in pixels. First value is from `left`, second is from `top`. Default
+ * is `[0, 0]`.
+ * @property {Number|Function} text.padding - The padding outside the text, in pixels.
+ * Default is `2`.
+ * @property {Number|Function} text.size - The size of the font, in pixels. Default is
+ * `16`.
+ * @property {Number|Function} text.wrap - The maximum width, in pixels, before the text
+ * is wrapped, because the string is too long. Default is `10`.
+ * @property {Number|Function} text.spacing - The spacing between the letters, in `em`.
+ * Default is `0`.
+ * @property {String|Function} text.transform - A value corresponding to the [CSS
+ * property
+ * `text-transform`](https://developer.mozilla.org/en-US/docs/Web/CSS/text-transform).
+ * Default is `none`.
+ * @property {String|Function} text.justify - A value corresponding to the [CSS property
+ * `text-align`](https://developer.mozilla.org/en-US/docs/Web/CSS/text-align).
+ * Default is `center`.
+ * @property {Number|Function} text.opacity - The opacity of the text. Can be between
+ * `0.0` and `1.0`. Default is `1.0`.
+ * @property {Array|Function} text.font - A list (as an array of string) of font family
+ * names, prioritized in the order it is set. Default is `Open Sans Regular,
+ * Arial Unicode MS Regular, sans-serif`.
+ * @property {String|Function} text.haloColor - The color of the halo. Can be any [valid
+ * color string](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
+ * Default is `#000000`.
+ * @property {Number|Function} text.haloWidth - The width of the halo, in pixels.
+ * Default is `0`.
+ * @property {Number|Function} text.haloBlur - The blur value of the halo, in pixels.
+ * Default is `0`.
+ *
+ * @property {Object} icon - Defines the appearance of icons attached to label.
+ * @property {String} icon.source - The url of the icons' image file.
+ * @property {String} icon.id - The id of the icons' sub-image in a vector tile data set.
+ * @property {String} icon.cropValues - the x, y, width and height (in pixel) of the sub image to use.
+ * @property {String} icon.anchor - The anchor of the icon compared to the label position.
+ * Can be `left`, `bottom`, `right`, `center`, `top-left`, `top-right`, `bottom-left`
+ * or `bottom-right`. Default is `center`.
+ * @property {Number} icon.size - If the icon's image is passed with `icon.source` and/or
+ * `icon.id`, its size when displayed on screen is multiplied by `icon.size`. Default is `1`.
+ * @property {String|Function} icon.color - The color of the icon. Can be any [valid
+ * color string](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
+ * It will change the color of the white pixels of the icon source image.
+ * @property {Number|Function} icon.opacity - The opacity of the icon. Can be between
+ * `0.0` and `1.0`. Default is `1.0`.
+ *
+ * @example
+ * const style = new itowns.Style({
+ *      stroke: { color: 'red' },
+ *      point: { color: 'white', line: 'red' },
+ * });
+ *
+ * const source = new itowns.FileSource(...);
+ *
+ * const layer = new itowns.ColorLayer('foo', {
+ *      source: source,
+ *      style: style,
+ * });
+ *
+ * view.addLayer(layer);
+ */
+declare class Style {
+    /**
+     * @param {StyleOptions} [params={}] An object that contain any properties
+     * (zoom, fill, stroke, point, text or/and icon)
+     * and sub properties of a Style ({@link StyleOptions}).
+     */
+    constructor(params?: StyleOptions);
+    isStyle: boolean;
+    context: StyleContext;
+    zoom: {};
+    fill: {};
+    stroke: {};
+    point: {};
+    text: {};
+    icon: {};
+    setContext(ctx: any): void;
+    /**
+     * Applies the style.fill to a polygon of the texture canvas.
+     * @param {CanvasRenderingContext2D} txtrCtx The Context 2D of the texture canvas.
+     * @param {Path2D} polygon The current texture canvas polygon.
+     * @param {Number} invCtxScale The ratio to scale line width and radius circle.
+     * @param {Boolean} canBeFilled - true if feature.type == FEATURE_TYPES.POLYGON.
+     */
+    applyToCanvasPolygon(txtrCtx: CanvasRenderingContext2D, polygon: Path2D, invCtxScale: number, canBeFilled: boolean): void;
+    _applyStrokeToPolygon(txtrCtx: any, invCtxScale: any, polygon: any): void;
+    _applyFillToPolygon(txtrCtx: any, invCtxScale: any, polygon: any): Promise<void>;
+    /**
+     * Applies this style to a DOM element. Limited to the `text` and `icon`
+     * properties of this style.
+     *
+     * @param {Element} domElement - The element to set the style to.
+     *
+     * @returns {undefined|Promise<HTMLImageElement>}
+     *          for a text label: undefined.
+     *          for an icon: a Promise resolving with the HTMLImageElement containing the image.
+     */
+    applyToHTML(domElement: Element, ...args: any[]): undefined | Promise<HTMLImageElement>;
+    /**
+     * Gets the values corresponding to the anchor of the text. It is
+     * proportions, to use with a `translate()` and a `transform` property.
+     *
+     * @return {Number[]} Two percentage values, for x and y respectively.
+     */
+    getTextAnchorPosition(): number[];
+}