@gisatcz/deckgl-geolib 2.6.0-dev.1 → 2.6.0-dev.3

package/dist/esm/react/index.js

@@ -0,0 +1,37 @@
+import { useState } from 'react';
+
+/**
+ * React hook for syncing terrain elevation bounds to overlay TileLayer for 3D frustum culling.
+ *
+ * Manages the zRange state needed to prevent foreground tile clipping when viewport is tilted in 3D.
+ *
+ * @returns Object with zRange state and onZRangeUpdate callback
+ *
+ * @example
+ * ```typescript
+ * const { zRange, onZRangeUpdate } = useTerrainZRange();
+ *
+ * const layers = useMemo(() => [
+ *   new TileLayer({
+ *     id: 'osm',
+ *     zRange: zRange,  // Pass elevation bounds to overlay
+ *     // ... other props
+ *   }),
+ *   new CogTerrainLayer({
+ *     id: 'terrain',
+ *     onZRangeUpdate: onZRangeUpdate,  // Sync elevation bounds from terrain
+ *     // ... other props
+ *   }),
+ * ], [zRange]);
+ * ```
+ */
+function useTerrainZRange() {
+    const [zRange, setZRange] = useState(null);
+    return {
+        zRange,
+        onZRangeUpdate: setZRange,
+    };
+}
+
+export { useTerrainZRange };
+//# sourceMappingURL=index.js.map

package/dist/esm/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/hooks/useTerrainZRange.ts"],"sourcesContent":["import { useState } from 'react';\nimport type { ZRange } from '../layers/CogTerrainLayer';\n\n/**\n * React hook for syncing terrain elevation bounds to overlay TileLayer for 3D frustum culling.\n *\n * Manages the zRange state needed to prevent foreground tile clipping when viewport is tilted in 3D.\n *\n * @returns Object with zRange state and onZRangeUpdate callback\n *\n * @example\n * ```typescript\n * const { zRange, onZRangeUpdate } = useTerrainZRange();\n *\n * const layers = useMemo(() => [\n *   new TileLayer({\n *     id: 'osm',\n *     zRange: zRange,  // Pass elevation bounds to overlay\n *     // ... other props\n *   }),\n *   new CogTerrainLayer({\n *     id: 'terrain',\n *     onZRangeUpdate: onZRangeUpdate,  // Sync elevation bounds from terrain\n *     // ... other props\n *   }),\n * ], [zRange]);\n * ```\n */\nexport function useTerrainZRange() {\n  const [zRange, setZRange] = useState<ZRange | null>(null);\n\n  return {\n    zRange,\n    onZRangeUpdate: setZRange,\n  };\n}\n"],"names":[],"mappings":";;AAGA;;;;;;;;;;;;;;;;;;;;;;;;AAwBG;SACa,gBAAgB,GAAA;IAC9B,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC;IAEzD,OAAO;QACL,MAAM;AACN,QAAA,cAAc,EAAE,SAAS;KAC1B;AACH;;;;"}

package/dist/esm/react/index.min.js

@@ -0,0 +1,2 @@
+import{useState as n}from"react";function t(){const[t,e]=n(null);return{zRange:t,onZRangeUpdate:e}}export{t as useTerrainZRange};
+//# sourceMappingURL=index.min.js.map

package/dist/esm/react/index.min.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.min.js","sources":["../../../src/hooks/useTerrainZRange.ts"],"sourcesContent":["import { useState } from 'react';\nimport type { ZRange } from '../layers/CogTerrainLayer';\n\n/**\n * React hook for syncing terrain elevation bounds to overlay TileLayer for 3D frustum culling.\n *\n * Manages the zRange state needed to prevent foreground tile clipping when viewport is tilted in 3D.\n *\n * @returns Object with zRange state and onZRangeUpdate callback\n *\n * @example\n * ```typescript\n * const { zRange, onZRangeUpdate } = useTerrainZRange();\n *\n * const layers = useMemo(() => [\n *   new TileLayer({\n *     id: 'osm',\n *     zRange: zRange,  // Pass elevation bounds to overlay\n *     // ... other props\n *   }),\n *   new CogTerrainLayer({\n *     id: 'terrain',\n *     onZRangeUpdate: onZRangeUpdate,  // Sync elevation bounds from terrain\n *     // ... other props\n *   }),\n * ], [zRange]);\n * ```\n */\nexport function useTerrainZRange() {\n  const [zRange, setZRange] = useState<ZRange | null>(null);\n\n  return {\n    zRange,\n    onZRangeUpdate: setZRange,\n  };\n}\n"],"names":["useTerrainZRange","zRange","setZRange","useState","onZRangeUpdate"],"mappings":"0CA4BgBA,IACd,MAAOC,EAAQC,GAAaC,EAAwB,MAEpD,MAAO,CACLF,SACAG,eAAgBF,EAEpB"}

