Skip to content

Commit 531e197

Browse files
gkjohnsonMSI\WIN11TQtong
authored
WMTSImageSource: take literals, deprecate "capabilities" (#1550)
* Chage wmts params(delete capabilities parameter) * fix(WMTSImageSource): correct TiledImageSource import path Made-with: Cursor * refactor(WMTSImageSource): remove subdomains support Made-with: Cursor * refactor(WMTSImageSource): accept contentBoundingBox in radians for consistency Made-with: Cursor * refactor(WMTSImageSource): remove redundant default fallbacks for style and tileMatrixSet Made-with: Cursor * refactor(WMTSImageSource): use Array.isArray for Tier 3 tileMatrices check Made-with: Cursor * feat(WMTSImageSource): add optional tileBounds field to WMTSTileMatrix Made-with: Cursor * feat(WMTSImageSource): add deprecated capabilities backward compatibility Made-with: Cursor * style(WMTSImageSource): minor formatting cleanup in init() destructuring Made-with: Cursor * refactor(WMTSImageSource): make tileBounds required in WMTSTileMatrix and remove auto-computed bounds Made-with: Cursor * fix(WMTSTilesPlugin): forward all WMTSImageSource options to match the latest API Made-with: Cursor * update(example): rewrite wmtsTiles example to use literal WMTS options with multiple source presets Made-with: Cursor * update(example): add capabilities-based WMTS usage alongside literal options with GUI service switcher Made-with: Cursor * fix(WMTSImageSource): add spaces inside template literal curly braces to satisfy template-curly-spacing lint rule Made-with: Cursor * Simplify example * Comment update * Update docs, cleanup --------- Co-authored-by: MSI\WIN11 <tangqi@bwton.com> Co-authored-by: Андрей <66043271+TQtong@users.noreply.github.com>
1 parent d512b10 commit 531e197

10 files changed

Lines changed: 423 additions & 261 deletions

File tree

‎example/three/wmtsTiles.js‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -160,15 +160,27 @@ function rebuildTiles() {
160160

161161
}
162162

163+
const layer = capabilities.layers.find( l => l.identifier === params.layer );
164+
const tileMatrixSet = layer.tileMatrixSets.find( tms => tms.identifier === params.tileMatrixSet );
165+
const url = layer.resourceUrls[ 0 ].template;
166+
const contentBoundingBox = layer.boundingBox.bounds;
167+
163168
// tiles
164169
tiles = new TilesRenderer();
165170
tiles.registerPlugin( new TilesFadePlugin() );
166171
tiles.registerPlugin( new UpdateOnChangePlugin() );
167172
tiles.registerPlugin( new WMTSTilesPlugin( {
168173
shape: params.planar ? 'planar' : 'ellipsoid',
169174
center: true,
170-
capabilities,
171-
...params,
175+
176+
url,
177+
tileMatrices: tileMatrixSet.tileMatrices,
178+
contentBoundingBox,
179+
projection: 'EPSG:4326',
180+
dimensions: params.dimensions,
181+
style: params.style,
182+
layer: params.layer,
183+
tileMatrixSet: params.tileMatrixSet,
172184
} ) );
173185

174186
tiles.setCamera( camera );

‎src/three/plugins/API.md‎

Lines changed: 50 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -287,17 +287,18 @@ directly. See the [WMTS specification](https://www.ogc.org/standard/wmts/).
287287
```js
288288
constructor(
289289
{
290-
capabilities?: Object,
290+
url?: string,
291291
layer?: string,
292292
tileMatrixSet?: string,
293-
style?: string,
294-
dimensions?: Object,
295-
opacity = 1: number,
296-
color = 0xffffff: number | Color,
297-
frame = null: Matrix4,
298-
preprocessURL = null: function,
299-
alphaMask = false: boolean,
300-
alphaInvert = false: boolean,
293+
style = 'default': string,
294+
format = 'image/jpeg': string,
295+
dimensions = null: Object<string, (string|number)> | null,
296+
tileMatrixLabels = null: Array<string> | null,
297+
tileMatrices = null: Array<WMTSTileMatrix> | null,
298+
projection = null: string | null,
299+
levels = 20: number,
300+
tileDimension = 256: number,
301+
contentBoundingBox = null: Array<number> | null,
301302
}
302303
)
303304
```
@@ -503,11 +504,18 @@ a URL template directly.
503504
```js
504505
constructor(
505506
{
506-
capabilities?: Object,
507+
url?: string,
507508
layer?: string,
508509
tileMatrixSet?: string,
509-
style?: string,
510-
dimensions?: Object,
510+
style = 'default': string,
511+
format = 'image/jpeg': string,
512+
dimensions = null: Object<string, (string|number)> | null,
513+
tileMatrixLabels = null: Array<string> | null,
514+
tileMatrices = null: Array<WMTSTileMatrix> | null,
515+
projection = null: string | null,
516+
levels = 20: number,
517+
tileDimension = 256: number,
518+
contentBoundingBox = null: Array<number> | null,
511519
}
512520
)
513521
```
@@ -1101,134 +1109,82 @@ Bounding box `bounds` arrays are in `[ minLon, minLat, maxLon, maxLat ]` order i
11011109
constructor( manager: LoadingManager )
11021110
```
11031111

1104-
## WMTSImageSource
1105-
1106-
_extends `TiledImageSource`_
1107-
1108-
WMTS (Web Map Tile Service) image source for loading tiled map imagery.
1109-
1110-
This class provides support for loading map tiles from WMTS-compliant services.
1111-
It handles parsing WMTS capabilities documents and constructing proper tile URLs.
1112-
1113-
1114-
### .capabilities
1115-
1116-
```js
1117-
capabilities: Object | null
1118-
```
1119-
1120-
Parsed WMTS capabilities object
1112+
## FeatureInfo
11211113

11221114

1123-
### .layer
1115+
### .label
11241116

11251117
```js
1126-
layer: string | Object | null
1118+
label: string | null
11271119
```
11281120

1129-
The layer to render (identifier string or layer object)
1130-
1131-
1132-
### .tileMatrixSet
1121+
### .propertyTable
11331122

11341123
```js
1135-
tileMatrixSet: string | Object | null
1124+
propertyTable: string | null
11361125
```
11371126

1138-
The tile matrix set to use (identifier string or object)
1139-
1140-
1141-
### .style
1127+
### .nullFeatureId
11421128

11431129
```js
1144-
style: string | null
1130+
nullFeatureId: number | null
11451131
```
11461132

1147-
The style identifier
1148-
1149-
1150-
### .dimensions
1133+
### .texture
11511134

11521135
```js
1153-
dimensions: Object
1136+
texture?: Object
11541137
```
11551138

1156-
Dimension values for the WMTS request
1139+
## WMTSTileMatrix
11571140

11581141

1159-
### .url
1142+
### .identifier
11601143

11611144
```js
1162-
url: string | null
1145+
identifier: string
11631146
```
11641147

1165-
The URL template for tile requests
1148+
TileMatrix identifier (e.g., 'Level0', 'EPSG:3857:0').
11661149

1167-
1168-
### .constructor
1150+
### .matrixWidth
11691151

11701152
```js
1171-
constructor(
1172-
{
1173-
capabilities = null: Object,
1174-
layer = null: string | Object,
1175-
tileMatrixSet = null: string | Object,
1176-
style = null: string,
1177-
url = null: string,
1178-
dimensions = {}: Object,
1179-
}
1180-
)
1153+
matrixWidth: number
11811154
```
11821155

1183-
Creates a new WMTSImageSource instance.
1156+
Number of tile columns at this level.
11841157

1185-
### .getUrl
1158+
### .matrixHeight
11861159

11871160
```js
1188-
getUrl( x: number, y: number, level: number ): string
1161+
matrixHeight: number
11891162
```
11901163

1191-
Generates the URL for a specific tile.
1192-
1164+
Number of tile rows at this level.
11931165

1194-
### .init
1166+
### .tileWidth
11951167

11961168
```js
1197-
init(): Promise<void>
1169+
tileWidth?: number
11981170
```
11991171

1200-
Initializes the image source by parsing capabilities and setting up the tiling scheme.
1201-
1202-
This method:
1203-
- Resolves layer, tileMatrixSet, and style from capabilities
1204-
- Determines the projection (EPSG:4326 or EPSG:3857)
1205-
- Configures the tiling scheme with proper bounds and tile sizes
1206-
- Constructs the final URL template
1207-
1208-
1209-
## FeatureInfo
1172+
Tile width in pixels (defaults to tileDimension).
12101173

1211-
1212-
### .label
1174+
### .tileHeight
12131175

12141176
```js
1215-
label: string | null
1177+
tileHeight?: number
12161178
```
12171179

1218-
### .propertyTable
1180+
Tile height in pixels (defaults to tileDimension).
12191181

1220-
```js
1221-
propertyTable: string | null
1222-
```
1223-
1224-
### .nullFeatureId
1182+
### .tileBounds
12251183

12261184
```js
1227-
nullFeatureId: number | null
1185+
tileBounds: Array<number>
12281186
```
12291187

1230-
### .texture
1231-
1232-
```js
1233-
texture?: Object
1234-
```
1188+
Tile grid bounds in radians `[west, south, east, north]`.
1189+
Required because the actual coverage depends on TopLeftCorner and ScaleDenominator
1190+
from the capabilities XML and cannot be computed from grid dimensions alone.

‎src/three/plugins/images/EPSGTilesPlugin.d.ts‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { WMTSCapabilitiesResult, WMTSLayer, WMTSTileMatrixSet } from '../loaders/WMTSCapabilitiesLoader.js';
1+
import { WMTSTileMatrix } from '../loaders/WMTSCapabilitiesLoader.js';
22

33
export class XYZTilesPlugin {
44

@@ -27,13 +27,18 @@ export class TMSTilesPlugin {
2727
export class WMTSTilesPlugin {
2828

2929
constructor( options: {
30-
capabilities?: WMTSCapabilitiesResult | null,
31-
layer?: WMTSLayer | string | null,
32-
tileMatrixSet?: WMTSTileMatrixSet | string | null,
30+
url?: string | null,
31+
layer?: string | null,
32+
tileMatrixSet?: string | null,
3333
style?: string,
34+
tileMatrixLabels?: Array<string>,
35+
tileMatrices: Array<WMTSTileMatrix>,
3436
dimensions?: { [ key: string ]: any } | null,
35-
center?: boolean,
37+
projection?: string,
3638
levels?: number,
39+
tileDimension?: number,
40+
contentBoundingBox?: Array<number>,
41+
3742
shape?: 'ellipsoid' | 'planar',
3843
useRecommendedSettings?: boolean,
3944
} );

‎src/three/plugins/images/EPSGTilesPlugin.js‎

Lines changed: 30 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11

2-
// Support for XYZ / Slippy tile systems
3-
2+
/** @import { WMTSTileMatrix } from './sources/WMTSImageSource.js' */
43
import { EllipsoidProjectionTilesPlugin } from './EllipsoidProjectionTilesPlugin.js';
54
import { XYZImageSource } from './sources/XYZImageSource.js';
65
import { TMSImageSource } from './sources/TMSImageSource.js';
@@ -66,22 +65,37 @@ export class TMSTilesPlugin extends EllipsoidProjectionTilesPlugin {
6665
* a URL template directly.
6766
* @extends EllipsoidProjectionTilesPlugin
6867
* @param {Object} [options]
69-
* @param {Object} [options.capabilities] Parsed WMTS capabilities from `WMTSCapabilitiesLoader`.
70-
* @param {string} [options.layer] WMTS layer identifier.
71-
* @param {string} [options.tileMatrixSet] Tile matrix set identifier.
72-
* @param {string} [options.style] Style identifier.
73-
* @param {Object} [options.dimensions] Additional WMTS dimension parameters.
68+
* @param {string} [options.url] - WMTS service URL.
69+
* @param {string} [options.layer] - WMTS layer identifier.
70+
* @param {string} [options.tileMatrixSet] - TileMatrixSet identifier (e.g., 'GoogleMapsCompatible', 'EPSG:3857').
71+
* @param {string} [options.style='default'] - Style identifier.
72+
* @param {string} [options.format='image/jpeg'] - Output image format (e.g., 'image/png', 'image/jpeg').
73+
* @param {Object<string, string|number>|null} [options.dimensions=null] - WMTS dimension values
74+
* @param {string[]|null} [options.tileMatrixLabels=null] - Custom TileMatrix identifiers per level
75+
* @param {WMTSTileMatrix[]|null} [options.tileMatrices=null] - Explicit per-level tile matrix definitions. When provided, `levels` and `tileMatrixLabels` are ignored.
76+
* @param {string|null} [options.projection=null] - Projection identifier ('EPSG:3857' or 'EPSG:4326'). Defaults to 'EPSG:3857' if not specified.
77+
* @param {number} [options.levels=20] - Number of zoom levels. Ignored if `tileMatrices` is provided.
78+
* @param {number} [options.tileDimension=256] - Default tile width and height in pixels.
79+
* @param {number[]|null} [options.contentBoundingBox=null] - Content bounding box in radians, `[west, south, east, north]`. If null, uses full projection bounds.
7480
*/
7581
export class WMTSTilesPlugin extends EllipsoidProjectionTilesPlugin {
7682

7783
constructor( options = {} ) {
7884

7985
const {
8086
capabilities,
87+
url,
8188
layer,
8289
tileMatrixSet,
8390
style,
91+
format,
8492
dimensions,
93+
tileMatrixLabels,
94+
tileMatrices,
95+
projection,
96+
levels,
97+
tileDimension,
98+
contentBoundingBox,
8599
...rest
86100
} = options;
87101

@@ -90,10 +104,18 @@ export class WMTSTilesPlugin extends EllipsoidProjectionTilesPlugin {
90104
this.name = 'WTMS_TILES_PLUGIN';
91105
this.imageSource = new WMTSImageSource( {
92106
capabilities,
107+
url,
93108
layer,
94109
tileMatrixSet,
95110
style,
96-
dimensions
111+
format,
112+
dimensions,
113+
tileMatrixLabels,
114+
tileMatrices,
115+
projection,
116+
levels,
117+
tileDimension,
118+
contentBoundingBox,
97119
} );
98120

99121
}

‎src/three/plugins/images/ImageOverlayPlugin.d.ts‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { Color, Matrix4, WebGLRenderer } from 'three';
2-
import { WMTSCapabilitiesResult, WMTSLayer, WMTSTileMatrixSet } from '../loaders/WMTSCapabilitiesLoader.js';
2+
import { WMTSTileMatrix } from '../loaders/WMTSCapabilitiesLoader.js';
33

44
export class ImageOverlayPlugin {
55

@@ -106,12 +106,17 @@ export class WMSTilesOverlay extends TiledImageOverlay {
106106
export class WMTSTilesOverlay extends TiledImageOverlay {
107107

108108
constructor( options: {
109-
dimensions?: { [ key: string ]: any } | null,
110109
url?: string | null,
111-
capabilities?: WMTSCapabilitiesResult | null,
112-
layer?: WMTSLayer | string | null,
113-
tileMatrixSet?: WMTSTileMatrixSet | string | null,
110+
layer?: string | null,
111+
tileMatrixSet?: string | null,
114112
style?: string,
113+
tileMatrixLabels?: Array<string>,
114+
tileMatrices: Array<WMTSTileMatrix>,
115+
dimensions?: { [ key: string ]: any } | null,
116+
projection?: string,
117+
levels?: number,
118+
tileDimension?: number,
119+
contentBoundingBox?: Array<number>,
115120

116121
color?: number | Color,
117122
opacity?: number,

0 commit comments

Comments
 (0)