Skip to content

Add PMTiles basemaps to iTowns #2662

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ymoisan wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Add PMTiles basemaps to iTowns #2662

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7afe87e
New MVT PMTiles source with example
ymoisan Dec 10, 2025
65648a3
Source implementations
ymoisan Dec 15, 2025
74db796
refactor(PMTilesVectorSource): address PR review feedback
ymoisan Jan 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
358 changes: 358 additions & 0 deletions examples/source_pmtiles_vector.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,358 @@
<html>
<head>
<title>Itowns - PMTiles Vector Source</title>

<script type="importmap">
{
"imports": {
"itowns": "../dist/itowns.js",
"debug": "../dist/debug.js",
"GuiTools": "./jsm/GUI/GuiTools.js",
"LoadingScreen": "./jsm/GUI/LoadingScreen.js",
"three": "https://unpkg.com/three@0.170.0/build/three.module.js",
"three/addons/": "https://unpkg.com/three@0.170.0/examples/jsm/",
"lil-gui": "https://unpkg.com/lil-gui@0.19.2/dist/lil-gui.esm.js"
}
}
</script>

<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">

<link rel="stylesheet" type="text/css" href="css/example.css">
<link rel="stylesheet" type="text/css" href="css/LoadingScreen.css">

<style type="text/css">
#description {
z-index: 2;
left: 10px;
max-width: 400px;
background: rgba(255, 255, 255, 0.95);
padding: 10px;
border-radius: 5px;
box-shadow: 0 2px 10px rgba(0,0,0,0.2);
}

#description .marg {
margin: 10px;
}

#layerInfo {
font-size: 12px;
color: #555;
margin-top: 10px;
}
</style>

</head>
<body>
<div id="viewerDiv"></div>
<div id="description">
<h3>PMTiles Vector Source</h3>
<p>Load vector tiles from a PMTiles archive:</p>
<input type="text" id="url" style="width: 100%; box-sizing: border-box;" placeholder="Enter PMTiles URL" />
<button id="loadButton" style="margin-top: 5px;">Load PMTiles</button>

<!-- Info -->
<div id="layerInfo" class="marg"></div>
</div>

<script type="module">
import * as THREE from 'three';
import { GUI } from 'lil-gui';
import setupLoadingScreen from 'LoadingScreen';
import * as itowns from 'itowns';

const {
TMSSource, WMTSSource, PMTilesVectorSource,
ColorLayer, ElevationLayer,
GlobeView, Coordinates, Fetcher, Style,
} = itowns;

// ---- Create a GlobeView ----

// Define camera initial position (matching 3dtiles_loader.html)
const placement = {
coord: new Coordinates('EPSG:4326', 2.351323, 48.856712),
range: 12500000,
};

const viewerDiv = document.getElementById('viewerDiv');

const view = new GlobeView(viewerDiv, placement, {
controls: { minDistance: 100 },
});

setupLoadingScreen(viewerDiv, view);

// ---- Add a basemap ----

Fetcher.json('./layers/JSONLayers/OPENSM.json').then((config) => {
const colorLayer = new ColorLayer('Ortho', {
...config,
source: new TMSSource(config.source),
});
view.addLayer(colorLayer);
});

// ---- Add 3D terrain ----

function addElevationLayerFromConfig(config) {
config.source = new itowns.WMTSSource(config.source);
const elevationLayer = new itowns.ElevationLayer(config.id, config);
view.addLayer(elevationLayer);
}
itowns.Fetcher.json('./layers/JSONLayers/IGN_MNT_HIGHRES.json').then(addElevationLayerFromConfig);
itowns.Fetcher.json('./layers/JSONLayers/WORLD_DTM.json').then(addElevationLayerFromConfig);

// ---- PMTiles Vector Layer ----

let pmtilesLayer = null;
let currentPmtilesSource = null;
let gui = null;
let layersFolder = null;

// User-controlled opacity (persists through layer refreshes)
let userOpacity = 0.5;

// Layer visibility state (managed at example level per reviewer feedback)
let layerVisibility = {};
let originalLayers = {};

// Constant style (reviewer: instantiate once since it never changes)
const LAYER_STYLE = new Style({
fill: {
color: '#4682b4',
opacity: 1.0,
},
stroke: {
color: '#ffffff',
width: 1,
},
point: {
color: '#4682b4',
radius: 4,
line: '#ffffff',
},
});

// Visibility helpers (moved from Source per reviewer feedback)
function setLayerVisibility(source, layerName, visible) {
layerVisibility[layerName] = visible;
if (originalLayers[layerName]) {
if (visible) {
source.layers[layerName] = [...originalLayers[layerName]];
} else {
source.layers[layerName] = [];
}
}
}

function setAllLayersVisibility(source, visible) {
Object.keys(originalLayers).forEach((layerName) => {
setLayerVisibility(source, layerName, visible);
});
}

function getLayerVisibility(layerName) {
return layerVisibility[layerName] !== false;
}

function initVisibilityState(source) {
layerVisibility = {};
originalLayers = {};
Object.keys(source.layers).forEach((name) => {
layerVisibility[name] = true;
originalLayers[name] = [...source.layers[name]];
});
}