package/dist/esm/types/hooks/index.d.ts

@@ -0,0 +1 @@
+export { useTerrainZRange } from './useTerrainZRange';

package/dist/esm/types/hooks/useTerrainZRange.d.ts

@@ -0,0 +1,30 @@
+import type { ZRange } from '../layers/CogTerrainLayer';
+/**
+ * React hook for syncing terrain elevation bounds to overlay TileLayer for 3D frustum culling.
+ *
+ * Manages the zRange state needed to prevent foreground tile clipping when viewport is tilted in 3D.
+ *
+ * @returns Object with zRange state and onZRangeUpdate callback
+ *
+ * @example
+ * ```typescript
+ * const { zRange, onZRangeUpdate } = useTerrainZRange();
+ *
+ * const layers = useMemo(() => [
+ *   new TileLayer({
+ *     id: 'osm',
+ *     zRange: zRange,  // Pass elevation bounds to overlay
+ *     // ... other props
+ *   }),
+ *   new CogTerrainLayer({
+ *     id: 'terrain',
+ *     onZRangeUpdate: onZRangeUpdate,  // Sync elevation bounds from terrain
+ *     // ... other props
+ *   }),
+ * ], [zRange]);
+ * ```
+ */
+export declare function useTerrainZRange(): {
+    zRange: ZRange | null;
+    onZRangeUpdate: import("react").Dispatch<import("react").SetStateAction<ZRange | null>>;
+};

package/dist/esm/types/index.d.ts

@@ -1,4 +1,6 @@
 export { CogBitmapLayer, CogTerrainLayer } from './layers/index';
 export { CogTiles, GeoImage } from './core/index';
 export { suppressGlobalAbortErrors } from './utils/suppressAbortErrors';
+export { extractTerrainCoordinate, sampleTerrainTileCoordinates } from './utils/terrainPickingUtils';
 export type { GeoImageOptions } from './core/index';
+export type { TerrainCoordinate } from './utils/terrainPickingUtils';

package/dist/esm/types/layers/CogTerrainLayer.d.ts

