@juun-roh/cesium-utils 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Juun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# Cesium Utils
+
+[![npm version](https://img.shields.io/npm/v/@juun-roh/cesium-utils.svg)](https://www.npmjs.com/package/@juun-roh/cesium-utils)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Documentation](https://img.shields.io/badge/docs-typedoc-blue)](https://juunie-roh.github.io/cesium-utils/)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/juunie-roh/cesium-utils/release-and-publish.yml)](https://github.com/juunie-roh/cesium-utils/actions)
+
+A utility library for Cesium.js that simplifies working with collections and terrain providers.
+
+[📚 API Documentation](https://juunie-roh.github.io/cesium-utils/) | [📦 NPM Package](https://www.npmjs.com/package/@juun-roh/cesium-utils)
+
+## Installation
+
+```bash
+# npm
+npm install @juun_roh/cesium-utils
+
+# yarn
+yarn add @juun_roh/cesium-utils
+
+# pnpm
+pnpm add @juun_roh/cesium-utils
+```
+
+## Browser Compatibility
+
+This library works in both modern browsers and Node.js environments. It supports:
+
+* ESM (ECMAScript modules)
+* CommonJS (via a bundled .cjs file)
+
+## Development
+
+### Building
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Run tests
+pnpm test
+```
+
+### Documentation
+
+Generate API documentation:
+
+```bash
+pnpm typedoc
+```
+
+## License
+
+MIT © Juun

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var k=Object.defineProperty;var H=Object.getOwnPropertyDescriptor;var Y=Object.getOwnPropertyNames;var q=Object.prototype.hasOwnProperty;var W=(n,e)=>{for(var t in e)k(n,t,{get:e[t],enumerable:!0})},$=(n,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of Y(e))!q.call(n,i)&&i!==t&&k(n,i,{get:()=>e[i],enumerable:!(r=H(e,i))||r.enumerable});return n};var U=n=>$(k({},"__esModule",{value:!0}),n);var X={};W(X,{Collection:()=>R,HybridTerrainProvider:()=>_,TerrainArea:()=>v,TerrainBounds:()=>h,TerrainVisualizer:()=>C,cloneViewer:()=>D,syncCameraState:()=>B});module.exports=U(X);var y=require("cesium"),M=class n{static symbol=Symbol("cesium-item-tag");tag;collection;_valuesCache=null;_tagMap=new Map;_eventListeners=new Map;constructor({collection:e,tag:t}){this.tag=t||"default",this.collection=e}_emit(e,t){let r=this._eventListeners.get(e);if(r){let i={type:e,...t};r.forEach(o=>o(i))}}_addToTagMap(e,t){this._tagMap.has(t)||this._tagMap.set(t,new Set),this._tagMap.get(t)?.add(e)}_removeFromTagMap(e){let t=e[n.symbol],r=this._tagMap.get(t);r&&(r.delete(e),r.size===0&&this._tagMap.delete(t))}_invalidateCache(){this._valuesCache=null}addEventListener(e,t){return this._eventListeners.has(e)||this._eventListeners.set(e,new Set),this._eventListeners.get(e)?.add(t),this}removeEventListener(e,t){return this._eventListeners.get(e)?.delete(t),this}add(e,t=this.tag,r){return Array.isArray(e)?e.forEach(i=>{this.add(i)}):(Object.defineProperty(e,n.symbol,{value:t,enumerable:!1,writable:!0,configurable:!0}),this.collection.add(e,r),this._addToTagMap(e,t),this._invalidateCache(),this._emit("add",{items:[e],tag:t})),e}contains(e){return this.collection.contains(e)}remove(e){let t=this.collection.remove(e);return t&&(this._removeFromTagMap(e),this._invalidateCache(),this._emit("remove",{items:[e]})),t}removeAll(){this._tagMap.clear(),this.collection.removeAll(),this._invalidateCache(),this._emit("clear")}get values(){if(this._valuesCache)return this._valuesCache;if(this.collection instanceof y.EntityCollection)this._valuesCache=this.collection.values||[];else{let e=[];for(let t=0;t<this.collection.length;t++)e.push(this.collection.get(t));this._valuesCache=e}return this._valuesCache}get length(){return this.values?.length||0}getByTag(e){let t=this._tagMap.get(e);return t?Array.from(t):[]}getFirstByTag(e){let t=this._tagMap.get(e);if(t&&t.size>0)return t.values().next().value}getTags(){return Array.from(this._tagMap.keys())}hasTag(e){let t=this._tagMap.get(e);return!!t&&t.size>0}updateTag(e,t){let r=this.getByTag(e);for(let i of r)this._removeFromTagMap(i),Object.defineProperty(i,n.symbol,t),this._addToTagMap(i,t);return r.length>0&&this._emit("update",{items:r,tag:t}),r.length}removeByTag(e){let t=0;return Array.isArray(e)?e.forEach(r=>{this.removeByTag(r)}):this.getByTag(e).forEach(r=>{this.remove(r)&&t++}),t}show(e){let t=this.getByTag(e),r=0;for(let i of t)(0,y.defined)(i.show)&&(i.show=!0,r++);return r}hide(e){let t=this.getByTag(e),r=0;for(let i of t)(0,y.defined)(i.show)&&(i.show=!1,r++);return r}toggle(e){let t=this.getByTag(e),r=0;for(let i of t)(0,y.defined)(i.show)&&(i.show=!i.show,r++);return r}setProperty(e,t,r){let i=this.getByTag(e),o=0;for(let a of i)t in a?(a[t]=r,o++):console.warn(`${t} does not exists in ${a}`);return o}filter(e,t){return(t?this.getByTag(t):this.values).filter(e)}forEach(e,t){(t?this.getByTag(t):this.values).forEach((i,o)=>e(i,o))}},R=M;var f=require("cesium");var O=require("cesium");var m=require("cesium"),h=class{_rectangle;_tilingScheme;_tileRanges;_levels;constructor(e,t){if(this._tilingScheme=t||new m.GeographicTilingScheme,this._rectangle=new m.Rectangle,this._tileRanges=new Map,this._levels=new Set,e.type==="rectangle"&&e.rectangle)this._rectangle=m.Rectangle.clone(e.rectangle);else if(e.type==="tileRange"&&e.tileRanges)e.tileRanges instanceof Map?this._tileRanges=new Map(e.tileRanges):this._tileRanges=new Map(Object.entries(e.tileRanges).map(([r,i])=>[parseInt(r),i])),this._calculateRectangleFromTileRanges();else throw new Error("Either rectangle or tileRanges must be provided.");this._levels=new Set(Array.from(this._tileRanges.keys()))}contains(e,t,r){if(this._tileRanges.has(r)){let o=this._tileRanges.get(r);return e>=o.start.x&&e<=o.end.x&&t>=o.start.y&&t<=o.end.y}let i=this._tilingScheme.tileXYToRectangle(e,t,r);return m.Rectangle.intersection(i,this._rectangle)!==void 0}configureAvailability(e){if(e.availability){e.availability._tilingScheme&&(e.availability._tilingScheme=this._tilingScheme);for(let[t,r]of this._tileRanges.entries())e.availability.addAvailableTileRange(t,r.start.x,r.start.y,r.end.x,r.end.y)}}get rectangle(){return this._rectangle}get tilingScheme(){return this._tilingScheme}get tileRanges(){return this._tileRanges}get levels(){return this._levels}_calculateRectangleFromTileRanges(){let e=Number.POSITIVE_INFINITY,t=Number.POSITIVE_INFINITY,r=Number.NEGATIVE_INFINITY,i=Number.NEGATIVE_INFINITY,o=Array.from(this._tileRanges.keys());if(o.length===0){this._rectangle=m.Rectangle.MAX_VALUE;return}let a=Math.min(...o),s=this._tileRanges.get(a);if(s){let{start:c,end:d}=s,b=this._tilingScheme.tileXYToRectangle(c.x,c.y,a),u=this._tilingScheme.tileXYToRectangle(d.x,d.y,a);e=Math.min(b.west,e),t=Math.min(u.south,t),r=Math.max(u.east,r),i=Math.max(b.north,i)}this._rectangle=new m.Rectangle(e,t,r,i)}};(t=>{function n(r,i,o,a=new m.GeographicTilingScheme){let s=new Map;return s.set(o,{start:{x:r,y:i},end:{x:r,y:i}}),new t({type:"tileRange",tileRanges:s},a)}t.fromTile=n;function e(r,i=new m.GeographicTilingScheme){return new t({type:"rectangle",rectangle:m.Rectangle.clone(r)},i)}t.fromRectangle=e})(h||={});var v=class n{_provider;_bounds;_levels;_ready=!1;_credit;_isCustom;constructor(e,t){this._bounds=e.bounds instanceof h?e.bounds:new h(e.bounds),this._levels=new Set(e.levels||[]),this._credit=e.credit||"custom",this._isCustom=e.isCustom!==void 0?e.isCustom:!0,this._provider=t,this._ready=!0,this._bounds.configureAvailability(this._provider)}static async create(e){let t;return typeof e.provider=="string"?t=await O.CesiumTerrainProvider.fromUrl(e.provider,{requestVertexNormals:!0,credit:e.credit||"custom"}):t=e.provider,new n(e,t)}contains(e,t,r){return this._levels.size>0&&!this._levels.has(r)?!1:this._bounds.contains(e,t,r)}requestTileGeometry(e,t,r,i){if(!(!this._ready||!this.contains(e,t,r)||!this._provider?.getTileDataAvailable(e,t,r)))return this._provider.requestTileGeometry(e,t,r,i)}getTileDataAvailable(e,t,r){return!this.contains(e,t,r)||!this._ready?!1:this._provider?.getTileDataAvailable(e,t,r)??!1}get isCustom(){return this._isCustom}get credit(){return this._credit}get provider(){return this._provider}get bounds(){return this._bounds}get levels(){return this._levels}get ready(){return this._ready}};(e=>{async function n(t,r,i,o="custom"){let a=new h({type:"tileRange",tileRanges:r});return await e.create({provider:t,bounds:a,levels:i||Object.keys(r).map(c=>parseInt(c)),credit:o})}e.fromUrl=n})(v||={});var I=class extends Array{async add(e){let t;return e instanceof v?t=e:t=await v.create(e),this.push(t)}remove(e){let t=this.indexOf(e);return t>=0?(this.splice(t,1),!0):!1}clear(){this.length=0}},_=class n{_terrainAreas=new I;_terrainProvider;_fallbackProvider;_tilingScheme;_ready=!1;_availability;constructor(e,t,r){this._terrainProvider=e,this._fallbackProvider=t,this._tilingScheme=e.tilingScheme||new f.GeographicTilingScheme,this._terrainAreas=new I(...r),this._availability=e.availability,this._ready=!0}static async create(e){try{let t;typeof e.terrainProvider=="string"?t=await f.CesiumTerrainProvider.fromUrl(e.terrainProvider,{requestVertexNormals:!0}):t=e.terrainProvider;let r;e.fallbackProvider?typeof e.fallbackProvider=="string"?r=await f.CesiumTerrainProvider.fromUrl(e.fallbackProvider,{requestVertexNormals:!0}):r=e.fallbackProvider:r=new f.EllipsoidTerrainProvider;let i=[];for(let o of e.terrainAreas){let a=await v.create(o);i.push(a)}return new n(t,r,i)}catch(t){throw console.error("Failed to initialize HybridTerrainProvider:",t),t}}get ready(){return this._ready}get tilingScheme(){return this._tilingScheme}get availability(){return this._availability}get terrainAreas(){return[...this._terrainAreas]}get defaultProvider(){return this._terrainProvider}get fallbackProvider(){return this._fallbackProvider}get credit(){return this._terrainProvider?.credit}get errorEvent(){return this._terrainProvider.errorEvent}get hasWaterMask(){return this._terrainProvider.hasWaterMask}get hasVertexNormals(){return this._terrainProvider.hasVertexNormals}loadTileDataAvailability(e,t,r){return this._terrainProvider.loadTileDataAvailability(e,t,r)}getLevelMaximumGeometricError(e){return this._terrainProvider.getLevelMaximumGeometricError(e)}requestTileGeometry(e,t,r,i){if(this._ready){for(let o of this._terrainAreas)if(o.contains(e,t,r))return o.requestTileGeometry(e,t,r,i);return this._terrainProvider.getTileDataAvailable(e,t,r)?this._terrainProvider.requestTileGeometry(e,t,r,i):this._fallbackProvider.requestTileGeometry(e,t,r,i)}}getTileDataAvailable(e,t,r){return this._terrainAreas.forEach(i=>{if(i.contains(e,t,r)&&i.getTileDataAvailable(e,t,r))return!0}),this._terrainProvider.getTileDataAvailable(e,t,r)||!0}};(e=>{async function n(t,r,i,o){return e.create({terrainAreas:[{provider:t,bounds:{type:"tileRange",tileRanges:i},levels:o||Object.keys(i).map(a=>parseInt(a)),credit:"custom"}],terrainProvider:r,fallbackProvider:new f.EllipsoidTerrainProvider})}e.createOverlay=n})(_||={});var l=require("cesium");var E=class extends R{},C=class n{_viewer;_collection;_hybridTerrain;_visible=!1;_level=15;_tileCoordinatesLayer;_colors=new Map([["custom",l.Color.RED],["default",l.Color.BLUE],["fallback",l.Color.GRAY],["grid",l.Color.YELLOW]]);constructor(e,t){this._viewer=e,this._collection=new E({collection:e.entities,tag:n.tag.default}),t&&(t.colors&&Object.entries(t.colors).forEach(([r,i])=>{this._colors.set(r,i)}),t.tile!==void 0&&(this._visible=t.tile),t.activeLevel!==void 0&&(this._level=t.activeLevel),t.terrainProvider&&this.setTerrainProvider(t.terrainProvider))}setTerrainProvider(e){this._hybridTerrain=e,this.update()}update(){this.clear(),this._visible&&this.show(this._level)}clear(){this._collection.removeByTag(this._collection.getTags())}show(e=15){if(!this._hybridTerrain)return;this._collection.removeByTag(n.tag.grid),this._level=e;let t=this._hybridTerrain.tilingScheme;this._tileCoordinatesLayer||(this._tileCoordinatesLayer=this._viewer.imageryLayers.addImageryProvider(new l.TileCoordinatesImageryProvider({tilingScheme:t,color:l.Color.YELLOW})));let r=(a,s,c)=>{if(this._hybridTerrain){for(let d of this._hybridTerrain.terrainAreas)if(d.contains(a,s,c))return d.isCustom?this._colors.get("custom")||l.Color.RED:this._colors.get("default")||l.Color.BLUE;if(this._hybridTerrain.getTileDataAvailable(a,s,c))return this._colors.get("default")||l.Color.BLUE}return this._colors.get("fallback")||l.Color.TRANSPARENT},i=this._getVisibleRectangle();if(!i)return;function o(a){return a&&Number.isFinite(a.west)&&Number.isFinite(a.south)&&Number.isFinite(a.east)&&Number.isFinite(a.north)&&a.west<=a.east&&a.south<=a.north}if(!o(i)){console.warn("Invalid visible rectangle detected, skipping grid display");return}try{let a=t.positionToTileXY(l.Rectangle.northwest(i),e),s=t.positionToTileXY(l.Rectangle.southeast(i),e);if(!a||!s)return;let c=100,d=Math.min(s.x-a.x+1,c),b=Math.min(s.y-a.y+1,c);for(let u=a.x;u<=a.x+d-1;u++)for(let T=a.y;T<=a.y+b-1;T++)try{let g=t.tileXYToRectangle(u,T,e);if(!o(g)){console.warn(`Invalid rectangle for tile (${u}, ${T}, ${e}), skipping`);continue}let P=r(u,T,e),p=n.createRectangle(g,P.withAlpha(.3));p.properties?.addProperty("tileX",u),p.properties?.addProperty("tileY",T),p.properties?.addProperty("tileLevel",e),this._collection.add(p,n.tag.grid)}catch(g){console.warn(`Error creating tile (${u}, ${T}, ${e}): ${g.message}`);continue}console.log("\u{1F680} ~ TerrainVisualizer ~ showGrid ~ collection:",this._collection),this._visible=!0}catch(a){console.error("Error displaying tile grid:",a)}}hide(){this._collection.removeByTag(n.tag.grid),this._tileCoordinatesLayer&&(this._viewer.imageryLayers.remove(this._tileCoordinatesLayer),this._tileCoordinatesLayer=void 0),this._visible=!1}setColors(e){Object.entries(e).forEach(([t,r])=>{this._colors.set(t,r)}),this.update()}flyTo(e,t){let{rectangle:r}=e.bounds;this._viewer.camera.flyTo({destination:r,...t,complete:()=>{this._visible&&this.update()}})}_getVisibleRectangle(){return this._viewer.camera.computeViewRectangle()}get level(){return this._level}set level(e){this._level=e,this._visible&&this.update()}get visible(){return this._visible}get collection(){return this._collection}get viewer(){return this._viewer}};(r=>{r.tag={default:"Terrain Visualizer",boundary:"Terrain Visualizer Boundary",grid:"Terrain Visualizer Tile Grid"};function e(i,o){return new l.Entity({rectangle:{coordinates:i,material:o,heightReference:l.HeightReference.CLAMP_TO_GROUND}})}r.createRectangle=e;function t(i,o,a){let s=a?.tag||"terrain_area_visualization",c=a?.color||l.Color.RED,d=a?.maxTilesToShow||100,b=a?.show!==void 0?a.show:!0,u=a?.alpha||.7,T=a?.tileAlpha||.2,g="provider"in i?i.bounds:i,P=new E({collection:o.entities,tag:s}),{rectangle:p}=g;if(P.add(r.createRectangle(p,c.withAlpha(u)),s),b&&g.levels.size>0){let{tilingScheme:N}=g;g.levels.forEach(V=>{let S=0,{tileRanges:G}=g;for(let[z,A]of G.entries())if(z===V)for(let x=A.start.x;x<=A.end.x&&S<d;x++)for(let L=A.start.y;L<=A.end.y&&S<d;L++){let F=N.tileXYToRectangle(x,L,V);P.add(e(F,c.withAlpha(T)),`${s}_tile`),S++}})}return P}r.visualize=t})(C||={});var w=require("cesium");function D(n,e,t){let r={baseLayerPicker:n.baseLayerPicker!==void 0,geocoder:n.geocoder!==void 0,homeButton:n.homeButton!==void 0,sceneModePicker:n.sceneModePicker!==void 0,timeline:n.timeline!==void 0,navigationHelpButton:n.navigationHelpButton!==void 0,animation:n.animation!==void 0,fullscreenButton:n.fullscreenButton!==void 0,shouldAnimate:n.clock.shouldAnimate,terrainProvider:n.terrainProvider,requestRenderMode:n.scene.requestRenderMode,infoBox:n.infoBox!==void 0},i=new w.Viewer(e,{...r,...t});B(n,i);let o=n.imageryLayers;i.imageryLayers.removeAll();for(let c=0;c<o.length;c++){let d=o.get(c);i.imageryLayers.addImageryProvider(d.imageryProvider,c)}i.clock.startTime=n.clock.startTime.clone(),i.clock.stopTime=n.clock.stopTime.clone(),i.clock.currentTime=n.clock.currentTime.clone(),i.clock.multiplier=n.clock.multiplier,i.clock.clockStep=n.clock.clockStep,i.clock.clockRange=n.clock.clockRange,i.clock.shouldAnimate=n.clock.shouldAnimate,i.scene.globe.enableLighting=n.scene.globe.enableLighting,i.scene.globe.depthTestAgainstTerrain=n.scene.globe.depthTestAgainstTerrain,i.scene.screenSpaceCameraController.enableCollisionDetection=n.scene.screenSpaceCameraController.enableCollisionDetection;let a=n.scene.screenSpaceCameraController.tiltEventTypes;a&&(i.scene.screenSpaceCameraController.tiltEventTypes=Array.isArray(a)?[...a]:a);let s=n.scene.screenSpaceCameraController.zoomEventTypes;return s&&(i.scene.screenSpaceCameraController.zoomEventTypes=Array.isArray(s)?[...s]:s),i}function B(n,e){if((0,w.defined)(n)&&(0,w.defined)(e)){let{camera:t}=n;e.camera.position=t.positionWC.clone(),e.camera.direction=t.directionWC.clone(),e.camera.up=t.upWC.clone()}}