save pmtiles debug

Author: AlaricBaraou

CLAUDE.md

@@ -0,0 +1,103 @@
+# 3DTilesRendererJS - Claude Code Guide
+
+## Project Overview
+
+**3DTilesRendererJS** is a Three.js renderer implementation for the [3D Tiles specification](https://github.com/CesiumGS/3d-tiles), an OGC standard for streaming massive geospatial 3D datasets. This NASA-AMMOS project supports rendering geographic and geometric tile data including Mars terrain, Google Photorealistic Tiles, and various map tile formats.
+
+- **Package**: `3d-tiles-renderer` (npm)
+- **License**: Apache-2.0
+
+## Build Commands
+
+```bash
+npm install          # Install dependencies
+npm start            # Dev server at http://localhost:5173
+npm run build-lib    # Build library to /build
+npm test             # TypeScript check + Vitest
+npm run lint         # ESLint + TypeScript
+```
+
+## Directory Structure
+
+```
+src/
+├── core/                    # Framework-agnostic implementations
+│   ├── plugins/             # Base plugin classes
+│   └── renderer/
+│       ├── loaders/         # Format loaders: B3DM, I3DM, PNTS, CMPT, MVT
+│       ├── tiles/           # Tile traversal algorithms
+│       └── utilities/       # BatchTable, PriorityQueue, LRUCache
+├── three/                   # Three.js-specific implementations
+│   ├── plugins/             # Three.js plugins
+│   │   ├── images/          # Image overlay plugins (TMS, XYZ, WMTS, WMS, MVT, PMTiles)
+│   │   │   └── sources/     # Image source implementations
+│   │   ├── gltf/            # GLTF extensions & metadata
+│   │   └── batched/         # Batched rendering optimization
+│   └── renderer/
+│       ├── loaders/         # Three.js tile format loaders
+│       ├── tiles/           # TilesRenderer & TilesGroup
+│       ├── controls/        # GlobeControls, EnvironmentControls
+│       └── math/            # Ellipsoid, OBB, GeoUtils
+├── r3f/                     # React Three Fiber components
+└── plugins.js               # Plugin re-exports
+
+example/                     # Three.js and R3F examples
+test/                        # Vitest unit tests
+```
+
+## Architecture
+
+### Main Classes
+
+- **TilesRenderer** (`src/three/renderer/tiles/TilesRenderer.js`) - Main Three.js rendering class
+- **TilesRendererBase** (`src/core/renderer/tiles/TilesRendererBase.js`) - Framework-agnostic core
+
+### Plugin System
+
+Plugins extend functionality through lifecycle hooks:
+
+```javascript
+class MyPlugin extends TilesPlugin {
+  constructor() {
+    super();
+    this.name = 'MY_PLUGIN';
+  }
+  preprocessURL( url ) { }
+  postProcess( tile ) { }
+  onLoadModel( { scene, tile } ) { }
+  onDisposeModel( { scene, tile } ) { }
+}
+```
+
+### Tile Formats Supported
+
+- **B3DM** - Batched 3D Model
+- **I3DM** - Instanced 3D Model
+- **PNTS** - Point Cloud
+- **CMPT** - Composite
+- **MVT** - Mapbox Vector Tiles (in development)
+- **Quantized Mesh** - Terrain mesh
+
+## Code Style
+
+- **Indentation**: Tabs
+- **Quotes**: Single quotes
+- **Semicolons**: Always
+- **Naming**: Long descriptive names preferred (`isHierarchicallyVisible` not `isVis`)
+- **Private members**: Underscore prefix (`this._internalState`)
+- **Comments**: Explain WHY, not WHAT
+
+## Key Technologies
+
+- **three**: ^0.170.0 (required peer dependency)
+- **vite**: Build tool
+- **vitest**: Test runner
+- **typescript**: Type checking (JSDoc-based)
+
+## Module Exports
+
+- `3d-tiles-renderer` - Full library
+- `3d-tiles-renderer/core` - Core only
+- `3d-tiles-renderer/three` - Three.js implementation
+- `3d-tiles-renderer/r3f` - React Three Fiber
+- `3d-tiles-renderer/three/plugins` - Three.js plugins

example/three/geojson.js

@@ -12,15 +12,16 @@ import {
 import {
 	UpdateOnChangePlugin,
 	MVTTilesPlugin,
-	MVTTilesMeshPlugin
+	MVTTilesMeshPlugin,
+	PMTilesPlugin
 } from '3d-tiles-renderer/plugins';
 
 import { GUI } from 'three/examples/jsm/libs/lil-gui.module.min.js';
 
 let scene, renderer, camera, controls, tiles, gui;
 
-const apiKey = localStorage.getItem( 'mapbox_key' ) || prompt( 'Enter Mapbox API Key' );
-if ( apiKey ) localStorage.setItem( 'mapbox_key', apiKey );
+// const apiKey = localStorage.getItem( 'mapbox_key' ) || prompt( 'Enter Mapbox API Key' );
+// if ( apiKey ) localStorage.setItem( 'mapbox_key', apiKey );
 
 // --- Dynamic Filter State ---
 const state = {
@@ -41,13 +42,13 @@ const state = {
 		landuse: '#caedc1',
 		building: '#eeeeee',
 		road: '#444444',
-		admin: '#ff0000',
+		boundaries: '#ff0000',
 		poi: '#ffcc00',
 		default: '#222222'
 	}
 };
 
-const MVT_URL = `https://api.mapbox.com/v4/mapbox.mapbox-streets-v8/{z}/{x}/{y}.vector.pbf?access_token=${apiKey}`;
+// const MVT_URL = `https://api.mapbox.com/v4/mapbox.mapbox-streets-v8/{z}/{x}/{y}.vector.pbf?access_token=${apiKey}`;
 
 init();
 setupGUI();
@@ -90,10 +91,10 @@ function mvtFilter( feature, layerName ) {
 	if ( layerName === 'landuse' && ! state.showLanduse ) return false;
 
 	// 2. Advanced Admin Filtering
-	if ( layerName === 'admin' ) {
+	if ( layerName === 'boundaries' ) {
 
 		if ( ! state.showAdmin ) return false;
-		return props.admin_level <= state.maxAdminLevel;
+		return true;
 
 	}
 
@@ -120,6 +121,8 @@ function recreateTiles() {
 
 	}
 
+	const PMTILES_URL = 'https://demo-bucket.protomaps.com/v4.pmtiles';
+
 	tiles = new TilesRenderer();
 	tiles.registerPlugin( new UpdateOnChangePlugin() );
 
@@ -128,20 +131,22 @@ function recreateTiles() {
 		shape: 'ellipsoid',
 		levels: 15,
 		tileDimension: 512,
-		url: MVT_URL,
+		url: PMTILES_URL,
 		styles: state.colors,
 		filter: mvtFilter
 	};
 
-	if ( state.pluginType === 'Mesh' ) {
+	tiles.registerPlugin( new PMTilesPlugin( pluginOptions ) );
 
-		tiles.registerPlugin( new MVTTilesMeshPlugin( pluginOptions ) );
+	// if ( state.pluginType === 'Mesh' ) {
 
-	} else {
+	// 	tiles.registerPlugin( new MVTTilesMeshPlugin( pluginOptions ) );
 
-		tiles.registerPlugin( new MVTTilesPlugin( pluginOptions ) );
+	// } else {
 
-	}
+	// 	tiles.registerPlugin( new MVTTilesPlugin( pluginOptions ) );
+
+	// }
 
 	tiles.group.rotation.x = - Math.PI / 2;
 	tiles.setCamera( camera );

example/three/mvt_globe.js

@@ -98,19 +98,21 @@
     "globals": "^16.5.0",
     "leva": "^0.10.0",
     "postprocessing": "^6.36.4",
+    "pmtiles": "^4.3.2",
     "three": "^0.170.0",
     "typescript": "^5.6.0",
     "typescript-eslint": "^8.48.1",
     "vite": "^6.2.2",
     "vitest": "^4.0.15"
   },
   "peerDependencies": {
+    "@mapbox/vector-tile": "^2.0.3",
     "@react-three/fiber": "^8.17.9 || ^9.0.0",
+    "earcut": "^3.0.2",
     "react": "^18.3.1 || ^19.0.0",
     "react-dom": "^18.3.1 || ^19.0.0",
     "three": ">=0.167.0",
-    "@mapbox/vector-tile": "^2.0.3",
-    "earcut": "^3.0.2"
+    "pmtiles": "^4.3.2"
   },
   "peerDependenciesMeta": {
     "@react-three/fiber": {
@@ -127,6 +129,9 @@
     },
     "earcut": {
       "optional": true
+    },
+    "pmtiles": {
+      "optional": true
     }
   }
 }

package-lock.json

@@ -0,0 +1,17 @@
+import { ColorRepresentation } from 'three';
+
+export class PMTilesPlugin {
+
+	constructor( options: {
+		url: string,
+		tileDimension?: number,
+		filter?: ( feature: any, layerName: string ) => boolean,
+		styles?: { [ layerName: string ]: ColorRepresentation },
+
+		center?: boolean,
+		shape?: 'ellipsoid' | 'planar',
+		endCaps?: boolean,
+		useRecommendedSettings?: boolean,
+	} );
+
+}

package.json

@@ -0,0 +1,28 @@
+import { EllipsoidProjectionTilesPlugin } from './EllipsoidProjectionTilesPlugin.js';
+import { PMTilesImageSource } from './sources/PMTilesImageSource.js';
+
+export class PMTilesPlugin extends EllipsoidProjectionTilesPlugin {
+
+	constructor( options = {} ) {
+
+		const { ...rest } = options;
+		super( rest );
+
+		this.name = 'PMTILES_PLUGIN';
+		this.imageSource = new PMTilesImageSource( options );
+
+	}
+
+	fetchData( url, options ) {
+
+		if ( url.startsWith( 'pmtiles://' ) ) {
+
+			return this.imageSource.fetchInternal( url, options );
+
+		}
+
+		return null;
+
+	}
+
+}

src/three/plugins/images/PMTilesPlugin.d.ts

@@ -56,7 +56,7 @@ export class MVTImageSource extends XYZImageSource {
 		const layerOrder = [
 			'landuse', 'park', 'water', 'waterway',
 			'transportation', 'road', 'building',
-			'admin', 'poi', 'place_label'
+			'boundaries', 'poi', 'place_label'
 		];
 
 		const layersToDraw = Object.keys( vectorTile.layers ).sort( ( a, b ) => {

src/three/plugins/images/PMTilesPlugin.js

@@ -0,0 +1,22 @@
+import { ColorRepresentation, Texture } from 'three';
+import { PMTiles } from 'pmtiles';
+
+export class PMTilesImageSource {
+
+	readonly pmtilesUrl: string;
+	readonly instance: PMTiles;
+
+	constructor( options: {
+		url: string,
+		tileDimension?: number,
+		filter?: ( feature: any, layerName: string ) => boolean,
+		styles?: { [ layerName: string ]: ColorRepresentation },
+		fetchOptions?: RequestInit,
+	} );
+
+	init(): Promise<void>;
+	getUrl( x: number, y: number, level: number ): string;
+	fetchInternal( url: string, options: { signal?: AbortSignal } ): Promise<ArrayBuffer | null>;
+	processBufferToTexture( buffer: ArrayBuffer ): Promise<Texture>;
+
+}