@@ -61,6 +61,11 @@ type _CogTerrainLayerProps = {
      * Useful for showing a neutral grey terrain during mode transitions.
      */
     disableTexture?: boolean;
+    /**
+     * Callback fired when the terrain zRange is updated.
+     * Used to sync overlay TileLayer zRange for proper 3D frustum culling.
+     */
+    onZRangeUpdate?: (zRange: ZRange | null) => void;
     /**
      * @deprecated Use `loadOptions.terrain.workerUrl` instead
      */

package/dist/esm/types/react/index.d.ts

@@ -0,0 +1 @@
+export { useTerrainZRange } from '../hooks/index';

package/dist/esm/types/utils/terrainPickingUtils.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Terrain coordinate extraction utility for CogTerrainLayer
+ * Enables precise lat/lon/elevation extraction from 3D terrain picks
+ */
+/**
+ * Represents a geographic coordinate with elevation from terrain picking
+ */
+export interface TerrainCoordinate {
+    /** Longitude in degrees */
+    longitude: number;
+    /** Latitude in degrees */
+    latitude: number;
+    /** Elevation in meters */
+    elevation: number;
+}
+/**
+ * Extracts precise geographic coordinates and elevation from a CogTerrainLayer pick result
+ *
+ * @param pickResult - DeckGL pickObject result from terrain-layer pick
+ * @returns TerrainCoordinate with lon/lat/elevation, or null if extraction fails
+ *
+ * @requires deck.gl >=9.3.0 (for `pickable: '3d'` support)
+ * @note Requires `pickable: '3d'` on CogTerrainLayer. With 3D picking enabled,
+ * deck.gl's terrain layer provides info.coordinate as a 3-element array [lon, lat, elevation]
+ * where elevation is read directly from the terrain mesh at the picked point.
+ * This gives accurate 3D coordinates regardless of camera pitch or bearing.
+ *
+ * @example
+ * ```ts
+ * const cogLayer = new CogTerrainLayer({
+ *   // ...
+ *   pickable: '3d',  // Requires deck.gl >=9.3.0
+ *   onClick: (info) => {
+ *     const coord = extractTerrainCoordinate(info);
+ *     if (coord) {
+ *       console.log(`Clicked at ${coord.latitude}, ${coord.longitude}, elevation: ${coord.elevation}m`);
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare function extractTerrainCoordinate(pickResult: any): TerrainCoordinate | null;
+/**
+ * Samples terrain coordinates in a grid around a pick point for debugging
+ * Useful for understanding terrain data layout and accuracy
+ *
+ * @param pickResult - DeckGL pickObject result from terrain-layer pick
+ * @param gridSize - Odd number for grid dimensions (default: 3 for 3x3 grid).
+ *                   gridSize=3 → 3×3 grid (offset±1), gridSize=5 → 5×5 grid (offset±2).
+ *                   Uses WebMercator projection for accurate latitude mapping.
+ * @returns Array of TerrainCoordinate samples, or empty array if extraction fails
+ *
+ * @example
+ * ```ts
+ * const samples = sampleTerrainTileCoordinates(info, 5); // 5x5 grid around click
+ * samples.forEach(coord => {
+ *   console.log(`Sample: ${coord.latitude}, ${coord.longitude}, elev: ${coord.elevation}m`);
+ * });
+ * ```
+ */
+export declare function sampleTerrainTileCoordinates(pickResult: any, gridSize?: number): TerrainCoordinate[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gisatcz/deckgl-geolib",
-  "version": "2.6.0-dev.1",
+  "version": "2.6.0-dev.3",
   "description": "Deck.gl extension for rendering Cloud-Optimized GeoTIFF (COG) data",
   "keywords": [
     "deck.gl",
@@ -30,6 +30,11 @@
       "types": "./dist/esm/types/index.d.ts",
       "import": "./dist/esm/index.js",
       "require": "./dist/cjs/index.js"
+    },
+    "./react": {
+      "types": "./dist/esm/types/react/index.d.ts",
+      "import": "./dist/esm/react/index.js",
+      "require": "./dist/cjs/react/index.js"
     }
   },
   "sideEffects": false,
@@ -64,20 +69,26 @@
     "@loaders.gl/schema": ">=4.0.0",
     "@luma.gl/core": ">=9.0.0",
     "@luma.gl/engine": ">=9.0.0",
-    "@luma.gl/shadertools": ">=9.0.0"
+    "@luma.gl/shadertools": ">=9.0.0",
+    "react": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@deck.gl/core": "^9.2.11",
-    "@deck.gl/extensions": "^9.2.11",
-    "@deck.gl/geo-layers": "^9.2.11",
-    "@deck.gl/layers": "^9.2.11",
-    "@deck.gl/mesh-layers": "^9.2.11",
-    "@loaders.gl/core": "^4.3.4",
-    "@loaders.gl/loader-utils": "^4.3.4",
-    "@loaders.gl/schema": "^4.3.4",
-    "@luma.gl/core": "^9.2.6",
-    "@luma.gl/engine": "^9.2.6",
-    "@luma.gl/shadertools": "^9.2.6",
+    "@deck.gl/core": "^9.3.2",
+    "@deck.gl/extensions": "^9.3.2",
+    "@deck.gl/geo-layers": "^9.3.2",
+    "@deck.gl/layers": "^9.3.2",
+    "@deck.gl/mesh-layers": "^9.3.2",
+    "@loaders.gl/core": "^4.4.1",
+    "@loaders.gl/loader-utils": "^4.4.1",
+    "@loaders.gl/schema": "^4.4.1",
+    "@luma.gl/core": "^9.3.3",
+    "@luma.gl/engine": "^9.3.3",
+    "@luma.gl/shadertools": "^9.3.3",
     "@rollup/plugin-commonjs": "^29.0.2",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",