potential bugfix/overscaled 3d tile raycast

[dwayneparton]

Issue

When using terrain with a DEM source that has a lower maxzoom than the current display zoom (e.g., DEM maxzoom of 10 while viewing at zoom 14), the pointCoordinate raycast was not consistent with the rendered terrain. This caused issues where clicking on the visible terrain surface would return incorrect 3D coordinates.

{"type":"raster-dem","tiles":["https://example.tile.server/v1/terrain/{z}/{x}/{y}.png"],"tileSize":256,"maxzoom":10,"encoding":"terrarium"}

bug-raycast-on-overscaled-tiles.mov

Solution

The raycast now uses a proxy tile-based approach when overzoomed, which matches the exact geometry rendered by the terrain shader.

fix-raycast-on-proxied-tiles.mov

API Changes

No API Changes

Launch Checklist

• Make sure the PR title is descriptive and preferably reflects the change from the user's perspective.
• Add additional detail and context in the PR description (with screenshots/videos if there are visual changes).
• Manually test the debug page.
• Write tests for all new functionality and make sure the CI checks pass.
• Document any changes to public APIs.
• Post benchmark scores if the change could affect performance.

Initial Draft

Intent is to show the issue and potential fix for support request 176617. Happy to add some tests, I did some rudimentary benchmark tests but this needs to be done a bit more in depth.

[CLAassistant]

All committers have signed the CLA.

[github-actions]

Hey, @dwayneparton 👋 Thanks for your contribution to Mapbox GL JS!

Important: This repository does not accept direct merges. All changes go through our internal review process.

What happens next:

1. A team member will review your PR here first
2. If it looks good, they will import it to our internal repository for further review
3. If approved, changes will be synced back here via our release process

Please respond to any review comments on this PR. For more details, see CONTRIBUTING.md.

[nicozink]

Hi @dwayneparton, thank you for the PR and contribution. I have tested this code and it does work really nicely. My main concern is performance - did you have any findings in your rudimentary benchmark tests? I'm seeing about a 5-30x increase, just wondering if you noticed the same.

[dwayneparton]

2026-02-10.09-58-27.mov

I'm definitely seeing a difference. It seems to vary between both raycasting methods. I would expect the raycast on the proxy tiles to be a performance hit, but not sure what would be acceptable. Here's how I was testing, then processed the measures in the console.

    override raycast(pos: vec3, dir: vec3, exaggeration: number): number | null | undefined {
        if (!this._visibleDemTiles)
            return null;

        performance.mark('startRaycast');
        // Check if we're overzoomed (display zoom > DEM source maxzoom)
        // In this case, proxy tile raycast provides more accurate results
        const sourceCache = this._source();
        const isOverZoomed = sourceCache && this.painter.transform.zoom > sourceCache.getSource().maxzoom;

        let tag = ''
        if (isOverZoomed && this.proxyCoords && this.proxyCoords.length > 0) {
            const result = this._raycastWithProxyTiles(pos, dir, exaggeration);
            if (result != null) {
                performance.mark('endRaycast');
                performance.measure('raycastWithProxyTiles', 'startRaycast', 'endRaycast');
                return result;
            }
            tag = 'RanBoth'
        }

        const defaultRaycast = this._raycastWithDemTree(pos, dir, exaggeration);
        performance.mark('endRaycast');
        performance.measure(`raycastWithDemTree${tag}`, 'startRaycast', 'endRaycast');
        return defaultRaycast;
    }