sparse wmts datasource fixes (#9024)

Co-authored-by: Ben Polinsky <ben-polinsky@users.noreply.github.com>
Co-authored-by: Daniel Zhong <32878167+danielzhong@users.noreply.github.com>

Author: ben-polinsky

common/changes/@itwin/core-frontend/wmts-fix_2026-02-27-17-51.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-frontend",
+      "comment": "Add support for WMTS sparse tilesets",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/core-frontend"
+}

core/frontend/src/internal/tile/map/ImageryProviders/WmtsMapLayerImageryProvider.ts

@@ -187,7 +187,13 @@ export class WmtsMapLayerImageryProvider extends MapLayerImageryProvider {
       assert(false);    // Must always hava a matrix set.
       return;
     }
-    const limits = matrixSetAndLimits.limits?.[quadId.level + 1]?.limits;
+    const childLevel = quadId.level + 1;
+    const childMatrixId = matrixSetAndLimits.tileMatrixSet.tileMatrix.length > childLevel
+      ? matrixSetAndLimits.tileMatrixSet.tileMatrix[childLevel].identifier
+      : undefined;
+    const limits = childMatrixId !== undefined
+      ? matrixSetAndLimits.limits?.find((l) => l.tileMatrix === childMatrixId)?.limits
+      : undefined;
     if (!limits) {
       resolveChildren(childIds);
       return;

core/frontend/src/internal/tile/map/WmtsCapabilities.ts

@@ -326,7 +326,7 @@ export namespace WmtsCapability {
 
       const tileMatrixLimitsRoot = elem.getElementsByTagName("TileMatrixSetLimits");
       if (tileMatrixLimitsRoot.length > 0) {
-        const tileMatrixLimits = tileMatrixLimitsRoot[0].getElementsByTagName("TileMatrixSetLimits");
+        const tileMatrixLimits = tileMatrixLimitsRoot[0].getElementsByTagName("TileMatrixLimits");
         for (const tmsl of tileMatrixLimits) {
           this.tileMatrixSetLimits.push(new TileMatrixSetLimits(tmsl));
         }

core/frontend/src/test/tile/map/ImageryTileTree.test.ts

@@ -3,15 +3,18 @@
 * See LICENSE.md in the project root for license terms and full copyright notice.
 *--------------------------------------------------------------------------------------------*/
 
+import { Range3d } from "@itwin/core-geometry";
 import { ImageMapLayerProps, ImageMapLayerSettings } from "@itwin/core-common";
 import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 import { MockRender } from "../../../internal/render/MockRender";
 import { createBlankConnection } from "../../createBlankConnection";
-import { ImageryMapLayerTreeReference } from "../../../tile/map/ImageryTileTree";
+import { ImageryMapLayerTreeReference, ImageryMapTile, ImageryMapTileTree } from "../../../tile/map/ImageryTileTree";
 import { IModelConnection } from "../../../IModelConnection";
 import { ImageryMapLayerFormat } from "../../../tile/map/MapLayerImageryFormats";
 import { MapLayerImageryProvider } from "../../../tile/map/MapLayerImageryProvider";
 import { IModelApp } from "../../../IModelApp";
+import { QuadId, TileTreeLoadStatus } from "../../../tile/internal";
+import { TileDrawArgs } from "../../../tile/TileDrawArgs";
 
 class CustomProvider extends MapLayerImageryProvider {
   public override async constructUrl(_row: number, _column: number, _zoomLevel: number) { return this._settings.url;}
@@ -96,4 +99,81 @@ describe("ImageryTileTree", () => {
         expect(tileTreeLhs!.modelId).not.toEqual(tileTreeRhs!.modelId);
     }
   });
+
+  /** Helper: create a tree and return the root tile + tree ref */
+  async function createTreeAndRoot() {
+    const props: ImageMapLayerProps = { formatId: "Custom1", url: "https://dummy.com", name: "TestLayer", subLayers: [{ name: "sub0", visible: true }] };
+    const settings = ImageMapLayerSettings.fromJSON(props);
+    const treeRef = new ImageryMapLayerTreeReference({ layerSettings: settings, layerIndex: 0, iModel: imodel });
+    const tree = await treeRef.treeOwner.loadTree() as ImageryMapTileTree;
+    expect(tree).toBeDefined();
+    const root = tree.rootTile as ImageryMapTile;
+    return { tree, root };
+  }
+
+  /** Helper: create a child ImageryMapTile under a parent */
+  function createChild(parent: ImageryMapTile, tree: ImageryMapTileTree, level: number, column: number, row: number, isLeaf = false): ImageryMapTile {
+    const quadId = new QuadId(level, column, row);
+    const rectangle = tree.tilingScheme.tileXYToRectangle(column, row, level);
+    const range = Range3d.createXYZXYZ(rectangle.low.x, rectangle.low.y, 0, rectangle.high.x, rectangle.high.y, 0);
+    return new ImageryMapTile({ parent, isLeaf, contentId: quadId.contentId, range, maximumSize: 256 }, tree, quadId, rectangle);
+  }
+
+  describe("setContent", () => {
+    it("should mark self as leaf when content has no texture, not the parent", async () => {
+      const { tree, root } = await createTreeAndRoot();
+      const child = createChild(root, tree, 1, 0, 0);
+
+      // Before setContent: neither should be a leaf
+      expect(child.isLeaf).toBe(false);
+      const rootWasLeaf = root.isLeaf;
+
+      // Set content with no texture (simulates empty tile from server)
+      child.setContent({});
+
+      // Child should be marked as leaf (no data below it)
+      expect(child.isLeaf).toBe(true);
+      // Parent should NOT be affected — siblings should remain traversable
+      expect(root.isLeaf).toBe(rootWasLeaf);
+    });
+
+    it("should not mark self as leaf when content has a texture", async () => {
+      const { tree, root } = await createTreeAndRoot();
+      const child = createChild(root, tree, 1, 0, 0);
+
+      // Create a mock texture
+      const mockTexture = { bytesUsed: 100 } as any;
+      child.setContent({ imageryTexture: mockTexture });
+
+      // Child should NOT be a leaf — texture exists, so deeper levels may too
+      expect(child.isLeaf).toBe(false);
+    });
+  });
+
+  describe("selectCartoDrapeTiles", () => {
+    it("should not treat a not-found tile as a terminal leaf", async () => {
+      const { tree, root } = await createTreeAndRoot();
+
+      // Simulate a sparse tile pyramid: level-1 child returns 404 (not found)
+      const child = createChild(root, tree, 1, 0, 0);
+      child.setNotFound();
+
+      expect(child.isNotFound).toBe(true);
+      expect(child.isLeaf).toBe(false);
+
+      const loadChildrenSpy = vi.spyOn(child as any, "loadChildren").mockReturnValue(TileTreeLoadStatus.Loading);
+
+      const drapeTiles: ImageryMapTile[] = [];
+      const highResTiles: ImageryMapTile[] = [];
+      const mockArgs = { markChildrenLoading: vi.fn() } as unknown as TileDrawArgs;
+      const status = child.selectCartoDrapeTiles(drapeTiles, highResTiles, child.rectangle, 0.0000001, mockArgs);
+
+      // Should attempt to load children rather than stopping at this tile
+      expect(loadChildrenSpy).toHaveBeenCalled();
+      expect(status).toBe(TileTreeLoadStatus.Loading);
+      // eslint-disable-next-line @typescript-eslint/unbound-method
+      expect(mockArgs.markChildrenLoading).toHaveBeenCalled();
+      expect(drapeTiles).toHaveLength(0);
+    });
+  });
 });

core/frontend/src/test/tile/map/WmtsCapabilities.test.ts

@@ -245,6 +245,169 @@ describe("WmtsCapabilities1", () => {
     expect(googleTms?.length).toEqual(2);
   });
 
+  it("should parse TileMatrixSetLimits from great-artesian-basin", () => {
+    // Minimal WMTS capabilities XML with TileMatrixSetLimits to test parsing.
+    // Based on the great-artesian-basin.xml fixture structure.
+    const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<Capabilities xmlns="http://www.opengis.net/wmts/1.0" xmlns:ows="http://www.opengis.net/ows/1.1" version="1.0.0">
+  <Contents>
+    <Layer>
+      <ows:Title>TestLayer</ows:Title>
+      <ows:Identifier>test-layer</ows:Identifier>
+      <Style isDefault="true"><ows:Identifier>default</ows:Identifier></Style>
+      <Format>image/png</Format>
+      <TileMatrixSetLink>
+        <TileMatrixSet>EPSG:3857</TileMatrixSet>
+        <TileMatrixSetLimits>
+          <TileMatrixLimits>
+            <TileMatrix>EPSG:3857:0</TileMatrix>
+            <MinTileRow>0</MinTileRow>
+            <MaxTileRow>0</MaxTileRow>
+            <MinTileCol>0</MinTileCol>
+            <MaxTileCol>0</MaxTileCol>
+          </TileMatrixLimits>
+          <TileMatrixLimits>
+            <TileMatrix>EPSG:3857:5</TileMatrix>
+            <MinTileRow>16</MinTileRow>
+            <MaxTileRow>19</MaxTileRow>
+            <MinTileCol>27</MinTileCol>
+            <MaxTileCol>30</MaxTileCol>
+          </TileMatrixLimits>
+        </TileMatrixSetLimits>
+      </TileMatrixSetLink>
+    </Layer>
+    <TileMatrixSet>
+      <ows:Identifier>EPSG:3857</ows:Identifier>
+      <ows:SupportedCRS>urn:ogc:def:crs:EPSG::3857</ows:SupportedCRS>
+      <TileMatrix><ows:Identifier>EPSG:3857:0</ows:Identifier><ScaleDenominator>559082264</ScaleDenominator><TopLeftCorner>-20037508 20037508</TopLeftCorner><TileWidth>256</TileWidth><TileHeight>256</TileHeight><MatrixWidth>1</MatrixWidth><MatrixHeight>1</MatrixHeight></TileMatrix>
+    </TileMatrixSet>
+  </Contents>
+</Capabilities>`;
+
+    const capabilities = WmtsCapabilities.createFromXml(xml);
+    expect(capabilities).toBeDefined();
+
+    const layer = capabilities?.contents?.layers[0];
+    expect(layer).toBeDefined();
+    expect(layer!.identifier).toEqual("test-layer");
+
+    const epsg3857Link = layer?.tileMatrixSetLinks.find((link) => link.tileMatrixSet === "EPSG:3857");
+    expect(epsg3857Link).toBeDefined();
+
+    // BUG: TileMatrixSetLimits are never parsed because inner getElementsByTagName uses
+    // "TileMatrixSetLimits" (the container tag) instead of "TileMatrixLimits" (the child tag).
+    // This test SHOULD pass once the parsing bug is fixed.
+    expect(epsg3857Link!.tileMatrixSetLimits.length).toEqual(2);
+
+    // Verify the first limit entry (level 0)
+    const firstLimit = epsg3857Link!.tileMatrixSetLimits[0];
+    expect(firstLimit.tileMatrix).toEqual("EPSG:3857:0");
+    expect(firstLimit.limits).toBeDefined();
+    expect(firstLimit.limits!.low.x).toEqual(0);  // MinTileCol
+    expect(firstLimit.limits!.low.y).toEqual(0);  // MinTileRow
+    expect(firstLimit.limits!.high.x).toEqual(0); // MaxTileCol
+    expect(firstLimit.limits!.high.y).toEqual(0); // MaxTileRow
+
+    // Verify level 5 limit entry
+    const level5Limit = epsg3857Link!.tileMatrixSetLimits[1];
+    expect(level5Limit.tileMatrix).toEqual("EPSG:3857:5");
+    expect(level5Limit.limits).toBeDefined();
+    expect(level5Limit.limits!.low.x).toEqual(27);  // MinTileCol
+    expect(level5Limit.limits!.low.y).toEqual(16);  // MinTileRow
+    expect(level5Limit.limits!.high.x).toEqual(30); // MaxTileCol
+    expect(level5Limit.limits!.high.y).toEqual(19); // MaxTileRow
+  });
+
+  it("should parse Propeller Aero NDOT capabilities", () => {
+    // Minimal XML representative of Propeller Aero WMTS: localized dataset,
+    // no TileMatrixSetLimits, resource URL template, small WGS84 bounding box.
+    const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<Capabilities xmlns="http://www.opengis.net/wmts/1.0" xmlns:ows="http://www.opengis.net/ows/1.1" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.0.0">
+  <ows:ServiceIdentification>
+    <ows:Title>PropellerAero WMTS Service</ows:Title>
+    <ows:ServiceType>OGC WMTS</ows:ServiceType>
+    <ows:ServiceTypeVersion>1.0.0</ows:ServiceTypeVersion>
+  </ows:ServiceIdentification>
+  <Contents>
+    <Layer>
+      <ows:Title>Oct 30, 2025</ows:Title>
+      <ows:Identifier>dsce0d0b33</ows:Identifier>
+      <ows:WGS84BoundingBox crs="urn:ogc:def:crs:OGC:2:84">
+        <ows:LowerCorner>-96.18430645001274 40.81005980948186</ows:LowerCorner>
+        <ows:UpperCorner>-96.17298696901085 40.81541280531352</ows:UpperCorner>
+      </ows:WGS84BoundingBox>
+      <Style isDefault="true">
+        <ows:Title>default</ows:Title>
+        <ows:Identifier>default</ows:Identifier>
+      </Style>
+      <Format>image/png</Format>
+      <TileMatrixSetLink>
+        <TileMatrixSet>PropellerAeroTileMatrix</TileMatrixSet>
+      </TileMatrixSetLink>
+      <ResourceURL format="image/png" resourceType="tile" template="https://cdn.example.com/tiles/{TileMatrixSet}/{TileMatrix}/{TileCol}/{TileRow}.png"/>
+    </Layer>
+    <TileMatrixSet>
+      <ows:Title>PropellerAeroTileMatrix</ows:Title>
+      <ows:Identifier>PropellerAeroTileMatrix</ows:Identifier>
+      <ows:SupportedCRS>urn:ogc:def:crs:EPSG::3857</ows:SupportedCRS>
+      <WellKnownScaleSet>urn:ogc:def:wkss:OGC:1.0:GoogleMapsCompatible</WellKnownScaleSet>
+      <TileMatrix><ows:Identifier>0</ows:Identifier><ScaleDenominator>559082264.0287178</ScaleDenominator><TopLeftCorner>-20037508.3427892 20037508.3427892</TopLeftCorner><TileWidth>256</TileWidth><TileHeight>256</TileHeight><MatrixWidth>1</MatrixWidth><MatrixHeight>1</MatrixHeight></TileMatrix>
+      <TileMatrix><ows:Identifier>1</ows:Identifier><ScaleDenominator>279541132.0143589</ScaleDenominator><TopLeftCorner>-20037508.3427892 20037508.3427892</TopLeftCorner><TileWidth>256</TileWidth><TileHeight>256</TileHeight><MatrixWidth>2</MatrixWidth><MatrixHeight>2</MatrixHeight></TileMatrix>
+      <TileMatrix><ows:Identifier>20</ows:Identifier><ScaleDenominator>533.182395962446</ScaleDenominator><TopLeftCorner>-20037508.3427892 20037508.3427892</TopLeftCorner><TileWidth>256</TileWidth><TileHeight>256</TileHeight><MatrixWidth>1048576</MatrixWidth><MatrixHeight>1048576</MatrixHeight></TileMatrix>
+    </TileMatrixSet>
+  </Contents>
+</Capabilities>`;
+
+    const capabilities = WmtsCapabilities.createFromXml(xml);
+    expect(capabilities).toBeDefined();
+    expect(capabilities?.version).toEqual("1.0.0");
+
+    // Service identification
+    expect(capabilities?.serviceIdentification?.title).toEqual("PropellerAero WMTS Service");
+    expect(capabilities?.serviceIdentification?.serviceType).toEqual("OGC WMTS");
+
+    // Layer
+    expect(capabilities?.contents?.layers.length).toEqual(1);
+    const layer = capabilities!.contents!.layers[0];
+    expect(layer.identifier).toEqual("dsce0d0b33");
+
+    // The layer covers a small area near Lincoln, NE
+    expect(layer.wsg84BoundingBox).toBeDefined();
+    expect(layer.wsg84BoundingBox!.west).toBeDefined();
+    const area = layer.wsg84BoundingBox!.globalLocationArea;
+    // Longitude ~ -96.18 to -96.17 (small site in Nebraska)
+    expect(area.southwest.longitudeDegrees).toBeCloseTo(-96.184, 2);
+    expect(area.northeast.longitudeDegrees).toBeCloseTo(-96.173, 2);
+    expect(area.southwest.latitudeDegrees).toBeCloseTo(40.810, 2);
+    expect(area.northeast.latitudeDegrees).toBeCloseTo(40.815, 2);
+
+    // Tile matrix set
+    expect(capabilities?.contents?.tileMatrixSets.length).toEqual(1);
+    const tms = capabilities!.contents!.tileMatrixSets[0];
+    expect(tms.identifier).toEqual("PropellerAeroTileMatrix");
+    expect(tms.supportedCrs).toContain("EPSG::3857");
+    expect(tms.wellKnownScaleSet).toContain("GoogleMapsCompatible");
+
+    // Verify it's recognized as Google Maps compatible
+    const googleTms = capabilities?.contents?.getGoogleMapsCompatibleTileMatrixSet();
+    expect(googleTms?.length).toEqual(1);
+    expect(googleTms![0].identifier).toEqual("PropellerAeroTileMatrix");
+
+    // No TileMatrixSetLimits — this Propeller endpoint doesn't publish them,
+    // which is part of why sparse tile requests fail.
+    const tmLink = layer.tileMatrixSetLinks[0];
+    expect(tmLink.tileMatrixSet).toEqual("PropellerAeroTileMatrix");
+    expect(tmLink.tileMatrixSetLimits.length).toEqual(0);
+
+    // Resource URL should be present
+    expect(layer.resourceUrls.length).toBeGreaterThan(0);
+    const pngUrl = layer.resourceUrls.find((u) => u.format.includes("png"));
+    expect(pngUrl).toBeDefined();
+    expect(pngUrl!.template).toContain("{TileMatrix}");
+    expect(pngUrl!.template).toContain("{TileCol}");
+    expect(pngUrl!.template).toContain("{TileRow}");
+  });
+
 
 
   it("should request proper URL", async () => {

core/frontend/src/test/tile/map/WmtsMapLayerImageryProvider.test.ts

@@ -5,10 +5,11 @@
 
 import { EmptyLocalization, ImageMapLayerSettings, ServerError } from "@itwin/core-common";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { WmtsCapabilities, WmtsMapLayerImageryProvider } from "../../../tile/internal";
+import { QuadId, WmtsCapabilities, WmtsCapability, WmtsMapLayerImageryProvider } from "../../../tile/internal";
 import { IModelApp } from "../../../IModelApp";
 import { RequestBasicCredentials } from "../../../request/Request";
 import { fakeTextFetch } from "./MapLayerTestUtilities";
+import { Range2d } from "@itwin/core-geometry";
 
 const wmtsSampleSource = { formatId: "WMTS", url: "https://localhost/wmts", name: "Test WMTS" };
 describe("WmtsMapLayerImageryProvider", () => {
@@ -127,6 +128,48 @@ describe("WmtsMapLayerImageryProvider", () => {
     expect(url).toEqual(`${refUrl}&${param1.toString()}&${param2.toString()}`);
   });
 
+  it("_generateChildIds should filter children by TileMatrixSetLimits", async () => {
+    // Set up a mock that returns limits restricting which tiles are valid.
+    // At level 1, only tile (col=1, row=1) is valid (matching great-artesian-basin level 1 limits).
+    const tileMatrixSet: Partial<WmtsCapability.TileMatrixSet> = {
+      tileMatrix: [
+        { identifier: "0" } as WmtsCapability.TileMatrix,
+        { identifier: "1" } as WmtsCapability.TileMatrix,
+      ],
+      identifier: "TestTMS",
+    };
+
+    // Level 1 limits: only col 1, row 1 is valid
+    const limitsLevel1: Partial<WmtsCapability.TileMatrixSetLimits> = {
+      tileMatrix: "1",
+      limits: Range2d.createXYXY(1, 1, 1, 1), // MinTileCol=1, MinTileRow=1, MaxTileCol=1, MaxTileRow=1
+    };
+
+    vi.spyOn(WmtsMapLayerImageryProvider.prototype, "getDisplayedTileMatrixSetAndLimits" as any).mockImplementation(() => {
+      return {
+        tileMatrixSet,
+        limits: [limitsLevel1 as WmtsCapability.TileMatrixSetLimits],
+      };
+    });
+
+    const settings = ImageMapLayerSettings.fromJSON({ formatId: "WMTS", name: "test", url: "https://fake/wmts" });
+    const provider = new WmtsMapLayerImageryProvider(settings);
+
+    // Parent is at level 0, col 0, row 0. Children at level 1 are:
+    // (col=0,row=0), (col=1,row=0), (col=0,row=1), (col=1,row=1)
+    // Only (col=1,row=1) should be returned since limits restrict to col=1,row=1.
+    const parentQuadId = new QuadId(0, 0, 0);
+    let resolvedChildIds: QuadId[] = [];
+    (provider as any)._generateChildIds(parentQuadId, (childIds: QuadId[]) => {
+      resolvedChildIds = childIds;
+    });
+
+    // Limits are matched by tileMatrix identifier, so only tiles within col=1,row=1 are returned.
+    expect(resolvedChildIds.length).toEqual(1);
+    expect(resolvedChildIds[0].column).toEqual(1);
+    expect(resolvedChildIds[0].row).toEqual(1);
+  });
+
   it("construct tile url using resource url", async () => {
     const response = await fetch(`/assets/wmts_capabilities/wmts_resource_url.xml`);
     const text = await response.text();