// Refresh the layer by removing and re-adding it
// Note: clearCache() removed per reviewer feedback - not needed for layer refresh
async function refreshLayer(pmtilesSource) {
if (!pmtilesLayer || !pmtilesSource) {
return;
}

const opacityToUse = userOpacity;

view.removeLayer('pmtiles-vectors');

pmtilesLayer = new ColorLayer('pmtiles-vectors', {
source: pmtilesSource,
transparent: true,
opacity: opacityToUse,
noTextureParentOutsideLimit: true,
style: LAYER_STYLE,
});

await view.addLayer(pmtilesLayer);
pmtilesLayer.opacity = opacityToUse;
view.notifyChange(pmtilesLayer);
}

// Setup lil-gui controls
function setupGui(pmtilesSource, names) {
if (gui) {
gui.destroy();
}

gui = new GUI({ title: 'PMTiles Controls' });

// Opacity control
const layerSettings = { opacity: userOpacity };
gui.add(layerSettings, 'opacity', 0, 1, 0.01)
.name('Opacity')
.onChange((value) => {
userOpacity = value;
if (pmtilesLayer) {
pmtilesLayer.opacity = value;
view.notifyChange(pmtilesLayer);
}
});

// Layer visibility controls (using example-level helpers)
if (names.length > 0) {
layersFolder = gui.addFolder('Source Layers');

const allLayersObj = { visible: true };
layersFolder.add(allLayersObj, 'visible')
.name('All Layers')
.onChange((value) => {
setAllLayersVisibility(pmtilesSource, value);
layerControllers.forEach((ctrl) => {
ctrl.setValue(value);
});
refreshLayer(pmtilesSource);
});

const layerControllers = [];
names.forEach((layerName) => {
const layerObj = { visible: getLayerVisibility(layerName) };
const ctrl = layersFolder.add(layerObj, 'visible')
.name(layerName)
.onChange((value) => {
setLayerVisibility(pmtilesSource, layerName, value);
refreshLayer(pmtilesSource);
});
layerControllers.push(ctrl);
});

layersFolder.open();
}
}

function loadPMTiles(url) {
if (!url) {
console.warn('No PMTiles URL provided');
return;
}

// Remove existing PMTiles layer and GUI
if (pmtilesLayer) {
view.removeLayer('pmtiles-vectors');
pmtilesLayer = null;
currentPmtilesSource = null;
}
if (gui) {
gui.destroy();
gui = null;
}

console.log('Loading PMTiles from:', url);
document.getElementById('layerInfo').innerHTML = '<p>Loading PMTiles header...</p>';

const pmtilesSource = new PMTilesVectorSource({ url });

// IMPORTANT: Wait for header to load BEFORE adding the layer
// This ensures extentInsideLimit has the correct bounds
pmtilesSource.whenReady.then((header) => {
console.log('PMTiles header:', header);
console.log('PMTiles metadata:', pmtilesSource._metadata);

const vectorLayers = pmtilesSource._metadata?.vector_layers || [];
const names = vectorLayers.map((l) => l.id);

document.getElementById('layerInfo').innerHTML = `
<p><b>PMTiles Info:</b></p>
<p>Zoom: ${header.minZoom} - ${header.maxZoom}</p>
<p>Bounds: [${header.minLon?.toFixed(4)}, ${header.minLat?.toFixed(4)}] to [${header.maxLon?.toFixed(4)}, ${header.maxLat?.toFixed(4)}]</p>
<p>Layers: ${names.length}</p>
`;

// Initialize visibility state (managed at example level)
initVisibilityState(pmtilesSource);

// Setup lil-gui after layer is ready
setupGui(pmtilesSource, names);
currentPmtilesSource = pmtilesSource;

// NOW create and add the layer - after extent is set
pmtilesLayer = new ColorLayer('pmtiles-vectors', {
source: pmtilesSource,
transparent: true,
opacity: userOpacity,
noTextureParentOutsideLimit: true,
style: LAYER_STYLE,
});

view.addLayer(pmtilesLayer).then(() => {
console.log('PMTiles layer added');
pmtilesLayer.opacity = userOpacity;
view.notifyChange(pmtilesLayer);
}).catch((err) => {
console.error('Error adding layer:', err);
});

// Move camera to PMTiles extent (only for non-global datasets)
if (header.minLon != null && header.minLat != null) {
const centerLon = (header.minLon + header.maxLon) / 2;
const centerLat = (header.minLat + header.maxLat) / 2;
const extentWidth = Math.abs(header.maxLon - header.minLon);
const extentHeight = Math.abs(header.maxLat - header.minLat);
const maxExtent = Math.max(extentWidth, extentHeight);

// Check if the extent is global (covers most of the world)
const isGlobalExtent = extentWidth > 300 || extentHeight > 150;

if (!isGlobalExtent) {
// For regional datasets, zoom to the extent
const range = maxExtent * 111000 * 2;

view.controls.lookAtCoordinate({
coord: new Coordinates('EPSG:4326', centerLon, centerLat),
range: Math.max(range, 1000),
tilt: 45,
heading: 0,
});
}
// For global datasets, keep the initial view (like 3dtiles_loader)
}
}).catch((err) => {
console.error('Error loading PMTiles:', err);
document.getElementById('layerInfo').innerHTML =
`<p style="color: red;">Error: ${err.message}</p>`;
});
}

// ---- Event Handlers ----

document.getElementById('loadButton').addEventListener('click', () => {
loadPMTiles(document.getElementById('url').value);
});

document.getElementById('url').addEventListener('keypress', (e) => {
if (e.key === 'Enter') {
loadPMTiles(e.target.value);
}
});

// Expose for debugging
window.view = view;
window.itowns = itowns;
window.THREE = THREE;
window.loadPMTiles = loadPMTiles;

</script>
</body>
</html>
Loading