How can load wmts service?

[TQtong]

Question

This is my reference address: https://cesium.com/learn/ion-sdk/ref-doc/WebMapTileServiceImageryProvider.html #943

But the request keeps returning errors.

https://jsfiddle.net/tangqi/fhzuvnL1/44/

Supplemental Data

const wmtsOverlay = new WMTSTilesOverlay( {
	url: 'https://basemap.nationalmap.gov/arcgis/rest/services/USGSShadedReliefOnly/MapServer/WMTS',
	layer: 'USGSShadedReliefOnly',
	style: 'default',
	format: 'image/jpeg',
	tileMatrixSet: 'default028mm',
	// tileMatrixLabels : ['default028mm:0', 'default028mm:1', 'default028mm:2' ...],
	maximumLevel: 19,
	color: '#ffffff',
	opacity: 1.0,
} );

Library Version

0.4.21

Three.js Version

r170.0

[TQtong]

I found an issue: In WMTSTilesOverlay, the capabilities are set as optional, but if I only pass the URL (without providing capabilities), it fails to load properly.

[TQtong]

WMTSImageSource Enhancement: Auto-load Capabilities Support

Problem Description

In the original implementation, the capabilities parameter in WMTSImageSource and WMTSTilesOverlay was marked as optional in the type definitions (capabilities?: WMTSCapabilitiesResult | null), but the actual code logic required capabilities to function properly.

Original Code Issue

init() {
    const { tiling, dimensions, capabilities } = this;
    
    // Directly accesses capabilities.layers, crashes if capabilities is null
    if ( ! layer ) {
        layer = capabilities.layers[ 0 ];  // ❌ Crashes when capabilities is null
    }
    
    // Even with url provided, capabilities is still needed for:
    // - layer info (boundingBox, dimensions, styles)
    // - tileMatrixSet info (supportedCRS, tileMatrices)
}

This prevented users from using WMTSTilesOverlay by simply passing a WMTS service URL.

Solution

Modified WMTSImageSource to support two usage patterns:

Pattern 1: Pass capabilities object (original approach)

const capabilities = await new WMTSCapabilitiesLoader().loadAsync(wmtsUrl);
const wmtsOverlay = new WMTSTilesOverlay({
    capabilities: capabilities,
    layer: 'layerName',
    style: 'default',
    tileMatrixSet: 'EPSG:4326',
    color: '#ffffff',
    opacity: 1.0,
});

Pattern 2: Pass only GetCapabilities URL (newly supported)

const wmtsOverlay = new WMTSTilesOverlay({
    url: 'https://example.com/wmts?SERVICE=WMTS&request=GetCapabilities',
    layer: 'layerName',  // optional, defaults to first layer
    color: '#ffffff',
    opacity: 1.0,
});

Code Changes

1. Add URL type detection function

// Determine if URL is a tile template or GetCapabilities URL
function isTileTemplateUrl( url ) {
    return /{\s*(TileMatrix|TileCol|TileRow)\s*}/i.test( url );
}

2. Change init method to async

async init() {
    const { tiling, dimensions } = this;
    let { capabilities, layer, tileMatrixSet, style, url } = this;

    // If no capabilities but url provided (and not a tile template), auto-load capabilities
    if ( ! capabilities && url && ! isTileTemplateUrl( url ) ) {
        const loader = new WMTSCapabilitiesLoader();
        loader.fetchData = this.fetchData;
        capabilities = await loader.loadAsync( url );
        this.capabilities = capabilities;
        url = null;  // Reset url, will extract tile template from capabilities
    }

    if ( ! capabilities ) {
        throw new Error( 'WMTSImageSource: capabilities is required...' );
    }

    // ... original logic
}

Modified Files

• src/three/plugins/images/sources/WMTSImageSource.js

Date

2026-02-25

Related Issues

• Original issue: capabilities marked as optional but actually required

[gkjohnson]

In WMTSTilesOverlay, the capabilities are set as optional, but if I only pass the URL (without providing capabilities), it fails to load properly.

"capabilities" is required if you are passing "layer" or "tileMatrixSet" etc as strings (I believe the tile matrix set content is the important piece here). Otherwise you can pass the actual structure of the tile matrices. WMTS is not a simple format and can reference many tile sets so it's not possible to infer the extents & structure of the tile hierarchy without this information.

I'm not a huge fan of the current interfaces, though. I have an issue in #1309 discussing how this can be improved so I'm open to ideas. Ideally only one style of options would be supported, though, to avoid added confusion.

[TQtong]

Thank you so much.

[TQtong]

I realize that currently, there's a situation where I only know the URL of the WMTS and nothing else. In this case, Cesium provides the UrlTemplateImageryProvider.

[TQtong]

I realize that currently, there's a situation where I only know the URL of the WMTS and nothing else. In this case, Cesium provides the UrlTemplateImageryProvider.

Here are the parameters I designed. At the same time, I solved this problem.

I mainly referenced three libraries: Leaflet, OpenLayers, and Cesium.

[gkjohnson]

I need to ask these explanations to be heavily simplified. Screenshots of code and long comments are not easy to follow. If you already have an implementation it's easier to see a PR with the code changes.

[TQtong]

I'm a bit confused — after removing the capabilities parameter, WMTSImageSource.js was almost entirely modified by me. Did I misunderstand something somewhere? After removing the capabilities property, I found that I need to determine whether the current URL is KVP or RESTful.

[gkjohnson]

I'm not exactly sure what you're referring to? The (now deleted) PR in #1503 changed files that didn't need to be and added new unrelated classes. It would be best to keep changes targeted and only change what needs to be changed in order to adjust the interface for WMTSImageSource. It's otherwise hard to understand what such a large amount of changes are doing and why they are being added.

[TQtong]

Okay, I have submitted a PR.