feat: add TmsSource docs and cleanup

Author: HoloTheDrunk

packages/Main/src/Layer/Layer.js

@@ -1,7 +1,7 @@
 import * as THREE from 'three';
 import { STRATEGY_MIN_NETWORK_TRAFFIC } from 'Layer/LayerUpdateStrategy';
 import InfoLayer from 'Layer/InfoLayer';
-import Source from 'Source/Source';
+import { Source } from 'Source/Source';
 import { LRUCache } from 'lru-cache';
 import Style from 'Core/Style';
 
@@ -149,7 +149,7 @@ class Layer extends THREE.EventDispatcher {
          * @type {number}
          */
         this.subdivisionThreshold = subdivisionThreshold;
-        this.sizeDiagonalTexture =  (2 * (this.subdivisionThreshold * this.subdivisionThreshold)) ** 0.5;
+        this.sizeDiagonalTexture = (2 * (this.subdivisionThreshold * this.subdivisionThreshold)) ** 0.5;
 
         this.addLabelLayer = addLabelLayer;
 
@@ -189,7 +189,7 @@ class Layer extends THREE.EventDispatcher {
             this._reject = rj;
         }).then(() => {
             this.ready = true;
-            this.source.onLayerAdded({ out: this });
+            this.source.capabilities.layerEventHandler?.onLayerAdded(this);
             return this;
         });
 

packages/Main/src/Main.js

@@ -78,6 +78,7 @@ export { default as GeoidLayer } from 'Layer/GeoidLayer';
 export { Source } from 'Source/Source';
 // export { default as FileSource } from 'Source/FileSource';
 export { TmsSource } from 'Source/TmsSource';
+export { default as WmtsSource } from 'Source/WmtsSource';
 // export { default as WFSSource } from 'Source/WFSSource';
 // export { default as WMSSource } from 'Source/WMSSource';
 // export { default as WMTSSource } from 'Source/WMTSSource';

packages/Main/src/Source/RemoteSource.ts

@@ -16,19 +16,19 @@ export abstract class RemoteSource<Key, Data> implements Source<Key, Promise<Dat
     public readonly isSource = true as const;
     public readonly isRemoteSource = true as const;
 
-    declare public capabilities: SourceCapabilities;
+    public abstract readonly capabilities: SourceCapabilities;
 
     protected loader: Loader<Data>;
 
+    public url: string;
     public readonly crs: CRS.ProjectionLike;
-    public readonly url: string;
     public readonly format: string;
     public networkOptions: RequestInit;
 
     public constructor(options: RemoteSourceOptions<Data>) {
         this.loader = options.loader;
-        this.crs = options.crs;
         this.url = options.url;
+        this.crs = options.crs;
         this.format = options.format;
         this.networkOptions = options.networkOptions;
     }

packages/Main/src/Source/TmsSource.ts

@@ -1,9 +1,9 @@
 import Tile from 'Core/Tile/Tile';
 import URLBuilder from 'Provider/URLBuilder';
 import { Extent } from '@itowns/geographic';
-import * as THREE from 'three';
 import Layer from 'Layer/Layer';
 import { RemoteSource, RemoteSourceOptions } from './RemoteSource';
+import { SourceCapabilities } from './SourceCapabilities';
 
 export type TmsLimit = {
     minTileRow: number;
@@ -19,21 +19,94 @@ export interface TmsSourceOptions<Data> extends RemoteSourceOptions<Data> {
     zoom?: { min: number; max: number; };
 }
 
-export class TmsSource<Data extends THREE.Texture>
-    extends RemoteSource<Tile, Data> {
+/**
+ * An object defining the source of resources to get from a
+ * [TMS](https://wiki.osgeo.org/wiki/Tile_Map_Service_Specification) server.
+ *
+ * @example
+ *
+ * **Source from OpenStreetMap server:**
+ * ```ts
+ * // Create the source
+ * const tmsSource = new itowns.TMSSource({
+ *     format: 'image/png',
+ *     url: 'http://osm.io/styles/${z}/${x}/${y}.png',
+ *     attribution: {
+ *         name: 'OpenStreetMap',
+ *         url: 'http://www.openstreetmap.org/',
+ *     },
+ *     crs: 'EPSG:3857',
+ * });
+ *
+ * // Create the layer
+ * const colorLayer = new itowns.ColorLayer('OPENSM', {
+ *     source: tmsSource,
+ * });
+ *
+ * // Add the layer
+ * view.addLayer(colorLayer);
+ * ```
+ *
+ * @example
+ *
+ * **Source from Mapbox server:**
+ * ```ts
+ * // Create the source
+ * const orthoSource = new itowns.TMSSource({
+ *     url: 'https://api.mapbox.com/v4/mapbox.satellite/${z}/${x}/${y}.jpg?access_token=' + accessToken,
+ *     crs: 'EPSG:3857',
+ * };
+ *
+ * // Create the layer
+ * const imageryLayer = new itowns.ColorLayer("Ortho", {
+ *     source: orthoSource,
+ * };
+ *
+ * // Add the layer to the view
+ * view.addLayer(imageryLayer);
+ * ```
+ */
+export class TmsSource<Data> extends RemoteSource<Tile, Data> {
+    /** Used to checkout whether this source is a TMSSource. */
     public readonly isTMSSource = true as const;
     public readonly isSourceEventHandler = true as const;
 
+    public readonly capabilities: SourceCapabilities = {
+        layerEventHandler: {
+            onLayerAdded: this.onLayerAdded,
+            onLayerRemoved: this.onLayerRemoved,
+        },
+    };
+
+    /**
+     * Minimum and maximum values of the zoom level.
+     * Defaults are 0 and Infinity.
+     */
     public zoom: { min: number; max: number; };
+    /**
+     * The isInverted property is to be set to the correct value, true or false
+     * (default being false) if the computation of the coordinates needs to be
+     * inverted to match the same scheme as OSM, Google Maps or other system.
+     * See [this link](https://alastaira.wordpress.com/2011/07/06/converting-tms-tile-coordinates-to-googlebingosm-tile-coordinates/)
+     * for more information.
+     */
     public isInverted: boolean;
 
+    /** Describes the available tile for this layer. */
     public tileMatrixSetLimits?: Record<number, TmsLimit>;
 
+    /** These are the extents of the set of identical zoom tiles. */
     public extentSetLimits: Record<string, Record<number, Extent>>;
 
+    /**
+     * Creates a TileMatrix identifier from the zoom level. For example, if set
+     * to `(zoomLevel) => 'EPSG:4326:' + zoomLevel`, the TileMatrix that will be
+     * fetched at zoom level 5 will be the one with identifier `EPSG:4326:5`.
+     * By default, the method returns the input zoom level.
+     */
     public tileMatrixCallback: (level: number) => string;
 
-    protected constructor(
+    public constructor(
         options: TmsSourceOptions<Data>,
     ) {
         super(options);
@@ -60,13 +133,6 @@ export class TmsSource<Data extends THREE.Texture>
                 max: Infinity,
             };
         }
-
-        this.capabilities = {
-            layerEventHandler: {
-                onLayerAdded: this.onLayerAdded,
-                onLayerRemoved: this.onLayerRemoved,
-            },
-        };
     }
 
     public async load(tile: Tile): Promise<Data> {

packages/Main/src/Source/WmtsSource.ts

@@ -0,0 +1,40 @@
+import { TmsSource } from 'Main';
+import { TmsSourceOptions } from './TmsSource';
+
+export interface WmtsSourceOptions<Data> extends TmsSourceOptions<Data> {
+    name: string,
+    version?: string,
+    style?: string,
+    tileMatrixSet?: string,
+    vendorSpecific?: Record<string, unknown>,
+}
+
+export class WmtsSource<Data> extends TmsSource<Data> {
+    public readonly isWmtsSource = true as const;
+
+    public constructor(options: WmtsSourceOptions<Data>) {
+        super(options);
+
+        const urlObj = new URL(this.url);
+        urlObj.searchParams.set('LAYER', options.name);
+        urlObj.searchParams.set('FORMAT', this.format);
+        urlObj.searchParams.set('SERVICE', 'WMTS');
+        urlObj.searchParams.set('VERSION', options.version ?? '1.0.0');
+        urlObj.searchParams.set('REQUEST', 'GetTile');
+        urlObj.searchParams.set('STYLE', options.style ?? 'normal');
+        urlObj.searchParams.set('TILEMATRIXSET', options.tileMatrixSet ?? 'WGS84');
+        urlObj.searchParams.set('TILEMATRIX', '%TILEMATRIX');
+        urlObj.searchParams.set('TILEROW', '%ROW');
+        urlObj.searchParams.set('TILECOL', '%COL');
+
+        const vendorSpecific: Record<string, string> = Object.fromEntries(
+            Object.entries(options.vendorSpecific ?? {}).map(([k, v]) => [k, String(v)]));
+        for (const name in vendorSpecific) {
+            if (Object.prototype.hasOwnProperty.call(vendorSpecific, name)) {
+                urlObj.searchParams.set(name, vendorSpecific[name]);
+            }
+        }
+
+        this.url = decodeURIComponent(urlObj.toString());
+    }
+}